Pdf.Ninja® provides web API functionality for working with PDF files.
Features
- Read a PDF file from a publicly accessible URL
- Read a PDF file from a POST request
- Retrieve PDF attributes such as metadata, page size, etc.
- Retrieve PDF form fields
- Fill the form fields in a PDF file with data
- Generate images of pages in a PDF file
- Embedding images into a PDF file
Please see the Terms of Use and the Privacy Policy before using the API.
Uptime
Please see the status page for API statistics.
Release Log
2.3.2
October 11, 2024
- Updated dependencies
- v2: Improved XFA support
- v2: Added 'formType' paramenter to info, fields, fill and image endpoints
- v2: CHANGE OF BEHAVIOR: When XFA documents are filled, the XFA form is either discarded or flattened, depending on existence of AcroForm in document
- Added EXIF orientation tag support for JPEG, PNG and WebP images
- Updated capabilities list
- Added 'returnCapabilities' paramenter
- Updated privacy policy
- Added terms of service
- Bug fix: incorrect field names with some PDFs
- Bug fix: incorrectly returning with field not found errors with some XFA PDFs
- Bug fix: filling edit combo boxes with certain values causes an error
- Added other fixes and improvements
Documentation
Authentication
All requests must provide 64 character randomly generated alphanumeric case-sensitive key used for identifying the user. The key can be obtained using the /api/v2/key endpoint.
PDF files
Files are submitted to the API by supplying a publicly accessible URL to the file along with MD5 sum of file's contents. The API server downloads and caches files for a period of time. When the supplied MD5 sum changes, the files are redownloaded. Additionally, the 'file' endpoint can be used to upload PDF files to the API server which are stored for a period of time. Generated files are returned via fileUrl response parameter that is only valid for a short period of time. Generated files can also be optionally returned directly via HTTP response by setting the 'dumpFile' argument to true or yes.
Request format
Requests must be sent to the API using the GET, POST and PUT methods. Data is needs to be passed in through the URL arguments.
Repsonse format
All responses return JSON object with a boolean 'success' fields. Upon failure, responses contain string 'error' containing the error message.
Success
{"success": true, "...": "..."}
Failure
{"success": false, "error": "..."}
Temporary Failure
{"success": false, "error": "...", "temporary": true}
Limits and Access Tiers
The API access is available in two tiers, each having a different set of limits.
- New keys per IP: 1 keys / 500 seconds
Free
- Requests per key: 10 requests / 10 seconds
- Requests per IP: 10 requests / 10 seconds
- New files per key: 4 files / 20 seconds
- Maximum file size: 2 MiB
- File cache expiration: 86400 seconds
- File cache size: 4 files
- Pdf.Ninja® Watermark
Pro (get pro key here)
- Requests per key: 50 requests / 10 seconds
- Requests per IP: 50 requests / 10 seconds
- New files per key: 10 files / 10 seconds
- Maximum file size: 32 MiB
- File cache expiration: 604800 seconds
- File cache size: 50 files
- No Watermark
Endpoints
GET /api/v2/key
Parameters
- email string(256)
Returns a newly generated key.
Request
$ curl "https://pdf.ninja/api/v2/key?email=test@pdf.ninja" Try me
Response
{
"success": true,
"key": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
POST /api/v2/file
Parameters
- key string(64)
- fileId string(64)
- md5sum string(32)
- file file
Receives and caches a PDF file. File cache is temporary and expires after a period of time. Do not rely on it to store your files. If your file is no longer in the cache then you will get "noSuchFileId" error message, in which case you will need to re-upload the PDF file before retrying the request.
Request
Response
{"success": true}
GET /api/v2/info
Parameters
- key string(64)
- fileUrl string(1024) or fileId string(64)
- md5sum string(32)
- formType enum(acroform|xfa|*) = acroform (or autodetected as xfa)
Returns information about the PDF file.
Request
$ curl "https://pdf.ninja/api/v2/info?fileId=test&formType=*&md5sum=022cb6201da97ab7b745f88978d4cab7&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me
$ curl "https://pdf.ninja/api/v2/info?fileUrl=https://pdf.ninja/demo.pdf&md5sum=022cb6201da97ab7b745f88978d4cab7&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me
Response
{"success": true, "title": "...", "subject": "...", "keywords": "...", "authors": ["...", "..."], "creator": "...", "producer": "...", "creationDate": "...", "modificationDate": "...", "pdfVersion": "...", "pages": [ {"number": 1, "width": "...", "height": "...", "sizeUnits": "pts"}, "..." ], "fields": [ {"type": "text|radio|select|checkbox", "name": "...", "alt": "...", "options": ["...", "..."], "flags": ["...", "..."]}, "..." ]}
If the fileId argument is used and the file cache has expired, "noSuchFileId" reason is returned.
{"success": false, "error": "no file with such file id", "reason": "noSuchFileId"}
If the md5sum argument does not match the md5 sum of the file contents, "md5sumMismatch" reason is returned.
{"success": false, "error": "MD5 sum mismatch", "reason": "md5sumMismatch"}
GET /api/v2/fields
Parameters
- key string(64)
- fileUrl string(1024) or fileId string(64)
- md5sum string(32)
- formType enum(acroform|xfa|*) = acroform (or autodetected as xfa)
Returns fields available in a PDF file.
Request
$ curl "https://pdf.ninja/api/v2/fields?fileId=test&md5sum=022cb6201da97ab7b745f88978d4cab7&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me
$ curl "https://pdf.ninja/api/v2/fields?fileUrl=https://pdf.ninja/demo.pdf&md5sum=022cb6201da97ab7b745f88978d4cab7&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me
Response
{"success": true, "fields": [ {"type": "text|radio|select|checkbox", "name": "...", "alt": "...", "options": ["...", "..."], "flags": ["...", "..."]}, "..." ]}
If the fileId argument is used and the file cache has expired, "noSuchFileId" reason is returned.
{"success": false, "error": "no file with such file id", "reason": "noSuchFileId"}
If the md5sum argument does not match the md5 sum of the file contents, "md5sumMismatch" reason is returned.
{"success": false, "error": "MD5 sum mismatch", "reason": "md5sumMismatch"}
Field Flags
Fields have common and type specific flags documented below,
| Type | Name | Meaning |
|---|---|---|
| * | ReadOnly | The user may not change the value of the field. |
| * | Required | The field must have a value at the time it is exported by a submit-form action. |
| * | NoExport | The field must not be exported by a submit-form action. |
| text | Multiline | The field may contain multiple lines of text. |
| text | RichText | The field allows formatted text. |
| text | Password | The field is intended for entering a secure password that should not be echoed visibly to the screen. |
| text | FileSelect | The text entered in the field represents the pathname of a file whose contents are to be submitted as the value of the field. |
| text, select | DoNotSpellCheck | The text entered in the field will not be spell-checked. |
| text | DoNotScroll | The field will not scroll (horizontally for single-line fields, vertically for multiple-line fields) to accommodate more text than will fit within its annotation rectangle. Once the field is full, no further text will be accepted. |
| radio | NoToggleToOff | Exactly one radio button must be selected at all times. |
| select | Combo | The field is a combo box. If this flag is not set, the field is a list box. |
| select | Edit | The combo box includes an editable text box as well as a drop list; if this flag is not set, it includes only a drop list. This flag is meaningful only if the Combo flag is set. |
| select | Sort | The field's option items should be sorted alphabetically. |
| select | MultiSelect | More than one of the field's option items may be selected simultaneously. |
Field Options
The options property of the field object is an array of possible options, which are either string values or objects with properties that contain more detailed information.
The options property is only relevant for the checkbox, radio, and select fields. Filling these fields requires that the value is set to the value (or index) one of the possible options. Multiple-choice select fields can be set to an array of values (and/or indexes).
POST /api/v2/fill
Parameters
- key string(64)
- fileUrl string(1024) or fileId string(64)
- md5sum string(32)
- data JSON string of an object that maps fields to values or array(string=>string); field names must be strings but values can be either a string or an array of strings (for multi-select fields)
- flatten boolean(0|1|true|false|yes|no) = 0
- formType enum(acroform|xfa|*) = acroform (or autodetected as xfa)
Fills fields in the PDF file and returns a temporary URL to the output PDF file.
Filling an XFA document will automatically flatten the form and convert it into a non-XFA document.
Request
$ curl -X POST "https://pdf.ninja/api/v2/fill" -F 'data={"Name":"John","Address":"My address"}' -F "fileId=test" -F "md5sum=022cb6201da97ab7b745f88978d4cab7" -F "key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me
$ curl -X POST "https://pdf.ninja/api/v2/fill" --data "data=%7B%22Name%22%3A%22John%22%2C%22Address%22%3A%22My address%22%7D&fileUrl=https://pdf.ninja/demo.pdf&md5sum=022cb6201da97ab7b745f88978d4cab7&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me
Response
{"success": true, "fileUrl": "https://..."}
If the fileId argument is used and the file cache has expired, "noSuchFileId" reason is returned.
{"success": false, "error": "no file with such file id", "reason": "noSuchFileId"}
If the md5sum argument does not match the md5 sum of the file contents, "md5sumMismatch" reason is returned.
{"success": false, "error": "MD5 sum mismatch", "reason": "md5sumMismatch"}
If the field doesn't exist in the PDF file, an error message is returned.
{"success": false, "error": "Field 'Name' does not exist"}
GET /api/v2/image
Parameters
- key string(64)
- fileUrl string(1024) or fileId string(64)
- md5sum string(32)
- type enum(jpeg|png|svg|pdf|webp|tiff|bmp) = jpeg
- page integer = 1
- resolution integer = 300 dpi
- formType enum(acroform|xfa) = acroform (or autodetected as xfa)
Converts PDF file to an image and returns a temporary URL to the output image file.
Supported output image formats: jpeg, png, svg, pdf, webp, tiff, bmp
Request
$ curl "https://pdf.ninja/api/v2/image?fileId=test&md5sum=022cb6201da97ab7b745f88978d4cab7&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me
$ curl "https://pdf.ninja/api/v2/image?fileUrl=https://pdf.ninja/demo.pdf&md5sum=022cb6201da97ab7b745f88978d4cab7&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me
Response
{"success": true, "fileUrl": "https://..."}
If the fileId argument is used and the file cache has expired, "noSuchFileId" reason is returned.
{"success": false, "error": "no file with such file id", "reason": "noSuchFileId"}
If the md5sum argument does not match the md5 sum of the file contents, "md5sumMismatch" reason is returned.
{"success": false, "error": "MD5 sum mismatch", "reason": "md5sumMismatch"}
POST /api/v2/embed
Parameters
- key string(64)
- fileUrl string(1024) or fileId string(64)
- md5sum string(32)
- images array of uploaded files
- embeds JSON string of an array of objects with the following attributes or array(array(string=>string)) = [ ]
- image string (image array index/key in the images array)
- frame integer = 0
- page integer = 0
- width decimal = 0 pts
- height decimal = 0 pts
- left decimal = 0 pts
- top decimal = 0 pts
- resolution integer = 300 dpi
- vAlign enum(top|middle|bottom) = bottom
- hAlign enum(left|center|right) = left
Embeds images into the specified pages and at the specified locations with the specified sizes and returns a temporary URL to the output PDF file. If page is not specified, the image is added at the center of every page. If location is not specified, the image is added in the center of the page. If size is not specified, the image is scaled to fill the page. If no embeds attributes are specified for a submitted image, defaults will be used.
Supported input image formats: jpeg, png, gif, tiff, bmp, svg, pdf, webp
Embedding into an XFA document will automatically flatten the form and convert it into a non-XFA document.
Request
Response
{"success": true, "fileUrl": "https://..."}
If the fileId argument is used and the file cache has expired, "noSuchFileId" reason is returned.
{"success": false, "error": "no file with such file id", "reason": "noSuchFileId"}
If the md5sum argument does not match the md5 sum of the file contents, "md5sumMismatch" reason is returned.
{"success": false, "error": "MD5 sum mismatch", "reason": "md5sumMismatch"}
POST /api/v2/fillembed
Parameters
- same parameters as with fill and embed
Combines fill and embed features into a single action.
Request
Response
{"success": true, "fileUrl": "https://..."}
If the fileId argument is used and the file cache has expired, "noSuchFileId" reason is returned.
{"success": false, "error": "no file with such file id", "reason": "noSuchFileId"}
If the md5sum argument does not match the md5 sum of the file contents, "md5sumMismatch" reason is returned.
{"success": false, "error": "MD5 sum mismatch", "reason": "md5sumMismatch"}
GET /api/v2/capabilities
Parameters
- key string(64) optional
Returns API capabilities.
Request
$ curl "https://pdf.ninja/api/v2/capabilities" Try me
Response
{"success": true, "features": []}
Capabilites can also be returned with each JSON response in the 'capabilities' property if the argument 'returnCapabilities' is set to 1, 'yes' or 'true'.
Terms of Use
Last Updated: October 11, 2024
Pdf.Ninja (the "Service") is an API provided by Maximum Software Inc ("we"/"us"/"our"). The Service enables users ("you") to access information about PDF documents, fill PDF forms, and embed images into PDFs via HTTP API requests. These terms outline the conditions under which you may use the Service.
Acceptance of Terms
By using the Service, you agree to these Terms of Use and our Privacy Policy. Your obligations under these Terms will survive any termination of your use of the Service.
Violations of these Terms of Use may result in termination of your access and potential legal action.
Changes to Terms
We may modify these Terms of Use periodically. Significant changes will be communicated via email and updated at https://pdf.ninja/#terms. Continued use of the Service after changes are made constitutes your acceptance of the new terms.
Use of the Service
The Service is available to users worldwide, where it is legal to use it. You are responsible for ensuring that your use complies with local laws and does not violate any laws applicable in the jurisdiction of Maximum Software Inc (State of Florida, United States).
You must not use the Service for illegal activities or unethical purposes. You are also prohibited from using the Service in a manner that causes Maximum Software Inc to violate any laws.
Data Handling and Privacy
You must review and accept the terms of our Privacy Policy. You are responsible for ensuring you have the legal rights and permissions for any data you transmit through the Service. Submission of illegal or unethical content is prohibited.
Service Availability
The Service is provided via third-party infrastructure. We strive for high availability but do not guarantee uninterrupted operation. Factors beyond our control may affect Service availability.
Intellectual Property
The content and technology related to the Service, including software, documentation, trademarks, and APIs, are owned by Maximum Software Inc or its licensors.
Ownership of Output: You own the derivative works created by the Service using your content. Maximum Software Inc does not claim ownership of these works.
Limited Grant of Rights for Input: By submitting content through the Service, you grant Maximum Software Inc a limited, non-exclusive, worldwide, royalty-free license to use the content for:
- Creating derivative works as Service output
- Temporary retention for quality assurance, improvement, and debugging
- Internal business activities, including business research, product development, security audits, and compliance
The Limited Grant of Rights for Input license does not allow for commercial use or redistribution of your content by Maximum Software Inc. The data will be retained only as necessary and deleted per our data retention policies.
You are prohibited from reverse engineering, decompiling, disassembling, or accessing the Service's source code or underlying technology, except as allowed by law. You may not circumvent any security measures or technical limitations.
Indemnification Obligations
You agree to indemnify and hold harmless Maximum Software Inc and related parties from any claims, damages, or expenses arising from your violation of these Terms of Use or misuse of the Service.
This indemnification includes claims from third parties due to your breach of these Terms of Use or illegal use of the Service.
Limitation of Liability
Maximum Software Inc is not liable for any damages, including direct, indirect, incidental, or consequential damages arising from the use or inability to use the Service.
Your sole remedy for dissatisfaction with the Service is to stop using it and request a refund.
Contact Us
For questions about these Terms of Use, contact us at https://maximum.software/contact/.
Jurisdiction
These Terms of Use are governed by the laws of the State of Florida, United States, without regard to conflict of law principles.
Privacy Policy
Last Updated: October 11, 2024
This Privacy Policy outlines how we collect, use, process, and protect your information, including personal data, when you access and use our API (the "Service"). By using the Service, you agree to the terms of this Privacy Policy.
We are committed to protecting your privacy and handling your data transparently and securely.
Acceptance of Privacy Policy
By accessing or using the Service, you confirm your acceptance of this Privacy Policy.
Changes to Privacy Policy
We may update this Privacy Policy periodically to reflect changes in our practices or for other operational, legal, or regulatory reasons. Significant changes will be communicated via the email address you provide, and the updated policy will be posted at https://pdf.ninja/#privacy.
Data Collection
We collect the following types of data:
- Personal Information: Your email address.
- Content Data: PDFs you submit through the Service.
- Technical Data: Your request's IP address, timestamps, HTTP headers (User-Agent and Referer).
- Usage Data: Data contained in your API requests and our responses.
Use of Data
We use the data collected to:
- Provide and improve the Service.
- Communicate important information, such as service changes, via your email.
- Temporarily cache PDFs for operational efficiency.
- Log and analyze API requests for quality assurance and debugging.
- Make informed business decisions based on aggregated data.
Data Retention
Data retention periods vary depending on the type of data and service tier:
- PDFs: Automatically deleted after a few minutes.
- Cache Data: Deleted after one week or less.
- API Request Logs: Retained for one month for quality and debugging purposes.
Data Sharing and Disclosure
We do not sell personal information. We share your data only as necessary to provide the Service, comply with legal obligations, or protect our rights.
Data Security
We employ robust security measures, including TLS encryption, to protect your data. We use reputable third-party providers to host our infrastructure, ensuring compliance with industry-standard security practices.
User Rights
You have the right to access, correct, delete, or object to the processing of your personal data. These rights can be exercised by contacting us. For users outside the United States, additional rights may apply under local data protection laws.
Contact Us
For questions or concerns about this policy, please contact us at https://maximum.software/contact/.
Jurisdiction
This Privacy Policy is governed by the laws of the State of Florida, USA, without regard to its conflict of law provisions. For users outside the United States, this choice of law does not deprive you of the protection afforded under mandatory local laws.