# Standard fill

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 /sessions
```

Authentication: Bearer API key required.

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. |

```curl
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"}'
```

```js
const res = await fetch("https://api.getemboss.ai/sessions", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ form_id: "6c47f7f5-f921-4698-910f-95dd7d81310b" }),
});
const session = await res.json();
```

```python
import requests

res = requests.post(
    "https://api.getemboss.ai/sessions",
    headers={"Authorization": "Bearer sk_..."},
    json={"form_id": "6c47f7f5-f921-4698-910f-95dd7d81310b"},
)
session = res.json()
```

### Response

```json
{
  "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
  }
}
```

### Status codes

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

## Get session state

```
GET /sessions/{id}
```

Authentication: Bearer API key required.

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. |

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

```js
const res = await fetch("https://api.getemboss.ai/sessions/6c47f7f5-f921-4698-910f-95dd7d81310b", {
  headers: { Authorization: "Bearer sk_..." },
});
const session = await res.json();
```

```python
import requests

res = requests.get(
    "https://api.getemboss.ai/sessions/6c47f7f5-f921-4698-910f-95dd7d81310b",
    headers={"Authorization": "Bearer sk_..."},
)
session = res.json()
```

### Response

```json
{
  "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": []
}
```

### Status codes

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

## Direct field fill

```
PUT /sessions/{id}/fields
```

Authentication: Bearer API key required.

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. |

```curl
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"}]}'
```

```js
const res = await fetch("https://api.getemboss.ai/sessions/6c47f7f5-f921-4698-910f-95dd7d81310b/fields", {
  method: "PUT",
  headers: {
    Authorization: "Bearer sk_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    updates: [{ field_id: 1, value: "Analytical Engines LLC" }],
  }),
});
const result = await res.json();
```

```python
import requests

res = requests.put(
    "https://api.getemboss.ai/sessions/6c47f7f5-f921-4698-910f-95dd7d81310b/fields",
    headers={"Authorization": "Bearer sk_..."},
    json={"updates": [{"field_id": 1, "value": "Analytical Engines LLC"}]},
)
result = res.json()
```

### Response

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

### Status codes

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

## Render the filled PDF

```
POST /sessions/{id}/fill
```

Authentication: Bearer API key required.

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. |

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

```js
const res = await fetch("https://api.getemboss.ai/sessions/6c47f7f5-f921-4698-910f-95dd7d81310b/fill", {
  method: "POST",
  headers: { Authorization: "Bearer sk_..." },
});
```

```python
import requests

res = requests.post(
    "https://api.getemboss.ai/sessions/6c47f7f5-f921-4698-910f-95dd7d81310b/fill",
    headers={"Authorization": "Bearer sk_..."},
)
```

### Response

```json
{
  "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" }]
}
```

### Status codes

| Code | Meaning |
| --- | --- |
| 200 | Filled; session is now completed. |
| 401 | Missing or invalid API key. |
| 402 | No 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. |
| 404 | No such session, or owned by another key. |
| 409 | Session already completed, or the form has no fillable PDF. |
| 410 | The form's documents have been deleted under its retention policy. |
| 422 | pdf_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."). |

## Download the PDF

```
GET /sessions/{id}/pdf
```

Authentication: Bearer API key required.

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. |

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

```js
const res = await fetch("https://api.getemboss.ai/sessions/6c47f7f5-f921-4698-910f-95dd7d81310b/pdf", {
  headers: { Authorization: "Bearer sk_..." },
});
const pdf = await res.arrayBuffer(); // the raw %PDF bytes
```

```python
import requests

res = requests.get(
    "https://api.getemboss.ai/sessions/6c47f7f5-f921-4698-910f-95dd7d81310b/pdf",
    headers={"Authorization": "Bearer sk_..."},
)
open("filled.pdf", "wb").write(res.content)
```

### Response

```json
%PDF-1.7
…binary…
```

### Status codes

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

## See also

- [Authentication](https://getemboss.ai/docs/authentication)
- [Fill PDFs from your own data](https://getemboss.ai/use-cases/fill-pdfs-from-your-data)