Live and test keys

Live keys start with al3_live_. Test keys start with al3_test_, behave exactly like live keys, and are never billed. The full key is shown once, when it is created. We store only a salted hash and a short visible prefix, so keep the key in your secret store.

Scopes

Each key carries one or more scopes. A request outside the key's scopes returns 403.

• parse: POST /v1/parse and POST /v1/validate
• usage:read: GET /v1/usage

Rotation, expiry and revocation

Keys can carry an expiry date and can be revoked at any time. When you rotate a key, the old and new keys both work for 24 hours, so you can roll the new key out with zero downtime.

POST/v1/parse

Converts an AL3 file into normalized JSON. Each policy transaction in the file becomes one object in transactions; meta reports versions, warnings and how much of the file was mapped. Files are parsed in memory and not stored.

{
  "transactions": [
    {
      "transaction": {
        "type": "PCH",
        "effectiveDate": "2026-11-01",
        "processingDate": "2026-10-28",
        "lineOfBusiness": "AUTOB",
        "carrier": { "name": "Example Mutual", "naic": "12345" },
        "agencyCodes": ["A0010001"]
      },
      "insured": {
        "names": ["Ridgeline Freight LLC"],
        "mailingAddress": { "line1": "400 Depot St", "city": "Dayton", "state": "OH", "zip": "45402" }
      },
      "policy": {
        "number": "CA2049117",
        "priorNumber": "CA1938841",
        "effectiveDate": "2026-11-01",
        "expirationDate": "2027-11-01",
        "termPremium": 18420.00,
        "billingType": "AGENCY"
      },
      "vehicles": [
        { "vin": "1FUJHHDR8KLKK1234", "year": 2019, "make": "FRHT", "model": "CASCADIA" }
      ],
      "drivers": [ { "name": "J. Alvarez", "licenseState": "OH" } ],
      "coverages": [
        { "code": "BI", "limit": 1000000, "premium": 9210.00, "level": "policy" }
      ],
      "additionalInterests": [],
      "forms": [ { "number": "CA0001", "edition": "1013" } ]
    }
  ],
  "meta": {
    "parserVersion": "1.4.0",
    "layoutVersions": { "5BPI": "3", "5BIS": "2" },
    "unmappedGroups": [],
    "warnings": [],
    "fieldCoverage": 0.97
  }
}

Warnings. Nothing in the file is dropped or guessed. Anything the parser cannot map, such as an unknown group or code or a date that does not parse, is returned raw and described in meta.warnings with its location:

{
  "code": "unknown_group",
  "groupCode": "9XAB",
  "offset": 1824,
  "message": "Group 9XAB has no layout. Returned raw."
}

POST/v1/validate

Takes the same input as /v1/parse and runs the structural checks only: messages, transactions, group lengths and codes. Use it to check files on arrival before parsing. Validation calls do not count toward your monthly transactions.

{
  "messages": 1,
  "transactions": 3,
  "groups": 42,
  "warnings": [
    { "code": "length_mismatch", "groupCode": "6CVA", "offset": 2210,
      "message": "Declared length 064, found 061." }
  ]
}

GET/v1/schema

Returns the JSON Schema of the parse output. Generate types from it or validate responses in your own pipeline. The schema covers transaction, insured, policy, vehicles[], drivers[], coverages[], additionalInterests[], forms[], raw and meta.

GET/v1/usage

Usage for your account over a date range, broken down by agency. Requires the usage:read scope.

{
  "from": "2026-10-01",
  "to": "2026-10-31",
  "totals": { "requests": 1284, "transactions": 3912, "bytesIn": 18734221 },
  "agencies": [
    { "agencyId": "7d1e…c42a", "name": "Harbor Insurance Group",
      "requests": 611, "transactions": 2040 },
    { "agencyId": "a93b…0f17", "name": "Summit Risk Partners",
      "requests": 673, "transactions": 1872 }
  ]
}

GET/v1/openapi.json

The OpenAPI 3.1 spec for every endpoint, generated from the same schemas that validate requests. Import it into Postman, Insomnia or your client generator.

GET/v1/health

Liveness and database connectivity. No authentication. Use it for uptime monitoring.

Request IDs

Every response carries an X-Request-Id header, and every error body repeats it. Send your own ID in X-Request-Id (8 to 128 characters of letters, digits, ., _ or -) and we use it, so a request can be traced end to end across your systems and ours.

Data handling

Files and parsed output are processed in memory and not stored. Logs and usage records hold IDs, sizes, counts and timings, never file content or policyholder data. Encrypted file retention for debugging is available per account, with automatic deletion after 30 days.