{ "openapi": "3.0.0", "info": { "title": "Brown Card API: claims", "description": "", "version": "1.0.0" }, "servers": [ { "url": "https://browncard.ecfatum.com/api/claims" } ], "tags": [ { "name": "Report an accident", "description": "Anyone can report a road accident without signing in. The national bureau of the country where the accident happened receives the report as a claim, and the reporter receives a claim reference to follow it." }, { "name": "Track a claim", "description": "A reporter follows a claim with its reference and the phone number given in the report. A six-digit code sent by SMS proves the number, then the stage the claim has reached is shown." }, { "name": "Handle claims", "description": "For national bureaux and insurers with an integration key: find the claims you can work on and read one with its vehicles, timeline and deadlines. A national bureau can also check the cover a vehicle had on the day of an accident and open a claim." } ], "paths": { "/claims/public": { "post": { "description": "Use this to report a road accident on behalf of anyone involved or anyone who saw it. Send where and when it happened, every vehicle you know of with its plate and role, and the name and phone number of the person reporting. The national bureau of the country where the accident happened receives the report as a new claim.\n\nThe answer holds the claim `reference`, for example `CLM-GH-2026-000141`. The reporter keeps the reference and the phone number: together they let the reporter follow the claim with **Request a code to follow a claim** and **Get the status of a claim with the SMS code**. Each accepted report creates a claim of its own with a new reference.\n\n**What to send.** `accidentCountry` is the two-letter code of a member state and `accidentDate` is a calendar day, `YYYY-MM-DD`, today or earlier. List 1 to 6 vehicles; mark the one believed to have caused the accident `AT_FAULT` and the others `VICTIM` or `WITNESS`. A phone number is read as a number of the accident country when it is written without a country code. Photos uploaded beforehand can be attached by their ids in `photoDocumentIds`, up to 8.\n\nThis operation accepts 20 requests per minute from one client address.\n\n**Access.** Open to everyone. No key is needed.", "operationId": "reportAccident", "parameters": [], "requestBody": { "required": true, "description": "The accident, the vehicles and the person reporting.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accidentCountry": { "type": "string", "minLength": 2, "maxLength": 2 }, "accidentDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "place": { "type": "string", "minLength": 3, "maxLength": 300 }, "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 }, "description": { "type": "string", "maxLength": 2000 }, "damageKind": { "default": "MATERIAL", "type": "string", "enum": [ "MATERIAL", "BODILY", "BOTH" ] }, "vehicles": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "registration": { "type": "string", "minLength": 2, "maxLength": 20 }, "role": { "default": "VICTIM", "type": "string", "enum": [ "AT_FAULT", "VICTIM", "WITNESS" ] }, "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "insurerName": { "type": "string", "maxLength": 160 }, "driverName": { "type": "string", "maxLength": 160 } }, "required": [ "registration" ] } }, "reporterName": { "type": "string", "minLength": 2, "maxLength": 160 }, "reporterPhone": { "type": "string", "pattern": "^\\+?[0-9 ()-]{7,20}$" }, "reporterEmail": { "anyOf": [ { "type": "string", "maxLength": 200, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "string", "enum": [ "" ] } ] }, "photoDocumentIds": { "default": [], "maxItems": 8, "type": "array", "items": { "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)$" } }, "locale": { "type": "string", "enum": [ "en", "fr", "pt" ] } }, "required": [ "accidentCountry", "accidentDate", "place", "vehicles", "reporterName", "reporterPhone" ] }, "examples": { "accra": { "summary": "A collision in Accra, no injuries", "description": "A Ghanaian driver reports that a Togolese minibus caused the accident.", "value": { "accidentCountry": "GH", "accidentDate": "2026-10-09", "place": "Spintex Road, near Baatsona, Accra", "lat": 5.6372, "lng": -0.1012, "description": "A minibus pulled out of a side road and hit the left side of my car. Nobody was hurt.", "damageKind": "MATERIAL", "vehicles": [ { "registration": "AS 4410-24", "role": "VICTIM", "country": "GH", "insurerName": "Volta Assurance", "driverName": "Yaw Darko" }, { "registration": "TG 8842 AC", "role": "AT_FAULT", "country": "TG", "insurerName": "Lomé Assurances" } ], "reporterName": "Yaw Darko", "reporterPhone": "+233 24 431 0042", "reporterEmail": "yaw.darko@example.org", "locale": "en" } }, "lome": { "summary": "A collision in Lomé with an injury, reported in French", "description": "The phone number carries its country code and `locale` is `fr`, so messages to the reporter are in French.", "value": { "accidentCountry": "TG", "accidentDate": "2026-09-28", "place": "Boulevard du 13 Janvier, Lomé", "lat": 6.1319, "lng": 1.2228, "description": "Une voiture immatriculée au Ghana a brûlé le feu rouge et heurté mon véhicule. Mon passager est blessé.", "damageKind": "BOTH", "vehicles": [ { "registration": "GR 4821-24", "role": "AT_FAULT", "country": "GH", "insurerName": "Volta Assurance" }, { "registration": "TG 1234 AB", "role": "VICTIM", "country": "TG", "insurerName": "Lomé Assurances", "driverName": "Afi Mensah" } ], "reporterName": "Afi Mensah", "reporterPhone": "+228 90 12 34 56", "locale": "fr" } }, "minimal": { "summary": "The least that is needed", "value": { "accidentCountry": "GH", "accidentDate": "2026-10-11", "place": "Kejetia, Kumasi", "vehicles": [ { "registration": "AS 2210-23" } ], "reporterName": "Esi Quaye", "reporterPhone": "0244310099" } } } } } }, "responses": { "201": { "description": "The accident was reported. `reference` identifies the new claim.", "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/ReportReceipt" }, "examples": { "reported": { "summary": "A claim was created", "value": { "reference": "CLM-GH-2026-000141" } } } } } }, "400": { "description": "Bad request. The `code` in the body says which of these it is.\n\n- `VALIDATION`: A field is missing or holds a value that is not accepted, for example a phone number that cannot be read; `errors` lists each one.\n- `UNKNOWN_COUNTRY`: `accidentCountry` is not a member state.\n- `FUTURE_DATE`: `accidentDate` is later than today.", "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": "A field is missing or holds a value that is not accepted, for example a phone number that cannot be read; `errors` lists each one.", "value": { "type": "urn:bc:problem:validation", "title": "Bad request", "status": 400, "code": "VALIDATION", "detail": "Some fields are missing or invalid.", "errors": [ { "path": "reporterPhone", "message": "Enter a phone number with its country code" } ], "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } }, "UNKNOWN_COUNTRY": { "summary": "400 UNKNOWN_COUNTRY", "description": "`accidentCountry` is not a member state.", "value": { "type": "urn:bc:problem:unknown_country", "title": "Bad request", "status": 400, "code": "UNKNOWN_COUNTRY", "detail": "ZZ is not a member state.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } }, "FUTURE_DATE": { "summary": "400 FUTURE_DATE", "description": "`accidentDate` is later than today.", "value": { "type": "urn:bc:problem:future_date", "title": "Bad request", "status": 400, "code": "FUTURE_DATE", "detail": "The accident date cannot be in the future.", "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`: More than 20 requests came from the same address within 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": "More than 20 requests came from the same address within 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": "Report an accident", "tags": [ "Report an accident" ], "x-integrator": true, "x-public": true, "security": [] } }, "/claims/track/start": { "post": { "description": "Use this first when a reporter wants to follow a claim. Send the claim `reference` and the phone number given in the report. When they match, the platform sends a six-digit code by SMS to that phone. The code works once and stays valid for 10 minutes.\n\nThe answer is the same for every request, so show the reporter a message such as \"If the details match a claim, a code is on its way\", then collect the code and continue with **Get the status of a claim with the SMS code**. A reporter can receive up to five codes an hour for one claim, and only the newest code works.\n\nThe phone number can be written the way the reporter gave it, with or without the country code. The SMS is sent in the language in `locale` (`en`, `fr` or `pt`), or in the language chosen in the report, or in English when neither is set.\n\nThis operation accepts 20 requests per minute from one client address.\n\n**Access.** Open to everyone. No key is needed.", "operationId": "startClaimTracking", "parameters": [], "requestBody": { "required": true, "description": "The claim reference and the phone number given in the report.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "maxLength": 40 }, "phone": { "type": "string", "maxLength": 30 }, "locale": { "type": "string", "enum": [ "en", "fr", "pt" ] } }, "required": [ "reference", "phone" ] }, "examples": { "international": { "summary": "Phone number with its country code", "value": { "reference": "CLM-GH-2026-000141", "phone": "+233244310042" } }, "french": { "summary": "Local number, SMS in French", "value": { "reference": "CLM-TG-2026-000057", "phone": "90 12 34 56", "locale": "fr" } } } } } }, "responses": { "202": { "description": "The request was accepted. When the reference and phone matched a claim, a code is on its way by SMS.", "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/TrackingCodeRequest" }, "examples": { "accepted": { "summary": "Request accepted", "value": { "sent": true, "expiresInMinutes": 10 } } } } } }, "400": { "description": "Bad request. The `code` in the body says which of these it is.\n\n- `VALIDATION`: `reference` or `phone` is missing or longer than the field allows; `errors` lists each one.", "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": "`reference` or `phone` is missing or longer than the field allows; `errors` lists each one.", "value": { "type": "urn:bc:problem:validation", "title": "Bad request", "status": 400, "code": "VALIDATION", "detail": "Some fields are missing or invalid.", "errors": [ { "path": "reference", "message": "Invalid input: expected string, received undefined" } ], "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`: More than 20 requests came from the same address within 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": "More than 20 requests came from the same address within 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": "Request a code to follow a claim", "tags": [ "Track a claim" ], "x-integrator": true, "x-public": true, "security": [] } }, "/claims/track/verify": { "post": { "description": "Use this after **Request a code to follow a claim**, once the reporter has the six-digit code from the SMS. Send the same `reference` and `phone` with the `code`. The answer shows the stage the claim has reached, its name in the language you ask for with `locale`, the day of the accident, the day the claim was last updated, and the six steps of a claim with the reached ones marked, ready for a progress display.\n\nA code works once and for 10 minutes. After five wrong tries on one code it stops working, even if the right digits are entered afterwards, and a new code is needed. Every failure gets the same `CODE_INVALID` answer, whether the code is wrong, expired or already used, or the reference and phone do not match a claim. Show its message and offer to send a new code.\n\n`stage` is one of `REPORTED`, `ACKNOWLEDGED`, `ASSESSING`, `OFFERED`, `PAID`, `CLOSED`, `DECLINED` or `WITHDRAWN`; the answer explains each one. The labels are in English unless `locale` is `fr` or `pt`.\n\nThis operation accepts 20 requests per minute from one client address.\n\n**Access.** Open to everyone. No key is needed.", "operationId": "confirmClaimTracking", "parameters": [], "requestBody": { "required": true, "description": "The reference and phone from the request for a code, and the code received.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "maxLength": 40 }, "phone": { "type": "string", "maxLength": 30 }, "locale": { "type": "string", "enum": [ "en", "fr", "pt" ] }, "code": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "reference", "phone", "code" ] }, "examples": { "english": { "summary": "Status in English", "value": { "reference": "CLM-GH-2026-000141", "phone": "0244310042", "code": "482915" } }, "french": { "summary": "Status in French", "value": { "reference": "CLM-TG-2026-000057", "phone": "+22890123456", "code": "073916", "locale": "fr" } } } } } }, "responses": { "200": { "description": "The code was right. The answer describes where the claim stands.", "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/ClaimStatus" }, "examples": { "reported": { "summary": "Just reported", "value": { "reference": "CLM-GH-2026-000141", "stage": "REPORTED", "stageLabel": "Reported", "accidentDate": "2026-10-09", "accidentCountry": "GH", "reportedOn": "2026-10-09", "updatedOn": "2026-10-09", "steps": [ { "stage": "REPORTED", "label": "Reported", "reached": true, "current": true }, { "stage": "ACKNOWLEDGED", "label": "Received by the bureau", "reached": false, "current": false }, { "stage": "ASSESSING", "label": "Damage being assessed", "reached": false, "current": false }, { "stage": "OFFERED", "label": "Compensation offered", "reached": false, "current": false }, { "stage": "PAID", "label": "Compensation paid", "reached": false, "current": false }, { "stage": "CLOSED", "label": "Closed", "reached": false, "current": false } ] } }, "assessingInFrench": { "summary": "Damage being assessed, in French", "value": { "reference": "CLM-TG-2026-000057", "stage": "ASSESSING", "stageLabel": "Évaluation des dommages", "accidentDate": "2026-09-28", "accidentCountry": "TG", "reportedOn": "2026-09-28", "updatedOn": "2026-10-07", "steps": [ { "stage": "REPORTED", "label": "Déclaré", "reached": true, "current": false }, { "stage": "ACKNOWLEDGED", "label": "Reçu par le Bureau", "reached": true, "current": false }, { "stage": "ASSESSING", "label": "Évaluation des dommages", "reached": true, "current": true }, { "stage": "OFFERED", "label": "Indemnité proposée", "reached": false, "current": false }, { "stage": "PAID", "label": "Indemnité versée", "reached": false, "current": false }, { "stage": "CLOSED", "label": "Clos", "reached": false, "current": false } ] } }, "declined": { "summary": "Declined", "description": "For a declined or withdrawn claim no step is marked.", "value": { "reference": "CLM-GH-2026-000098", "stage": "DECLINED", "stageLabel": "Declined", "accidentDate": "2026-08-14", "accidentCountry": "GH", "reportedOn": "2026-08-15", "updatedOn": "2026-08-21", "steps": [ { "stage": "REPORTED", "label": "Reported", "reached": false, "current": false }, { "stage": "ACKNOWLEDGED", "label": "Received by the bureau", "reached": false, "current": false }, { "stage": "ASSESSING", "label": "Damage being assessed", "reached": false, "current": false }, { "stage": "OFFERED", "label": "Compensation offered", "reached": false, "current": false }, { "stage": "PAID", "label": "Compensation paid", "reached": false, "current": false }, { "stage": "CLOSED", "label": "Closed", "reached": false, "current": false } ] } } } } } }, "400": { "description": "Bad request. The `code` in the body says which of these it is.\n\n- `CODE_INVALID`: The code is wrong, expired, already used or tried five times, or the reference and phone do not match a claim.\n- `VALIDATION`: A field is missing or too long, or `code` is not six digits; `errors` lists each one.", "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": { "CODE_INVALID": { "summary": "400 CODE_INVALID", "description": "The code is wrong, expired, already used or tried five times, or the reference and phone do not match a claim.", "value": { "type": "urn:bc:problem:code_invalid", "title": "Bad request", "status": 400, "code": "CODE_INVALID", "detail": "The code is not right or has expired. Check the reference and phone, or ask for a new code.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } }, "VALIDATION": { "summary": "400 VALIDATION", "description": "A field is missing or too long, or `code` is not six digits; `errors` lists each one.", "value": { "type": "urn:bc:problem:validation", "title": "Bad request", "status": 400, "code": "VALIDATION", "detail": "Some fields are missing or invalid.", "errors": [ { "path": "code", "message": "Enter the 6-digit code" } ], "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`: More than 20 requests came from the same address within 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": "More than 20 requests came from the same address within 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 status of a claim with the SMS code", "tags": [ "Track a claim" ], "x-integrator": true, "x-public": true, "security": [] } }, "/claims": { "get": { "description": "Use this to find the claims your organisation can work on, or to look one up by reference, certificate number or plate. A national bureau sees the claims for accidents in its own country and the claims on certificates issued in its own country. An insurer sees the claims made on its own certificates.\n\nThe answer is a list, most recently updated first, of at most `limit` claims. Each item shows the stage, the country of the accident and of the certificate, the plate, the certificate number, whether the cover was confirmed in the certificate register, the amount recoverable once the damage is assessed, and the next Convention deadline. Read a whole claim with **Get a claim**, using the `id` of the item.\n\nNarrow the list with `view`, `status`, `country`, `overdue` and `q`. The list holds the `limit` most recently updated claims that match, so tighten the filters, for example `status=open` with `overdue=true`, to reach a particular group of claims.\n\n**Access.** Send an integration key or a signed-in session. The caller needs the permission `claim.read`; choose it when you create the key under Integrations → Integration keys.", "operationId": "listClaims", "parameters": [ { "name": "view", "in": "query", "required": false, "description": "For a bureau: `handling` for accidents in your country, `issuing` for claims on certificates issued in your country, `all` (the default) for everything you can see. One of `handling`, `issuing`, `all`. Example: `handling`.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "A stage such as `ACKNOWLEDGED`, or `open` for every claim that is not closed, declined or withdrawn. One of `REPORTED`, `ACKNOWLEDGED`, `ASSESSING`, `OFFERED`, `AGREED`, `PAID`, `RECOVERY`, `DEMANDED`, `REIMBURSED`, `DISPUTED`, `ARBITRATION`, `CLOSED`, `DECLINED`, `WITHDRAWN`, `open`. Example: `open`.", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "A two-letter country code, in capitals or not. Keeps the claims where the accident happened or the certificate was issued in that country. Example: `TG`.", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "overdue", "in": "query", "required": false, "description": "`true` or `1` keeps only the claims whose next deadline has passed. `false` or `0` applies no filter. One of `0`, `1`, `true`, `false`. Example: `true`.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Up to 60 characters. Matches part of a claim reference or certificate number, or a whole plate whatever its spaces and hyphens. Example: `GR 4821-24`.", "schema": { "type": "string", "maxLength": 60 } }, { "name": "limit", "in": "query", "required": false, "description": "How many claims to return, from 1 to 200.", "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 200 }, "example": 50 } ], "responses": { "200": { "description": "The claims that match, most recently updated first. An empty list means none.", "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": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimSummary" } }, "examples": { "claims": { "summary": "Three claims", "value": [ { "id": "3b6e1f08-5c27-4d9a-8e41-7a02c9d5b316", "reference": "CLM-GH-2026-000142", "status": "ACKNOWLEDGED", "accidentCountry": "GH", "issuingCountry": "TG", "accidentDate": "2026-10-10", "plate": "TG 1234 AB", "certificateNumber": "TG-2026-0002056", "coverConfirmed": true, "amountUa": null, "nextDeadline": { "kind": "POLICE_REPORT", "dueOn": "2026-12-10", "article": "Arts. 31, 81", "basis": "The police report reaches the insurer within two months of the accident", "party": "POLICE", "state": "OPEN", "doneOn": null, "daysLeft": 59 }, "updatedAt": "2026-10-12T09:41:07.241Z" }, { "id": "c2a8d417-96f3-4e0b-b5d2-18e7f40a3c69", "reference": "CLM-GH-2026-000141", "status": "REPORTED", "accidentCountry": "GH", "issuingCountry": null, "accidentDate": "2026-10-09", "plate": "TG 8842 AC", "certificateNumber": null, "coverConfirmed": false, "amountUa": null, "nextDeadline": { "kind": "POLICE_REPORT", "dueOn": "2026-12-09", "article": "Arts. 31, 81", "basis": "The police report reaches the insurer within two months of the accident", "party": "POLICE", "state": "OPEN", "doneOn": null, "daysLeft": 58 }, "updatedAt": "2026-10-09T17:22:41.380Z" }, { "id": "b9e47a30-2d1c-4f86-a53e-c6082f1d9b74", "reference": "CLM-TG-2026-000057", "status": "ASSESSING", "accidentCountry": "TG", "issuingCountry": "GH", "accidentDate": "2026-09-28", "plate": "GR 4821-24", "certificateNumber": "GH-2026-0004711", "coverConfirmed": true, "amountUa": 185000, "nextDeadline": { "kind": "POLICE_REPORT", "dueOn": "2026-11-28", "article": "Arts. 31, 81", "basis": "The police report reaches the insurer within two months of the accident", "party": "POLICE", "state": "OPEN", "doneOn": null, "daysLeft": 47 }, "updatedAt": "2026-10-07T14:05:19.774Z" } ] }, "none": { "summary": "No claim matches", "value": [] } } } } }, "400": { "description": "Bad request. The `code` in the body says which of these it is.\n\n- `VALIDATION`: A filter has a value that is not accepted; `errors` names it.", "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": "A filter has a value that is not accepted; `errors` names it.", "value": { "type": "urn:bc:problem:validation", "title": "Bad request", "status": 400, "code": "VALIDATION", "detail": "Some fields are missing or invalid.", "errors": [ { "path": "limit", "message": "Too big: expected number to be <=200" } ], "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } }, "401": { "description": "Unauthorized. The `code` in the body says which of these it is.\n\n- `UNAUTHENTICATED`: The key is missing, mistyped or revoked, or the session has expired.", "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": "The key is missing, mistyped or revoked, or the session has expired.", "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" } } } } } }, "403": { "description": "Forbidden. The `code` in the body says which of these it is.\n\n- `FORBIDDEN`: The key was created without the permission this operation needs.", "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": { "FORBIDDEN": { "summary": "403 FORBIDDEN", "description": "The key was created without the permission this operation needs.", "value": { "type": "urn:bc:problem:forbidden", "title": "Forbidden", "status": 403, "code": "FORBIDDEN", "detail": "You do not have permission to do this.", "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 for this key. Try again in a minute.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } } }, "summary": "List the claims you can see", "tags": [ "Handle claims" ], "x-integrator": true, "x-permissions": [ "claim.read" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] }, "post": { "description": "Use this when your bureau has learned of an accident in its own country that involves a vehicle covered by a certificate from another country, and you want to start the claim yourself. Send where and when it happened, what is known about it, and the cover. The accident country is the country of your bureau and is not part of the request.\n\nGive the cover as `{ \"lookup\": { \"by\": \"plate\", \"value\": \"TG 1234 AB\" } }` to have the certificate found in the register as it stood on the accident date, or as `{ \"manual\": { … } }` to type the certificate when the register has no answer. Cover found in the register is marked as confirmed on the claim; cover typed in is marked as not confirmed. Either way the certificate must come from another country than yours.\n\n`place` names the location, from 3 to 300 characters. `lat`, `lng` and `description` are optional. `victim` is optional and describes the injured party’s vehicle: `registration` is required with it, and `name`, `insurerName` and `vehicleUse` (`PRIVATE`, the default, or `COMMERCIAL`) are optional.\n\nThe claim is created in your bureau’s name and starts at `ACKNOWLEDGED`. The answer holds its `id` and `reference`; read the claim with **Get a claim**. `accidentDate` is a calendar day, `YYYY-MM-DD`, today or earlier, and `damageKind` is `MATERIAL` (the default), `BODILY` or `BOTH`.\n\n**Access.** Send an integration key or a signed-in session. The caller needs the permission `claim.open`; choose it when you create the key under Integrations → Integration keys.", "operationId": "openClaim", "parameters": [], "requestBody": { "required": true, "description": "The accident, the cover and, if known, the victim’s vehicle.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accidentDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "place": { "type": "string", "minLength": 3, "maxLength": 300 }, "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 }, "description": { "type": "string", "maxLength": 2000 }, "damageKind": { "default": "MATERIAL", "type": "string", "enum": [ "MATERIAL", "BODILY", "BOTH" ] }, "cover": { "anyOf": [ { "type": "object", "properties": { "lookup": { "type": "object", "properties": { "by": { "type": "string", "enum": [ "plate", "certificate", "policy" ] }, "value": { "type": "string", "minLength": 2, "maxLength": 60 } }, "required": [ "by", "value" ] } }, "required": [ "lookup" ] }, { "type": "object", "properties": { "manual": { "type": "object", "properties": { "certificateNumber": { "type": "string", "minLength": 3, "maxLength": 40 }, "issuingCountry": { "type": "string", "minLength": 2, "maxLength": 2 }, "insurerName": { "type": "string", "minLength": 2, "maxLength": 160 }, "policyNumber": { "type": "string", "maxLength": 60 }, "registration": { "type": "string", "minLength": 2, "maxLength": 20 }, "validFrom": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "validTo": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "holderName": { "type": "string", "maxLength": 160 } }, "required": [ "certificateNumber", "issuingCountry", "insurerName", "registration" ] } }, "required": [ "manual" ] } ] }, "victim": { "type": "object", "properties": { "registration": { "type": "string", "minLength": 2, "maxLength": 20 }, "name": { "type": "string", "maxLength": 160 }, "insurerName": { "type": "string", "maxLength": 160 }, "vehicleUse": { "default": "PRIVATE", "type": "string", "enum": [ "COMMERCIAL", "PRIVATE" ] } }, "required": [ "registration" ] } }, "required": [ "accidentDate", "place", "cover" ] }, "examples": { "lookup": { "summary": "Cover found in the register by plate", "value": { "accidentDate": "2026-10-10", "place": "Tema Motorway roundabout, Tema", "lat": 5.6698, "lng": -0.0166, "description": "The minibus ran into the back of a stationary car at the roundabout.", "damageKind": "MATERIAL", "cover": { "lookup": { "by": "plate", "value": "TG 1234 AB" } }, "victim": { "registration": "GT 3342-25", "name": "Ama Boateng", "insurerName": "Volta Assurance", "vehicleUse": "PRIVATE" } } }, "manual": { "summary": "Cover typed in from the certificate shown at the scene", "description": "Use this when the register has no answer for the vehicle.", "value": { "accidentDate": "2026-10-11", "place": "Kejetia, Kumasi", "damageKind": "BODILY", "cover": { "manual": { "certificateNumber": "TG-2026-0003310", "issuingCountry": "TG", "insurerName": "Lomé Assurances", "policyNumber": "LA-MOT-61877", "registration": "TG 5120 AD", "validFrom": "2026-05-01", "validTo": "2027-04-30", "holderName": "Afi Mensah" } } } } } } } }, "responses": { "201": { "description": "The claim was opened and is at `ACKNOWLEDGED`.", "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/OpenedClaim" }, "examples": { "opened": { "summary": "Claim opened", "value": { "id": "3b6e1f08-5c27-4d9a-8e41-7a02c9d5b316", "reference": "CLM-GH-2026-000142" } } } } } }, "400": { "description": "Bad request. The `code` in the body says which of these it is.\n\n- `VALIDATION`: A field is missing or not accepted, for example a `place` that is too short or a `cover` that is neither a lookup nor a manual entry; `errors` lists each one.\n- `FUTURE_DATE`: `accidentDate` is later than today.\n- `UNKNOWN_COUNTRY`: With cover typed in, `issuingCountry` is not a member state.", "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": "A field is missing or not accepted, for example a `place` that is too short or a `cover` that is neither a lookup nor a manual entry; `errors` lists each one.", "value": { "type": "urn:bc:problem:validation", "title": "Bad request", "status": 400, "code": "VALIDATION", "detail": "Some fields are missing or invalid.", "errors": [ { "path": "place", "message": "Too small: expected string to have >=3 characters" } ], "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } }, "FUTURE_DATE": { "summary": "400 FUTURE_DATE", "description": "`accidentDate` is later than today.", "value": { "type": "urn:bc:problem:future_date", "title": "Bad request", "status": 400, "code": "FUTURE_DATE", "detail": "The accident date cannot be in the future.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } }, "UNKNOWN_COUNTRY": { "summary": "400 UNKNOWN_COUNTRY", "description": "With cover typed in, `issuingCountry` is not a member state.", "value": { "type": "urn:bc:problem:unknown_country", "title": "Bad request", "status": 400, "code": "UNKNOWN_COUNTRY", "detail": "XX is not a member state.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } }, "401": { "description": "Unauthorized. The `code` in the body says which of these it is.\n\n- `UNAUTHENTICATED`: The key is missing, mistyped or revoked, or the session has expired.", "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": "The key is missing, mistyped or revoked, or the session has expired.", "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" } } } } } }, "403": { "description": "Forbidden. The `code` in the body says which of these it is.\n\n- `FORBIDDEN`: The key belongs to an organisation that is not a national bureau, or was created without `claim.open` (`detail` then reads \"You do not have permission to do this.\").", "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": { "FORBIDDEN": { "summary": "403 FORBIDDEN", "description": "The key belongs to an organisation that is not a national bureau, or was created without `claim.open` (`detail` then reads \"You do not have permission to do this.\").", "value": { "type": "urn:bc:problem:forbidden", "title": "Forbidden", "status": 403, "code": "FORBIDDEN", "detail": "Only a national bureau can open a cross-border claim.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } }, "409": { "description": "Conflict. The `code` in the body says which of these it is.\n\n- `COVER_NOT_FOUND`: The lookup found no certificate for the value on the accident date.\n- `NOT_CROSS_BORDER`: The certificate, found in the register or typed in, was issued in your own country.", "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": { "COVER_NOT_FOUND": { "summary": "409 COVER_NOT_FOUND", "description": "The lookup found no certificate for the value on the accident date.", "value": { "type": "urn:bc:problem:cover_not_found", "title": "Conflict", "status": 409, "code": "COVER_NOT_FOUND", "detail": "No certificate matches \"TG 9911 AD\" on 2026-10-10. Check the number, or enter the cover by hand.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } }, "NOT_CROSS_BORDER": { "summary": "409 NOT_CROSS_BORDER", "description": "The certificate, found in the register or typed in, was issued in your own country.", "value": { "type": "urn:bc:problem:not_cross_border", "title": "Conflict", "status": 409, "code": "NOT_CROSS_BORDER", "detail": "The accident happened in Ghana, the country that issued this certificate, so the claim is handled nationally with Volta Assurance.", "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 for this key. Try again in a minute.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } }, "503": { "description": "Unavailable. The `code` in the body says which of these it is.\n\n- `REGISTER_UNAVAILABLE`: A lookup was asked for and the certificate register did not answer. Repeat the call shortly, or send the cover as `manual`.", "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": { "REGISTER_UNAVAILABLE": { "summary": "503 REGISTER_UNAVAILABLE", "description": "A lookup was asked for and the certificate register did not answer. Repeat the call shortly, or send the cover as `manual`.", "value": { "type": "urn:bc:problem:register_unavailable", "title": "Unavailable", "status": 503, "code": "REGISTER_UNAVAILABLE", "detail": "The certificate register is not answering. Try again in a moment, or enter the cover by hand.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } } }, "summary": "Open a claim for an accident in your country", "tags": [ "Handle claims" ], "x-integrator": true, "x-permissions": [ "claim.open" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/claims/cover-lookup": { "post": { "description": "Use this before opening a claim, to see which certificate covered the vehicle that caused an accident in your country. Give the plate, the certificate number or the policy number in `value` and say which it is in `by`, then the day of the accident and the country where it happened. The country must be the country of your bureau.\n\nThe answer says whether a certificate was found (`found`), whether it was valid on that day (`inForce`), whether it covered the accident country (`coversAccidentCountry`) and whether the claim is a cross-border claim (`crossBorder`), meaning the certificate was issued in another country. `certificate` holds the certificate number, policy number, insurer, validity, plate, vehicle and policyholder. A plate matches whatever its spaces and hyphens. When several certificates match, the answer describes the one in force on that day.\n\nWhen `crossBorder` is false the accident happened in the country that issued the certificate and the claim is handled nationally with the insurer; `refusal` holds a sentence that says so and can be shown as it is. A certificate that was found and crosses the border can be used as the cover when you open a claim. When nothing is found, open the claim with the cover entered by hand.\n\n**Access.** Send an integration key or a signed-in session. The caller needs the permission `claim.open`; choose it when you create the key under Integrations → Integration keys.", "operationId": "lookUpCover", "parameters": [], "requestBody": { "required": true, "description": "What to look up and the accident it is for.", "content": { "application/json": { "schema": { "type": "object", "properties": { "by": { "type": "string", "enum": [ "plate", "certificate", "policy" ] }, "value": { "type": "string", "minLength": 2, "maxLength": 60 }, "accidentDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "accidentCountry": { "type": "string", "minLength": 2, "maxLength": 2 } }, "required": [ "by", "value", "accidentDate", "accidentCountry" ] }, "examples": { "byPlate": { "summary": "By plate, for an accident in Tema", "value": { "by": "plate", "value": "TG 1234 AB", "accidentDate": "2026-10-10", "accidentCountry": "GH" } }, "byCertificate": { "summary": "By certificate number, for an accident in Lomé", "description": "Sent with the key of the Togo bureau.", "value": { "by": "certificate", "value": "GH-2026-0004711", "accidentDate": "2026-09-28", "accidentCountry": "TG" } }, "byPolicy": { "summary": "By policy number", "value": { "by": "policy", "value": "LA-MOT-55102", "accidentDate": "2026-10-10", "accidentCountry": "GH" } } } } } }, "responses": { "200": { "description": "What the certificate register says about the vehicle on that day.", "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/CoverLookup" }, "examples": { "crossBorder": { "summary": "A Togolese certificate for an accident in Ghana", "value": { "found": true, "inForce": true, "coversAccidentCountry": true, "crossBorder": true, "refusal": null, "issuingCountry": "TG", "certificate": { "certificateId": "a6d3e1f9-4b27-4c85-8d06-5e92b7a1c430", "number": "TG-2026-0002056", "policyNumber": "LA-MOT-55102", "scope": "ECOWAS", "territories": [ "BJ", "BF", "CV", "CI", "GM", "GH", "GN", "GW", "LR", "ML", "NE", "NG", "SN", "SL", "TG" ], "validFrom": "2026-03-01", "validTo": "2027-02-28", "statusOnDate": "ISSUED", "insurerOrgId": "8f30d5a1-6c72-5e19-a4b8-2d7e91c0f463", "insurerName": "Lomé Assurances", "registration": "TG 1234 AB", "vehicle": "Toyota Hiace", "holderName": "Komi Agbeko" } } }, "national": { "summary": "A Ghanaian certificate for an accident in Ghana", "description": "The claim is handled nationally, so it cannot be opened as a cross-border claim.", "value": { "found": true, "inForce": true, "coversAccidentCountry": true, "crossBorder": false, "refusal": "The accident happened in Ghana, the country that issued this certificate, so the claim is handled nationally with Volta Assurance.", "issuingCountry": "GH", "certificate": { "certificateId": "7c1f0a52-3a8e-4b8d-9f6e-2d4a9c1b7e30", "number": "GH-2026-0004711", "policyNumber": "POL-GH-7781204", "scope": "ECOWAS", "territories": [ "BJ", "BF", "CV", "CI", "GM", "GH", "GN", "GW", "LR", "ML", "NE", "NG", "SN", "SL", "TG" ], "validFrom": "2026-01-15", "validTo": "2027-01-14", "statusOnDate": "ISSUED", "insurerOrgId": "0e6b3a14-52c8-5d7f-9a21-8b4f6c0d7e13", "insurerName": "Volta Assurance", "registration": "GR 4821-24", "vehicle": "Toyota Corolla", "holderName": "Kojo Essien" } } }, "notFound": { "summary": "No certificate matches", "value": { "found": false, "inForce": false, "coversAccidentCountry": null, "crossBorder": false, "refusal": null, "issuingCountry": null, "certificate": null } } } } } }, "400": { "description": "Bad request. The `code` in the body says which of these it is.\n\n- `VALIDATION`: A field is missing or not accepted, for example a date that is not `YYYY-MM-DD`; `errors` lists each one.", "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": "A field is missing or not accepted, for example a date that is not `YYYY-MM-DD`; `errors` lists each one.", "value": { "type": "urn:bc:problem:validation", "title": "Bad request", "status": 400, "code": "VALIDATION", "detail": "Some fields are missing or invalid.", "errors": [ { "path": "accidentDate", "message": "Use the format YYYY-MM-DD" } ], "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } }, "401": { "description": "Unauthorized. The `code` in the body says which of these it is.\n\n- `UNAUTHENTICATED`: The key is missing, mistyped or revoked, or the session has expired.", "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": "The key is missing, mistyped or revoked, or the session has expired.", "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" } } } } } }, "403": { "description": "Forbidden. The `code` in the body says which of these it is.\n\n- `FORBIDDEN`: `accidentCountry` is not the country of the bureau that owns the key, or the key was created without `claim.open` (`detail` then reads \"You do not have permission to do this.\").", "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": { "FORBIDDEN": { "summary": "403 FORBIDDEN", "description": "`accidentCountry` is not the country of the bureau that owns the key, or the key was created without `claim.open` (`detail` then reads \"You do not have permission to do this.\").", "value": { "type": "urn:bc:problem:forbidden", "title": "Forbidden", "status": 403, "code": "FORBIDDEN", "detail": "You open claims for accidents in Ghana.", "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 for this key. Try again in a minute.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } }, "503": { "description": "Unavailable. The `code` in the body says which of these it is.\n\n- `REGISTER_UNAVAILABLE`: The certificate register did not answer. Repeat the lookup shortly.", "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": { "REGISTER_UNAVAILABLE": { "summary": "503 REGISTER_UNAVAILABLE", "description": "The certificate register did not answer. Repeat the lookup shortly.", "value": { "type": "urn:bc:problem:register_unavailable", "title": "Unavailable", "status": 503, "code": "REGISTER_UNAVAILABLE", "detail": "The certificate register is not answering. Try again in a moment, or enter the cover by hand.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } } }, "summary": "Look up the cover a vehicle had on the day of an accident", "tags": [ "Handle claims" ], "x-integrator": true, "x-permissions": [ "claim.open" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/claims/{id}": { "get": { "description": "Use this to read one claim in full: where and when the accident happened, the cover, the vehicles involved, the stage the claim has reached, the timeline of what happened, the attached documents and the Convention time limits that apply. Take the `id` from the list of claims or from the answer to opening a claim.\n\n`role` says how you relate to the claim: `HANDLING` for the bureau of the accident country, `ISSUING` for the bureau of the country that issued the certificate, `OBSERVER` for an insurer on whose certificate it was made. The handling bureau also receives the reporter’s contact details in `reporter`, and the names of the people in `parties` are shown to bureaux and insurers.\n\nThe sections for assessments, offers, payments, notices, demands and arbitrations fill in as the bureaux work on the claim and are empty before that. `deadlines` lists each Convention time limit with the day it falls due and its state, and `actions` lists what the platform offers you on the claim now.\n\n**Access.** Send an integration key or a signed-in session. The caller needs the permission `claim.read`; choose it when you create the key under Integrations → Integration keys.", "operationId": "getClaim", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the claim: the `id` in the list of claims or in the answer to opening a claim. The reference is a different value.", "schema": { "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)$" }, "example": "3b6e1f08-5c27-4d9a-8e41-7a02c9d5b316" } ], "responses": { "200": { "description": "The claim with everything you may see.", "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/Claim" }, "examples": { "opened": { "summary": "A claim opened by the bureau, with cover from the register", "value": { "id": "3b6e1f08-5c27-4d9a-8e41-7a02c9d5b316", "reference": "CLM-GH-2026-000142", "status": "ACKNOWLEDGED", "statusReason": null, "accidentCountry": "GH", "issuingCountry": "TG", "handlingBureauOrgId": "5a1c7e92-3d04-5b68-9f27-c81e0a4d6b35", "issuingBureauOrgId": "e4d92b60-17a3-5c8f-b0d6-39f5a71c2e84", "insurerOrgId": "8f30d5a1-6c72-5e19-a4b8-2d7e91c0f463", "certificateNumber": "TG-2026-0002056", "coverConfirmed": true, "coversAccidentCountry": true, "cover": { "certificateId": "a6d3e1f9-4b27-4c85-8d06-5e92b7a1c430", "number": "TG-2026-0002056", "policyId": "19b4c7e2-8a3d-4f61-a9c5-d02e6b38f714", "policyNumber": "LA-MOT-55102", "insurerOrgId": "8f30d5a1-6c72-5e19-a4b8-2d7e91c0f463", "insurerName": "Lomé Assurances", "insurerCode": "TG-LOME", "country": "TG", "scope": "ECOWAS", "territories": [ "BJ", "BF", "CV", "CI", "GM", "GH", "GN", "GW", "LR", "ML", "NE", "NG", "SN", "SL", "TG" ], "validFrom": "2026-03-01", "validTo": "2027-02-28", "status": "ISSUED", "version": 1, "kind": "CERTIFICATE", "vehicle": { "registration": "TG 1234 AB", "registrationKey": "TG1234AB", "vin": null, "make": "Toyota", "model": "Hiace", "category": "MINIBUS" }, "holder": { "maskedName": "K. A*****", "ref": "d7a31c58-0e94-4b62-a1f3-85c6b9e2d047" }, "source": "API", "sourceSystem": null, "keyId": "TG-2026-1", "issuedAt": "2026-03-01T08:30:12.000Z", "renewalOf": null, "asOf": "2026-10-10", "statusOnDate": "ISSUED", "inForce": true, "coversAccidentCountry": true, "vehicleUse": "COMMERCIAL" }, "accidentDate": "2026-10-10", "accidentPlace": "Tema Motorway roundabout, Tema", "lat": 5.6698, "lng": -0.0166, "description": "The minibus ran into the back of a stationary car at the roundabout.", "damageKind": "MATERIAL", "reportedBy": "BUREAU", "reporter": { "name": null, "phone": null, "email": null }, "facts": { "policeReportOn": null, "insurerNotifiedOn": null, "deathOn": null, "documentsCompleteOn": null, "consolidationNotifiedOn": null, "victimAbroad": false }, "createdAt": "2026-10-12T09:41:07.236Z", "updatedAt": "2026-10-12T09:41:07.241Z", "currency": "GHS", "role": "HANDLING", "parties": [ { "id": "0b7d5e21-94c3-4a68-8f10-6c3a2e9d1b57", "role": "AT_FAULT", "registration": "TG 1234 AB", "country": "TG", "name": "Komi Agbeko", "insurerName": "Lomé Assurances", "vehicleUse": null, "vehicle": "Toyota Hiace" }, { "id": "f4c19a63-2b80-4d75-9e3a-a7518d0c6e24", "role": "VICTIM", "registration": "GT 3342-25", "country": "GH", "name": "Ama Boateng", "insurerName": "Volta Assurance", "vehicleUse": "PRIVATE", "vehicle": null } ], "route": null, "assessments": [], "offers": [], "payments": [], "notices": [], "demands": [], "arbitrations": [], "documents": [], "unlinkedDocumentIds": [], "events": [ { "id": "6e2a9c40-b1d7-4f83-a05c-3d84e7b19f62", "type": "STATUS", "from": "REPORTED", "to": "ACKNOWLEDGED", "note": null, "event": { "kind": "STATUS_CHANGED", "params": { "from": "REPORTED", "to": "ACKNOWLEDGED", "reason": null } }, "at": "2026-10-12T09:41:07.241Z", "byOrg": "5a1c7e92-3d04-5b68-9f27-c81e0a4d6b35" }, { "id": "9d03f5b8-6a4e-4c21-b7d9-12c8a0e5f376", "type": "STATUS", "from": null, "to": "REPORTED", "note": null, "event": { "kind": "STATUS_CHANGED", "params": { "from": null, "to": "REPORTED", "reason": null } }, "at": "2026-10-12T09:41:07.236Z", "byOrg": "5a1c7e92-3d04-5b68-9f27-c81e0a4d6b35" } ], "deadlines": [ { "kind": "POLICE_REPORT", "dueOn": "2026-12-10", "article": "Arts. 31, 81", "basis": "The police report reaches the insurer within two months of the accident", "party": "POLICE", "state": "OPEN", "doneOn": null, "daysLeft": 59 }, { "kind": "LIMITATION", "dueOn": "2031-10-10", "article": "Art. 57", "basis": "Claims are time-barred five years after the accident", "party": "VICTIM", "state": "OPEN", "doneOn": null, "daysLeft": 1824 } ], "actions": [ "attachCover", "decline", "withdraw" ] } }, "reported": { "summary": "A claim reported by a member of the public, cover not yet attached", "value": { "id": "c2a8d417-96f3-4e0b-b5d2-18e7f40a3c69", "reference": "CLM-GH-2026-000141", "status": "REPORTED", "statusReason": null, "accidentCountry": "GH", "issuingCountry": null, "handlingBureauOrgId": "5a1c7e92-3d04-5b68-9f27-c81e0a4d6b35", "issuingBureauOrgId": null, "insurerOrgId": null, "certificateNumber": null, "coverConfirmed": false, "coversAccidentCountry": null, "cover": null, "accidentDate": "2026-10-09", "accidentPlace": "Spintex Road, near Baatsona, Accra", "lat": 5.6372, "lng": -0.1012, "description": "A minibus pulled out of a side road and hit the left side of my car. Nobody was hurt.", "damageKind": "MATERIAL", "reportedBy": "PUBLIC", "reporter": { "name": "Yaw Darko", "phone": "+233244310042", "email": "yaw.darko@example.org" }, "facts": { "policeReportOn": null, "insurerNotifiedOn": null, "deathOn": null, "documentsCompleteOn": null, "consolidationNotifiedOn": null, "victimAbroad": false }, "createdAt": "2026-10-09T17:22:41.380Z", "updatedAt": "2026-10-09T17:22:41.380Z", "currency": "GHS", "role": "HANDLING", "parties": [ { "id": "84a6c3d1-5f92-4e07-b1a8-0d7e2c9f4a35", "role": "VICTIM", "registration": "AS 4410-24", "country": "GH", "name": "Yaw Darko", "insurerName": "Volta Assurance", "vehicleUse": null, "vehicle": null }, { "id": "c5190e7a-3d68-4b24-9a51-e8f3b60d2c97", "role": "AT_FAULT", "registration": "TG 8842 AC", "country": "TG", "name": null, "insurerName": "Lomé Assurances", "vehicleUse": null, "vehicle": null } ], "route": null, "assessments": [], "offers": [], "payments": [], "notices": [], "demands": [], "arbitrations": [], "documents": [], "unlinkedDocumentIds": [], "events": [ { "id": "2f8b4d96-a0c5-4e13-8b72-5c1e9d3a6f08", "type": "STATUS", "from": null, "to": "REPORTED", "note": null, "event": { "kind": "STATUS_CHANGED", "params": { "from": null, "to": "REPORTED", "reason": null } }, "at": "2026-10-09T17:22:41.380Z", "byOrg": null } ], "deadlines": [ { "kind": "POLICE_REPORT", "dueOn": "2026-12-09", "article": "Arts. 31, 81", "basis": "The police report reaches the insurer within two months of the accident", "party": "POLICE", "state": "OPEN", "doneOn": null, "daysLeft": 58 }, { "kind": "LIMITATION", "dueOn": "2031-10-09", "article": "Art. 57", "basis": "Claims are time-barred five years after the accident", "party": "VICTIM", "state": "OPEN", "doneOn": null, "daysLeft": 1823 } ], "actions": [ "attachCover", "decline", "acknowledge", "withdraw" ] } } } } } }, "401": { "description": "Unauthorized. The `code` in the body says which of these it is.\n\n- `UNAUTHENTICATED`: The key is missing, mistyped or revoked, or the session has expired.", "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": "The key is missing, mistyped or revoked, or the session has expired.", "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" } } } } } }, "403": { "description": "Forbidden. The `code` in the body says which of these it is.\n\n- `FORBIDDEN`: The key was created without the permission this operation needs.", "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": { "FORBIDDEN": { "summary": "403 FORBIDDEN", "description": "The key was created without the permission this operation needs.", "value": { "type": "urn:bc:problem:forbidden", "title": "Forbidden", "status": 403, "code": "FORBIDDEN", "detail": "You do not have permission to do this.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } }, "404": { "description": "Not found. The `code` in the body says which of these it is.\n\n- `NOT_FOUND`: No claim with this id exists among the claims you can see.", "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_FOUND": { "summary": "404 NOT_FOUND", "description": "No claim with this id exists among the claims you can see.", "value": { "type": "urn:bc:problem:not_found", "title": "Not found", "status": 404, "code": "NOT_FOUND", "detail": "The claim was not found.", "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 for this key. Try again in a minute.", "correlationId": "9f2b1c64-3d0e-4a57-b8c1-6e7d5a0f4b21" } } } } } } }, "summary": "Get a claim", "tags": [ "Handle claims" ], "x-integrator": true, "x-permissions": [ "claim.read" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } } }, "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": { "ReportReceipt": { "type": "object", "properties": { "reference": { "type": "string", "description": "The reference of the new claim: `CLM-`, the country of the accident, the year and a six-digit number. Keep it: with the reporter’s phone number it is how the claim is followed.", "example": "CLM-GH-2026-000141" } }, "required": [ "reference" ], "description": "The answer to reporting an accident." }, "TrackingCodeRequest": { "type": "object", "properties": { "sent": { "type": "boolean", "enum": [ true ], "description": "Always `true`: the answer is the same for every request, whether or not a code was sent." }, "expiresInMinutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How long a code works, counted from the moment it is sent.", "example": 10 } }, "required": [ "sent", "expiresInMinutes" ], "description": "The answer to asking for a code." }, "ClaimStatus": { "type": "object", "properties": { "reference": { "type": "string", "example": "CLM-GH-2026-000141" }, "stage": { "type": "string", "enum": [ "REPORTED", "ACKNOWLEDGED", "ASSESSING", "OFFERED", "PAID", "CLOSED", "DECLINED", "WITHDRAWN" ], "description": "`REPORTED`: the report is in. `ACKNOWLEDGED`: the national bureau has received it. `ASSESSING`: the damage is being assessed. `OFFERED`: compensation has been offered or agreed. `PAID`: compensation has been paid; the claim stays here while the bureaux settle between themselves. `CLOSED`: the claim is finished. `DECLINED`: the bureau did not accept the claim. `WITHDRAWN`: the claim was withdrawn.", "example": "ASSESSING" }, "stageLabel": { "type": "string", "description": "The name of the stage in the language you asked for, ready to show.", "example": "Damage being assessed" }, "accidentDate": { "type": "string", "description": "The day of the accident, `YYYY-MM-DD`." }, "accidentCountry": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Two-letter code of the country where the accident happened." }, "reportedOn": { "type": "string", "description": "The day the claim was created, `YYYY-MM-DD`." }, "updatedOn": { "type": "string", "description": "The day the claim was last updated, `YYYY-MM-DD`." }, "steps": { "type": "array", "items": { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "REPORTED", "ACKNOWLEDGED", "ASSESSING", "OFFERED", "PAID", "CLOSED" ] }, "label": { "type": "string", "description": "The name of the step, in the same language." }, "reached": { "type": "boolean", "description": "True for this step and every step before it. Nothing is reached for a declined or withdrawn claim." }, "current": { "type": "boolean", "description": "True for the step the claim is at." } }, "required": [ "stage", "label", "reached", "current" ] }, "description": "The six steps of a claim in order, for a progress display: reported, received by the bureau, assessed, offered, paid, closed." } }, "required": [ "reference", "stage", "stageLabel", "accidentDate", "accidentCountry", "reportedOn", "updatedOn", "steps" ], "description": "Where a claim stands, safe to show to the reporter." }, "ClaimSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the claim. Use it to read the claim.", "example": "3b6e1f08-5c27-4d9a-8e41-7a02c9d5b316" }, "reference": { "type": "string", "description": "The reference people quote: `CLM-`, the accident country, the year, a number.", "example": "CLM-GH-2026-000142" }, "status": { "$ref": "#/components/schemas/ClaimStage" }, "accidentCountry": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Two-letter code of the country where the accident happened." }, "issuingCountry": { "nullable": true, "description": "Two-letter code of the country that issued the certificate; null until cover is attached.", "type": "string" }, "accidentDate": { "type": "string", "description": "The day of the accident, `YYYY-MM-DD`." }, "plate": { "nullable": true, "description": "The plate of the vehicle at fault, or of the first vehicle listed.", "example": "TG 1234 AB", "type": "string" }, "certificateNumber": { "nullable": true, "description": "The certificate the claim is made on; null until cover is attached.", "example": "TG-2026-0002056", "type": "string" }, "coverConfirmed": { "type": "boolean", "description": "True when the certificate was found in the certificate register. False when the cover was typed in or is not attached yet." }, "amountUa": { "nullable": true, "description": "The amount recoverable from the issuing bureau once the damage is assessed, in hundredths of a unit of account (UA); null before that.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "nextDeadline": { "nullable": true, "description": "The next time limit someone has to act on; null when the claim is finished or none is running.", "allOf": [ { "$ref": "#/components/schemas/Deadline" } ] }, "updatedAt": { "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 claim last changed." } }, "required": [ "id", "reference", "status", "accidentCountry", "issuingCountry", "accidentDate", "plate", "certificateNumber", "coverConfirmed", "amountUa", "nextDeadline", "updatedAt" ], "description": "A claim as it appears in a list." }, "ClaimStage": { "type": "string", "enum": [ "REPORTED", "ACKNOWLEDGED", "ASSESSING", "OFFERED", "AGREED", "PAID", "RECOVERY", "DEMANDED", "REIMBURSED", "DISPUTED", "ARBITRATION", "CLOSED", "DECLINED", "WITHDRAWN" ], "description": "`REPORTED`: reported, not yet taken by the handling bureau. `ACKNOWLEDGED`: taken by the handling bureau. `ASSESSING`: the damage is being assessed. `OFFERED`: an offer was made to the victim. `AGREED`: the victim accepted. `PAID`: the victim was paid. `RECOVERY`: the handling bureau has told the issuing bureau. `DEMANDED`: reimbursement was claimed. `REIMBURSED`: the issuing bureau reimbursed. `DISPUTED` and `ARBITRATION`: the claim is contested. `CLOSED`: finished. `DECLINED`: not accepted. `WITHDRAWN`: withdrawn.", "example": "ACKNOWLEDGED" }, "Deadline": { "type": "object", "properties": { "kind": { "type": "string", "description": "What the time limit is for, for example `POLICE_REPORT`, `OFFER`, `VICTIM_PAYMENT`, `NOTICE_ANSWER`, `REIMBURSEMENT` or `LIMITATION`.", "example": "POLICE_REPORT" }, "dueOn": { "type": "string", "description": "The day it falls due, `YYYY-MM-DD`." }, "article": { "type": "string", "description": "The article of the Convention that sets the limit.", "example": "Arts. 31, 81" }, "basis": { "type": "string", "description": "The rule in a sentence.", "example": "The police report reaches the insurer within two months of the accident" }, "party": { "type": "string", "enum": [ "POLICE", "HANDLING_BUREAU", "ISSUING_BUREAU", "VICTIM" ], "description": "Who has to act." }, "state": { "type": "string", "enum": [ "OPEN", "OVERDUE", "MET", "LATE", "SUSPENDED", "CLOSED" ], "description": "`OPEN`: still running. `OVERDUE`: passed with nothing done. `MET`: done in time. `LATE`: done after the day. `SUSPENDED`: the clock is stopped. `CLOSED`: the window has closed." }, "doneOn": { "nullable": true, "description": "The day it was done, if it has been.", "type": "string" }, "daysLeft": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Days from today to `dueOn`; negative once the day has passed." } }, "required": [ "kind", "dueOn", "article", "basis", "party", "state", "doneOn", "daysLeft" ], "description": "A time limit of the Convention that applies to a claim." }, "OpenedClaim": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the claim.", "example": "3b6e1f08-5c27-4d9a-8e41-7a02c9d5b316" }, "reference": { "type": "string", "description": "The reference to quote, such as `CLM-GH-2026-000142`.", "example": "CLM-GH-2026-000142" } }, "required": [ "id", "reference" ], "description": "The claim that was opened." }, "CoverLookup": { "type": "object", "properties": { "found": { "type": "boolean", "description": "True when a certificate matches the plate, certificate number or policy number you gave. One that was not in force on the day is still returned, with `inForce` false." }, "inForce": { "type": "boolean", "description": "True when the certificate was valid on the day of the accident." }, "coversAccidentCountry": { "nullable": true, "description": "True when the certificate covered the accident country on that day, false when it did not, null when no certificate was found.", "type": "boolean" }, "crossBorder": { "type": "boolean", "description": "True when the certificate was issued in another country than the one where the accident happened. Only then can a claim be opened on it." }, "refusal": { "nullable": true, "description": "A sentence to show when the certificate was issued in the accident country, so the claim is handled nationally; null otherwise.", "type": "string" }, "issuingCountry": { "nullable": true, "description": "Two-letter code of the country that issued the certificate.", "type": "string" }, "certificate": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CoverCertificate" } ] } }, "required": [ "found", "inForce", "coversAccidentCountry", "crossBorder", "refusal", "issuingCountry", "certificate" ], "description": "The cover found for a vehicle on the day." }, "CoverCertificate": { "type": "object", "properties": { "certificateId": { "type": "string" }, "number": { "type": "string", "example": "TG-2026-0002056" }, "policyNumber": { "type": "string" }, "scope": { "type": "string", "enum": [ "NATIONAL", "ECOWAS" ], "description": "`NATIONAL` covers the issuing country only. `ECOWAS` is the Brown Card." }, "territories": { "type": "array", "items": { "type": "string" }, "description": "The countries a Brown Card covers." }, "validFrom": { "type": "string" }, "validTo": { "type": "string" }, "statusOnDate": { "nullable": true, "description": "The status of the certificate on the day of the accident.", "type": "string", "enum": [ "ISSUED", "SUSPENDED", "CANCELLED", "EXPIRED", "REPLACED" ] }, "insurerOrgId": { "type": "string" }, "insurerName": { "type": "string" }, "registration": { "type": "string", "description": "The plate the certificate was issued for." }, "vehicle": { "nullable": true, "description": "Make and model.", "example": "Toyota Hiace", "type": "string" }, "holderName": { "nullable": true, "description": "The policyholder’s full name.", "type": "string" } }, "required": [ "certificateId", "number", "policyNumber", "scope", "territories", "validFrom", "validTo", "statusOnDate", "insurerOrgId", "insurerName", "registration", "vehicle", "holderName" ], "description": "The certificate that applied on the day." }, "Claim": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the claim.", "example": "3b6e1f08-5c27-4d9a-8e41-7a02c9d5b316" }, "reference": { "type": "string", "example": "CLM-GH-2026-000142" }, "status": { "$ref": "#/components/schemas/ClaimStage" }, "statusReason": { "nullable": true, "description": "The reason given when the claim was declined or withdrawn.", "type": "string" }, "accidentCountry": { "type": "string", "minLength": 2, "maxLength": 2, "description": "The country where the accident happened. Its national bureau handles the claim." }, "issuingCountry": { "nullable": true, "description": "The country that issued the certificate; null until cover is attached.", "type": "string" }, "handlingBureauOrgId": { "type": "string", "description": "The national bureau handling the claim." }, "issuingBureauOrgId": { "nullable": true, "description": "The national bureau of the country that issued the certificate.", "type": "string" }, "insurerOrgId": { "nullable": true, "description": "The insurer that issued the certificate, when it is on the platform.", "type": "string" }, "certificateNumber": { "nullable": true, "type": "string" }, "coverConfirmed": { "type": "boolean", "description": "True when the certificate was found in the certificate register. False when the cover was typed in or is not attached yet." }, "coversAccidentCountry": { "nullable": true, "description": "Whether the certificate covered the accident country on the day; null when that was not checked.", "type": "boolean" }, "cover": { "nullable": true, "description": "The certificate as it stood on the day of the accident: number, insurer, validity, territories and vehicle. Null until cover is attached.", "type": "object", "additionalProperties": {} }, "accidentDate": { "type": "string", "description": "The day of the accident, `YYYY-MM-DD`." }, "accidentPlace": { "type": "string" }, "lat": { "nullable": true, "type": "number" }, "lng": { "nullable": true, "type": "number" }, "description": { "nullable": true, "type": "string" }, "damageKind": { "type": "string", "description": "`MATERIAL`, `BODILY` or `BOTH`.", "example": "MATERIAL" }, "reportedBy": { "type": "string", "description": "Who reported the accident: `PUBLIC`, `POLICYHOLDER`, `BUREAU`, `INSURER` or `USSD`.", "example": "BUREAU" }, "reporter": { "nullable": true, "description": "The reporter’s contact details. Shown to the handling bureau and to the policyholder who reported; null for everyone else.", "type": "object", "properties": { "name": { "nullable": true, "type": "string" }, "phone": { "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" } }, "required": [ "name", "phone", "email" ] }, "facts": { "type": "object", "properties": { "policeReportOn": { "nullable": true, "type": "string" }, "insurerNotifiedOn": { "nullable": true, "type": "string" }, "deathOn": { "nullable": true, "type": "string" }, "documentsCompleteOn": { "nullable": true, "type": "string" }, "consolidationNotifiedOn": { "nullable": true, "type": "string" }, "victimAbroad": { "type": "boolean" } }, "required": [ "policeReportOn", "insurerNotifiedOn", "deathOn", "documentsCompleteOn", "consolidationNotifiedOn", "victimAbroad" ], "description": "The dates the handling bureau has recorded. The Convention time limits in `deadlines` are counted from them." }, "createdAt": { "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))$" }, "updatedAt": { "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))$" }, "currency": { "nullable": true, "description": "The national currency of the accident country, in which the victim is paid.", "example": "GHS", "type": "string" }, "role": { "type": "string", "enum": [ "HANDLING", "ISSUING", "REPORTER", "OBSERVER" ], "description": "How you relate to this claim. `HANDLING`: the bureau of the accident country. `ISSUING`: the bureau of the country that issued the certificate. `REPORTER`: the policyholder who reported it. `OBSERVER`: anyone else who can see it, such as the insurer." }, "parties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "AT_FAULT", "VICTIM", "WITNESS" ], "description": "`AT_FAULT`, `VICTIM` or `WITNESS`." }, "registration": { "nullable": true, "type": "string" }, "country": { "nullable": true, "type": "string" }, "name": { "nullable": true, "description": "Shown to bureaux and insurers; null for everyone else.", "type": "string" }, "insurerName": { "nullable": true, "type": "string" }, "vehicleUse": { "nullable": true, "type": "string" }, "vehicle": { "nullable": true, "type": "string" } }, "required": [ "id", "role", "registration", "country", "name", "insurerName", "vehicleUse", "vehicle" ] }, "description": "The vehicles and people involved." }, "route": { "nullable": true, "description": "How the handling bureau tells the issuing bureau about a payment, which depends on the amount. Null until the damage is assessed.", "type": "object", "properties": { "route": { "type": "string", "enum": [ "SETTLE_AND_NOTIFY", "PRIOR_APPROVAL" ] }, "answerMonths": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "article": { "type": "string" }, "basis": { "type": "string" } }, "required": [ "route", "answerMonths", "article", "basis" ] }, "assessments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Each new assessment of a claim has the next number." }, "liabilityBasis": { "type": "string" }, "liabilityPercent": { "type": "number" }, "liabilityArticle": { "type": "string" }, "inputs": { "type": "object", "additionalProperties": {} }, "heads": { "type": "array", "items": { "type": "object", "properties": { "head": { "type": "string", "enum": [ "REPAIR", "LOSS_OF_USE", "TOWING", "SURVEYOR", "REPORT", "OTHER_LOSS" ] }, "article": { "type": "string" }, "claimedUa": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "allowedUa": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "capUa": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "capped": { "type": "boolean" }, "basis": { "type": "string" } }, "required": [ "head", "article", "claimedUa", "allowedUa", "capUa", "capped", "basis" ] } }, "totalUa": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "recoverableUa": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "totalLocal": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "recoverableLocal": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string" }, "ratePerUa": { "type": "string" }, "rateDate": { "type": "string", "description": "`YYYY-MM-DD`." }, "note": { "nullable": true, "type": "string" }, "createdAt": { "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": [ "id", "version", "liabilityBasis", "liabilityPercent", "liabilityArticle", "inputs", "heads", "totalUa", "recoverableUa", "totalLocal", "recoverableLocal", "currency", "ratePerUa", "rateDate", "note", "createdAt" ] }, "description": "Assessments of the damage, newest first. Empty until the damage is assessed." }, "offers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string" }, "amountUa": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "madeOn": { "type": "string", "description": "`YYYY-MM-DD`." }, "response": { "nullable": true, "type": "string" }, "respondedOn": { "nullable": true, "type": "string", "description": "`YYYY-MM-DD`." }, "lateInterest": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdAt": { "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": [ "id", "kind", "amount", "currency", "amountUa", "madeOn", "response", "respondedOn", "lateInterest", "createdAt" ] }, "description": "Offers made to the victim, newest first." }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string" }, "amountUa": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "paidOn": { "type": "string", "description": "`YYYY-MM-DD`." }, "reference": { "type": "string" }, "createdAt": { "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))$" }, "lateInterest": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "dueOn": { "nullable": true, "type": "string", "description": "`YYYY-MM-DD`." } }, "required": [ "id", "amount", "currency", "amountUa", "paidOn", "reference", "createdAt", "lateInterest", "dueOn" ] }, "description": "Payments made to the victim." }, "notices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "route": { "type": "string", "enum": [ "SETTLE_AND_NOTIFY", "PRIOR_APPROVAL" ] }, "amountUa": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amountLocal": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string" }, "sentOn": { "type": "string", "description": "`YYYY-MM-DD`." }, "sentAt": { "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))$" }, "answerDueOn": { "type": "string", "description": "`YYYY-MM-DD`." }, "answer": { "nullable": true, "type": "string", "enum": [ "APPROVED", "REJECTED" ] }, "deemed": { "type": "boolean" }, "reason": { "nullable": true, "type": "string" }, "answeredAt": { "nullable": true, "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))$" }, "pending": { "type": "boolean" } }, "required": [ "id", "route", "amountUa", "amountLocal", "currency", "sentOn", "sentAt", "answerDueOn", "answer", "deemed", "reason", "answeredAt", "pending" ] }, "description": "Notices from the handling bureau to the issuing bureau about a payment." }, "demands": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "noticeId": { "nullable": true, "type": "string" }, "amountUa": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amountLocal": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string" }, "ratePerUa": { "type": "string" }, "rateDate": { "type": "string", "description": "`YYYY-MM-DD`." }, "notifiedOn": { "type": "string", "description": "`YYYY-MM-DD`." }, "rejectBy": { "nullable": true, "type": "string", "description": "`YYYY-MM-DD`." }, "dueOn": { "type": "string", "description": "`YYYY-MM-DD`." }, "interestFrom": { "type": "string", "description": "`YYYY-MM-DD`." }, "status": { "type": "string", "enum": [ "OPEN", "ACCEPTED", "REJECTED", "DUE", "PAID", "DISPUTED" ] }, "deemed": { "type": "boolean" }, "rejectionReason": { "nullable": true, "type": "string" }, "answeredAt": { "nullable": true, "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))$" }, "declaredReference": { "nullable": true, "type": "string" }, "declaredOn": { "nullable": true, "type": "string", "description": "`YYYY-MM-DD`." }, "declaredAmount": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "confirmedOn": { "nullable": true, "type": "string", "description": "`YYYY-MM-DD`." }, "interestAccrued": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdAt": { "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))$" }, "pendingDeclaration": { "nullable": true, "description": "The payment the issuing bureau declared, while the handling bureau has not confirmed it. A second declaration is refused with `PAYMENT_ALREADY_DECLARED`.", "type": "object", "properties": { "reference": { "type": "string" }, "paidOn": { "type": "string", "description": "`YYYY-MM-DD`." }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string" }, "owed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Principal and interest at `paidOn`, in minor units." }, "short": { "type": "boolean", "description": "True when the payment is less than principal and interest at its date, so it cannot be confirmed and the full payment is declared again." } }, "required": [ "reference", "paidOn", "amount", "currency", "owed", "short" ] }, "position": { "type": "object", "properties": { "asOf": { "type": "string", "description": "`YYYY-MM-DD`." }, "article": { "type": "string" }, "interestFrom": { "type": "string", "description": "`YYYY-MM-DD`." }, "lines": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "description": "`YYYY-MM-DD`." }, "to": { "type": "string", "description": "`YYYY-MM-DD`." }, "days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "percent": { "type": "number" }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amountUa": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "from", "to", "days", "percent", "amount", "amountUa" ] } }, "interest": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "interestUa": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "owed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "owedUa": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "asOf", "article", "interestFrom", "lines", "interest", "interestUa", "owed", "owedUa" ] } }, "required": [ "id", "noticeId", "amountUa", "amountLocal", "currency", "ratePerUa", "rateDate", "notifiedOn", "rejectBy", "dueOn", "interestFrom", "status", "deemed", "rejectionReason", "answeredAt", "declaredReference", "declaredOn", "declaredAmount", "confirmedOn", "interestAccrued", "createdAt", "pendingDeclaration", "position" ] }, "description": "Requests from the handling bureau to the issuing bureau for reimbursement." }, "arbitrations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "demandId": { "nullable": true, "type": "string" }, "noticeId": { "nullable": true, "type": "string" }, "arbitrators": { "type": "array", "items": { "type": "string" } }, "documentIds": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "outcome": { "nullable": true, "type": "string" }, "decidedOn": { "nullable": true, "type": "string", "description": "`YYYY-MM-DD`." }, "awardAmount": { "nullable": true, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "nullable": true, "type": "string" }, "note": { "nullable": true, "type": "string" }, "createdAt": { "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": [ "id", "demandId", "noticeId", "arbitrators", "documentIds", "status", "outcome", "decidedOn", "awardAmount", "currency", "note", "createdAt" ] }, "description": "Arbitrations on the claim." }, "documents": { "type": "array", "items": { "type": "object", "properties": { "documentId": { "type": "string" }, "kind": { "type": "string" }, "filename": { "nullable": true, "type": "string" }, "addedAt": { "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": [ "documentId", "kind", "filename", "addedAt" ] }, "description": "Documents and photos attached to the claim." }, "unlinkedDocumentIds": { "description": "Photos of the report that are still being attached.", "type": "array", "items": { "type": "string" } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "description": "For example `STATUS`, `COVER` or `DOCUMENT`." }, "from": { "nullable": true, "type": "string" }, "to": { "nullable": true, "type": "string" }, "note": { "nullable": true, "type": "string" }, "event": { "nullable": true, "description": "What happened, with its values, for wording in the reader’s language. Null on older entries.", "type": "object", "properties": { "kind": { "type": "string", "enum": [ "CLAIM_REPORTED", "STATUS_CHANGED", "OPENED_WITH_MANUAL_COVER", "COVER_FOUND", "COVER_ENTERED", "FACTS_RECORDED", "DOCUMENT_ADDED", "ASSESSMENT_SAVED", "OFFER_MADE", "OFFER_ACCEPTED", "OFFER_REFUSED", "OFFER_DENOUNCED", "VICTIM_PAID", "SETTLEMENT_NOTIFIED", "APPROVAL_REQUESTED", "NOTICE_APPROVED", "NOTICE_REJECTED", "NOTICE_DEEMED_APPROVED", "DEMAND_RAISED", "DEMAND_ACCEPTED", "DEMAND_REJECTED", "DEMAND_DUE", "REIMBURSEMENT_DECLARED", "REIMBURSEMENT_CONFIRMED", "ARBITRATION_OPENED", "ARBITRATION_DECIDED" ], "description": "What happened, as a stable code." }, "params": { "type": "object", "additionalProperties": {}, "description": "The values to word it with. They depend on `kind`." } }, "required": [ "kind", "params" ] }, "at": { "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))$" }, "byOrg": { "nullable": true, "type": "string" } }, "required": [ "id", "type", "from", "to", "note", "event", "at", "byOrg" ] }, "description": "The timeline of the claim, newest first." }, "deadlines": { "type": "array", "items": { "$ref": "#/components/schemas/Deadline" }, "description": "Every Convention time limit that applies now, soonest first." }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "attachCover", "acknowledge", "decline", "withdraw", "recordFacts", "assess", "offer", "respondOffer", "pay", "sendNotice", "answerNotice", "raiseDemand", "answerDemand", "declarePayment", "confirmPayment", "openArbitration", "decideArbitration", "close", "upload" ] }, "description": "What the platform offers you to do on this claim now, given your role and its stage." } }, "required": [ "id", "reference", "status", "statusReason", "accidentCountry", "issuingCountry", "handlingBureauOrgId", "issuingBureauOrgId", "insurerOrgId", "certificateNumber", "coverConfirmed", "coversAccidentCountry", "cover", "accidentDate", "accidentPlace", "lat", "lng", "description", "damageKind", "reportedBy", "reporter", "facts", "createdAt", "updatedAt", "currency", "role", "parties", "route", "assessments", "offers", "payments", "notices", "demands", "arbitrations", "documents", "events", "deadlines", "actions" ], "description": "A claim with everything the caller may see." }, "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." } } } } } } } } }