Insert Watermark into PDF
Purpose
This API allows you to add a text or image watermark to a PDF and either download the result or store it in Zoho WorkDrive.
Quick Reference
| Property | Value |
|---|---|
| Method | POST |
| Request URL (Download) | https://{zohoapis_domain}/pdfeditor/api/v1/pdf/watermark |
| Request URL (Store) | https://{zohoapis_domain}/pdfeditor/api/v1/pdf/watermark/store |
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 is available via a publicly accessible web URL, you can provide the URL using the same parameter. |
| input_options | For text watermark: { "type": "text", "text_info": { "content": "Confidential", "rotation": "Diagonal" | "Horizontal", "font_color": "rgb(255,0,0)", "font_family": "Roboto", "font_size": 72 } } For image watermark: { "type": "image", "image_info": { "opacity": 0.4, "height": 200, "width": 200 } } | Mandatory | type(mandatory) – Specifies the watermark type. Download variant supports text and image. Store variant currently supports only text. text_info – Contains text watermark settings: content(mandatory) – Specify the text to display. rotation(mandatory) – Specify the watermark direction. Possible values: diagonal, horizontal. font_color(optional) – Specify the font color as an RGB value. font_family(optional) – Specify the text font. font_size(optional) – Specify the font size. image_info – Contains image watermark settings for the download variant. opacity(optional) – Specify the opacity of the image. height(optional) – Specify the image height. width(optional) – Specify the image width. |
| output_settings | { "name": "<document_name>" } | Mandatory for download variant | Specify output configuration for downloadable result. |
| image_file | File | Conditional for download variant | Upload the image to be used as a watermark. Required only when type is set to image in the download variant. |
| output_settings | { "name": "<document_name>", "folder_id": "<folder_id>", "overwrite_existing_file": true | false } | Mandatory for store variant | name – Specify the name for the output 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. |
input_options Parameters
| Parameter | Data Type | Possible Values | Default Value |
|---|---|---|---|
| content | String | Maximum 500 characters | – |
| rotation | String | diagonal, horizontal | – |
| font_color | String | RGB value (e.g., rgb(255,0,0)) | Black |
| font_family | String | Web-safe fonts | Roboto |
| font_size | Integer | Maximum up to 108 | 72 |
| opacity | Float | Maximum 1.0 | 0.4 |
| height | Integer | – | 200 |
| width | Integer | – | 200 |
output_settings (Download) Parameters
| Parameter | Data Type | Possible Values | Default Value |
|---|---|---|---|
| name | String | Name for the modified PDF document | – |
output_settings (Store) Parameters
| Parameter | Data Type | Possible Values | Default Value |
|---|---|---|---|
| name | String | Name for the modified PDF document | – |
| folder_id | String | ID of the folder in Zoho WorkDrive to store the modified PDF | – |
| overwrite_existing_file | Boolean | true, false | false |
Notes and Limits
- The maximum file size allowed for the input PDF is 50 MB. It cannot be more than 400 pages.
- The image_file parameter is required only when type is set to image in the download variant. Maximum image file size: 10 MB.
- The store variant requires a Zoho WorkDrive account.
- To use the download variant, 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:
Download Variant Sample Request
Copiedcurl --location --request POST "https://www.zohoapis.com/pdfeditor/api/v1/pdf/watermark" \
--header "Authorization: Zoho-oauthtoken xxx.yyy.zzz" \
--form 'file=@"/Users/username/Documents/Sample.pdf"' \
--form 'input_options="{\"type\":\"text\",\"text_info\":{\"content\":\"Confidential\",\"font_color\":\"rgb(191,191,191)\",\"font_family\":\"Arimo\",\"font_size\":70,\"rotation\":\"Diagonal\"}}"' \
--form 'output_settings=“{\”name\”:\”ModifiedFile.pdf\"}"'Once the process begins, you will initially receive the 'status_url'. By invoking the 'status_url', you will be able to monitor the status of the scheduled job.
Store Variant Sample Request
Copiedcurl --location --request POST "https://www.zohoapis.com/pdfeditor/api/v1/pdf/watermark" \
--header "Authorization: Zoho-oauthtoken xxx.yyy.zzz" \
--form 'file=@"/Users/username/Documents/Sample.pdf"' \
--form 'input_options="{\"type\":\"text\",\"text_info\":{\"content\":\"Confidential\",\"font_color\":\"rgb(191,191,191)\",\"font_family\":\"Arimo\",\"font_size\":70,\"rotation\":\"Diagonal\"}}"' \
--form 'output_settings=“{\”name\”:\”ModifiedFile.pdf\"}"'Once the process begins, you will initially receive the 'status_url'. By invoking the 'status_url', you will be able to monitor the status of the scheduled job.
Download Variant Sample Response
Copied{
"status_check_url": "https://pdf.zoho.com/pdfeditor/api/v1/pdf/watermark/job/f931a01183b33",
"status": "inprogress"
}Download Variant Success Response
Copied{
"download_url" :"https://pdf.zoho.com/pdfeditor/api/v1/pdf/watermark/download/f931a01183b33",
"status": "success"
}Store Variant Sample Response
Copied{
"download_url" :"https://pdf.zoho.com/pdfeditor/api/v1/pdf/watermark/download/f931a01183b33",
"status": "success"
}Store Variant Success Response
Copied{
"status_check_url" : "https://pdf.zoho.com/pdfeditor/api/v1/pdf/watermark/store/job/f931a01183b33",
"document_url" : "https://workdrive.zoho.com/file/ponazfea04477109f4681a831e7177d96bc40",
"document_id" : "ponazfea04477109f4681a831e7177d96bc40",
"status" : "inprogress"
}