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 download_url.
• 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.

Tip

We recommend using the sync.api.docspring.com subdomain for all API requests. 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. The wait query parameter has no effect on the async subdomain.

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/v1/templates/{template_id}/submissions
• Create Submission Batch: POST /api/v1/submissions/batches
• Create Combined Submission: POST /api/v1/combined_submissions
• Create Template: POST /api/v1/templates
• Get Submission: GET /api/v1/submissions/{submission_id}
• Get Submission Batch: GET /api/v1/submissions/batches/{submission_batch_id}
• Get Combined Submission: GET /api/v1/combined_submissions/{combined_submission_id}
• Get Template: GET /api/v1/templates/{template_id}

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 response still includes the submission (or the template, combined submission or submission batch you created), and processing carries on in the background:

{
  "status": "error",
  "error": {
    "code": "polling_timeout",
    "message": "polling timeout after 1m35s"
  },
  "submission": {
    "id": "sub_1234567890abcdef01",
    "state": "pending"
  }
}

(Other submission fields are left out here.)

Use the ID to check the submission’s status, or use webhooks to find out when it’s ready. A status check on the synchronous subdomain also waits up to 95 seconds for the PDF. Add ?wait=false to get the current status straight away.

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 creates a duplicate.

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.