CSV Import

The CSV import endpoint allows you to upload a CSV file containing multiple claims for batch processing. This is useful for onboarding historical data or regular bulk uploads from your claims management system.

CSV format

Your CSV file must include a header row with the following columns. Column names must match exactly.

Client columns

Name
first_name
Type
string (required)
Description
The client's first name. Maximum 255 characters.
Name
last_name
Type
string (required)
Description
The client's last name. Maximum 255 characters.
Name
date_of_birth
Type
string (required)
Description
The client's date of birth in YYYY-MM-DD format. Must be before today.
Name
id_type
Type
string (required)
Description
Identity document type. One of: passport, national_id, alien_registration.
Name
id_number
Type
string (required)
Description
The document number. Maximum 255 characters. Country prefixes (e.g., CY-) are automatically stripped during normalization.

Claim columns

Name
claim_date
Type
string (required)
Description
Date in YYYY-MM-DD format. Must not be in the future and must be within the last 3 years.
Name
claim_type
Type
string (optional)
Description
One of: accident, theft, other.
Name
amount
Type
number (optional)
Description
The claim amount. Must be >= 0.
Name
currency
Type
string (optional)
Description
Currency code. Currently only EUR. Defaults to EUR if omitted.
Name
is_at_fault
Type
boolean (optional)
Description
true, false, 1, or 0.

Example CSV

first_name,last_name,date_of_birth,id_type,id_number,claim_date,claim_type,amount,currency,is_at_fault
John,Doe,1990-05-15,passport,CY-12345678,2025-11-15,accident,2500.00,EUR,true
Jane,Smith,1985-03-22,national_id,87654321,2025-10-20,theft,8000.00,EUR,false
Bob,Johnson,1978-12-01,alien_registration,ARC-11223344,2025-09-01,other,1200.00,EUR,true

The system uses the client's date of birth and identity document to resolve or create a client record. If the same person submits claims with different document types over time, their identity documents accumulate on a single client record.

POST/api/v1/claims/import

Import claims

Upload a CSV file to bulk import claims. Each row is validated independently — valid rows are imported and invalid rows are reported in the response. The maximum file size is 10 MB.

Each row resolves or creates a client record using the client identity matching algorithm, then creates the associated claim.

Required attributes

Name
file
Type
file
Description
A CSV or TXT file (Content-Type: multipart/form-data). Maximum 10 MB.

Request

POST

/api/v1/claims/import

curl -X POST https://YOUR_DOMAIN/api/v1/claims/import \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -F "[email protected]"

Response

POST

/api/v1/claims/import

{
  "message": "Import completed.",
  "imported": 2,
  "failed": 1,
  "errors": [
    {
      "row": 4,
      "messages": {
        "claim_date": [
          "The claim date cannot be in the future."
        ]
      }
    }
  ]
}

Error handling

The import endpoint uses partial success semantics. Valid rows are imported even if some rows fail validation. The response always includes:

imported — number of successfully imported records
failed — number of rows that failed validation
errors — array of error details for each failed row, including the row number and validation messages

If a row's identity document matches an existing client but the date of birth doesn't match, that row is rejected with a data quality error. This prevents accidental identity merges.

If the file itself is invalid (wrong format or too large), a standard 422 validation error is returned before any processing begins.