ICON Pdf.Ninja API

The API provides 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

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/v1/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: 1 files / 20 seconds
  • Maximum file size: 2 MiB
  • Pdf.Ninja API 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
  • No Watermark

Endpoints

GET /api/v1/key

Parameters

Returns a newly generated key.

Request
$ curl "https://pdf.ninja/api/v1/key?email=test@pdf.ninja" Try me
Response
{
    "success": true,
    "key": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

POST /api/v1/file

Parameters

Receives and caches a PDF file.

Request
$ curl "https://pdf.ninja/api/v1/file" -F file=@test.pdf -F "fileId=test" -F "md5sum=d57c2e56520a2bdd0161060f0185cb2a" -F "key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Try me
Response
{"success": true}

GET /api/v1/info

Parameters

Returns information about the PDF file.

Request
$ curl "https://pdf.ninja/api/v1/info?fileId=test&md5sum=d57c2e56520a2bdd0161060f0185cb2a&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me $ curl "https://pdf.ninja/api/v1/info?fileUrl=https://pdf.ninja/interactiveform_enabled.pdf&md5sum=d57c2e56520a2bdd0161060f0185cb2a&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/v1/fields

Parameters

Returns fields available in a PDF file.

Request
$ curl "https://pdf.ninja/api/v1/fields?fileId=test&md5sum=d57c2e56520a2bdd0161060f0185cb2a&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me $ curl "https://pdf.ninja/api/v1/fields?fileUrl=https://pdf.ninja/interactiveform_enabled.pdf&md5sum=d57c2e56520a2bdd0161060f0185cb2a&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 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.

POST /api/v1/fill

Parameters

Fills fields in the PDF file and returns a temporary URL to the output PDF file.

Request
$ curl -X POST "https://pdf.ninja/api/v1/fill" -F 'data={"Name_First":"my first name","Name_Last":"my last name"}' -F "fileId=test" -F "md5sum=d57c2e56520a2bdd0161060f0185cb2a" -F "key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me $ curl -X POST "https://pdf.ninja/api/v1/fill" --data "data=%7B%22Name_First%22%3A%22my%20first%20name%22%2C%22Name_Last%22%3A%22my%20last%20name%22%7D&fileUrl=https://pdf.ninja/interactiveform_enabled.pdf&md5sum=d57c2e56520a2bdd0161060f0185cb2a&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/v1/image

Parameters

Converts PDF file to an image and returns a temporary URL to the output image file.

Supported output image formats: jpeg, png, svg, tiff, ps, eps

Request
$ curl "https://pdf.ninja/api/v1/image?fileId=test&md5sum=d57c2e56520a2bdd0161060f0185cb2a&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" Try me $ curl "https://pdf.ninja/api/v1/image?fileUrl=https://pdf.ninja/interactiveform_enabled.pdf&md5sum=d57c2e56520a2bdd0161060f0185cb2a&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/v1/embed

Parameters

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, svg, bmp, pdf, eps

Request
$ curl "https://pdf.ninja/api/v1/embed" -F images[1]=@embed.png -F 'embeds=[{"image":1,"page":1,"left":10,"top":10,"width":50,"height":50},{"image":1,"page":1,"left":70,"top":10,"width":50,"height":50}]' -F "fileId=test" -F "md5sum=d57c2e56520a2bdd0161060f0185cb2a" -F "key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Try me
$ curl "https://pdf.ninja/api/v1/embed" -F images[1]=@embed.png -F "fileUrl=https://pdf.ninja/interactiveform_enabled.pdf" -F "md5sum=d57c2e56520a2bdd0161060f0185cb2a" -F "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/v1/fillembed

Parameters

Combines fill and embed features into a single action.

Request
$ curl "https://pdf.ninja/api/v1/fillembed" -F 'data={"Name_First":"my first name","Name_Last":"my last name"}' -F images[1]=@embed.png -F 'embeds=[{"image":1,"page":1,"left":10,"top":10,"width":50,"height":50},{"image":1,"page":1,"left":70,"top":10,"width":50,"height":50}]' -F "fileId=test" -F "md5sum=d57c2e56520a2bdd0161060f0185cb2a" -F "key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Try me
$ curl "https://pdf.ninja/api/v1/fillembed" -F 'data={"Name_First":"my first name","Name_Last":"my last name"}' -F images[1]=@embed.png -F 'embeds=[{"image":1,"page":1,"left":10,"top":10,"width":50,"height":50},{"image":1,"page":1,"left":70,"top":10,"width":50,"height":50}]' -F "fileUrl=https://pdf.ninja/interactiveform_enabled.pdf" -F "md5sum=d57c2e56520a2bdd0161060f0185cb2a" -F "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"}

Privacy Policy

Your privacy and data security is our top priority. The API infrastructure is hosted in a secure environment. The generated PDFs are deleted on the server after a few minutes. Blank (original) PDFs are cached on the server for a week. Request data and responses are logged for debugging purposes and are deleted after a month. Generated PDF files are randomly reviewed to ensure proper API operation and to detect bugs. All user data is eventually deleted from all systems after about a month. Contact us for more information.