Templates

A template (tpl_…) is a saved verification setup: which documents you accept (expect), what you check (checks), what gets stored and for how long, and when a person has to look at the result. You create it once and use it by id with template in any flow, instead of repeating the same options on every call. Step-by-step guide with examples in four languages: Reuse settings with templates.

Every route uses a secret key (ck_test_… or ck_live_…) from your backend. Templates belong to the account, not to a mode: the same template works with test and live keys. You can also manage them in the dashboard, under Templates.

The template objectCopy Anchor Link

{
  "id": "tpl_01J9Z8Q3K4M5N6P7Q8R9S0T1V2",
  "object": "template",
  "name": "Valid Spanish ID, adult holder",
  "description": "A Spanish ID card that has not expired, held by someone aged 18 or over.",
  "expect": "es_dni",
  "checks": { "not_expired": true, "min_age_years": 18 },
  "extract": true,
  "storage": "review",
  "ttl_hours": null,
  "keep_results": true,
  "export": [],
  "processing": null,
  "language": null,
  "redact": false,
  "mask_fields": ["document_number"],
  "verdict_without_expect": true,
  "retention_days": 90,
  "review_retention_hours_after_decision": 0,
  "review_max_days": 7,
  "review": { "auto_approve_valid": true, "require_human_for": ["review", "invalid"] },
  "example": false,
  "created_at": "2026-09-30T09:12:44Z",
  "updated_at": "2026-09-30T09:12:44Z"
}

Analysis optionsCopy Anchor Link

They mean the same and are validated the same way as in POST /v1/analyze. A null value in the response means the template doesn't set it: the request's value is used or, if the request doesn't send it either, the account's.

When you create or change a template, precise_bboxes is accepted too (as in analyze), although it isn't returned in the object.

Retention and review deadlinesCopy Anchor Link

The deadlines are resolved when each analysis is created and stored with it: changing the template later doesn't alter analyses already made.

Human review policy (review)Copy Anchor Link

An analysis made with the template is left pending (review.status: "pending", verdict.final_status: null) if its verdict is in require_human_for, or if it is valid and auto_approve_valid is false. Without a template, only review ones. The queue is handled in the dashboard or through the API: see Reviews.

Other fieldsCopy Anchor Link

Using a templateCopy Anchor Link

Pass the template id with template. The template is applied first and the request's options on top, and they win; checks is merged key by key (you can add holder on each request and keep the template's other checks).

curl https://api.constaia.com/v1/analyze \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F "file=@dni.jpg" \
  -F 'options={"template":"tpl_01J9Z8Q3K4M5N6P7Q8R9S0T1V2","checks":{"holder":{"full_name":"María García López"}},"metadata":{"user_id":"123"}}'

The analysis returns the template used in template_id (and in its alias template). If the template doesn't exist in the account (or was deleted): 422 template_not_found, with param: "options.template" in analyze, classify, batches and sessions, and param: "template" in links and dossiers.

Create a templateCopy Anchor Link

POST /v1/templates
Content-Type: application/json

Only name is required. The other fields are the object's (without id, object, example or dates). Fields are strict: an unknown one returns 422 invalid_parameter with its param.

curl https://api.constaia.com/v1/templates \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Valid ID, adult holder",
    "expect": ["es_dni", "es_nie"],
    "checks": { "not_expired": true, "min_age_years": 18 },
    "storage": "review",
    "review_max_days": 7,
    "mask_fields": ["document_number"],
    "review": { "require_human_for": ["review", "invalid"] }
  }'

Answers 201 with the template object. If expect or a check is not valid, 422 invalid_parameter with the exact param (expect, checks.min_age_years, review.require_human_for…).

List templatesCopy Anchor Link

GET /v1/templates?limit=20

Returns { "object": "list", "data": [...], "has_more": false, "url": "/v1/templates" }, newest first. See Pagination.

Retrieve, change and deleteCopy Anchor Link

curl https://api.constaia.com/v1/templates/tpl_01J9Z8Q3K4M5N6P7Q8R9S0T1V2 \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

curl -X PATCH https://api.constaia.com/v1/templates/tpl_01J9Z8Q3K4M5N6P7Q8R9S0T1V2 \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "checks": { "not_expired": true, "min_age_years": 16 }, "ttl_hours": null }'

curl -X DELETE https://api.constaia.com/v1/templates/tpl_01J9Z8Q3K4M5N6P7Q8R9S0T1V2 \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

• PATCH is partial: it only changes the fields you send. An analysis field set to null is removed from the template (the request or the account decide again). checks is replaced as a whole, not merged.
• review is replaced as a whole: whatever you leave out of review goes back to its default.
• Changes only affect analyses created afterwards.
• DELETE returns { "id": "tpl_…", "object": "template", "deleted": true }. Analyses, links and dossiers already created with it don't change; new requests that use it get 422 template_not_found.

A template that doesn't exist in the account returns 404 resource_missing.

Example templatesCopy Anchor Link

Every account starts with five templates (example: true), named in the account's language: valid Spanish ID with an adult holder, sports medical certificate under 6 months, sexual offences certificate with no records, bank transfer receipt and invoice (with an XLSX export). They are created when the account signs up or, for older accounts, on the first read of the list. You can use them as they are, change them or delete them.

SDKsCopy Anchor Link

import { Constaia } from "@constaia/sdk";

const constaia = new Constaia();

const tpl = await constaia.templates.create({
  name: "Valid ID, adult holder",
  expect: ["es_dni", "es_nie"],
  checks: { notExpired: true, minAgeYears: 18 },
  review: { requireHumanFor: ["review", "invalid"] },
  reviewMaxDays: 7,
});

for await (const t of constaia.templates.list()) console.log(t.id, t.name);
await constaia.templates.update(tpl.id, { maskFields: ["document_number"] });
await constaia.templates.delete(tpl.id);

ErrorsCopy Anchor Link

Next stepsCopy Anchor Link