docs

Forms

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

NameInTypeRequiredDescription
filebodyfile (multipart)yesThe flat PDF to detect fields in.
Idempotency-KeyheaderstringnoOptional. Retrying a create with the same key returns the original job instead of creating a new one. Scoped to your account, valid 24 hours.
callback_urlbodystring (url)noOptional. A public https URL Emboss POSTs the result to when the job finishes (ready or failed), signed with X-Emboss-Signature. See the Callbacks guide. Private or non-https URLs are rejected with 400.

Status codes

  • 202Accepted; detection started.
  • 400Not a readable PDF.
  • 401Missing or invalid API key.
  • 402Over the free tier with no payment method on file.
  • 413Upload too large (max 10 MB) or too many pages (max 100).
  • 429Rate limit exceeded.
curl -X POST https://api.getemboss.ai/forms \
  -H "Authorization: Bearer sk_live_yourkey" \
  -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.

Parameters

NameInTypeRequiredDescription
idpathstringyesThe 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_live_yourkey"
Response
{
  "id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "ready",
  "title": "Form W-9",
  "schema_version": "1.0",
  "error": null
}