Skip to main content
POST
Create Document via API
When your automation’s data source is set to API, you pass all field data directly in the request body. This is the most flexible option, as you control exactly what data goes into the document.

Endpoint

Request Body

string
required
The automation ID. Find it on the automation’s settings page or via GET /automations. docId is also accepted, so existing integrations keep working. Send only one of the two: a request with different values in automationId and docId fails with HTTP 400.
object
required
Key-value pairs for template placeholders. Keys must match the placeholder names in your template (e.g., {{customer_name}} in your template → "customer_name" in the data object). Line items are also included inside this object as line_items_1, line_items_2, etc. See Example with Line Items below.
string | string[]
Emails of people who must approve this document before it goes out: one email, several separated by commas, semicolons or line breaks, or a list of up to 10. Send it at the top level of the request, not inside data. The document waits for approval even when approval is off for the automation. Anyone named can join as an approver, from any email domain. When Approvers need an account is off, a person who is not on your team decides from their own email link without an account; see Approve without an account. Fails with an error on a plan without Approvals. See Approvers in an API call.
string
Custom name for the generated document. Overrides the automation’s document name setting.
boolean
default:"false"
By default the request waits and returns the document (HTTP 200 with pdfUrl). When true, it returns immediately with a jobId (HTTP 202) instead. Poll GET /job/{jobId} for the result.
string
Your own key for this document, up to 255 characters, for example "proposal-1042-v2". When you send the same request again with the same key within 7 days, no new document is created and you get the result of the first request. Also accepted as an Idempotency-Key request header; when both are sent, the body value is used. See Safe retries with an idempotency key.
object
Custom parameters passed through to webhook notifications under both webhookParams and additionalParams (identical content; the latter is kept for backward compatibility).
boolean
default:"false"
When true, skips e-signing for this request even if the automation has e-signing enabled. The document is generated and delivered normally (Drive save, email, webhook), but no signing session is started and no signing invitations are sent. Useful for two-step approval flows: generate a draft for review first, then re-run without skipEsign to send the document for signing. Also accepted as a query parameter (?skipEsign=true) on GET requests.
object[]
Who signs or accepts this document. Each entry is { "signer": 1, "email": "anna@acme.com", "name": "Anna Weber" }. signer is the signer’s number in the automation: for signing it matches the number in the template tags (1 in {{esign.signature_1}}), for acceptance it is the position in the Recipients list. name is optional; without it the name set in the automation is used.A listed signer’s email and name replace the saved ones for this document only. Signers you leave out keep their saved setup, and nothing is saved on the automation. The automation decides how many signers there are, so recipients never adds a signer. You can leave out signer when the automation has exactly one signer. With two or more signers, every entry needs it.In the automation’s Signing & Acceptance settings, a signer’s email can be set to Given with each request. This option is available for API and MCP automations and automations without a data source. Every request must then name that signer in recipients, or it fails with “Signer 1 needs an email: pass it in recipients”.The request fails before anything is generated when a signer number does not exist, the same signer is listed twice, an email is invalid, or the automation has no signing or acceptance step.
string
Email address of the team member generating this document. When the automation’s email delivery (or e-signature email settings) has Send from the team member who generates the document enabled, the email is sent from this member’s own connected Gmail or Outlook account instead of the configured sender. The address must match a mailbox connected to the workspace; otherwise DocsAutomator falls back to the automation’s configured sender. Also accepted as a query parameter (?actingUserEmail=...) on GET requests or as an X-Acting-User-Email request header (the header takes precedence). The in-app Generate button passes this automatically.
string[]
Array of publicly accessible PDF URLs to merge or prepend to the generated document.
Override the automation’s Google Doc template URL for this request only. Pass a full Google Docs URL or just the document ID.
Word templates only. Use a different Word file for this request only: an https link to a .docx file that our servers can download. The data, mapping, signing and output settings still come from the automation in docId. The file can be up to 25 MB. Links to private or internal network addresses are refused.
string
Word templates only. The same as wordTemplateLink, but you send the .docx file itself, encoded as base64, in the JSON body. Use this when you cannot host the file. Up to 25 MB before encoding. Send either wordTemplateLink or wordTemplateBase64, not both.
PDF templates only. Use a different PDF as the background for this request only: an https link to a PDF file that our servers can download. The automation’s saved fields are placed on this PDF at their saved positions, for example to fill in a check or a form that another tool created. The data, mapping, signing and output settings still come from the automation in docId. The file can be up to 25 MB. Links to private or internal network addresses are refused, and so are password-protected PDFs.The PDF must have every page that holds a saved field. If a field is on a page the PDF does not have, the request fails and the error names the fields and pages. If a page has a different size from the page in the saved template, each field keeps its distance from the top-left corner of the page and is not scaled. The response then lists the affected pages in warnings.
string
PDF templates only. The same as pdfTemplateLink, but you send the PDF itself, encoded as base64, in the JSON body. Use this when you cannot host the file. Up to 25 MB before encoding. Send either pdfTemplateLink or pdfTemplateBase64, not both.

