Synchronous API Requests

The DocSpring API supports both synchronous and asynchronous API requests.

• Synchronous API requests make it much easier to integrate DocSpring with your application. When you make a synchronous API request, the API will wait until the PDF is generated before returning a 201 response with the PDF’s download_url (in files.pdf).
• Asynchronous requests are useful when generating a PDF takes a long time, or when you want to generate a PDF in the background. When you make an asynchronous request, the API will return a 201 response immediately, and you can check the status of the request later.

A synchronous create request returns 201 with the record in its final state, whether the PDF was generated or processing failed. Check the submission’s state: processed when the PDF is ready, or a failure state with an error_message that says why (error, syntax_error, image_download_failed or image_processing_failed). The one exception is running out of credits, which returns a 402 with an insufficient_credits error and the record’s ID (see Credits & Rate Limits).

A synchronous batch returns a 402 as soon as any submission in it is waiting for credits, even if other submissions in the batch were already processed and charged. The error has the batch’s submission_batch_id: get the batch to see each submission’s state, and don’t resubmit the batch: the waiting submissions resume automatically once you add credits.

Only requests that create a submission, batch, combined PDF or template PDF, or add files to a submission, wait. A GET always returns the record straight away, in its current state, including a failure state or insufficient_credits.

Tip

We recommend using the sync.api.docspring.com subdomain for all API requests (sync.api-eu.docspring.com for accounts in our EU region). The synchronous subdomain supports all API endpoints, so you can use it for all your API requests.

All of our API client libraries will use this subdomain by default. (You can always override the host when configuring your client.)

You can force the synchronous subdomain to return a pending response immediately by adding the ?wait=false query parameter to one of the requests that wait. The wait query parameter has no effect on the async subdomain, and other requests don’t take it: wait on any other request is a 422.

Subdomains and Endpoints

• Requests to sync.api.docspring.com are synchronous by default. (The API waits for the PDF to be processed before returning a response.)
  • Customers in our EU region should use sync.api-eu.docspring.com
• Requests to api.docspring.com are asynchronous by default. (Pending PDF is returned immediately.)
  • Customers in our EU region should use api-eu.docspring.com

Synchronous API Endpoints

• Create Submission: POST /api/v2/templates/{template_id}/submissions
• Create Submission Batch: POST /api/v2/submissions/batches
• Create Combined PDF: POST /api/v2/combined_pdfs
• Create Template: POST /api/v2/templates and POST /api/v2/templates/upload
• Update Template Document: PUT /api/v2/templates/{template_id}/document and PUT /api/v2/templates/{template_id}/document/upload
• Generate More Files: POST /api/v2/submissions/{submission_id}/generate_files

A template request waits until the template’s PDF has been processed, and until a document_url has been downloaded (its document.state isn’t pending or downloading). A request for more files waits until they’ve been made (none of the submission’s files has the state pending).

Time limit

The synchronous subdomain waits up to 95 seconds for your PDF. Most PDFs are ready within a few seconds, so this is only an upper limit.

If the PDF still isn’t ready after 95 seconds, the API returns a 504 response with the error code polling_timeout. The error includes the ID of the submission (or the submission_batch_id, combined_pdf_id or template_id of the record you created), and processing carries on in the background:

{
  "error": {
    "code": "polling_timeout",
    "message": "Timed out waiting for the submission to be processed. It's still being processed: get it with GET /api/v2/submissions/sub_1234567890abcdef01 until its state isn't pending.",
    "details": [],
    "request_id": "req_1234567890abcdef01",
    "submission_id": "sub_1234567890abcdef01"
  }
}

Use the ID to check the submission’s status, or use webhooks to find out when it’s ready.

Caution

If a request to create a submission (or another record) returns a polling_timeout error that includes the record, don’t send that request again. The record was already created, so sending it again without an Idempotency-Key creates a duplicate. A polling_timeout error without an ID means DocSpring didn’t answer the request in time, so the record may or may not have been created: send the request again with the same Idempotency-Key, or check for the record first.

If some of your PDFs regularly take longer than 95 seconds, add ?wait=false to those requests. You’ll get the pending submission straight away, and can then check its status or use webhooks as described above.

Sending a request again

Every request that creates, changes or deletes something (each POST, PUT and DELETE) takes an Idempotency-Key header: a key of your own, such as a UUID, of up to 255 printable ASCII characters. Send a new key with each new request, and the same key each time you send the same request again, such as after a timeout, a network error or a 5xx. For 24 hours, DocSpring answers a request with a key that your API token has already used with the first request’s response, and an Idempotent-Replayed: true header, instead of processing it again.

• The same key with a different request (another path, query or body) is a 422 with the error code idempotency_key_reused.
• A 409 with the error code idempotency_key_in_use and a Retry-After header means the first request is still being processed: send the request again after that many seconds. Without Retry-After, the first request was processed but its response is no longer kept, because it was too large or its data has expired. The error has the ID of the record the first request created, when it created one.
• wait doesn’t change the request: a request with ?wait=false and the same request without it are the same request.

The API clients take the key as each method’s last argument, or as an option.