docs

The contract shape

When Emboss processes a form it produces a contract: the structured list of every field it detected. The contract is the source of truth for what's on the form — its labels, types, and positions — and you can inspect it directly.

Getting the contract

Once a form has finished detection, fetch its contract from GET /forms/{id}/contract:

curl https://api.getemboss.ai/forms/6c47f7f5-f921-4698-910f-95dd7d81310b/contract \
  -H "Authorization: Bearer sk_live_yourkey"
  • 200 — detection is complete; the body is the contract JSON.
  • 409 — the form isn't ready yet (contract not available (status: …)). Poll again shortly.
  • 404 — no such form, or it belongs to another owner.

What's in it

The contract has top-level schema_version, page_count, field_count, and a form object (its title), plus a fields array. Each field has an integer id, a machine name, the detected label, a widget type, the expected data_type, whether it's required, the page it's on, a rect (its position), and its current value.

{
  "schema_version": "1.0",
  "page_count": 1,
  "field_count": 16,
  "form": { "title": "Form W-9" },
  "fields": [
    {
      "id": 1,
      "name": "business_name",
      "label": "Business name",
      "type": "text",
      "data_type": "string",
      "required": true,
      "page": 0,
      "rect": { "x": 72, "y": 540, "width": 320, "height": 18 },
      "value": null
    },
    {
      "id": 7,
      "label": "Federal tax classification",
      "type": "checkbox",
      "data_type": "boolean",
      "required": false,
      "page": 0,
      "rect": { "x": 88, "y": 470, "width": 12, "height": 12 },
      "value": null
    }
  ]
}

Fields carry a few more keys too — description, instructions, format_hint, section, group, related_fields, option_label, office_use, and confidence — but the ones above are what you'll reach for most. Once a field is filled, its value is no longer null.

Why inspect it

  • Verify detection before you commit to a fill — confirm the fields and labels are what you expect.
  • Map your own data to each field's integer id — that same id is the field_id you pass to PUT /sessions/{sid}/fields for a precise, deterministic fill (see Sessions).
  • Audit which fields are checkboxes, signatures, or free text.

Because the contract spells out every detected field, you can inspect exactly what Emboss found before you fill — and confirm the fields are what you expect.