Basic Example

Example with Line Items

Pass line items as arrays inside the data object. Use line_items_1 for the first group, line_items_2 for a second group, and so on. There is no limit on the number of line item groups. Each object’s keys must match the line item placeholder names in your template.

Nested Line Items

Use the children key for nesting (up to 2 levels):
Learn more about setting up line items in your template in the Line Items guide.

Images

Any placeholder whose name contains image is filled with a picture. Pass a publicly accessible URL as the value (a single URL, or an array for a multi-image placeholder):
To make an image a clickable link, pass it as a { "url", "link" } object instead of a plain URL string. No automation setup is required, and the link survives PDF export (Google Doc and Word templates). Arrays work too, with a link per image:
See Dynamic Images for supported formats, resizing, choosing which image to insert, and clickable links.

Async Mode

For high-volume or latency-sensitive workflows, use async mode. The API returns a jobId immediately, and you poll for the result.

Safe retries with an idempotency key

A network error or a timeout can leave you unsure whether a document was created. Send an idempotency key with the request, and you can send the same request again without creating a second document, a second signing session or a second approval request. Choose one key per document you want, for example the record id plus a version: "proposal-1042-v2". Keys belong to your workspace, so another workspace can use the same key. A key is kept for 7 days after the first request. After that, the same key creates a new document. Why sync mode answers 409 while the first request runs: a second request that waits for the first one can hit your own timeout and leave you where you started. The 409 answer comes back at once, names the running job, and the next retry with the same key returns the finished result. What counts as the same request: we compare the automation id and everything else you send in the body and the query string, in any key order. async, the key itself and your API key are not compared. For an automation with a record source such as Airtable, the request holds the record id, not the record’s values, so a change to the record does not make it a different request. Use a new key when you want a new document from the changed record. Requests without a key work as before: every request creates a new document.

Airtable script example

This script runs in an Airtable automation (“Run a script” action). It uses the record id and a version field as the key, so running it again for the same record never creates a second proposal, and raising the version creates a new one.

Response

Sync mode (200)

message, pdfUrl and documentName are always present. When the automation uses Approvals and the document waits for approval, message and status are "awaiting_approval", pdfUrl and googleDocUrl are null, and the save fields are left out. The answer also has logId, holdId and approval. The webhook fires after the approval. Additional fields are included depending on your automation’s configuration:

Async mode (202)

E-invoices

When the e-invoice add-on is on for the workspace and the automation, every document you create through the API is also an e-invoice. You send the same request; nothing in the request changes.
  • Fields: the e-invoice reads the request keys mapped in the automation’s E-invoice section, including the line_items_1 list. Send amounts in euros, as numbers (1059) or as text ("1.059,00 €").
  • ZUGFeRD: pdfUrl is the e-invoice (a PDF/A-3 file with the data embedded).
  • XRechnung: pdfUrl is the readable PDF, and eInvoice.xmlUrl is the XML file.
  • Async mode: the job result carries the same eInvoice field.
  • Test mode: with isPreview: true the e-invoice is valid but marked as a test (TEST- invoice number and a test note).
If the data cannot make a valid e-invoice, no document is created and nothing is delivered. The request fails with a message that starts with “E-invoice not created” and names each problem; in async mode the job ends with status failed and the same text in error:
If the e-invoice check itself is not reachable, the message is “The e-invoice check is not available right now. Nothing was sent; please try again in a few minutes.” Send the request again later.
Last modified on October 21, 2026