Batch fill

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.
402Over the free tier with no payment method on file.
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_live_yourkey" \
  -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}}.

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.
402Over the free tier with no payment method on file.
404No such form, or owned by another key.
409Form not ready or not yet fillable.
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_live_yourkey" \
  -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_live_yourkey"

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.

curl https://api.getemboss.ai/forms/fill-batch/a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/rows/1/pdf \
  -H "Authorization: Bearer sk_live_yourkey" \
  -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.

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

Response

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