Compress PDF

Purpose

This API allows you to reduce the file size of a PDF for download, WorkDrive storage, or callback delivery.

Quick Reference

Property	Value
Method	POST
Request URL (Download)	https://{zohoapis_domain}/pdfeditor/api/v1/pdf/compress
Request URL (Store)	https://{zohoapis_domain}/pdfeditor/api/v1/pdf/compress/store
Request URL (Callback)	https://{zohoapis_domain}/pdfeditor/api/v1/pdf/compress/callback

Body Parameters

Parameter	Value	Mandatory/Optional	Description
file	File or String	Mandatory	Upload the PDF file from your local drive or desktop. If the PDF file is available via a publicly accessible web URL, you can provide the URL using the same parameter.
input_options	{ "image_settings": { ... }, "font_settings": { ... }, "resource_optimization": { ... }, "discard_objects": { ... }, "discard_user_data": { ... }, "color_management": { ... } }	Mandatory	Specify the compression configuration as a JSON object. Only include the setting groups and keys you want to customize.
password	String	Optional	If the input PDF is password protected, specify the password to unlock it.
output_settings	{ "name": "<document_name>", "folder_id": "<folder_id>", "overwrite_existing_file": true \| false }	Mandatory for store variant	name – Specify the name for the compressed PDF document. folder_id – Specify the ID of the WorkDrive folder in which to store the output file. overwrite_existing_file(optional) – Set to true to overwrite an existing file with the same name in the folder.
callback	{ "invoke_url": "<callback_url>", "timeout": 60, "retry_interval": 60, "headers": { "header_name": "header_value" }, "http_method_type": "post" }	Mandatory for callback variant	Specify the callback delivery configuration for the /callback variant.

input_options Parameters

Parameter	Data Type	Possible Values	Default Value
image_settings	JSON Object	Contains compression settings for color, grayscale, and monochrome images.	–
font_settings	JSON Object	Contains font optimization settings such as deduplicate_fonts and subset_fonts.	–
resource_optimization	JSON Object	Contains cleanup and stream compression settings.	–
discard_objects	JSON Object	Contains flags to remove annotations, thumbnails, bookmarks, page actions, and similar objects.	–
discard_user_data	JSON Object	Contains flags to remove metadata, JavaScript, embedded files, rich media, accessibility tags, and private application data.	–
color_management	JSON Object	Contains transparency normalization and RGB conversion settings.	–

The following sub-sections describe each supported settings object.

image_settings.color_images

Parameter	Type	Possible Values	Default Value
enable_resize	Boolean	true / false	false
enable_dpi_reduction	Boolean	true / false	false
target_dpi	Integer	≥ 72 (Recommended: 72–300)	150
max_dimension	Integer	≥ 256 (pixels)	1500
convert_to_grayscale	Boolean	true / false	false
compression_type	String	jpeg / lossless	jpeg
quality	Float	0.1 – 1.0 (0.3 = high compression, 0.6 = balanced, 0.8–1.0 = high quality). Applicable only when `compression_type` is `jpeg`.	0.75
deduplicate_images	Boolean	true / false	false
extract_inline_images	Boolean	true / false	false

image_settings.grayscale_images

Parameter	Type	Possible Values	Default Value
enable_resize	Boolean	true / false	false
enable_dpi_reduction	Boolean	true / false	false
target_dpi	Integer	≥ 72	150
max_dimension	Integer	≥ 256	1500
compression_type	String	jpeg / lossless	jpeg
quality	Float	0.1 – 1.0	0.8
deduplicate_images	Boolean	true / false	false

image_settings.monochrome_images

Parameter	Type	Possible Values	Default Value
enable_resize	Boolean	true / false	false
enable_dpi_reduction	Boolean	true / false	false
target_dpi	Integer	≥ 150	300
compression_type	String	jpeg / lossless	lossless
quality	String	lossless / lossy	lossless

