Client History

The client history endpoint allows you to search for a client's claims history across all participating insurance companies. This is the core feature of the shared claims database — enabling cross-company risk assessment.

Response structure

The client history response wraps an array of claim objects with metadata about the query period.

Meta properties

Name
total_claims
Type
integer
Description
The total number of claims found for this client within the query period.
Name
query_period.from
Type
string (YYYY-MM-DD)
Description
The start date of the search window (3 years before today).
Name
query_period.to
Type
string (YYYY-MM-DD)
Description
The end date of the search window (today).

POST/api/v1/claims/search

Search client history

Search for all claims associated with a client across all participating companies. Results are limited to the last 3 years and ordered by claim date (newest first).

The system matches clients using a combination of date of birth and identity document numbers. This means the same person will be found regardless of which company submitted their claims — even if they used different document types (e.g., passport vs national ID). See Client Identity for details on matching.

Required attributes

Name
client
Type
object
Description
Structured client identity data for the search.
Name
client.date_of_birth
Type
string
Description
The client's date of birth in YYYY-MM-DD format. Must be before today.
Name
client.id_documents
Type
array
Description
At least one identity document to match against. Each document has type and number.
Name
client.id_documents[].type
Type
string
Description
Document type. One of: passport, national_id, alien_registration.
Name
client.id_documents[].number
Type
string
Description
The document number. Maximum 255 characters. Country prefixes (e.g., CY-) are automatically stripped during normalization.

Request

POST

/api/v1/claims/search

curl -X POST https://YOUR_DOMAIN/api/v1/claims/search \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "client": {
      "date_of_birth": "1990-05-15",
      "id_documents": [
        {
          "type": "passport",
          "number": "CY-12345678"
        }
      ]
    }
  }'

Response

POST

/api/v1/claims/search

{
  "data": [
    {
      "id": "9e5f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
      "client": {
        "id": "c1a2b3c4-d5e6-7f89-0abc-def123456789",
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "1990-05-15",
        "id_documents": [
          {
            "type": "passport"
          }
        ]
      },
      "claim_date": "2025-11-15",
      "claim_type": "accident",
      "amount": "2500.00",
      "currency": "EUR",
      "is_at_fault": true,
      "source": "api",
      "company_name": "Cyprus General Insurance",
      "created_at": "2025-11-20T10:30:00+00:00"
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "client": {
        "id": "c1a2b3c4-d5e6-7f89-0abc-def123456789",
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "1990-05-15",
        "id_documents": [
          {
            "type": "passport"
          },
          {
            "type": "national_id"
          }
        ]
      },
      "claim_date": "2024-06-03",
      "claim_type": "theft",
      "amount": "8000.00",
      "currency": "EUR",
      "is_at_fault": false,
      "source": "bulk_import",
      "company_name": "Mediterranean Insurance Ltd",
      "created_at": "2024-07-01T08:15:00+00:00"
    }
  ],
  "meta": {
    "total_claims": 2,
    "query_period": {
      "from": "2023-03-07",
      "to": "2026-03-07"
    }
  }
}

No results

If no claims are found for the given client (or no matching client exists), the API returns an empty data array with total_claims: 0:

No claims found

{
  "data": [],
  "meta": {
    "total_claims": 0,
    "query_period": {
      "from": "2023-03-07",
      "to": "2026-03-07"
    }
  }
}