API documentation

Sign in, open Integrations, then Integration keys. Name the system that will use the key and choose its permissions. The key is shown once, so copy it then. Revoke it from the same page whenever you need to.

Insurer keys can carry

certificate.issuecertificate.readcertificate.renewcertificate.cancelbatch.submitbatch.readstock.readclaim.read

National bureau keys can carry

certificate.readbatch.submitbatch.readfeed.manageclaim.readclaim.open

Each operation names the permission it needs.

Send the key in the x-api-key header. A bearer header works as well: Authorization: Bearer followed by the key. Operations marked public need no key.

curl "https://browncard.ecfatum.com/api/registry/certificates?limit=5" \
  -H "x-api-key: bc_1a2b3c4d_YOUR_KEY"

Add an Idempotency-Key header of up to 200 characters to a call that creates certificates; sending a batch requires one. If you repeat the call with the same key, for example after a timeout, you receive the first result and nothing is created twice. Use a new key for each new request.

Idempotency-Key: policy-GH-7781204-2026-10-12

Each key has a per-minute allowance, 600 calls by default. Public operations allow fewer calls from one address: 60 a minute for verification, 30 for public card pictures, 20 for accident reports and claim tracking. Past the allowance the answer is 429 with a Retry-After header: wait that many seconds. To send many certificates, send one batch rather than many calls.

A failed call returns application/problem+json (RFC 9457). Show detail to people and branch on code in your software. Validation errors list each field in errors. Quote correlationId when you contact support.

{
  "type": "urn:bc:problem:stock_empty",
  "title": "Conflict",
  "status": 409,
  "code": "STOCK_EMPTY",
  "detail": "You have no certificate credits left. …",
  "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21"
}

List operations take limit and offset and answer with items, total, limit and offset. Fetch the next page by adding limit to offset, until a page has fewer items than limit. Totals stop at 1,000 where counting further would be slow, and totalCapped says so.

GET /api/registry/certificates?limit=50&offset=100

Dates are calendar days written YYYY-MM-DD in UTC, and a period of insurance includes its first and last day. Times are ISO 8601 in UTC, such as 2026-10-12T08:14:04Z. Batch rows and uploaded files also accept DD/MM/YYYY.

Amounts are whole numbers in the smallest unit of the currency, with the ISO 4217 code beside them: 1250 GHS is 12.50 cedis. XOF has no minor unit, so 25000 XOF is twenty-five thousand francs.

Choose an API below, open an operation and select Test Request. Paste your key under Authentication. Calls go from your browser straight to this platform, and the key is kept only while the page is open.