ICON Pdf.Ninja API

The API provides functionality for working with PDF forms.

Features

  • Read PDF file from a publicly accessible URL
  • Read PDF file from a POST request
  • Retrieve PDF form fields
  • Fill the form fields in 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.

Limits and Paid Access

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: 1MB
  • 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: 32MB
  • No Watermark

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. The generated files are returned by URL to a file that is only valid for a short period of time.

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}

Methods

GET /api/v1/key

Parameters

Returns a newly generated key.

GET /api/v1/key?email={your-email}
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.

POST /api/v1/file fileId={64-or-less-character-file-id} md5sum={pdf-file-contents-md5-sum} key={64-character-key} file=... (multipart/form-data)
Request
$ curl "https://pdf.ninja/api/v1/file" -F file=@test.pdf -F "fileId=test" -F "md5sum=d57c2e56520a2bdd0161060f0185cb2a" -F "key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Response
{success: true}

GET /api/v1/fields

Parameters

Returns fields available in a PDF file.

GET /api/v1/fields?fileId={64-or-less-character-file-id}&md5sum={pdf-file-contents-md5-sum}&key={64-character-key} GET /api/v1/fields?fileUrl={encoded-url-to-pdf-file}&md5sum={pdf-file-contents-md5-sum}&key={64-character-key}
Request
$ curl "https://pdf.ninja/api/v1/fields?fileId=test&md5sum=d57c2e56520a2bdd0161060f0185cb2a&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" $ curl "https://pdf.ninja/api/v1/fields?fileUrl=http://help.adobe.com/en_US/Acrobat/9.0/Samples/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.

POST /api/v1/fill data[field1_name]=value&data[field2_name]=value&fileId={64-or-less-character-file-id}&md5sum={pdf-file-contents-md5-sum}&key={64-character-key} POST /api/v1/fill data={"field1_name":"value","field2_name":"value"}&fileUrl={encoded-url-to-pdf-file}&md5sum={pdf-file-contents-md5-sum}&key={64-character-key}
Request
$ curl -X POST "https://pdf.ninja/api/v1/fill" --data "data[Name_First]=my%20first%20name&data[Name_Last]=my%20last%20name&fileId=test&md5sum=d57c2e56520a2bdd0161060f0185cb2a&key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" $ 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=http://help.adobe.com/en_US/Acrobat/9.0/Samples/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"}