Standard fill

Standard fill writes values you supply straight onto a form. Open a session over a detected form, set field values through direct-fill or per-field actions (confirm, skip, decline), 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.
400Missing or invalid form_id.
401Missing or invalid API key.
404No such form, or owned by another key.
409Form not ready.

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

Response

{
  "session_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "next_prompt": "What is the business name?",
  "status": "open"
}

Get session state

GET/sessions/{id}Bearer auth

Read the current state of a session and its fields.

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.

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

Response

{
  "session_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "open",
  "fields": [
    { "id": 1, "label": "Business name", "value": "Analytical Engines LLC", "state": "confirmed" }
  ]
}

Confirm a field

POST/sessions/{id}/confirmBearer auth

Confirm proposed field values. Deterministic.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	The session_id.
`field_ids`	body	array<integer>	yes	The field ids to confirm.

Status codes

200Fields confirmed.
401Missing or invalid API key.
404No such session/field, or owned by another key.
409Session is completed (terminal).

curl -X POST https://api.getemboss.ai/sessions/6c47f7f5-f921-4698-910f-95dd7d81310b/confirm \
  -H "Authorization: Bearer sk_live_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"field_ids":[1,7]}'

Response

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

Skip a field

POST/sessions/{id}/skipBearer auth

Mark fields as skipped. Deterministic.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	The session_id.
`field_ids`	body	array<integer>	yes	The field ids to skip.

Status codes

200Fields skipped.
401Missing or invalid API key.
404No such session/field, or owned by another key.
409Session is completed (terminal).

curl -X POST https://api.getemboss.ai/sessions/6c47f7f5-f921-4698-910f-95dd7d81310b/skip \
  -H "Authorization: Bearer sk_live_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"field_ids":[1,7]}'

Response

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

Decline a field

POST/sessions/{id}/declineBearer auth

Decline proposed values, clearing them. Deterministic.

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	The session_id.
`field_ids`	body	array<integer>	yes	The field ids to decline.

Status codes

200Fields declined.
401Missing or invalid API key.
404No such session/field, or owned by another key.
409Session is completed (terminal).

curl -X POST https://api.getemboss.ai/sessions/6c47f7f5-f921-4698-910f-95dd7d81310b/decline \
  -H "Authorization: Bearer sk_live_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"field_ids":[1,7]}'

Response

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

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).
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_live_yourkey" \
  -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.

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.
404No such session, or owned by another key.
409Session already completed, or the form has no fillable PDF.

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

Response

{
  "session_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "completed"
}

Download the PDF

GET/sessions/{id}/pdfBearer auth

Download the rendered PDF. The response body is the raw %PDF bytes.

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.

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

Response

%PDF-1.7
…binary…