Standard fill

View as Markdown

Standard fill writes values you supply straight onto a form. Open a session over a detected form, set field values with direct fill, then render and download the finished PDF. Every action is deterministic.

Create a session

POST/sessionsBearer auth

Open a session over a previously created form. Returns 201 with the session_id.

Parameters

Name	In	Type	Required	Description
`form_id`	body	string	yes	The form to open a session over.

Status codes

201Session created.
400form_id is not a UUID: "form_id must be a UUID".
401Missing or invalid API key.
404No such form, or owned by another key.
409Form not ready.
410The form's documents have been deleted under its retention policy.
422form_id is missing from the body.

curl -X POST https://api.getemboss.ai/sessions \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"form_id":"6c47f7f5-f921-4698-910f-95dd7d81310b"}'

Response

{
  "session_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "next_prompt": null,
  "missing": [1],
  "pending_confirmation": [],
  "form_state": {
    "fields": {
      "1": { "candidates": [], "confidence": null, "evidence": [], "history": [], "invalid_reason": null, "note": null, "origin": null, "reoffered": false, "source": null, "status": "unfilled", "value": null }
    },
    "turn_count": 0
  }
}

Get session state

GET/sessions/{id}Bearer auth

Read a session's status (active, then completed once filled) and the values set on it so far, in form_state.fields keyed by field id. Once the session is filled it also carries artifact_id and artifacts (the filled file's number, role filled); before that artifact_id is null and artifacts is empty.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	The session_id.

Status codes

200The session state.
401Missing or invalid API key.
404No such session, or owned by another key.
410The form's documents have been deleted under its retention policy.

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

Response

{
  "session_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "active",
  "form_state": {
    "fields": {
      "1": { "candidates": [], "confidence": "high", "evidence": [], "history": [{ "status": "filled", "turn": 1, "value": "Analytical Engines LLC" }, { "status": "confirmed", "turn": 1, "value": "Analytical Engines LLC" }], "invalid_reason": null, "note": null, "origin": "caller", "reoffered": false, "source": "direct", "status": "confirmed", "value": "Analytical Engines LLC" }
    },
    "turn_count": 1
  },
  "artifact_id": null,
  "artifacts": []
}

Direct field fill

PUT/sessions/{id}/fieldsBearer auth

Set field values directly by id. A structured, deterministic fill.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	The session_id.
`updates`	body	array<{field_id:integer, value:string}>	yes	Field updates: each maps a contract field id to its value.

Status codes

200Fields set.
401Missing or invalid API key.
404No such session, or owned by another key.
409Session is completed (terminal).
410The form's documents have been deleted under its retention policy.
422Field validation failed (unknown id or invalid value).

curl -X PUT https://api.getemboss.ai/sessions/6c47f7f5-f921-4698-910f-95dd7d81310b/fields \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"updates":[{"field_id":1,"value":"Analytical Engines LLC"}]}'

Response

{
  "session_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "applied": [1]
}

Render the filled PDF

POST/sessions/{id}/fillBearer auth

Render the session's confirmed values into a filled PDF and mark it completed. The answer carries the filled file's artifact_id, also listed under artifacts with role filled, so it can be passed to the free PDF tools or the fax.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	The session_id.

Status codes

200Filled; session is now completed.
401Missing or invalid API key.
402No payment method on file and the monthly free standard fills are used up, or the form is over the free tier's 5-page cap. The body's detail carries code, message and billing_url.
404No such session, or owned by another key.
409Session already completed, or the form has no fillable PDF.
410The form's documents have been deleted under its retention policy.
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.").

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

Response

{
  "session_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "completed",
  "artifact_id": "99999999-aaaa-bbbb-cccc-dddddddddddd",
  "artifacts": [{ "artifact_id": "99999999-aaaa-bbbb-cccc-dddddddddddd", "role": "filled", "mime_type": "application/pdf" }]
}

Download the PDF

GET/sessions/{id}/pdfBearer auth

Download the filled PDF. The response body is the raw %PDF bytes. A session started with POST /sessions must be filled with POST /sessions/{id}/fill first; a session made by a fill from documents downloads straight away.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	The session_id.

Status codes

200The PDF bytes (application/pdf).
401Missing or invalid API key.
404No such session, or owned by another key.
409Session has not been filled yet: the body's code is not_filled. Fill it with POST /sessions/{id}/fill, the billed step, then download.
410The form's documents have been deleted under its retention policy.

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

Response

%PDF-1.7
…binary…