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 pixel 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/form_3d9a/contract \
  -H "Authorization: Bearer sk_live_yourkey"

• 200 — detection is complete; the body is the contract JSON.
• 409 — the form exists but detection isn't ready yet. Poll again shortly.
• 404 — no such form, or it belongs to another owner.

What's in it

The contract is an object with a fields array. Each field has a stable id, the detected label, a widget type, the expected data_type, and a rect giving its position on the page.

{
  "form_id": "form_3d9a",
  "fields": [
    {
      "id": "f_001",
      "label": "Business name",
      "type": "text",
      "data_type": "string",
      "rect": { "page": 0, "x": 72, "y": 540, "w": 320, "h": 18 }
    },
    {
      "id": "f_007",
      "label": "Federal tax classification",
      "type": "checkbox",
      "data_type": "boolean",
      "rect": { "page": 0, "x": 88, "y": 470, "w": 12, "h": 12 }
    },
    {
      "id": "f_014",
      "label": "Signature",
      "type": "signature",
      "data_type": "signature",
      "rect": { "page": 0, "x": 72, "y": 120, "w": 240, "h": 28 }
    }
  ]
}

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 field ids for a precise, deterministic fill via PUT /sessions/{id}/fields (see Sessions).
• Audit which fields are checkboxes, signatures, or free text.

The contract endpoint exists so the detected structure is never a black box — you can always see exactly what Emboss is going to fill.