Documents in. Traceable JSON out.

Create a job

POST https://formatara.com/api/v1/documents
Authorization: Bearer ptk_••••
Content-Type: multipart/form-data

file=@contrato.pdf

→ 202 Accepted
{
  "document": {
    "id": "018f...",
    "status": "queued",
    "pageCount": 4
  }
}

Password-protected PDF

If the upload returns status: "password_required", send the password in the body of this second request. It is only used to prepare an unlocked working copy: it is not stored or added to the queue. OCR does not start until the password is correct.

→ 202 Accepted
{
  "document": {
    "id": "018f...",
    "status": "password_required"
  }
}

POST https://formatara.com/api/v1/documents/{id}/password
Authorization: Bearer ptk_••••
Content-Type: application/json

{ "password": "••••••••" }

→ 202 Accepted
{ "document": { "id": "018f...", "status": "queued" } }

Retrieve the result

GET https://formatara.com/api/v1/documents/{id}

{
  "document": {
    "status": "completed",
    "result": {
      "pages": [{
        "number": 1,
        "blocks": [{
          "type": "table",
          "bbox": [84, 322, 918, 704],
          "confidence": null,
          "table": { "rows": [["Concepto", "Total"]] }
        }]
      }]
    }
  }
}

Export and correct

• POST /api/v1/documents/{id}/exports with {"mode":"editable"}. Keep the export.id returned in the response.
• Poll GET /api/v1/documents/{id}/exports/{exportId} until it returns status: "completed" and a downloadUrl. If it remains queued, repeat the same POST: the operation is idempotent and does not create another export.
• The available Word export is editable: it reconstructs text, fields, tables and forms according to their position on the page, including tables with incomplete borders. Recognized photographs, logos and stamps are preserved as images.
• GET /api/v1/documents/{id}/export?format=json|markdown|csv
• PATCH /api/v1/documents/{id} with text or cell corrections.

Input limits

• Multi-page documents are supported; each page uses one balance unit, and the processor keeps a technical ceiling of 500 pages and 200 MB per job.
• PDF, PNG, JPG, WEBP and TIFF. Protected PDFs require the password step above.
• The initial pageCount may be an estimate; the actual count is reconciled when processing finishes.

Design decisions

• OCR is asynchronous because a document can take several minutes to process. Word exports use an idempotent job resource to prevent duplicates.
• Quota is reserved when the document is accepted, reconciled against the actual page count and returned if processing fails.
• Confidence remains null when no sufficiently reliable score is available.
• bbox may be null when no valid coordinates are available.
• Exports do not consume additional credits.
• Tokens are shown only once; Formatara stores only their SHA-256 hash.