AXIUMS API — Pending Requirements

Version 1 · Base URL https://api.axiums.ai/v1

The AXIUMS API gives an agency programmatic access to the pending requirements AXIUMS collects from carrier portals on behalf of its agents. Requirements are returned as the carrier stated them, with sync freshness attached so you always know how current the data is.

Requesting access

API access is granted per agency and approved by AXIUMS.

1. Submit a request at axiums.ai/api — agency name, primary contact, technical contact, and a short description of the integration.
2. AXIUMS reviews the request. You'll be notified by email at the address on the request.
3. On approval you receive a live API key. Keys are shown once at creation and cannot be retrieved afterward — store it in your secrets manager immediately.

An agency may hold up to two active keys at a time, so a key can be rotated without downtime.

What your key can reach

A key is scoped to your agency. It returns requirements only for agents who belong to your agency in AXIUMS. A request for an NPN outside your agency returns the same response as an NPN that doesn't exist — the API does not reveal whether an NPN it won't serve is real.

Agents can see that their agency holds API access to their requirements on their own AXIUMS dashboard. Nothing is shared invisibly.

Authentication

Pass your key as a bearer token on every request.

Authorization: Bearer axm_live_7f3c9a12e8b4d6f0a5c1

All requests must use HTTPS. Use api.axiums.ai — it serves the API directly. Calling axiums.ai/api/v1 redirects to another host, and most HTTP clients drop the Authorization header across a redirect, which produces a confusing 401.

A missing, malformed, revoked or expired key returns 401 with code unauthorized. Revocation takes effect immediately.

Carrier coverage

Requirements are only available for carriers AXIUMS has built extraction for.

Every carrier appears in every response, including unavailable ones. A carrier with no coverage is reported as unavailable rather than omitted or returned as empty — absence of coverage is stated, never hidden.

Coverage expands over time. Branch on the coverage value rather than hardcoding which carriers return requirements.

Data freshness

AXIUMS reads carrier portals on a daily schedule. Every carrier block carries sync metadata:

• lastSyncedAt — when AXIUMS last successfully read that carrier for that agent, or null
• syncStatus — one of five values:

Branch on syncStatus, never on array length. This is the single most likely way to misread this API. A healthy carrier with genuinely nothing outstanding returns ok with an empty requirements array. A carrier we could not read also returns an empty array — but with failing. Those two look identical if you only count rows, and they mean opposite things. Treat failing and stale as "do not act on this without confirming at the carrier."

Field provenance

Every carrier block includes a fieldProvenance map marking where each field's value came from:

• carrier_verbatim — the value exactly as the carrier reported it. Not reworded, reformatted, summarized or interpreted.
• axiums_derived — derived or added by AXIUMS.

Field names are AXIUMS-normalized so carriers can be consumed uniformly, but any value marked carrier_verbatim is the carrier's own.

Carriers return different fields, so the shape of a requirement object varies by carrier. Read fieldProvenance to see what that carrier's block contains.

Get requirements for one agent

GET /v1/requirements?npn={npn}

status=open excludes requirements the carrier has marked resolved — cancelled, completed, received, waived or withdrawn. It deliberately keeps anything still in flight, including requirements marked submitted, since a submitted item has not been accepted yet. status=all returns every row. Carrier status strings are always returned verbatim, so you can filter further yourself.

Example

curl https://api.axiums.ai/v1/requirements?npn=8241905573 \
  -H "Authorization: Bearer axm_live_7f3c9a12e8b4d6f0a5c1"

Response

{
  "agent": { "npn": "8241905573", "name": "Jordan Ellery" },
  "carriers": [
    {
      "carrier": "mutual-of-omaha",
      "coverage": "full",
      "syncStatus": "ok",
      "lastSyncedAt": "2026-08-09T15:48:56.520Z",
      "fieldProvenance": {
        "policyNumber": "carrier_verbatim",
        "policyStatus": "carrier_verbatim",
        "requirement": "carrier_verbatim",
        "comments": "carrier_verbatim",
        "requestedDate": "carrier_verbatim",
        "insuredName": "axiums_derived"
      },
      "requirements": [
        {
          "policyNumber": "BU6747044",
          "policyStatus": "Issued",
          "requirement": "GOOD HEALTH STATEMENT - SIMPLIFIED",
          "comments": "",
          "requestedDate": "2026-07-29",
          "insuredName": "MARK HOPKINS"
        }
      ]
    },
    {
      "carrier": "liberty-bankers",
      "coverage": "status_only",
      "syncStatus": "ok",
      "lastSyncedAt": "2026-08-09T15:44:59.614Z",
      "fieldProvenance": {
        "policyNumber": "carrier_verbatim",
        "initialPremiumNotPaid": "axiums_derived"
      },
      "requirements": [
        { "policyNumber": "42946S", "initialPremiumNotPaid": true }
      ]
    },
    {
      "carrier": "ethos",
      "coverage": "unavailable",
      "syncStatus": "unavailable",
      "lastSyncedAt": null,
      "fieldProvenance": {},
      "requirements": []
    }
  ]
}

Nullable fields

agent.name is string | null. An agent may not have set their name, so it can be present and null. Do not assume a string.

Individual requirement fields can also be null where the carrier didn't supply a value. Parse defensively.

agencyId is not returned — your key is the agency.

Batch: requirements for multiple agents

POST /v1/requirements/batch

Example

curl -X POST https://api.axiums.ai/v1/requirements/batch \
  -H "Authorization: Bearer axm_live_7f3c9a12e8b4d6f0a5c1" \
  -H "Content-Type: application/json" \
  -d '{ "npns": ["8241905573", "6017384492"], "carrier": "foresters" }'

Response

Every requested NPN appears in the response with an explicit status. A batch never silently drops an NPN.

{
  "requested": 2,
  "summary": { "found": 1, "unavailable": 1 },
  "results": [
    {
      "agent": { "npn": "8241905573", "name": "Jordan Ellery" },
      "status": "found",
      "carriers": [ "..." ]
    },
    {
      "npn": "6017384492",
      "status": "unavailable"
    }
  ]
}

A found result carries an agent object and carriers. An unavailable result carries only npn and status — no agent object, because no agent was resolved.

Per-NPN failures do not fail the batch. The HTTP status is 200 when the request itself was valid, even if every NPN in it was unavailable.

Errors

{
  "error": "agent_unavailable",
  "message": "No agent available for this NPN under your API access."
}

agent_unavailable covers three cases with one identical response: the NPN doesn't exist, it exists but has no AXIUMS agent, or it belongs to an agent outside your agency. This is deliberate — distinguishing them would let any approved key enumerate which NPNs are in AXIUMS.

Rate limits

Rate limit state is returned on authenticated responses:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1786321140

These headers are absent on a 401, since an unauthenticated caller is given no rate state.

A 429 includes Retry-After in seconds. Retry with exponential backoff.

Versioning

The version is in the path. Breaking changes ship as a new version; v1 continues to be served. Additive changes — new fields, new carriers, new status values — can land in v1 without notice, so parse defensively and ignore unknown fields.

Support

Technical questions and key rotation: api@axiums.ai