font_settings

Parameter	Type	Possible Values	Default Value
deduplicate_fonts	Boolean	true / false	false
subset_fonts	Boolean	true / false	false

resource_optimization

Parameter	Type	Possible Values	Default Value
remove_unused_resources	Boolean	true / false	false
deduplicate_streams	Boolean	true / false	false
compress_objects	Boolean	true / false	false
enable_stream_compression	Boolean	true / false	true

discard_objects

Parameter	Type	Possible Values	Default Value
discard_form_fields	Boolean	true / false	false
flatten_form_fields	Boolean	true / false	false
discard_annotations	Boolean	true / false	false
discard_hidden_annotations	Boolean	true / false	false
discard_alternate_images	Boolean	true / false	false
discard_bookmarks	Boolean	true / false	false
discard_thumbnails	Boolean	true / false	false
discard_page_actions	Boolean	true / false	false
discard_open_actions	Boolean	true / false	false
discard_output_intents	Boolean	true / false	false
discard_optional_content_layers	Boolean	true / false	false

discard_user_data

Parameter	Type	Possible Values	Default Value
discard_metadata	Boolean	true / false	false
discard_javascript	Boolean	true / false	false
discard_embedded_files	Boolean	true / false	false
discard_rich_media	Boolean	true / false	false
discard_accessibility_tags	Boolean	true / false	false
discard_private_application_data	Boolean	true / false	false

color_management

Parameter	Type	Possible Values	Default Value
normalize_transparency	Boolean	true / false	false
force_rgb	Boolean	true / false	false

callback Parameters

Parameter	Data Type	Possible Values	Default Value
invoke_url	String	URL. Maximum length: 300 characters.	–
timeout	Integer	10 to 120 seconds	60 seconds
retry_interval	Integer	60 to 28800 seconds	60 seconds
headers	JSON Object	Maximum 10 keys. Allowed characters for keys: alphabets, numbers, hyphen, underscore, dot. Maximum key length: 100. Maximum value length: 2500.	–
http_method_type	String	put, post	post

Notes and Limits

The maximum file size allowed for the input PDF is 50 MB.
Only the keys you pass inside input_options are customized. Omitted keys fall back to their default values.
This API stores the result in Zoho WorkDrive only for the /store variant. A WorkDrive account is required for that variant.
To use the download or callback variants, an OAuth token should be generated with the following scopes: ZohoWriter.pdfEditor.ALL
To use the store variant, an OAuth token should be generated with the following scopes: ZohoWriter.pdfEditor.ALL, WorkDrive.files.ALL, WorkDrive.organization.ALL

Possible Errors

Refer to the following pages for the list of possible errors for this API:

General Errors

Download Variant Sample Request

Copiedcurl --location --request POST "https://{zohoapis_domain}/pdfeditor/api/v1/pdf/compress" \
  --header "Authorization: Zoho-oauthtoken xxx.yyy.zzz" \
  --form 'file=@/Users/username/Documents/Original.pdf' \
  --form 'password="pdf_password"' \
  --form 'input_options={
    "image_settings": {
      "color_images": {
        "enable_resize": true,
        "enable_dpi_reduction": true,
        "target_dpi": 120,
        "max_dimension": 1200,
        "quality": 0.6
      },
      "grayscale_images": {
        "quality": 0.7
      },
      "monochrome_images": {
        "target_dpi": 300
      }
    },
    "font_settings": { "deduplicate_fonts": true },
    "resource_optimization": { "remove_unused_resources": true, "enable_stream_compression": true }
  }'

Store Variant Sample Request

