Batch fill

View as Markdown

Map a spreadsheet's columns to form fields once, then fill one PDF per row. Each row goes through deterministic standard fill. Each filled row bills one standard fill.

Suggest a column mapping

POST/forms/{form_id}/suggest-mappingBearer auth

Upload a spreadsheet and let Emboss suggest which column maps to which form field. Bills one context fill on success.

Parameters

Name	In	Type	Required	Description
`form_id`	path	string	yes	An existing form whose status is ready.
`file`	body	file (multipart)	yes	The spreadsheet (CSV or XLSX) whose header row names the columns to map.

Status codes

200Mapping suggestion returned.
400Bad or unparseable spreadsheet.
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.
404No such form, or owned by another key.
409Form not ready. Detection has not finished.
413Spreadsheet too large, or the request exceeds the size cap.
429Rate limit exceeded.
502Mapping failed upstream.

curl -X POST https://api.getemboss.ai/forms/6c47f7f5-f921-4698-910f-95dd7d81310b/suggest-mapping \
  -H "Authorization: Bearer sk_..." \
  -F "file=@./records.csv"

Response

{
  "mapping": {
    "Phone": { "field_id": 0, "confidence": "high" },
    "Email": { "field_id": 1, "confidence": "high" }
  },
  "unmapped_columns": ["Notes"]
}

Start a batch fill

POST/forms/{form_id}/fill-batchBearer auth

Upload the spreadsheet and a resolved mapping to start a batch fill. Returns 202 with a batch id. Each filled row bills one standard fill.

Parameters

Name	In	Type	Required	Description
`form_id`	path	string	yes	The form to fill, with status ready.
`file`	body	file (multipart)	yes	The spreadsheet of records. One row produces one output PDF. Max 1000 rows.
`mapping`	body	string (JSON)	yes	Resolved column-to-field mapping. Each key is a spreadsheet column name and each value contains a field_id from the form's contract. Example: {"Phone":{"field_id":0},"Email":{"field_id":1}}.
`retention`	body	string	no	Optional. ephemeral or account_default; default account_default. See the Ephemeral processing guide.

Status codes

202Batch started.
400Bad spreadsheet, invalid mapping JSON, mapping references an unknown column or field, or too many rows (max 1000).
401Missing or invalid API key.
402No payment method on file, and the monthly free allowance is used up, the batch has more rows than the free fills left (the body then carries rows and remaining), or the form 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.
404No such form, or owned by another key.
409Form not ready or not yet fillable.
410The form's documents have been deleted under its retention policy.
413Spreadsheet too large, or the request exceeds the size cap.
429Rate limit exceeded.

curl -X POST https://api.getemboss.ai/forms/6c47f7f5-f921-4698-910f-95dd7d81310b/fill-batch \
  -H "Authorization: Bearer sk_..." \
  -F "file=@./records.csv" \
  -F 'mapping={"Phone":{"field_id":0},"Email":{"field_id":1}}'

Response

{
  "batch_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

Get batch status

GET/forms/fill-batch/{batch_id}Bearer auth

Return the batch manifest. status is one of processing, complete, or failed. Poll until it is complete or failed. Each result entry links to its row PDF.

Parameters

Name	In	Type	Required	Description
`batch_id`	path	string	yes	The batch id returned by POST fill-batch.

Status codes

200Batch status returned.
401Missing or invalid API key.
404No such batch, or owned by another key.

curl https://api.getemboss.ai/forms/fill-batch/a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer sk_..."

Response

{
  "status": "complete",
  "total": 2,
  "filled": 2,
  "failed": 0,
  "results": [
    { "row": 1, "status": "filled", "pdf_url": "/forms/fill-batch/a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/rows/1/pdf" },
    { "row": 2, "status": "filled", "pdf_url": "/forms/fill-batch/a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/rows/2/pdf" }
  ],
  "error": null
}

Download a row PDF

GET/forms/fill-batch/{batch_id}/rows/{n}/pdfBearer auth

Download one filled row's PDF. n is the 1-based row index from the batch manifest.

Parameters

Name	In	Type	Required	Description
`batch_id`	path	string	yes	The batch id returned by POST fill-batch.
`n`	path	integer	yes	The 1-based row number from the batch results manifest.

Status codes

200PDF returned.
401Missing or invalid API key.
404No such batch, or that row was not filled.
410The form's documents have been deleted under its retention policy.

curl https://api.getemboss.ai/forms/fill-batch/a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/rows/1/pdf \
  -H "Authorization: Bearer sk_..." \
  -o row-1.pdf

Response

Binary PDF (Content-Type: application/pdf).

Download all rows as ZIP

GET/forms/fill-batch/{batch_id}/zipBearer auth

Download a ZIP of every filled row PDF. Only filled rows are included. The archive is named batch-{id}.zip.

Parameters

Name	In	Type	Required	Description
`batch_id`	path	string	yes	The batch id returned by POST fill-batch.

Status codes

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

curl https://api.getemboss.ai/forms/fill-batch/a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/zip \
  -H "Authorization: Bearer sk_..." \
  -o batch.zip

Response

Binary ZIP (Content-Type: application/zip) containing one row-N.pdf per filled row.