{ "openapi": "3.0.0", "info": { "title": "Brown Card API: verification", "description": "", "version": "1.0.0" }, "servers": [ { "url": "https://browncard.ecfatum.com/api/verify" } ], "tags": [ { "name": "Check a certificate", "description": "Find out whether a vehicle has motor insurance cover in force. Check by certificate number, number plate or paper serial, from the signed QR code on a certificate, or from a picture of the certificate. Every answer says what the check found and whether the cover applies in the country where the check is made." }, { "name": "Check without a connection", "description": "Download the public signing keys of every issuing country, so that a verifier can check signed QR codes on a device that is not connected." } ], "paths": { "/check": { "get": { "description": "Use this when someone gives you a certificate number, a number plate or the serial of a paper certificate and you need to know whether the vehicle is insured. Anyone can ask.\n\nEvery answer has a `result`. `VALID` means the certificate is in force today. `NOT_YET_VALID`, `EXPIRED`, `SUSPENDED` and `CANCELLED` say why it is not, and `reason` adds detail where the result alone does not. `PAPER_REGISTERED` means the serial of a paper certificate is registered and in date. `NOT_FOUND` means nothing is known for what you sent. When more than one applies the first of these wins: cancelled, expired, suspended, not yet started. Dates are judged on the current calendar day in UTC, and the first and last day of the period both count as covered.\n\n**Plates.** A plate finds the vehicle however it is written: `GR 4821-24`, `gr482124` and `GR-4821-24` are the same plate. When a vehicle has several certificates, the one in force today is the answer, and among valid certificates one that covers `country` is preferred. The others are listed in `history`.\n\n**Where the check is made.** Send `country`, the two-letter code of the country where you are, and `certificate.coversHere` says whether the certificate covers it. `result` is about the certificate alone: a national certificate checked in another country is `VALID` with `coversHere: false`. Without `country`, `coversHere` is `null`.\n\n**What the answer holds.** A public answer describes the certificate and the vehicle: insurer, period of insurance, countries covered, make and model. A verifying authority, signed in or using a key with `verify.authority`, also receives the policyholder’s name and the policy number, and its own country is used for `coversHere`.\n\nEvery check is recorded. Each client address can make 60 calls a minute to the verification operations; further calls are answered with `429` until the minute is over.\n\n**Access.** Open to everyone. A key with `verify.authority` adds the detail reserved for verifying authorities.", "operationId": "checkCertificate", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "What to look for: a certificate number, a number plate or the serial of a paper certificate, from 2 to 80 characters. Write it in any case, with or without spaces and dashes: `GH-2026-0004711`, `gh20260004711` and `GR 4821-24` all work.", "schema": { "type": "string", "minLength": 2, "maxLength": 80 }, "example": "GR 4821-24" }, { "name": "country", "in": "query", "required": false, "description": "The two-letter code of the country where the check is made, for example `TG`. The answer then says in `certificate.coversHere` whether the certificate covers that country. A verifying authority’s own country, when it has one, takes its place. Example: `TG`.", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "channel", "in": "query", "required": false, "description": "Where the check comes from: `WEB` for the website, `PWA` for the verifier app, `API` for your own system. Recorded with the check. The default is `WEB`; a call made with an integration key is recorded as `API`. One of `WEB`, `PWA`, `API`. Example: `API`.", "schema": { "type": "string" } }, { "name": "lat", "in": "query", "required": false, "description": "Latitude of the place where the check is made, from -90 to 90. Recorded with the check. Example: `6.1725`.", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lng", "in": "query", "required": false, "description": "Longitude of the place where the check is made, from -180 to 180. Recorded with the check. Example: `1.2314`.", "schema": { "type": "number", "minimum": -180, "maximum": 180 } } ], "responses": { "200": { "description": "The answer to the check. Read `result` first; `certificate`, `paper` and `history` hold the details.", "headers": { "x-correlation-id": { "description": "Identifies this call. It repeats the `x-correlation-id` you sent, or is generated. Quote it to support.", "schema": { "type": "string" }, "example": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResult" }, "examples": { "valid": { "summary": "A valid certificate that covers the country of the check", "description": "A Ghanaian Brown Card found by plate and checked in Togo. `coversHere` is `true` because Togo is one of its `territories`.", "value": { "scanId": "a4f1c7d2-5b83-4e09-8c26-9d7e0b3a5f14", "result": "VALID", "reason": null, "query": { "kind": "PLATE", "value": "GR 4821-24" }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "TG", "certificate": { "certificateId": "7c1f0a52-3a8e-4b8d-9f6e-2d4a9c1b7e30", "number": "GH-2026-0004711", "kind": "CERTIFICATE", "scope": "ECOWAS", "status": "ISSUED", "country": "GH", "validFrom": "2026-09-01", "validTo": "2027-08-31", "territories": [ "BJ", "GH", "TG" ], "coversHere": true, "insurer": { "name": "Volta Assurance", "code": "GH-VOLTA" }, "vehicle": { "registration": "GR 4821-24", "make": "Toyota", "model": "Corolla", "category": "CAR" }, "version": 1 }, "paper": null, "history": [], "signature": null, "asIssued": null } }, "validElsewhere": { "summary": "A valid certificate that does not cover the country of the check", "description": "The same certificate checked in Nigeria. The certificate is in force, so `result` is `VALID`, and `coversHere` is `false` because Nigeria is not among its `territories`.", "value": { "scanId": "b7e2d915-6c04-4a38-9f71-2e8c1d4b6a03", "result": "VALID", "reason": null, "query": { "kind": "NUMBER", "value": "GH-2026-0004711" }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "NG", "certificate": { "certificateId": "7c1f0a52-3a8e-4b8d-9f6e-2d4a9c1b7e30", "number": "GH-2026-0004711", "kind": "CERTIFICATE", "scope": "ECOWAS", "status": "ISSUED", "country": "GH", "validFrom": "2026-09-01", "validTo": "2027-08-31", "territories": [ "BJ", "GH", "TG" ], "coversHere": false, "insurer": { "name": "Volta Assurance", "code": "GH-VOLTA" }, "vehicle": { "registration": "GR 4821-24", "make": "Toyota", "model": "Corolla", "category": "CAR" }, "version": 1 }, "paper": null, "history": [], "signature": null, "asIssued": null } }, "validNational": { "summary": "A valid national certificate", "description": "A certificate from Lomé Assurances that covers Togo only, checked in Togo.", "value": { "scanId": "c9a3e826-7d15-4b49-a082-3f9d2e5c7b25", "result": "VALID", "reason": null, "query": { "kind": "PLATE", "value": "TG 1234 AB" }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "TG", "certificate": { "certificateId": "3a9d5e71-6c04-4f2b-8e17-b05c9d4a6f82", "number": "TG-2026-0000412", "kind": "CERTIFICATE", "scope": "NATIONAL", "status": "ISSUED", "country": "TG", "validFrom": "2026-04-01", "validTo": "2027-03-31", "territories": [ "TG" ], "coversHere": true, "insurer": { "name": "Lomé Assurances", "code": "TG-LOME" }, "vehicle": { "registration": "TG 1234 AB", "make": "Toyota", "model": "Hilux", "category": "PICKUP" }, "version": 1 }, "paper": null, "history": [], "signature": null, "asIssued": null } }, "validNoCountry": { "summary": "A check without a country", "description": "No `country` was sent, so the answer does not say where the check was made and `coversHere` is `null`.", "value": { "scanId": "d1b4f937-8e26-4c5a-b193-4a0e3f6d8c36", "result": "VALID", "reason": null, "query": { "kind": "NUMBER", "value": "GH-2026-0004711" }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": null, "certificate": { "certificateId": "7c1f0a52-3a8e-4b8d-9f6e-2d4a9c1b7e30", "number": "GH-2026-0004711", "kind": "CERTIFICATE", "scope": "ECOWAS", "status": "ISSUED", "country": "GH", "validFrom": "2026-09-01", "validTo": "2027-08-31", "territories": [ "BJ", "GH", "TG" ], "coversHere": null, "insurer": { "name": "Volta Assurance", "code": "GH-VOLTA" }, "vehicle": { "registration": "GR 4821-24", "make": "Toyota", "model": "Corolla", "category": "CAR" }, "version": 1 }, "paper": null, "history": [], "signature": null, "asIssued": null } }, "validWithHistory": { "summary": "A plate with an earlier certificate", "description": "The vehicle was insured by another company before. The certificate in force is the answer; the earlier one is listed in `history`.", "value": { "scanId": "e2c5a048-9f37-4d6b-8204-5b1f4a7e9d47", "result": "VALID", "reason": null, "query": { "kind": "PLATE", "value": "gr482124" }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "GH", "certificate": { "certificateId": "7c1f0a52-3a8e-4b8d-9f6e-2d4a9c1b7e30", "number": "GH-2026-0004711", "kind": "CERTIFICATE", "scope": "ECOWAS", "status": "ISSUED", "country": "GH", "validFrom": "2026-09-01", "validTo": "2027-08-31", "territories": [ "BJ", "GH", "TG" ], "coversHere": true, "insurer": { "name": "Volta Assurance", "code": "GH-VOLTA" }, "vehicle": { "registration": "GR 4821-24", "make": "Toyota", "model": "Corolla", "category": "CAR" }, "version": 1 }, "paper": null, "history": [ { "certificateId": "5d2e8b94-7a13-4c60-b9f5-1e3c7a0d4862", "number": "GH-2025-0012877", "result": "EXPIRED", "validFrom": "2025-08-31", "validTo": "2026-08-30", "insurerName": "Adinkra Insurance", "scope": "NATIONAL" } ], "signature": null, "asIssued": null } }, "authority": { "summary": "A check by a verifying authority", "description": "Sent with a key or session that carries `verify.authority`. The certificate also holds the policyholder’s name and the policy number, and the country is the authority’s own.", "value": { "scanId": "f3d6b159-0a48-4e7c-9315-6c2a5b8f0e58", "result": "VALID", "reason": null, "query": { "kind": "NUMBER", "value": "GH-2026-0004711" }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "GH", "certificate": { "certificateId": "7c1f0a52-3a8e-4b8d-9f6e-2d4a9c1b7e30", "number": "GH-2026-0004711", "kind": "CERTIFICATE", "scope": "ECOWAS", "status": "ISSUED", "country": "GH", "validFrom": "2026-09-01", "validTo": "2027-08-31", "territories": [ "BJ", "GH", "TG" ], "coversHere": true, "insurer": { "name": "Volta Assurance", "code": "GH-VOLTA" }, "vehicle": { "registration": "GR 4821-24", "make": "Toyota", "model": "Corolla", "category": "CAR" }, "version": 1, "holderName": "Kofi Mensah", "holderNameMasked": false, "policyNumber": "POL-GH-7781204" }, "paper": null, "history": [], "signature": null, "asIssued": null } }, "notYetValid": { "summary": "A certificate that starts later", "value": { "scanId": "0a7c2e6b-1d59-4f8d-a426-7d3b6c9a1f69", "result": "NOT_YET_VALID", "reason": null, "query": { "kind": "NUMBER", "value": "GH-2026-0005020" }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "GH", "certificate": { "certificateId": "9e4b7c13-2f60-4a85-b7d9-8c1a5e3f0b74", "number": "GH-2026-0005020", "kind": "CERTIFICATE", "scope": "ECOWAS", "status": "ISSUED", "country": "GH", "validFrom": "2026-10-15", "validTo": "2027-10-14", "territories": [ "BJ", "GH", "TG" ], "coversHere": true, "insurer": { "name": "Volta Assurance", "code": "GH-VOLTA" }, "vehicle": { "registration": "GR 4821-24", "make": "Toyota", "model": "Corolla", "category": "CAR" }, "version": 1 }, "paper": null, "history": [], "signature": null, "asIssued": null } }, "expired": { "summary": "An expired certificate", "description": "The last day of the period of insurance was 19 September 2026.", "value": { "scanId": "1b8d3f7c-2e6a-4a09-8537-8e4c7dab2a7a", "result": "EXPIRED", "reason": null, "query": { "kind": "PLATE", "value": "GT 3342-25" }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "GH", "certificate": { "certificateId": "2f5a8d41-9c37-4b62-a8e0-3d7b1c6e4a95", "number": "GH-2025-0009312", "kind": "CERTIFICATE", "scope": "NATIONAL", "status": "EXPIRED", "country": "GH", "validFrom": "2025-09-20", "validTo": "2026-09-19", "territories": [ "GH" ], "coversHere": true, "insurer": { "name": "Volta Assurance", "code": "GH-VOLTA" }, "vehicle": { "registration": "GT 3342-25", "make": "Nissan", "model": "Navara", "category": "PICKUP" }, "version": 1 }, "paper": null, "history": [], "signature": null, "asIssued": null } }, "suspended": { "summary": "A suspended certificate", "description": "The cover was suspended; `reason` is `null`.", "value": { "scanId": "2c9e4a8d-3f7b-4b1a-9648-9f5d8ebc3b8b", "result": "SUSPENDED", "reason": null, "query": { "kind": "PLATE", "value": "AS 2210-23" }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "GH", "certificate": { "certificateId": "6a1d9e52-0b84-4c73-8f16-2e8c4b7d5a06", "number": "GH-2026-0003120", "kind": "CERTIFICATE", "scope": "ECOWAS", "status": "SUSPENDED", "country": "GH", "validFrom": "2026-09-01", "validTo": "2027-08-31", "territories": [ "BJ", "GH", "TG" ], "coversHere": true, "insurer": { "name": "Volta Assurance", "code": "GH-VOLTA" }, "vehicle": { "registration": "AS 2210-23", "make": "Mercedes-Benz", "model": "Actros", "category": "TRUCK" }, "version": 1 }, "paper": null, "history": [], "signature": null, "asIssued": null } }, "insurerSuspended": { "summary": "An insurer that is not in good standing", "description": "The certificate itself is in order, but its insurer is suspended. Ask the holder to contact the insurer.", "value": { "scanId": "3dae5b9e-4a8c-4c2b-a759-0a6e9fcd4c9c", "result": "SUSPENDED", "reason": "INSURER_SUSPENDED", "query": { "kind": "PLATE", "value": "TG 5120 BC" }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "TG", "certificate": { "certificateId": "8b3e6a24-1c95-4d70-b4a2-5f9d7e0c3b17", "number": "TG-2026-0000377", "kind": "CERTIFICATE", "scope": "NATIONAL", "status": "ISSUED", "country": "TG", "validFrom": "2026-04-01", "validTo": "2027-03-31", "territories": [ "TG" ], "coversHere": true, "insurer": { "name": "Lomé Assurances", "code": "TG-LOME" }, "vehicle": { "registration": "TG 5120 BC", "make": "Suzuki", "model": "Swift", "category": "CAR" }, "version": 1 }, "paper": null, "history": [], "signature": null, "asIssued": null } }, "paperRegistered": { "summary": "A registered paper certificate", "description": "The serial of a paper certificate is registered and in date. `certificate` is `null`.", "value": { "scanId": "4ebf6caf-5b9d-4d3c-8860-1b7fa0de5dad", "result": "PAPER_REGISTERED", "reason": null, "query": { "kind": "PAPER_SERIAL", "value": "GH-P-0048291" }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "GH", "certificate": null, "paper": { "serial": "GH-P-0048291", "insurerName": "Volta Assurance", "country": "GH", "registration": "BA 5567-26", "validFrom": "2026-07-01", "validTo": "2027-06-30", "status": "VALID" }, "history": [], "signature": null, "asIssued": null } }, "notFound": { "summary": "Nothing is known for this plate", "value": { "scanId": "5fc07db0-6cae-4e4d-9971-2c80b1ef6ebe", "result": "NOT_FOUND", "reason": null, "query": { "kind": "PLATE", "value": "GR 9999-24" }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "GH", "certificate": null, "paper": null, "history": [], "signature": null, "asIssued": null } } } } } }, "400": { "description": "Bad request. The `code` in the body says which of these it is.\n\n- `VALIDATION`: `q` is missing, shorter than 2 or longer than 80 characters, `country` is not two letters, `channel` is not `WEB`, `PWA` or `API`, or `lat` or `lng` is out of range; `errors` names each field.", "headers": { "x-correlation-id": { "description": "Quote this to support.", "schema": { "type": "string" }, "example": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "VALIDATION": { "summary": "400 VALIDATION", "description": "`q` is missing, shorter than 2 or longer than 80 characters, `country` is not two letters, `channel` is not `WEB`, `PWA` or `API`, or `lat` or `lng` is out of range; `errors` names each field.", "value": { "type": "urn:bc:problem:validation", "title": "Bad request", "status": 400, "code": "VALIDATION", "detail": "Some fields are missing or invalid.", "errors": [ { "path": "q", "message": "Too small: expected string to have >=2 characters" } ], "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } }, "401": { "description": "Unauthorized. The `code` in the body says which of these it is.\n\n- `UNAUTHENTICATED`: A key or session was sent and is not valid: the key is mistyped or revoked, or the session has expired. Send a valid key, or leave the credentials out to check without them.", "headers": { "x-correlation-id": { "description": "Quote this to support.", "schema": { "type": "string" }, "example": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "UNAUTHENTICATED": { "summary": "401 UNAUTHENTICATED", "description": "A key or session was sent and is not valid: the key is mistyped or revoked, or the session has expired. Send a valid key, or leave the credentials out to check without them.", "value": { "type": "urn:bc:problem:unauthenticated", "title": "Unauthorized", "status": 401, "code": "UNAUTHENTICATED", "detail": "Your session has expired or the key is not valid.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } }, "429": { "description": "Too many requests. The `code` in the body says which of these it is.\n\n- `RATE_LIMITED`: Too many calls in a minute. Wait for the number of seconds in `retry-after`, then continue.", "headers": { "x-correlation-id": { "description": "Quote this to support.", "schema": { "type": "string" }, "example": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" }, "retry-after": { "description": "Seconds to wait before the next call.", "schema": { "type": "integer" }, "example": 42 } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "RATE_LIMITED": { "summary": "429 RATE_LIMITED", "description": "Too many calls in a minute. Wait for the number of seconds in `retry-after`, then continue.", "value": { "type": "urn:bc:problem:rate_limited", "title": "Too many requests", "status": 429, "code": "RATE_LIMITED", "detail": "Too many requests from this address. Try again in a minute.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } } }, "summary": "Check a certificate by number, plate or paper serial", "tags": [ "Check a certificate" ], "x-integrator": true, "x-public": true, "security": [ {}, { "apiKey": [] }, { "bearer": [] } ] } }, "/token/{jws}": { "get": { "description": "Use this when a verifier scans the QR code on a certificate. The code opens an address of the form `/v/`; send the long text after `/v/` as `{jws}` in the path of this call.\n\nThe signature is checked first, against the public signing keys of the issuing countries. A code whose signature does not match, or that was signed with a key no country lists, is answered `NOT_AUTHENTIC` with a `reason`, and `signature.valid` is `false`. A genuine code is matched with the certificate as it stands today, so a certificate that was cancelled after printing reads `CANCELLED`. `asIssued` repeats what the code said, and `signature` names the key that signed it.\n\nA code from an earlier copy of a certificate that a duplicate has since replaced reads `CANCELLED` with the reason `SUPERSEDED`, and `certificate` describes the current copy. Two answers mean the code could not be judged just now: `KEY_UNAVAILABLE`, when the signing key is not held here and the list of keys could not be fetched, and `STATUS_UNAVAILABLE`, when the signature is genuine and the state of the certificate is not available. Both come back as `NOT_FOUND`; ask again shortly.\n\n`country`, `channel`, `lat` and `lng` work as they do when checking by number, and a verifying authority receives the same added detail. Each client address can make 60 calls a minute to the verification operations; further calls are answered with `429` until the minute is over.\n\n**Access.** Open to everyone. A key with `verify.authority` adds the detail reserved for verifying authorities.", "operationId": "checkQrCode", "parameters": [ { "name": "jws", "in": "path", "required": true, "description": "The signed code from the QR code’s address: the text after `/v/`, in three parts separated by dots. It can be up to 4,000 characters long.", "schema": { "type": "string", "maxLength": 4000 }, "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6IkdILTIwMjYtMSJ9.eyJuIjoiR0gtMjAyNi0wMDA0NzExIiwiciI6IkdSIDQ4MjEtMjQiLCJpIjoiR0gtVk9MVEEiLCJjIjoiR0giLCJzIjoiRUNPV0FTIiwidCI6WyJCSiIsIkdIIiwiVEciXSwiZiI6IjIwMjYtMDktMDEiLCJ1IjoiMjAyNy0wOC0zMSIsInYiOjEsImsiOiJDRVJUSUZJQ0FURSJ9.oHfNmuxlUZbee5hUfkRqV1gCIElx4E5Az6D-uIt9TKF-lYdHG-G46QYXQAeZeyzyu0PZEDwttmmxTfavAI4APw" }, { "name": "country", "in": "query", "required": false, "description": "The two-letter code of the country where the check is made, for example `TG`. The answer then says in `certificate.coversHere` whether the certificate covers that country. A verifying authority’s own country, when it has one, takes its place. Example: `TG`.", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "channel", "in": "query", "required": false, "description": "Where the check comes from: `WEB` for the website, `PWA` for the verifier app, `API` for your own system. Recorded with the check. The default is `WEB`; a call made with an integration key is recorded as `API`. One of `WEB`, `PWA`, `API`. Example: `API`.", "schema": { "type": "string" } }, { "name": "lat", "in": "query", "required": false, "description": "Latitude of the place where the check is made, from -90 to 90. Recorded with the check. Example: `6.1725`.", "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lng", "in": "query", "required": false, "description": "Longitude of the place where the check is made, from -180 to 180. Recorded with the check. Example: `1.2314`.", "schema": { "type": "number", "minimum": -180, "maximum": 180 } } ], "responses": { "200": { "description": "The answer to the check. `signature` and `asIssued` describe the code that was scanned.", "headers": { "x-correlation-id": { "description": "Identifies this call. It repeats the `x-correlation-id` you sent, or is generated. Quote it to support.", "schema": { "type": "string" }, "example": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResult" }, "examples": { "valid": { "summary": "A genuine code for a certificate in force", "description": "The signature matches a listed key. `asIssued` repeats what the code said, and `certificate` is how the certificate stands today.", "value": { "scanId": "6ad18ec1-7dbf-4f5e-aa82-3d91c2f07fcf", "result": "VALID", "reason": null, "query": { "kind": "QR", "value": "GH-2026-0004711" }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "TG", "certificate": { "certificateId": "7c1f0a52-3a8e-4b8d-9f6e-2d4a9c1b7e30", "number": "GH-2026-0004711", "kind": "CERTIFICATE", "scope": "ECOWAS", "status": "ISSUED", "country": "GH", "validFrom": "2026-09-01", "validTo": "2027-08-31", "territories": [ "BJ", "GH", "TG" ], "coversHere": true, "insurer": { "name": "Volta Assurance", "code": "GH-VOLTA" }, "vehicle": { "registration": "GR 4821-24", "make": "Toyota", "model": "Corolla", "category": "CAR" }, "version": 1 }, "paper": null, "history": [], "signature": { "valid": true, "kid": "GH-2026-1" }, "asIssued": { "number": "GH-2026-0004711", "registration": "GR 4821-24", "insurer": "GH-VOLTA", "country": "GH", "scope": "ECOWAS", "territories": [ "BJ", "GH", "TG" ], "validFrom": "2026-09-01", "validTo": "2027-08-31", "version": 1, "kind": "CERTIFICATE" } } }, "superseded": { "summary": "The code on a copy that a duplicate replaced", "description": "The code is genuine, but a duplicate of the certificate was issued since. `certificate` describes the current copy (version 2) and `asIssued` the copy that was scanned (version 1).", "value": { "scanId": "7be29fd2-8ec0-4a6f-bb93-4ea2d3a18ad0", "result": "CANCELLED", "reason": "SUPERSEDED", "query": { "kind": "QR", "value": "GH-2026-0004711" }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "GH", "certificate": { "certificateId": "7c1f0a52-3a8e-4b8d-9f6e-2d4a9c1b7e30", "number": "GH-2026-0004711", "kind": "CERTIFICATE", "scope": "ECOWAS", "status": "ISSUED", "country": "GH", "validFrom": "2026-09-01", "validTo": "2027-08-31", "territories": [ "BJ", "GH", "TG" ], "coversHere": true, "insurer": { "name": "Volta Assurance", "code": "GH-VOLTA" }, "vehicle": { "registration": "GR 4821-24", "make": "Toyota", "model": "Corolla", "category": "CAR" }, "version": 2 }, "paper": null, "history": [], "signature": { "valid": true, "kid": "GH-2026-1" }, "asIssued": { "number": "GH-2026-0004711", "registration": "GR 4821-24", "insurer": "GH-VOLTA", "country": "GH", "scope": "ECOWAS", "territories": [ "BJ", "GH", "TG" ], "validFrom": "2026-09-01", "validTo": "2027-08-31", "version": 1, "kind": "CERTIFICATE" } } }, "badSignature": { "summary": "A code whose signature does not match", "description": "The code was altered or made up, so `certificate` and `asIssued` are `null`.", "value": { "scanId": "8cf3a0e3-9fd1-4b70-8ca4-5fb3e4b29be1", "result": "NOT_AUTHENTIC", "reason": "BAD_SIGNATURE", "query": { "kind": "QR", "value": null }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "TG", "certificate": null, "paper": null, "history": [], "signature": { "valid": false, "kid": "GH-2026-1" }, "asIssued": null } }, "unknownKey": { "summary": "A code signed with a key that is not listed", "value": { "scanId": "9d04b1f4-a0e2-4c81-9db5-6ac4f5c3acf2", "result": "NOT_AUTHENTIC", "reason": "UNKNOWN_KEY", "query": { "kind": "QR", "value": null }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "TG", "certificate": null, "paper": null, "history": [], "signature": { "valid": false, "kid": "GH-2026-7" }, "asIssued": null } }, "keyUnavailable": { "summary": "The signing key could not be fetched", "description": "The code could not be checked just now. Ask again shortly.", "value": { "scanId": "ae15c205-b1f3-4d92-8ac6-7bd5a6d4bd03", "result": "NOT_FOUND", "reason": "KEY_UNAVAILABLE", "query": { "kind": "QR", "value": null }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "TG", "certificate": null, "paper": null, "history": [], "signature": null, "asIssued": null } }, "statusUnavailable": { "summary": "A genuine code whose certificate cannot be read just now", "description": "The signature is genuine, and the current state of the certificate is not available. `asIssued` shows what the code said.", "value": { "scanId": "bf26d316-c204-4ea3-9bd7-8ce6b7e5ce14", "result": "NOT_FOUND", "reason": "STATUS_UNAVAILABLE", "query": { "kind": "QR", "value": "GH-2026-0004711" }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "TG", "certificate": null, "paper": null, "history": [], "signature": { "valid": true, "kid": "GH-2026-1" }, "asIssued": { "number": "GH-2026-0004711", "registration": "GR 4821-24", "insurer": "GH-VOLTA", "country": "GH", "scope": "ECOWAS", "territories": [ "BJ", "GH", "TG" ], "validFrom": "2026-09-01", "validTo": "2027-08-31", "version": 1, "kind": "CERTIFICATE" } } } } } } }, "400": { "description": "Bad request. The `code` in the body says which of these it is.\n\n- `VALIDATION`: The signed code in the path is longer than 4,000 characters. The answer holds `detail` only.\n- `VALIDATION`: `country` is not two letters, `channel` is not `WEB`, `PWA` or `API`, or `lat` or `lng` is out of range; `errors` names each field.", "headers": { "x-correlation-id": { "description": "Quote this to support.", "schema": { "type": "string" }, "example": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "VALIDATION": { "summary": "400 VALIDATION", "description": "`country` is not two letters, `channel` is not `WEB`, `PWA` or `API`, or `lat` or `lng` is out of range; `errors` names each field.", "value": { "type": "urn:bc:problem:validation", "title": "Bad request", "status": 400, "code": "VALIDATION", "detail": "Some fields are missing or invalid.", "errors": [ { "path": "country", "message": "Too big: expected string to have exactly 2 characters" } ], "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } }, "401": { "description": "Unauthorized. The `code` in the body says which of these it is.\n\n- `UNAUTHENTICATED`: A key or session was sent and is not valid: the key is mistyped or revoked, or the session has expired. Send a valid key, or leave the credentials out to check without them.", "headers": { "x-correlation-id": { "description": "Quote this to support.", "schema": { "type": "string" }, "example": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "UNAUTHENTICATED": { "summary": "401 UNAUTHENTICATED", "description": "A key or session was sent and is not valid: the key is mistyped or revoked, or the session has expired. Send a valid key, or leave the credentials out to check without them.", "value": { "type": "urn:bc:problem:unauthenticated", "title": "Unauthorized", "status": 401, "code": "UNAUTHENTICATED", "detail": "Your session has expired or the key is not valid.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } }, "429": { "description": "Too many requests. The `code` in the body says which of these it is.\n\n- `RATE_LIMITED`: Too many calls in a minute. Wait for the number of seconds in `retry-after`, then continue.", "headers": { "x-correlation-id": { "description": "Quote this to support.", "schema": { "type": "string" }, "example": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" }, "retry-after": { "description": "Seconds to wait before the next call.", "schema": { "type": "integer" }, "example": 42 } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "RATE_LIMITED": { "summary": "429 RATE_LIMITED", "description": "Too many calls in a minute. Wait for the number of seconds in `retry-after`, then continue.", "value": { "type": "urn:bc:problem:rate_limited", "title": "Too many requests", "status": 429, "code": "RATE_LIMITED", "detail": "Too many requests from this address. Try again in a minute.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } } }, "summary": "Check a signed QR code", "tags": [ "Check a certificate" ], "x-integrator": true, "x-public": true, "security": [ {}, { "apiKey": [] }, { "bearer": [] } ] } }, "/file": { "post": { "description": "Use this when you hold a picture of a certificate, for example a scan or a photo sent by email, and want to know whether it is genuine and in force. Every certificate picture carries a hidden mark that holds the same signed code as the QR code.\n\nSend the picture as a PNG of at most 5 MB, in the form field `file` of a `multipart/form-data` call. A call with the content type `image/png` and the picture itself as the body is read the same way. Use the PNG as it was issued: pictures of more than 4 million pixels are refused, and so are PNG files that are interlaced or do not use 8 bits per channel. The mark is part of the pixels, so a copy that was resized, compressed or photographed usually no longer carries it.\n\nThe mark is read and its signature checked like a QR code (see **Check a signed QR code**). A genuine picture is answered with the certificate as it stands today. A picture without a mark is answered `NOT_AUTHENTIC` with the reason `NO_MARK`, and one whose mark does not match its signature with `BAD_SIGNATURE`. `query.kind` is `FILE`.\n\nSend `country` to learn whether the certificate covers the country where you are. A verifying authority receives the same added detail as in the other checks. Each client address can make 60 calls a minute to the verification operations; further calls are answered with `429` until the minute is over.\n\n**Access.** Open to everyone. A key with `verify.authority` adds the detail reserved for verifying authorities.", "operationId": "checkCertificateFile", "parameters": [ { "name": "country", "in": "query", "required": false, "description": "The two-letter code of the country where the check is made, for example `TG`. The answer then says in `certificate.coversHere` whether the certificate covers that country. A verifying authority’s own country, when it has one, takes its place. Example: `TG`.", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "The answer to the check. `result` is `NOT_AUTHENTIC` when the picture carries no valid mark.", "headers": { "x-correlation-id": { "description": "Identifies this call. It repeats the `x-correlation-id` you sent, or is generated. Quote it to support.", "schema": { "type": "string" }, "example": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResult" }, "examples": { "valid": { "summary": "A genuine certificate picture", "value": { "scanId": "c037e427-d315-4fb4-8ce8-9df7c8f6df25", "result": "VALID", "reason": null, "query": { "kind": "FILE", "value": "GH-2026-0004711" }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "TG", "certificate": { "certificateId": "7c1f0a52-3a8e-4b8d-9f6e-2d4a9c1b7e30", "number": "GH-2026-0004711", "kind": "CERTIFICATE", "scope": "ECOWAS", "status": "ISSUED", "country": "GH", "validFrom": "2026-09-01", "validTo": "2027-08-31", "territories": [ "BJ", "GH", "TG" ], "coversHere": true, "insurer": { "name": "Volta Assurance", "code": "GH-VOLTA" }, "vehicle": { "registration": "GR 4821-24", "make": "Toyota", "model": "Corolla", "category": "CAR" }, "version": 1 }, "paper": null, "history": [], "signature": { "valid": true, "kid": "GH-2026-1" }, "asIssued": { "number": "GH-2026-0004711", "registration": "GR 4821-24", "insurer": "GH-VOLTA", "country": "GH", "scope": "ECOWAS", "territories": [ "BJ", "GH", "TG" ], "validFrom": "2026-09-01", "validTo": "2027-08-31", "version": 1, "kind": "CERTIFICATE" } } }, "noMark": { "summary": "A picture without the hidden mark", "description": "A picture that was resized or compressed, or that was never issued, carries no mark.", "value": { "scanId": "d148f538-e426-4ac5-9df9-ae08d9a7ea36", "result": "NOT_AUTHENTIC", "reason": "NO_MARK", "query": { "kind": "FILE", "value": null }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "TG", "certificate": null, "paper": null, "history": [], "signature": null, "asIssued": null } }, "badSignature": { "summary": "A picture whose mark does not match its signature", "value": { "scanId": "e259a649-f537-4bd6-8eaa-bf19eab8fb47", "result": "NOT_AUTHENTIC", "reason": "BAD_SIGNATURE", "query": { "kind": "FILE", "value": null }, "checkedAt": "2026-10-12T09:41:27.318Z", "country": "TG", "certificate": null, "paper": null, "history": [], "signature": { "valid": false, "kid": "GH-2026-1" }, "asIssued": null } } } } } }, "400": { "description": "Bad request. The `code` in the body says which of these it is.\n\n- `NO_FILE`: The call carried no file, or the file was empty.", "headers": { "x-correlation-id": { "description": "Quote this to support.", "schema": { "type": "string" }, "example": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "NO_FILE": { "summary": "400 NO_FILE", "description": "The call carried no file, or the file was empty.", "value": { "type": "urn:bc:problem:no_file", "title": "Bad request", "status": 400, "code": "NO_FILE", "detail": "Choose a certificate file to check.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } }, "401": { "description": "Unauthorized. The `code` in the body says which of these it is.\n\n- `UNAUTHENTICATED`: A key or session was sent and is not valid: the key is mistyped or revoked, or the session has expired. Send a valid key, or leave the credentials out to check without them.", "headers": { "x-correlation-id": { "description": "Quote this to support.", "schema": { "type": "string" }, "example": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "UNAUTHENTICATED": { "summary": "401 UNAUTHENTICATED", "description": "A key or session was sent and is not valid: the key is mistyped or revoked, or the session has expired. Send a valid key, or leave the credentials out to check without them.", "value": { "type": "urn:bc:problem:unauthenticated", "title": "Unauthorized", "status": 401, "code": "UNAUTHENTICATED", "detail": "Your session has expired or the key is not valid.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } }, "413": { "description": "Payload too large. The `code` in the body says which of these it is.\n\n- `FILE_TOO_LARGE`: The file is larger than 5 MB.\n- `IMAGE_TOO_LARGE`: The picture has more than 4 million pixels, for example 2,500 by 1,700.", "headers": { "x-correlation-id": { "description": "Quote this to support.", "schema": { "type": "string" }, "example": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "FILE_TOO_LARGE": { "summary": "413 FILE_TOO_LARGE", "description": "The file is larger than 5 MB.", "value": { "type": "urn:bc:problem:file_too_large", "title": "Payload too large", "status": 413, "code": "FILE_TOO_LARGE", "detail": "The file is larger than 5 MB. Upload the certificate image.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } }, "IMAGE_TOO_LARGE": { "summary": "413 IMAGE_TOO_LARGE", "description": "The picture has more than 4 million pixels, for example 2,500 by 1,700.", "value": { "type": "urn:bc:problem:image_too_large", "title": "Payload too large", "status": 413, "code": "IMAGE_TOO_LARGE", "detail": "The image is too large to check. Upload the certificate image at its original size.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } }, "415": { "description": "Unsupported media type. The `code` in the body says which of these it is.\n\n- `NOT_PNG`: The call is neither `multipart/form-data` nor `image/png`, or the file is not a PNG the check can read (8 bits per channel, no interlacing).", "headers": { "x-correlation-id": { "description": "Quote this to support.", "schema": { "type": "string" }, "example": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "NOT_PNG": { "summary": "415 NOT_PNG", "description": "The call is neither `multipart/form-data` nor `image/png`, or the file is not a PNG the check can read (8 bits per channel, no interlacing).", "value": { "type": "urn:bc:problem:not_png", "title": "Unsupported media type", "status": 415, "code": "NOT_PNG", "detail": "Upload the certificate as a PNG image.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } }, "429": { "description": "Too many requests. The `code` in the body says which of these it is.\n\n- `RATE_LIMITED`: Too many calls in a minute. Wait for the number of seconds in `retry-after`, then continue.", "headers": { "x-correlation-id": { "description": "Quote this to support.", "schema": { "type": "string" }, "example": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" }, "retry-after": { "description": "Seconds to wait before the next call.", "schema": { "type": "integer" }, "example": 42 } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "RATE_LIMITED": { "summary": "429 RATE_LIMITED", "description": "Too many calls in a minute. Wait for the number of seconds in `retry-after`, then continue.", "value": { "type": "urn:bc:problem:rate_limited", "title": "Too many requests", "status": 429, "code": "RATE_LIMITED", "detail": "Too many requests from this address. Try again in a minute.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } } }, "summary": "Check the hidden mark in a certificate picture", "tags": [ "Check a certificate" ], "x-integrator": true, "x-public": true, "requestBody": { "required": true, "description": "The certificate picture in the form field `file`. A PNG of at most 5 MB.", "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The certificate picture: a PNG of at most 5 MB." } } }, "examples": { "png": { "summary": "A certificate picture", "description": "The field `file` holds the PNG as a file part.", "value": { "file": "(PNG image, up to 5 MB)" } } } } } }, "security": [ {}, { "apiKey": [] }, { "bearer": [] } ] } }, "/trust-list": { "get": { "description": "Use this to check signed QR codes on a device that is not connected: fetch the keys while you have a connection, keep them, and check each code against them. Each issuing country signs with its own keys, and a key signs only the certificates of its country.\n\nThe answer is a JSON Web Key Set. Each entry in `keys` is an ES256 public key (ECDSA with P-256 and SHA-256) with its `kid` and its `country`, and `refreshedAt` says when the list was last brought up to date. To check a code, read `kid` from the header of the signed code, take the key with the same `kid`, verify the signature, and confirm that the country in the signed content is the country of the key. A key that has been withdrawn is dropped from the list, so refresh it regularly. The response may be kept for 24 hours.\n\nAn offline check shows that the code was signed by the issuing country; the online checks show whether the certificate is in force today. Each client address can make 60 calls a minute to the verification operations; further calls are answered with `429` until the minute is over.\n\n**Access.** Open to everyone. No key is needed.", "operationId": "getTrustList", "parameters": [], "responses": { "200": { "description": "The public signing keys of the issuing countries.", "headers": { "x-correlation-id": { "description": "Identifies this call. It repeats the `x-correlation-id` you sent, or is generated. Quote it to support.", "schema": { "type": "string" }, "example": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" }, "cache-control": { "description": "The list may be kept for 24 hours.", "schema": { "type": "string" }, "example": "public, max-age=86400" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustList" }, "examples": { "keys": { "summary": "Two keys", "description": "The first key verifies the signed code in the example of **Check a signed QR code**.", "value": { "keys": [ { "kty": "EC", "crv": "P-256", "x": "tVfUNyOrOs_Egy9xkI5UTkJ_xrsxGKfagbCcTXI05nE", "y": "eloNlunb-eagPgLvMuMGVSq41p9A2krEBk_sAkloEDw", "kid": "GH-2026-1", "alg": "ES256", "use": "sig", "country": "GH" }, { "kty": "EC", "crv": "P-256", "x": "aRNKGQUzcMiYCschonHag3ESsmcLG1Ux_sMuNQ-7vi0", "y": "svVyDwJrf688roGIdXzfoN3S-3zHk4IXz923E0piumo", "kid": "TG-2026-1", "alg": "ES256", "use": "sig", "country": "TG" } ], "refreshedAt": "2026-10-12T09:30:00.000Z" } } } } } }, "429": { "description": "Too many requests. The `code` in the body says which of these it is.\n\n- `RATE_LIMITED`: Too many calls in a minute. Wait for the number of seconds in `retry-after`, then continue.", "headers": { "x-correlation-id": { "description": "Quote this to support.", "schema": { "type": "string" }, "example": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" }, "retry-after": { "description": "Seconds to wait before the next call.", "schema": { "type": "integer" }, "example": 42 } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "RATE_LIMITED": { "summary": "429 RATE_LIMITED", "description": "Too many calls in a minute. Wait for the number of seconds in `retry-after`, then continue.", "value": { "type": "urn:bc:problem:rate_limited", "title": "Too many requests", "status": 429, "code": "RATE_LIMITED", "detail": "Too many requests from this address. Try again in a minute.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } } }, "summary": "Get the public signing keys of every issuing country", "tags": [ "Check without a connection" ], "x-integrator": true, "x-public": true, "security": [] } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "An integration key, created under Integrations → Integration keys. It looks like `bc_1a2b3c4d_…` and is shown once, when you create it." }, "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http", "description": "An integration key sent as `Authorization: Bearer bc_…`, or the session token of a signed-in user." } }, "schemas": { "VerifyResult": { "type": "object", "properties": { "scanId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifies this check. Quote it when you ask about it." }, "result": { "$ref": "#/components/schemas/VerificationResult" }, "reason": { "nullable": true, "description": "Why the result is what it is, when the result alone does not say; otherwise `null`.", "allOf": [ { "$ref": "#/components/schemas/ResultReason" } ] }, "query": { "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/QueryKind" }, "value": { "nullable": true, "description": "What was looked up: the text you sent, or the certificate number read from a signed code. `null` when nothing could be read. A search that finds nothing is recorded as `NUMBER` when it looks like a certificate number and as `PLATE` otherwise.", "type": "string" } }, "required": [ "kind", "value" ], "description": "What was looked up and how." }, "checkedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the check was made." }, "country": { "nullable": true, "description": "The country the check was made in: the `country` you sent, or the verifying authority’s own. `null` when neither is known.", "type": "string", "minLength": 2, "maxLength": 2 }, "certificate": { "nullable": true, "description": "The certificate that was found. `null` when none was found or the code is not authentic.", "allOf": [ { "$ref": "#/components/schemas/CertificateResult" } ] }, "paper": { "nullable": true, "description": "The paper certificate that was found. `null` unless a paper serial matched.", "allOf": [ { "$ref": "#/components/schemas/PaperResult" } ] }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryItem" }, "description": "Other certificates for the same vehicle, best first. For a plate search this lists the certificates that were not chosen as the answer." }, "signature": { "nullable": true, "description": "QR code and picture checks: the outcome of checking the signature. `null` for other checks and when the code could not be checked.", "allOf": [ { "$ref": "#/components/schemas/SignatureInfo" } ] }, "asIssued": { "nullable": true, "description": "QR code and picture checks with a genuine signature: the content that was signed when the certificate was issued, with `number`, `registration`, `insurer`, `country`, `scope`, `territories`, `validFrom`, `validTo`, `version` and `kind`. It shows what the code said even when the certificate has changed since. `null` otherwise.", "type": "object", "additionalProperties": {} } }, "required": [ "scanId", "result", "reason", "query", "checkedAt", "country", "certificate", "paper", "history", "signature", "asIssued" ], "description": "The answer to a check: what was found (`result`), the certificate or paper certificate behind it, and where the check was made." }, "VerificationResult": { "type": "string", "enum": [ "VALID", "EXPIRED", "NOT_YET_VALID", "SUSPENDED", "CANCELLED", "NOT_FOUND", "NOT_AUTHENTIC", "PAPER_REGISTERED" ], "description": "What the check found, judged on the current calendar day in UTC.\n\n- `VALID`: the certificate is in force.\n- `PAPER_REGISTERED`: the serial of a paper certificate is registered and in date.\n- `NOT_YET_VALID`: the period of insurance starts later.\n- `EXPIRED`: the period of insurance has ended.\n- `SUSPENDED`: the cover is suspended, or the insurer is suspended or not in good standing (see `reason`).\n- `CANCELLED`: the certificate was cancelled, or a duplicate replaced this copy (see `reason`).\n- `NOT_FOUND`: nothing is known for what was checked, or a signed code could not be judged just now (see `reason`).\n- `NOT_AUTHENTIC`: a signed code or a certificate picture failed the check: the signature is wrong, the signing key is unknown, or the picture carries no mark (see `reason`)." }, "ResultReason": { "type": "string", "enum": [ "INSURER_SUSPENDED", "SUPERSEDED", "NO_MARK", "UNKNOWN_KEY", "BAD_SIGNATURE", "KEY_UNAVAILABLE", "STATUS_UNAVAILABLE" ], "description": "Why the result is what it is, when the result alone does not say.\n\n- `INSURER_SUSPENDED`: with `SUSPENDED`. The insurer is suspended or not in good standing; the holder should contact the insurer.\n- `SUPERSEDED`: with `CANCELLED`. A duplicate of the certificate was issued and replaces this copy.\n- `NO_MARK`: with `NOT_AUTHENTIC`. The picture carries no hidden mark.\n- `UNKNOWN_KEY`: with `NOT_AUTHENTIC`. The code was signed with a key that no issuing country lists.\n- `BAD_SIGNATURE`: with `NOT_AUTHENTIC`. The signature does not match the content, the code cannot be read, or the key belongs to another country than the certificate.\n- `KEY_UNAVAILABLE`: with `NOT_FOUND`. The signing key is not held here and the list of keys could not be fetched just now, so the code could not be checked. Ask again shortly.\n- `STATUS_UNAVAILABLE`: with `NOT_FOUND`. The signature is genuine and the current state of the certificate is not available here. Ask again shortly." }, "QueryKind": { "type": "string", "enum": [ "QR", "NUMBER", "PLATE", "PAPER_SERIAL", "FILE" ], "description": "How the certificate was looked up: `NUMBER`, `PLATE` or `PAPER_SERIAL` for a search, `QR` for a signed code, `FILE` for a certificate picture." }, "CertificateResult": { "type": "object", "properties": { "certificateId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The identifier of the certificate." }, "number": { "type": "string", "description": "The certificate number.", "example": "GH-2026-0004711" }, "kind": { "type": "string", "enum": [ "CERTIFICATE", "COVER_NOTE" ], "description": "`COVER_NOTE` is a short-term cover that runs for one month at most; `CERTIFICATE` is the regular certificate." }, "scope": { "type": "string", "enum": [ "NATIONAL", "ECOWAS" ], "description": "`NATIONAL` is valid in the issuing country. `ECOWAS` is the Brown Card and is valid in every country listed in `territories`." }, "status": { "type": "string", "description": "The status recorded when the certificate was issued or last changed: `ISSUED`, `SUSPENDED`, `CANCELLED`, `EXPIRED` or `REPLACED`. Read `result` for the verdict: it also takes the dates and the insurer’s standing into account.", "example": "ISSUED" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 code of the issuing country.", "example": "GH" }, "validFrom": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "The first day of the period of insurance.", "example": "2026-09-01" }, "validTo": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "The last day of the period of insurance. The cover includes this day.", "example": "2027-08-31" }, "territories": { "type": "array", "items": { "type": "string" }, "description": "The countries the certificate covers, as ISO 3166-1 alpha-2 codes. A `NATIONAL` certificate lists its issuing country.", "example": [ "BJ", "GH", "TG" ] }, "coversHere": { "nullable": true, "description": "Whether the certificate covers the country where the check was made (`country` of the answer). `null` when that country is not known. It is independent of `result`: a `VALID` certificate that does not cover this country has `coversHere: false`.", "type": "boolean" }, "insurer": { "type": "object", "properties": { "name": { "type": "string", "description": "The insurer’s name.", "example": "Volta Assurance" }, "code": { "type": "string", "description": "The insurer’s code.", "example": "GH-VOLTA" } }, "required": [ "name", "code" ], "description": "The insurer that issued the certificate." }, "vehicle": { "type": "object", "properties": { "registration": { "type": "string", "description": "The registration plate as recorded on the certificate.", "example": "GR 4821-24" }, "make": { "nullable": true, "description": "The make of the vehicle.", "type": "string" }, "model": { "nullable": true, "description": "The model of the vehicle.", "type": "string" }, "category": { "nullable": true, "description": "The type of vehicle, for example `CAR`, `MINIBUS`, `TRUCK` or `MOTORCYCLE`.", "type": "string" } }, "required": [ "registration", "make", "model", "category" ], "description": "The insured vehicle." }, "holderName": { "description": "Verifying authorities only: the policyholder’s full name, or a shortened form such as `K. M*****` when `holderNameMasked` is `true`.", "example": "Kofi Mensah", "type": "string" }, "holderNameMasked": { "description": "Verifying authorities only: `true` when `holderName` is the shortened form because the full name could not be read just now.", "type": "boolean" }, "policyNumber": { "description": "Verifying authorities only: the insurer’s policy number.", "example": "POL-GH-7781204", "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Which copy of the certificate this is. A duplicate carries the next number, and the signed code on the earlier copy then reads `CANCELLED` with the reason `SUPERSEDED`.", "example": 1 } }, "required": [ "certificateId", "number", "kind", "scope", "status", "country", "validFrom", "validTo", "territories", "coversHere", "insurer", "vehicle", "version" ], "description": "The certificate that was found, as it stands today. A public answer describes the certificate and the vehicle; the policyholder’s name and the policy number are added for verifying authorities." }, "PaperResult": { "type": "object", "properties": { "serial": { "type": "string", "description": "The serial printed on the paper certificate.", "example": "GH-P-0048291" }, "insurerName": { "type": "string", "description": "The insurer that registered the serial.", "example": "Volta Assurance" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 code of the country." }, "registration": { "nullable": true, "description": "The registration plate the paper certificate was registered for, if recorded.", "example": "BA 5567-26", "type": "string" }, "validFrom": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "The first day of the period of insurance." }, "validTo": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "The last day of the period of insurance. The cover includes this day." }, "status": { "type": "string", "enum": [ "VALID", "CANCELLED" ], "description": "Whether the insurer still stands behind the serial. Read `result` for the verdict, which also takes the dates into account." } }, "required": [ "serial", "insurerName", "country", "registration", "validFrom", "validTo", "status" ], "description": "The paper certificate that was found. Present when `result` rests on a paper serial." }, "HistoryItem": { "type": "object", "properties": { "certificateId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "number": { "type": "string", "example": "GH-2025-0012877" }, "result": { "$ref": "#/components/schemas/VerificationResult" }, "validFrom": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "validTo": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "insurerName": { "type": "string" }, "scope": { "type": "string", "enum": [ "NATIONAL", "ECOWAS" ] } }, "required": [ "certificateId", "number", "result", "validFrom", "validTo", "insurerName", "scope" ], "description": "Another certificate for the same vehicle, such as a renewal or one from a previous insurer, with what it reads today." }, "SignatureInfo": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "`true` when the signature matches the content." }, "kid": { "nullable": true, "description": "The identifier of the key the code names. It matches the `kid` of a key in the list of signing keys.", "example": "GH-2026-1", "type": "string" } }, "required": [ "valid", "kid" ], "description": "The result of checking the signature of a QR code or a certificate picture." }, "TrustList": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/TrustKey" }, "description": "The public keys, ordered by `kid`." }, "refreshedAt": { "nullable": true, "description": "When the list was last brought up to date. `null` when no key is known yet.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "keys", "refreshedAt" ], "description": "The public signing keys of every issuing country, as a JSON Web Key Set." }, "TrustKey": { "type": "object", "properties": { "kty": { "type": "string", "description": "The key type: `EC`.", "example": "EC" }, "crv": { "type": "string", "description": "The curve: `P-256`.", "example": "P-256" }, "x": { "type": "string", "description": "The x coordinate of the public key, base64url." }, "y": { "type": "string", "description": "The y coordinate of the public key, base64url." }, "kid": { "type": "string", "description": "The key identifier. A signed code names it in its header.", "example": "GH-2026-1" }, "alg": { "type": "string", "description": "The signature algorithm: `ES256`.", "example": "ES256" }, "use": { "type": "string", "description": "What the key is for: `sig`, signatures.", "example": "sig" }, "country": { "description": "The country whose certificates the key signs, as an ISO 3166-1 alpha-2 code. A key signs only the certificates of its country.", "example": "GH", "type": "string" } }, "required": [ "kty", "crv", "x", "y", "kid", "alg", "use" ], "description": "The public signing key of an issuing country, as a JWK." }, "Problem": { "type": "object", "description": "An error, as RFC 9457 problem details. Show `detail` to people; branch on `code` in code.", "required": [ "type", "title", "status", "code", "detail", "correlationId" ], "properties": { "type": { "type": "string", "description": "Identifies the kind of problem: `urn:bc:problem:` followed by `code` in lower case.", "example": "urn:bc:problem:stock_empty" }, "title": { "type": "string", "description": "The name of the HTTP status.", "example": "Conflict" }, "status": { "type": "integer", "description": "The HTTP status.", "example": 409 }, "code": { "type": "string", "description": "A stable machine-readable code. Codes are never reused for another meaning.", "example": "STOCK_EMPTY" }, "detail": { "type": "string", "description": "A plain sentence that can be shown to a person.", "example": "No certificate credits are left." }, "correlationId": { "type": "string", "description": "Quote this when you contact support. The same value is in the `x-correlation-id` response header.", "example": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" }, "errors": { "type": "array", "description": "Present on validation errors: one entry per field that needs attention.", "items": { "type": "object", "required": [ "path", "message" ], "properties": { "path": { "type": "string", "description": "The field, for example `holder.address`." }, "message": { "type": "string", "description": "What to correct." } } } } } } } } }