US documents

The Constaia catalogue includes 31 United States-specific types (and 5 Canadian ones) on top of the universal ones, such as the ICAO passport. You use them like any other: pass them in expect and you get a verdict with its reasons, the extracted fields and each type's deterministic checks.

curl -s 'https://api.constaia.com/v1/document-types?country=USA&strict=true&language=en' \
  | jq -r '.data[] | "\(.type)\t\(.label)"'

Without strict=true the list also includes the universal types (passport, invoice…). Fields, validators and checks for each type: GET /v1/document-types or the full catalogue.

Which types there areCopy Anchor Link

Driver's licenses and state IDs: the PDF417 barcodeCopy Anchor Link

The back of a US driver's license or state ID (and of Canadian licences) carries a PDF417 barcode with the holder's data in the AAMVA standard. Constaia reads it on its own servers, without sending it to any AI provider and at no extra cost, and:

• fills in any missing fields from it (number, name, dates, address…);
• cross-checks it with the printed front: number, first name, last name, date of birth and expiry. The result is the aamva_matches_visual check; if something doesn't match, it fails, the affected fields get validated: false and the verdict becomes invalid;
• validates the license number format for the issuing state (issuing_state) and the ZIP code (id_number_format).

For it to be read, the file must include the back: one image with both sides or a two-page PDF (still 1 credit). The widget with sides="2" captures both sides and joins them. If only the front arrives, there is no aamva_matches_visual and everything else works the same.

curl https://api.constaia.com/v1/analyze \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F file=@driver_license_both_sides.jpg \
  -F 'options={"expect":["us_driver_license","us_state_id"],"checks":{"min_age_years":21},"language":"en"}'

{
  "document": { "type": "us_driver_license", "label": "US driver's license", "country": "USA" },
  "verdict": {
    "status": "valid",
    "reasons": [
      { "code": "type_match", "severity": "info", "message": "The document is US driver's license." },
      { "code": "not_expired", "severity": "info", "message": "Valid until 30/07/2031." },
      { "code": "age", "severity": "info", "message": "The holder is 41 years old." },
      { "code": "i9_list", "severity": "info", "message": "Acceptable Form I-9 document: List B." }
    ]
  },
  "checks": [
    { "code": "id_number_format", "passed": true, "message": "Identifier document_number (us_dl) is valid." },
    { "code": "id_number_format", "passed": true, "message": "Identifier postal_code (us_zip) is valid." },
    { "code": "aamva_matches_visual", "passed": true, "message": "The PDF417 barcode (AAMVA v10) was read and matches the printed data." }
  ]
}

The fields include issuing_state, document_number, first_name, middle_name, last_name, birth_date, issue_date, expiry_date, address, postal_code, real_id_compliant, class, restrictions, endorsements, commercial and barcode_data (the PDF417 text). Expiry is checked by default. Full guide: Verify a US driver's license.

Form I-9: Lists A, B and CCopy Anchor Link

Types that can be used for Form I-9 show their list in i9_lists (["A"], ["B"], ["C"] or ["B","C"]) in the catalogue, and when analysed with expect they add an informational reason:

{ "code": "i9_list", "severity": "info", "message": "Acceptable Form I-9 document: List A." }

Constaia tags the list; whether the combination is complete (one List A document, or one from List B plus one from List C) is up to your code, and the employer remains responsible for the form. There is no E-Verify integration. Full guide: Form I-9 documents.

US identifiersCopy Anchor Link

These identifiers are validated deterministically (no AI) on the types that carry them. Only the format or check digit is checked: Constaia never queries the SSA, the IRS or USCIS.

The result goes in checks[] as id_number_format or id_number_checksum. On some types the identifier is marked as soft (for example the SSN on a W-2 or a 1099, which is often masked): its failure gives a reason with warning and leads to review instead of invalid. Which schemes each type has is listed in field_validators in the catalogue.

TestingCopy Anchor Link

With a ck_test_ key there are no US scenarios: a US document returns the generic type and, with expect, a review verdict with type_unknown. To see the US types for real, use a live key: the month's 150 free credits are enough (free credits in live mode require a verified email). See Test mode.

Where data is processedCopy Anchor Link

Today every document, including those from US customers, is processed and stored in the EU, and processing.region is eu. Constaia does no biometrics and doesn't query public records (DMV, IRS, SSA, E-Verify). Notes on DPPA, CCPA, GLBA/FCRA and biometric laws in Data residency & compliance.

GuidesCopy Anchor Link