Forms

View as Markdown

Create a form by uploading a flat PDF. Emboss detects its fields asynchronously; check the form's status before fetching its contract or filling it.

Create a form

POST/formsBearer auth

Upload a flat PDF. Returns 202 with an id while field detection runs in the background.

Parameters

Name	In	Type	Required	Description
`file`	body	file (multipart)	no	The flat PDF. Send this or library: one of the two is required.
`Idempotency-Key`	header	string	no	Optional. Retrying with the same key answers 200 with the original job instead of starting a new one. Scoped to your account, valid 24 hours, and shared by every call on the account, so use a fresh key for each request. A request that is rejected (any 4xx) does not consume the key: fix the cause and retry with the same key.
`callback_url`	body	string (url)	no	Optional. A public https URL Emboss POSTs the result to when the job finishes (ready or failed), signed with X-Emboss-Signature using your account's callback signing secret (shown on the API Keys page of the dashboard). See the Callbacks guide. Private or non-https URLs are rejected with 400.
`retention`	body	string	no	Optional. ephemeral or account_default; default account_default. See the Ephemeral processing guide.
`library`	body	string	no	Optional. Create from a form already in the library instead of uploading a file: the slug of one of the entries at GET /library. Mutually exclusive with file; sending both is 400.

Status codes

202Accepted; detection started.
400Not a readable PDF; neither file nor library was sent: "field required: file"; both were sent: "send a file or a library slug, not both"; "invalid callback_url"; or a retention value other than ephemeral or account_default.
401Missing or invalid API key.
402No payment method on file and either the monthly free allowance is used up or the request is over the free tier's 5-page cap. The body's detail carries code (over_free_tier or over_page_cap), message and billing_url, the page where a payment method can be added.
404The library slug does not match any library form: "no library form named <slug>".
413Upload too large (max 10 MB) or too many pages (max 100).
422pdf_unsafe: the PDF's form fields are built in a way that could compromise the service, so it is refused before any price, charge or stored file. The body's detail carries code and message ("Emboss does not process PDF files that could compromise the service.").
429Rate limit exceeded.
503The library form's stored copy could not be read: "library copy unavailable"; retry.

curl -X POST https://api.getemboss.ai/forms \
  -H "Authorization: Bearer sk_..." \
  -F "file=@./w9.pdf"

Response

{
  "form_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "processing"
}

Get a form

GET/forms/{id}Bearer auth

Check a form's detection status. Poll until status is processing, ready, or failed. reused_layout is true when this form's field map came from a blank-form layout Emboss already knew, rather than a fresh detection run.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	The form id returned by POST /forms.

Status codes

200The form status (processing | ready | failed).
401Missing or invalid API key.
404No such form, or owned by another key.

curl https://api.getemboss.ai/forms/6c47f7f5-f921-4698-910f-95dd7d81310b \
  -H "Authorization: Bearer sk_..."

Response

{
  "id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "ready",
  "title": "Form W-9",
  "schema_version": "1.0",
  "reused_layout": false,
  "library": { "slug": "irs-w-9", "revision": "Rev. March 2024" },
  "error": null
}

List your forms

GET/formsBearer auth

List the forms this key owns, newest first. By default only forms whose detection finished (states=ready); pass states=all to include ones still processing or failed.

Parameters

Name	In	Type	Required	Description
`states`	query	string	no	ready (default) or all. With all, the listing pages, has_thumbnail and no_fields are populated, and total is the full count.
`limit`	query	integer	no	Page size, default 100, clamped to 1..200. Honoured with states=all; the default states=ready listing always returns up to 100 rows regardless of what you pass.
`offset`	query	integer	no	Rows to skip, default 0. Honoured with states=all; with states=ready the listing is a fixed 100-row page and total is the number of rows returned, not a full count.

Status codes

200The page of forms, with total, limit and offset.
401Missing or invalid API key.

curl "https://api.getemboss.ai/forms?states=all&limit=20" \
  -H "Authorization: Bearer sk_..."

Response

{
  "forms": [
    {
      "id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
      "title": "Form W-9",
      "status": "ready",
      "created_at": "2026-09-08T12:52:10Z",
      "has_thumbnail": true,
      "no_fields": false,
      "retention": {
        "policy": "account_default",
        "documents_deleted_after": null,
        "documents_deleted_at": null
      }
    }
  ],
  "total": 1,
  "limit": 100,
  "offset": 0
}

Delete a form

DELETE/forms/{id}Bearer auth

Delete a form you own. Its stored documents are removed first, under every retention policy, then the form itself. A form with a fill, a batch or a fill-from-documents job still running is not deleted.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	The form id returned by POST /forms.

Status codes

200Deleted.
401Missing or invalid API key.
404No such form, or owned by another key.
409A fill, a batch or a fill-from-documents job is still running on this form; try again when it finishes.

curl -X DELETE https://api.getemboss.ai/forms/6c47f7f5-f921-4698-910f-95dd7d81310b \
  -H "Authorization: Bearer sk_..."

Response

{ "ok": true }

Download the fillable PDF

GET/forms/{form_id}/fillableBearer auth

The blank fillable PDF: the detected fields turned into real form widgets, with no values entered. Ready forms only.

Parameters

Name	In	Type	Required	Description
`form_id`	path	string	yes	The form.

Status codes

200The PDF bytes (application/pdf).
401Missing or invalid API key.
404No such form, not yours, or not ready yet: "fillable PDF not available".
410The form's documents have been deleted under its retention policy.

curl https://api.getemboss.ai/forms/6c47f7f5-f921-4698-910f-95dd7d81310b/fillable \
  -H "Authorization: Bearer sk_..." -o fillable.pdf

Response

%PDF-1.7
…binary…

Download the thumbnail

GET/forms/{form_id}/thumbnailBearer auth

A small PNG of the form's first page, for a picker or a library view.

Parameters

Name	In	Type	Required	Description
`form_id`	path	string	yes	The form.

Status codes

200The PNG bytes (image/png).
401Missing or invalid API key.
404No such form, not yours, or no thumbnail was made: "thumbnail not available".
410The form's documents have been deleted under its retention policy.

curl https://api.getemboss.ai/forms/6c47f7f5-f921-4698-910f-95dd7d81310b/thumbnail \
  -H "Authorization: Bearer sk_..." -o thumbnail.png

Response

PNG image bytes (image/png)