Constaia
Endpoints

GET /v1/document-types

Reference for GET /v1/document-types: the public catalogue of document types with fields, JSON Schema, validators and applicable checks, no API key needed.

Esta página ainda não está traduzida para o seu idioma. Mostramos a versão em inglês.

GET /v1/document-types returns the catalogue of document types Constaia recognises: the type you pass in expect, its fields, the extraction JSON Schema, the validators that run and the checks it supports. It is the source of truth for the catalogue: when a type is added, it shows up here.

It is public: it needs no key and spends no credits. It can be cached (the response carries Cache-Control: public, max-age=300).

Method and routeWhat it does
GET /v1/document-typesLists the types (the whole catalogue, 167 types, in one page by default), with optional filters.
GET /v1/document-types/{type}Detail of one type. 404 resource_missing if it does not exist.

For a human-readable view, see the document types page or the full catalogue.

Parameters

ParameterValuesDefaultDescription
languagees, en, pt, fresLanguage of label, description and slug. labels, descriptions and slugs always carry the four languages.
countryISO 3166-1 alpha-3 (ESP, USA, MEX…)—Types issued in that country. Includes the universal ones (countries: ["*"], such as passport or invoice) unless strict=true.
stricttrue, falsefalseWith country, leaves out the universal types.
categoryidentity, residence, driving, certificate, health, education, employment, tax, finance, address, legal, vehicle, civil, sports, other—Types in that category.
qtext (max. 100)—Accent- and case-insensitive search in each type's type, labels, descriptions and keywords. Every word must match.
limit1–500500Types per page. By default the whole catalogue fits.
starting_aftertype—Cursor: returns the types that come after this one.

GET /v1/document-types/{type} only takes language. An invalid value (for example country=US) returns 422 invalid_parameter.

# US types without the universal ones, in English
curl -s 'https://api.constaia.com/v1/document-types?country=USA&strict=true&language=en' \
  | jq '{total, types: [.data[].type]}'

# Text search
curl -s 'https://api.constaia.com/v1/document-types?q=driver%20license&language=en' | jq -r '.data[].type'

Response

List

{
  "object": "list",
  "data": [ { "object": "document_type", "type": "es_dni", "…": "…" } ],
  "has_more": false,
  "total": 167,
  "url": "/v1/document-types"
}

total is the number of types matching the filters (not just the ones on this page). To paginate, pass the type of the last item in starting_after while has_more is true. More in Pagination.

Detail

Real response of GET /v1/document-types/es_dni?language=en, with schema.properties trimmed to three fields:

curl -s 'https://api.constaia.com/v1/document-types/es_dni?language=en'
{
  "object": "document_type",
  "type": "es_dni",
  "label": "Spanish ID card (DNI)",
  "labels": {
    "es": "DNI (España)",
    "en": "Spanish ID card (DNI)",
    "pt": "Documento de identidade espanhol (DNI)",
    "fr": "Carte d'identité espagnole (DNI)"
  },
  "description": "Spanish national identity card, front and back.",
  "descriptions": { "es": "…", "en": "…", "pt": "…", "fr": "…" },
  "category": "identity",
  "countries": ["ESP"],
  "slug": "spanish-id-card-dni",
  "slugs": {
    "es": "dni-espana",
    "en": "spanish-id-card-dni",
    "pt": "documento-de-identidade-espanhol-dni",
    "fr": "carte-d-identite-espagnole-dni"
  },
  "fields": [
    "document_number", "first_name", "last_name_1", "last_name_2", "sex", "nationality",
    "birth_date", "expiry_date", "issue_date", "support_number", "address", "birth_place",
    "parents", "mrz"
  ],
  "schema": {
    "type": "object",
    "properties": {
      "document_number": { "type": "string", "description": "Número de DNI (8 cifras + letra)" },
      "sex": { "type": "string", "description": "Sexo (M/F)", "enum": ["M", "F", "X"] },
      "birth_date": { "type": "string", "description": "Fecha de nacimiento", "format": "date" }
    },
    "additionalProperties": false
  },
  "validators": ["nif_check_digit", "mrz_checksums", "mrz_matches_visual", "not_expired", "holder", "age"],
  "field_validators": [],
  "checks": ["not_expired", "reference_date", "min_age_years", "max_age_years", "holder", "require_fields"],
  "expiry_check_default": true,
  "mrz": "TD1",
  "signed_pdf": false,
  "i9_lists": null
}
FieldDescription
objectAlways "document_type".
typeIdentifier you use in expect and receive in document.type.
labelName in the language you asked for.
labelsName in es, en, pt and fr.
descriptionShort description in the language you asked for. descriptions carries it in the four languages.
slug, slugsIdentifier of the type's page in the catalogue, in the language you asked for and in all four.
categoryOne of the 15 categories of the category parameter.
countriesISO alpha-3 countries where it is issued. * means any country.
fieldsNames of the fields returned by extract: true, in order.
schemaJSON Schema of those fields: type, format (date), allowed values (enum) and description. The schema's description texts are in Spanish.
validatorsValidations Constaia applies to this type (for example aamva_barcode, id_number, pdf_signature, i9_list).
field_validatorsIdentifiers validated per field: { field, scheme }, with a scheme from @constaia/validators (us_dl, us_zip, br_cpf…).
checkschecks options that have an effect on this type. An option outside this list does not apply to this type.
expiry_check_defaulttrue if not_expired is checked by default (types with an expiry date).
mrzMRZ format read locally (TD1, TD2, TD3) or null.
signed_pdftrue if the document is downloaded signed from an official e-government site: it supports require_valid_signature. See Digital signatures in PDF.
i9_listsUS Form I-9 lists (A, B, C) it belongs to, or null. See US documents.

Common uses

Validate your configuration at startup

If your application stores which expect and checks each form uses, check them against the catalogue when you deploy: you will catch a misspelt type or a check that does not apply before an analysis fails.

Build forms or review screens

schema describes each field with type, format and possible values. You can generate a manual review form: an input type="date" for format: "date", a select for enum, and use description as help text.

Start from the schema for your own extract

If you only need some fields, copy the properties you want from schema and pass them in extract. fields will return only the fields of your schema. See Extracting fields with your own schema.

# US identity types (and the universal ones)
curl -s 'https://api.constaia.com/v1/document-types?country=USA&category=identity&language=en' \
  | jq -r '.data[] | "\(.type)\t\(.label)"'

The catalogue grows. Your code should not break if document.type carries a type it does not know: treat it as "other" and send it to review.

Next steps

Document types

How to use expect with several types and generic with your schema.

Full catalogue

Every type with its fields, validators and examples.

POST /v1/analyze

Use the type in expect and the checks it supports.

POST /v1/batches

Reference for POST /v1/batches: analyse up to 100 documents in one asynchronous call, with common or per-document options and a combined export.

Balance and usage

Reference for GET /v1/balance and GET /v1/usage: pack credits, free tier, reservations and daily usage by document type, with examples.

Nesta página

ParametersResponseListDetailCommon usesValidate your configuration at startupBuild forms or review screensStart from the schema for your own extractNext steps