Fill with context

Fill a form from supporting context documents. By default, fill a form you've already created (POST /forms/{form_id}/with-context); or upload a brand-new flat PDF to extract and fill it in one call (POST /forms/with-context). Both run asynchronously — poll the job, then download the resulting session's PDF.

Fill an existing form with context

POST/forms/{form_id}/with-contextBearer auth

Fill a form you've already created, from one or more context files. Returns 202 with a job id; bills one context fill.

Parameters

Name	In	Type	Required	Description
`form_id`	path	string	yes	The id of a form you've already created (status ready).
`context`	body	file (multipart, repeatable)	no	Supporting document(s) to infer values from.
`Idempotency-Key`	header	string	no	Optional. Retrying a create with the same key returns the original job instead of creating a new one. Scoped to your account, valid 24 hours.
`callback_url`	body	string (url)	no	Optional. A public https URL Emboss POSTs the result to when the job finishes (ready or failed), signed with X-Emboss-Signature. See the Callbacks guide. Private or non-https URLs are rejected with 400.

Status codes

202Accepted; fill job started.
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.
413Too many context files (max 5), file too large (max 10 MB), or request over 30 MB.
429Rate limit exceeded.

curl -X POST https://api.getemboss.ai/forms/6c47f7f5-f921-4698-910f-95dd7d81310b/with-context \
  -H "Authorization: Bearer sk_live_yourkey" \
  -F "context=@./profile.pdf"

Response

{
  "job_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "processing"
}

Fill with context

POST/forms/with-contextBearer auth

Submit a PDF plus one or more context files. Returns 202 with a job id; detection and fill run in the background.

Parameters

Name	In	Type	Required	Description
`file`	body	file (multipart)	yes	The flat PDF to fill.
`context`	body	file (multipart, repeatable)	no	Supporting document(s) Emboss reads to infer field values. Repeat for multiple files.
`Idempotency-Key`	header	string	no	Optional. Retrying a create with the same key returns the original job instead of creating a new one. Scoped to your account, valid 24 hours.
`callback_url`	body	string (url)	no	Optional. A public https URL Emboss POSTs the result to when the job finishes (ready or failed), signed with X-Emboss-Signature. See the Callbacks guide. Private or non-https URLs are rejected with 400.

Status codes

202Accepted; fill job started.
400Missing file or unreadable PDF.
401Missing or invalid API key.
402Over the free tier with no payment method on file.
413Too many context files (max 5), file too large (max 10 MB), or request over 30 MB.
429Rate limit exceeded.

curl -X POST https://api.getemboss.ai/forms/with-context \
  -H "Authorization: Bearer sk_live_yourkey" \
  -F "file=@./w9.pdf" \
  -F "context=@./profile.pdf"

Response

{
  "job_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "processing"
}

Get the fill job

GET/forms/with-context/{job_id}Bearer auth

Poll the fill job. When complete, returns the session_id; on failure, error is an object { code, message } — a stable code plus a human-readable message. Codes: context_too_large, unsupported_context_file, context_fill_failed, apply_rejected, form_processing_failed, job_failed (fallback).

Parameters

Name	In	Type	Required	Description
`job_id`	path	string	yes	The job_id returned by POST /forms/with-context.

Status codes

200The job state (processing | ready | failed).
401Missing or invalid API key.
404No such job, or owned by another key.

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

Response

{
  "job_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "ready",
  "session_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "error": null
}

// On failure, status is "failed" and error is { code, message }:
{
  "job_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "failed",
  "session_id": null,
  "error": { "code": "context_too_large", "message": "context too large: 5000 > 4000 tokens" }
}