Fleet Inspections

Create fleet inspections, add vehicles, and start vehicle assessments from your server.

Before you start

Generate an API key from the Curacel Auto dashboard by following the authentication guide. Keep the key on a trusted server and send it as a bearer token with every request.

export BASE_URL="https://api.sandbox.autoinsure.curacel.co"
export API_TOKEN="your-api-key"

The API allows 60 requests per minute for each authenticated account.

Understand the identifiers

Resource	Identifier	Use
Fleet inspection	uid or id, both ULID strings	Fleet URLs
Fleet vehicle	Integer id	fleet_vehicle_id in an assessment request
Vehicle	vin	Create or update the vehicle within a fleet

Do not use a fleet database integer in a fleet URL. Do not use a VIN as fleet_vehicle_id.

1. Create a fleet inspection

Fleet creation uses multipart/form-data because supporting documents are required.

Personal fleets require proof_of_address and director_identity_card.

curl --request POST "$BASE_URL/api/fleets" \
  --header "Authorization: Bearer $API_TOKEN" \
  --header "Accept: application/json" \
  --form "name=Delivery Fleet" \
  --form "inspection_type=personal" \
  --form "company_name=Example Logistics Limited" \
  --form "company_email=fleet@example.com" \
  --form "company_phone_no=08012345678" \
  --form "proof_of_address=@/path/to/proof-of-address.pdf" \
  --form "director_identity_card=@/path/to/director-id.jpg"

Corporate fleets require cac_document, memart, and director_identity_card.

curl --request POST "$BASE_URL/api/fleets" \
  --header "Authorization: Bearer $API_TOKEN" \
  --header "Accept: application/json" \
  --form "name=Corporate Delivery Fleet" \
  --form "inspection_type=corporate" \
  --form "company_name=Example Logistics Limited" \
  --form "company_email=fleet@example.com" \
  --form "company_phone_no=08012345678" \
  --form "cac_document=@/path/to/cac-document.pdf" \
  --form "memart=@/path/to/memart.pdf" \
  --form "director_identity_card=@/path/to/director-id.jpg"

Documents can be PNG, JPEG, or PDF files up to 1500 KB. Save the returned fleet uid for later requests. See the create fleet inspection reference.

2. List or retrieve fleet inspections

List the fleets owned by the authenticated insurer:

curl --request GET "$BASE_URL/api/fleets?search=delivery&per_page=20" \
  --header "Authorization: Bearer $API_TOKEN" \
  --header "Accept: application/json"

The default page size is 10. Set filter=all to receive an unpaginated minimal collection. This ignores search and per_page.

Retrieve one fleet using its ULID:

export FLEET_ID="01JZ7M5BCW8T2W4QWR5SN1MMBQ"

curl --request GET "$BASE_URL/api/fleets/$FLEET_ID" \
  --header "Authorization: Bearer $API_TOKEN" \
  --header "Accept: application/json"

See the list fleet inspections and get fleet inspection references.

3. Add vehicles

Send one JSON object to add one vehicle:

curl --request POST "$BASE_URL/api/fleets/$FLEET_ID/vehicles" \
  --header "Authorization: Bearer $API_TOKEN" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "chassis_number": "JH4KA8260MC000000",
    "vehicle_regno": "ABC123DE",
    "engine_no": "ENG123456",
    "vehicle_type": "SUV",
    "manufacturer": "Toyota",
    "model": "Corolla",
    "year": 2024,
    "color": "Black"
  }'

Send a root JSON array to add multiple vehicles. A batch must contain between 1 and 500 vehicles. Do not wrap the array in a vehicles property.

curl --request POST "$BASE_URL/api/fleets/$FLEET_ID/vehicles" \
  --header "Authorization: Bearer $API_TOKEN" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '[
    {
      "chassis_number": "JH4KA8260MC000000",
      "vehicle_regno": "ABC123DE",
      "engine_no": "ENG123456",
      "vehicle_type": "SUV",
      "manufacturer": "Toyota",
      "model": "Corolla",
      "year": 2024,
      "color": "Black"
    },
    {
      "chassis_number": "1HGCM82633A004352",
      "vehicle_regno": "XYZ456AB",
      "engine_no": "ENG987654",
      "vehicle_type": "Sedan",
      "manufacturer": "Honda",
      "model": "Accord",
      "year": 2023,
      "color": "Blue"
    }
  ]'

All vehicles are validated before any record is saved. Batch validation keys include the zero based position, such as vehicles.1.chassis_number. Sending an existing VIN for the same fleet updates that vehicle. Response order matches request order.

Save each returned integer vehicle id. See the add fleet vehicles reference.

4. Start a fleet vehicle assessment

Fleet vehicles support pre-policy assessments only. Supply the integer fleet vehicle id; registration_number is not required because the stored registration takes precedence.

curl --request POST "$BASE_URL/api/v1/vehicle-assessments" \
  --header "Authorization: Bearer $API_TOKEN" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "assessment_type": "pre-policy",
    "fleet_vehicle_id": 4812,
    "images": [
      {"part": "front", "url": "https://public-storage-host/vehicle/front.jpg"},
      {"part": "rear", "url": "https://public-storage-host/vehicle/rear.jpg"},
      {"part": "left", "url": "https://public-storage-host/vehicle/left.jpg"},
      {"part": "right", "url": "https://public-storage-host/vehicle/right.jpg"},
      {"part": "vin-plate", "url": "https://public-storage-host/vehicle/vin.jpg"}
    ]
  }'

A successful request returns HTTP 200:

{
  "id": 98765,
  "fleet_vehicle_id": 4812,
  "fleet_id": "01JZ7M5BCW8T2W4QWR5SN1MMBQ",
  "info": "Processing images. Updates will be sent via webhooks."
}

fleet_vehicle_id and fleet_id are returned only for a fleet vehicle assessment. Existing non-fleet assessment responses remain unchanged. fleet_id is the public fleet ULID used in fleet API URLs.

Image processing continues asynchronously. Configure your insurer webhook before using this flow in production. See the vehicle assessment reference.

Invalid front, rear, left, and right images return HTTP 422. Each message includes the reason without changing the validation response structure:

{
  "message": "The front image must be a vehicle image. Reason: blurry image.",
  "error": {
    "images": [
      "The front image must be a vehicle image. Reason: blurry image."
    ]
  }
}

Ownership and errors

Status	Meaning
401	The bearer token is missing, invalid, or revoked
403	The authenticated insurer does not own the requested fleet
404	The requested fleet ULID does not exist
422	Request validation failed, including an unknown or foreign fleet_vehicle_id
429	The request limit was exceeded

Keep the API key out of browser code, mobile application code, source control, logs, and URLs. Rotate it from the dashboard immediately if it is exposed.