Copiedcurl --location --request POST "https://{zohoapis_domain}/pdfeditor/api/v1/pdf/compress/store" \
  --header "Authorization: Zoho-oauthtoken xxx.yyy.zzz" \
  --form 'file=@/Users/username/Documents/Original.pdf' \
  --form 'password="pdf_password"' \
  --form 'input_options={
    "image_settings": {
      "color_images": {
        "enable_resize": true,
        "enable_dpi_reduction": true,
        "target_dpi": 120,
        "max_dimension": 1200,
        "quality": 0.6
      },
      "grayscale_images": {
        "quality": 0.7
      }
    },
    "font_settings": { "deduplicate_fonts": true },
    "resource_optimization": { "remove_unused_resources": true, "enable_stream_compression": true }
  }' \
  --form 'output_settings={"name": "Compressed_Document.pdf", "folder_id": "<folder_id>", "overwrite_existing_file": true}'

Callback Variant Sample Request

Copiedcurl --location --request POST "https://{zohoapis_domain}/pdfeditor/api/v1/pdf/compress/callback" \
  --header "Authorization: Zoho-oauthtoken xxx.yyy.zzz" \
  --form 'file=@/Users/username/Documents/Original.pdf' \
  --form 'password="pdf_password"' \
  --form 'input_options={
    "image_settings": {
      "color_images": {
        "enable_resize": true,
        "enable_dpi_reduction": true,
        "target_dpi": 120,
        "max_dimension": 1200,
        "quality": 0.6
      },
      "monochrome_images": {
        "target_dpi": 300
      }
    },
    "font_settings": { "deduplicate_fonts": true },
    "resource_optimization": { "remove_unused_resources": true, "enable_stream_compression": true }
  }' \
  --form 'callback={"invoke_url": "https://www.example.com/v1/api/callback/savecallback", "timeout": 120, "retry_interval": 60, "http_method_type": "post"}'

Download Variant Sample Response

Copied{
  "status": "inprogress",
  "status_check_url": "https://pdf.zoho.com/pdfeditor/api/v1/pdf/compress/job/e9051e30fd7f0093cba4247d1f831e03e945a127bde429ed6e9ef3a703b15a6060b830256c650cb88a3f687773c33076"
}

Download Variant Success Response

Copied{
  "status": "success",
  "download_url": "https://pdf.zoho.com/pdfeditor/api/v1/pdf/compress/download/d2e4f6a8b9c1d3e5f7a9b1c3d5e7f9a1",
  "response_generated_time": 1780912499331
}

Store Variant Sample Response

Copied{
  "status": "inprogress",
  "status_check_url": "https://pdf.zoho.com/pdfeditor/api/v1/pdf/compress/job/2ae74c719bdb14ed9941fe351ade742439bf75ab0fb8fdf0a68b57a7a60cbd54ab7cb7bea5d0fafb4d2560a90331aaf8",
  "document_id": "hf3e60435a4c7576f4d21a16cfc292a4c64a9",
  "document_url": "https://workdrive.zoho.com/file/hf3e60435a4c7576f4d21a16cfc292a4c64a9"
}

Store Variant Success Response

Copied{
  "status": "success",
  "document_id": "hf3e60435a4c7576f4d21a16cfc292a4c64a9",
  "document_url": "https://workdrive.zoho.com/file/hf3e60435a4c7576f4d21a16cfc292a4c64a9",
  "response_generated_time": 1780912529135
}

Callback Variant Sample Response

Copied{
  "status": "inprogress",
  "status_check_url": "https://pdf.zoho.com/pdfeditor/api/v1/pdf/compress/job/1d358192770dc68d173ca34b8f7c9dcb121ad0bf3d6307b7387be79e76dacf586f9d62cd253c26020f8c3dcf79d51b6b"
}

Callback Variant Success Response

Copied{
  "status": "success",
  "callback_response": {
    "invoked_time": 1780912655806,
    "http_status_code": 200,
    "message": {
      "download_url": "https://pdf.zoho.com/pdfeditor/api/v1/pdf/compress/download/d2e4f6a8b9c1d3e5f7a9b1c3d5e7f9a1",
      "response_generated_time": 1780912656237
    }
  }
}