Claims

The claims endpoint allows you to submit individual insurance claims to the shared database. Each claim is associated with your company and a resolved client identity.

The claim model

A claim represents a single insurance event recorded in the shared database.

Properties

Name
id
Type
string (UUID)
Description
Unique identifier for the claim.
Name
client
Type
object
Description
The resolved client associated with this claim. See the client model for details.
Name
claim_date
Type
string (YYYY-MM-DD)
Description
The date the claim occurred.
Name
claim_type
Type
string | null
Description
The type of claim. One of: accident, theft, other, or null.
Name
amount
Type
string | null
Description
The monetary amount of the claim, formatted as a decimal string (e.g., "2500.00").
Name
currency
Type
string
Description
The currency code. Currently only EUR is supported.
Name
is_at_fault
Type
boolean | null
Description
Whether the claimant was at fault.
Name
vehicle_registration
Type
string
Description
The vehicle registration (plate) number associated with the claim. Automatically normalized: spaces, dots, and dashes are stripped, and the value is uppercased (e.g., ABC.123 becomes ABC123).
Name
source
Type
string
Description
How the claim was submitted: api, bulk_import, or assisted.
Name
status
Type
string
Description
The current status of the claim. One of: filed, under_investigation, settled, closed, disputed.
Name
company_name
Type
string
Description
The name of the company that submitted the claim.
Name
created_at
Type
string (ISO 8601)
Description
Timestamp of when the claim was created.

POST/api/v1/claims

Submit a new insurance claim to the shared database. You must provide structured client identity data — the system will automatically resolve or create the client record. See Client Identity for details on how client matching works.

Required attributes

Name
client
Type
object
Description
Structured client identity data. See below for nested attributes.
Name
client.first_name
Type
string
Description
The client's first name. Maximum 255 characters.
Name
client.last_name
Type
string
Description
The client's last name. Maximum 255 characters.
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. 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.
Name
claim_date
Type
string
Description
The date the claim occurred, in YYYY-MM-DD format. Must not be in the future and must be within the last 3 years.
Name
vehicle_registration
Type
string
Description
The vehicle registration (plate) number. Maximum 20 characters. Automatically normalized: spaces, dots, and dashes are stripped, and the value is uppercased (e.g., ABC.123 becomes ABC123).

Optional attributes

Name
claim_type
Type
string
Description
The type of claim. One of: accident, theft, other.
Name
amount
Type
number
Description
The claim amount. Must be >= 0.
Name
currency
Type
string
Description
The currency code. Currently only EUR is accepted. Defaults to EUR if omitted.
Name
is_at_fault
Type
boolean
Description
Whether the claimant was at fault in the incident.
Name
status
Type
string
Description
The initial status of the claim. One of: filed, under_investigation, settled, closed, disputed. Defaults to filed.

Request

POST

/api/v1/claims

curl -X POST https://YOUR_DOMAIN/api/v1/claims \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "client": {
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1990-05-15",
      "id_documents": [
        {
          "type": "passport",
          "number": "CY-12345678"
        }
      ]
    },
    "claim_date": "2025-11-15",
    "claim_type": "accident",
    "amount": 2500.00,
    "currency": "EUR",
    "is_at_fault": true,
    "vehicle_registration": "ABC123"
  }'

Response

POST

/api/v1/claims

{
  "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,
    "vehicle_registration": "ABC123",
    "source": "api",
    "status": "filed",
    "company_name": "Cyprus General Insurance",
    "created_at": "2025-11-20T10:30:00+00:00"
  }
}

PATCH/api/v1/claims/:id/status

Update claim status

Update the status of an existing claim that belongs to your company. Only the submitting company can update the status of their own claims.

Required attributes

Name
status
Type
string
Description
The new status. One of: filed, under_investigation, settled, closed, disputed.

Request

PATCH

/api/v1/claims/:id/status

curl -X PATCH https://YOUR_DOMAIN/api/v1/claims/9e5f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b/status \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "status": "settled"
  }'

Response

PATCH

/api/v1/claims/:id/status

{
  "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,
    "vehicle_registration": "ABC123",
    "source": "api",
    "status": "settled",
    "company_name": "Cyprus General Insurance",
    "created_at": "2025-11-20T10:30:00+00:00"
  }
}

POST/api/v1/claims/search-by-plate

Search claims by vehicle registration

Search for all claims associated with a given vehicle registration (plate) number across all companies. The plate number is automatically normalized before matching — spaces, dots, and dashes are stripped, and the value is uppercased.

Only claims within the configured history window (default: 3 years) are returned.

Required attributes

Name
vehicle_registration
Type
string
Description
The vehicle registration (plate) number to search for. Maximum 20 characters. Normalized before matching (e.g., ABC.123 and abc 123 both match ABC123).

Request

POST

/api/v1/claims/search-by-plate

curl -X POST https://YOUR_DOMAIN/api/v1/claims/search-by-plate \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "vehicle_registration": "ABC123"
  }'

Response

POST

/api/v1/claims/search-by-plate

{
  "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,
      "vehicle_registration": "ABC123",
      "source": "api",
      "status": "filed",
      "company_name": "Cyprus General Insurance",
      "created_at": "2025-11-20T10:30:00+00:00"
    }
  ],
  "meta": {
    "total_claims": 1,
    "query_period": "3 years"
  }
}

Claims

The claim model

Properties

Submit a claim

Required attributes

Optional attributes

Request

Response

Update claim status

Required attributes

Request

Response

Search claims by vehicle registration

Required attributes

Request

Response