Insurance Types and Schemas

An insurance type is Lunixi's provider-independent insurance code. In quote and order requests you state which insurance you want with this code. Which provider product is used is decided by your provider connections, not by your request.

• A published type code never changes and is never removed. New types are added to the catalog.
• Field names and formats are the same whichever provider you work with. Provider-specific field names are not accepted.
• Who collects the premium depends on the product in your connection, not on the type. Check the premiumCollectedBy field of the quote option; if it is PROVIDER, your provider collects the premium: Provider Collection.

Type catalog

The basket item category is the item's insuranceCategory value; which basket item a type is offered for is resolved from this field (see Basket Items). The DEVICE category has two separate types: device insurance and the repair plan are two products with different coverage, inputs and documents.

A type without a basket item category is not linked to a basket item; it is sold only on the API path, without a basket item: Selling Without a Basket Item. Types marked "also sold without a basket item" are sold both ways: with a basket item, and on the API path without one. All other types are offered only with a basket item.

Type objects other than tickets are singular: a quote covers a single stay, device, product, vehicle, trip, musical instrument, event ticket, rental, medical procedure, animal, period or home; on a basket-linked quote this is a single basket item. A PERSONAL_ACCIDENT, FOREIGN_RESIDENT_HEALTH or SUPPLEMENTARY_HEALTH quote covers a single person. On an INBOUND_TRAVEL_HEALTH or ABROAD_STAY_HEALTH quote all insured persons are on the same policy.

Lead types ("lead only") do not return a quote. These types have no quote, premium collection or policy; the buyer's details are passed to the provider in your connection as a lead: Leads. A quote request for a lead type receives 412 insurance.type.not_available. The fields of lead types are in their lead schema.

Types marked "leads too" both return quotes and accept leads. A quote request is sent with the type's schema, a lead request with the type's lead schema. A quote goes to the product in your connections that returns quotes, a lead to the product that accepts leads; they are separate products.

Schema version (schemaVersion)

The fields of each type are defined by a schema, and schemas are versioned per type (schemaVersion).

• A published schema version never changes: its field set and requirements are not tightened later.
• A breaking change is published as a new schemaVersion; the old version stays available alongside it.
• A provider updating its own product does not change the Lunixi schema.

Pre-fill data in the basket item

For every type sold with a basket item, you can also give the fields on this page in the basket item, before the quote request:

• Some of the non-personal fields are filled from the item's insuranceContext. Which key fills which field in which type: Basket Items › Pre-filling.
• The person fields and the other fields of the type object are given with the item's insuranceData. Field names and formats are the same as on this page; the type object is a single object for the item (tickets included) and carries no basketItemId: Basket Items › Insurance pre-fill data.
• The fields you give in the basket count towards the requirements of the quote. In the quote request you send only the missing ones: Quote › Quote with pre-fill data.

The fields of types sold only without a basket item, and of lead types, are sent in the request.

Stages

Whether a field is required depends on the stage of the request:

• If the quote is linked to a payment's basket (by payment ID or on the Checkout Form), basketItemId is also required on the type object; on every entry when the type object is an array, such as tickets.
• On a quote obtained without a basket item, basketItemId is not sent; if it is, the request is rejected.
• Send the POLICY stage fields in the quote request as well. Order and policy requests carry no extra fields; the policy is issued with the quote's data. See Quotes.

Additional product requirements

A type's schema covers the fields of every product that offers the type. A product in your connections may make a field that is optional in the schema required, or ask for a field at an earlier stage than the schema does.

• These fields are marked with requiredBy in the fields array of the Eligibility response.
• If a field the product needs at the quote stage is missing, only that product's option is excluded; the other options are returned: Quotes › Excluded options.
• If a field the product needs at the policy stage is missing, the order is rejected with 422 insurance.validation.invalid.

Person fields (policyholder, insured[])

The person fields are the same for every type. What varies between types is which identity types are accepted, how many insured persons can be sent, and which field is required at which stage. These are in the person table of each type's section.

address:

The health declaration (heightCm, weightKg, pregnancyStatus) is special-category personal data.

Where a person table says "address (province, district, line)", address is required at that stage together with cityCode, districtCode and line. Where it says "address (country, province, district, line)", countryCode is required too; where it says "address line", address is required with line only. Person fields not named in the table are optional.

In lead schemas, policyholder carries only the identity type and number, date of birth, email and phone; any other person field is rejected. See Lead schemas.

Format details: Data Formats.

Reference codes

Fields such as brand, model, vehicle type, usage, liability limit, product category, occupation, medical procedure, pet breed, dwelling type, bank and district carry a Lunixi reference code. Provider identifiers are not accepted. Get the valid codes from this endpoint:

GET /api/v1/insurance/reference/{kind}

In the response the codes are in the data.items array; each entry carries code, label (display names by language code, e.g. tr-TR) and parentCode. Paging information is in the pageInfo field. The list returns only codes in use and is the same for all merchants; the brand and model list filtered by vehicle type and year and the address chain are the exceptions.

• Send the code as is; do not use the display name (label) in requests.
• A code that is well-formed but not recognized, or that has no counterpart at your connection's provider, is rejected at quote time with 422 insurance.reference.unknown (Error Codes). Do not send guessed or empty values.
• The country code (COUNTRY) is also used in nationality and destination country fields. If a country has no counterpart at your connection's provider, that field receives 422 insurance.reference.unknown too.

List by vehicle type and year

You can filter the VEHICLE_BRAND and VEHICLE_MODEL lists by vehicle type and model year: GET /api/v1/insurance/reference/VEHICLE_BRAND?vehicleTypeCode=<vehicle type code>&modelYear=<year>. For the model list, send the brand as parentCode.

• The filtered list is read from the providers in your connections at request time. Only the brands and models that your connections offer and that have a Lunixi code are returned, so the list is specific to your account and can change over time.
• vehicleTypeCode and modelYear are sent together. If one is missing, the request receives 422 insurance.validation.invalid (reason: required). If neither is sent, all codes in use are returned.
• The model year must be between 1950 and the year after the current year; otherwise reason: invalid_model_year.
• If these parameters are sent for another kind, reason: not_applicable is returned.
• If none of your connections has a provider that offers a filtered list, the response is 422 insurance.validation.invalid (field: kind, reason: live_reference_unavailable). If the vehicle type code has no counterpart at your connection's provider, the response is 422 insurance.reference.unknown.

UAVT address chain

In the home types (COMPULSORY_EARTHQUAKE, HOME_INSURANCE) the home's address is sent as a single field: property.uavtAddressCode, the address code of the independent unit in the National Address Database (UAVT). The UAVT address code is a national code. If your buyer knows the code, you can send it directly; otherwise find it by walking the address chain step by step. At each step, show the list to the buyer and send the code of the chosen entry as the parentCode of the next step:

The code of the entry chosen at the last step is the UAVT address code; send it in the quote request as property.uavtAddressCode. The other codes of the chain are not sent with the quote.

• From the town or village step onwards, the lists are read from the providers in your connections at request time and are not stored permanently. If none of your connections has a provider that offers the address chain, the request receives 422 insurance.validation.invalid (field: kind, reason: live_reference_unavailable).
• The codes of the chain are national address codes. Town or village, neighbourhood, avenue or street and building codes have 1-12 digits; the independent unit's code (the UAVT address code) has 10 digits. Codes are text; leading zeros are kept. At these steps, a malformed parent code receives reason: invalid_reference_code with the field path parentCode.
• At the town or village step, if the district code has no counterpart at your connection's provider, the request receives 422 insurance.reference.unknown with the field path parentCode.
• The building list needs the building's outer door number (outerDoorNumber) together with the street code. An outer door number starts with a digit; it can contain digits, letters, /, -, . and spaces; it has at most 16 characters (e.g. 12, 12A, 12/1). If it is not sent, reason: required is returned; if it is malformed, reason: invalid_outer_door_number. If it is sent for another kind, reason: not_applicable is returned.
• In address lists label is the official place name; tr-TR and en-US carry the same text. Paging is the same as for the other reference lists (limit, cursor).
• An address is personal data. Do not send the chain codes or the UAVT address code in the insuranceContext field of a basket item.

The UAVT address code is checked at quote time. A malformed code receives 422 insurance.validation.invalid (reason: invalid_uavt_address_code) with the field path property.uavtAddressCode. A well-formed code that does not exist in UAVT receives reason: unknown_uavt_address_code with the same field path, and the quote request is not sent to the provider.

TICKET_CANCELLATION: schema version 1

Insurance against the cancellation of a bus, flight or train ticket. It is resolved from a basket item with insuranceCategory: TICKET.

The type-specific fields of the request body have three roots: policyholder, insured and the type object tickets.

tickets[]

Fields marked "FLIGHT only" apply only to a ticket with transportMode: FLIGHT, and their requirement is applied only then. If they are sent for another transport mode, the request is rejected.

Persons

No person field in policyholder is required on its own; only identityType and identityNumber are sent together.

Person insured with a passport

You can insure a foreign passenger with a passport (identityType: PASSPORT) instead of a Turkish identity number. A person with a passport also needs these fields:

If gender or residenceCountryCode is sent with a Turkish identity number, the field path gets not_applicable. These fields can also be given on the basket item with insuranceData: Basket Items › Insurance data.

Example request: Quotes.

HOTEL_CANCELLATION: schema version 1

Insurance against the cancellation of a hotel booking. It is resolved from a basket item with insuranceCategory: HOTEL. The type object stay is a single stay.

stay

Dates are calendar days at the place of stay.

Persons

Example

The examples on this page show only the type-specific fields of the quote request, together with the policy fields; for the currency and the basket source see Quotes. Values are examples; replace the values in angle brackets with your buyer's details, and the reference codes with codes you got from the reference endpoints:

{
  "insuranceType": "HOTEL_CANCELLATION",
  "policyholder": {
    "identityType": "TCKN",
    "identityNumber": "<identity number>",
    "birthDate": "<YYYY-MM-DD>",
    "email": "<email>",
    "phone": "<E.164 phone>",
    "address": {
      "cityCode": "35",
      "districtCode": "<district code>",
      "line": "<address line>"
    }
  },
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "birthDate": "<YYYY-MM-DD>"
    }
  ],
  "stay": {
    "basketItemId": "hotel-1",
    "hotelName": "Example Hotel",
    "checkInDate": "2025-12-23",
    "checkOutDate": "2025-12-25",
    "guestCount": 2,
    "reservationAmount": 450000,
    "cityCode": "35"
  }
}

DEVICE_INSURANCE: schema version 1

An insurance policy for a mobile phone. It is resolved from a basket item with insuranceCategory: DEVICE. The type object device is a single device. The device's IMEI and the sum insured are required at the quote stage.

device

Persons

The price is calculated with the insured person's details; that is why the person fields are required at the quote stage.

Example

{
  "insuranceType": "DEVICE_INSURANCE",
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "firstName": "<first name>",
      "lastName": "<last name>",
      "birthDate": "<YYYY-MM-DD>",
      "gender": "FEMALE",
      "email": "<email>",
      "phone": "<E.164 phone>",
      "address": {
        "cityCode": "34",
        "districtCode": "<district code>",
        "line": "<address line>"
      }
    }
  ],
  "device": {
    "basketItemId": "phone-1",
    "brandCode": "<brand code>",
    "modelCode": "<model code>",
    "imei": "<IMEI>",
    "sumInsuredAmount": 3500000
  }
}

DEVICE_PROTECTION: schema version 1

A protection plan that covers the repair costs of a mobile phone. It is resolved from a basket item with insuranceCategory: DEVICE. The type object device is a single device. The quote is taken with the brand and model only, without the IMEI and without personal data.

device

The IMEI cannot be registered after the policy; send it in the quote request at the latest, together with the policy fields.

Persons

Example

{
  "insuranceType": "DEVICE_PROTECTION",
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "birthDate": "<YYYY-MM-DD>",
      "email": "<email>",
      "phone": "<E.164 phone>",
      "address": {
        "cityCode": "06",
        "districtCode": "<district code>",
        "line": "<address line>"
      }
    }
  ],
  "device": {
    "basketItemId": "phone-1",
    "brandCode": "<brand code>",
    "modelCode": "<model code>",
    "imei": "<IMEI>"
  }
}

EXTENDED_WARRANTY: schema version 1

12 or 24 more months of cover for electronics and home appliances after the manufacturer's warranty ends. It is resolved from a basket item with insuranceCategory: ELECTRONICS. The type object product is a single product. The quote is taken without personal data.

product

The upper limit of the product price is a rule of the product in your connection; a request above the limit is rejected at the quote stage. Corporate customers (tax identity number) are not supported in this version.

Persons

Example

{
  "insuranceType": "EXTENDED_WARRANTY",
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "firstName": "<first name>",
      "lastName": "<last name>",
      "birthDate": "<YYYY-MM-DD>",
      "email": "<email>",
      "phone": "<E.164 phone>",
      "address": {
        "cityCode": "16",
        "districtCode": "<district code>",
        "line": "<address line>"
      }
    }
  ],
  "product": {
    "basketItemId": "tv-1",
    "categoryCode": "<category code>",
    "brand": "Example Brand",
    "model": "Example Model 55",
    "priceAmount": 2500000,
    "warrantyMonths": 24
  }
}

ROADSIDE_ASSISTANCE: schema version 1

Towing and on-site assistance when a vehicle breaks down on the road. It is resolved from a basket item with insuranceCategory: VEHICLE. The type object vehicle is a single vehicle. The quote is taken without personal data and without the plate.

vehicle

This version accepts only vehicles with a Turkish plate.

Persons

The insured person's identity and date of birth are optional. The address is also used as the billing address.

Example

{
  "insuranceType": "ROADSIDE_ASSISTANCE",
  "insured": [
    {
      "firstName": "<first name>",
      "lastName": "<last name>",
      "email": "<email>",
      "phone": "<E.164 phone>",
      "address": {
        "cityCode": "07",
        "districtCode": "<district code>",
        "line": "<address line>"
      }
    }
  ],
  "vehicle": {
    "basketItemId": "car-1",
    "brandCode": "<brand code>",
    "modelCode": "<model code>",
    "modelYear": 2022,
    "vehicleTypeCode": "<vehicle type code>",
    "plate": "<plate>"
  }
}

TRAVEL_HEALTH: schema version 1

Health insurance for domestic and international travel. It is resolved from a basket item with insuranceCategory: TRAVEL. The type object trip is a single trip; all insured persons of the trip are on the same policy.

trip

Fields marked "INTERNATIONAL only" and "DOMESTIC only" apply only in that scope, and their requirement is applied only then. If they are sent for the other scope, the request is rejected.

Persons

The products in your connection differ by the scope of the trip and by the identity type of the insured persons. For a person insured with a passport, the first name, last name and gender (gender) may also be needed; send these fields if you have them. A product that does not fit the request returns no quote. If no product fits the request (for example, the products in your connection accept a single destination country and you sent several), the quote is rejected with 422 insurance.quote.declined.

Example

International trip:

{
  "insuranceType": "TRAVEL_HEALTH",
  "policyholder": {
    "identityType": "TCKN",
    "identityNumber": "<identity number>",
    "birthDate": "<YYYY-MM-DD>",
    "email": "<email>",
    "phone": "<E.164 phone>"
  },
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "birthDate": "<YYYY-MM-DD>"
    }
  ],
  "trip": {
    "basketItemId": "tour-1",
    "scope": "INTERNATIONAL",
    "startDate": "2025-12-23",
    "endDate": "2025-12-30",
    "residenceCountryCode": "TR",
    "destinationCountryCodes": ["DE"]
  }
}

On a domestic trip, destinationCountryCodes is not sent; for the policy, the departure province originCityCode is sent:

{
  "scope": "DOMESTIC",
  "startDate": "2025-12-23",
  "endDate": "2025-12-26",
  "residenceCountryCode": "TR",
  "originCityCode": "06"
}

MUSICAL_INSTRUMENT_PROTECTION: schema version 1

A protection plan that covers the repair cost of a musical instrument after sudden and unforeseen damage. It is resolved from a basket item with insuranceCategory: MUSICAL_INSTRUMENT. The type object instrument is a single instrument. The quote is obtained without personal data, from the instrument's brand, model and value.

instrument

• Musical instrument categories are in the PRODUCT_CATEGORY list. For this type, a code that is not a musical instrument category (for example an electronics product category) is rejected with 422 insurance.reference.unknown.
• If you send the serial number, it is printed on the policy document.
• If the product in your connection offers several plans, one quote request returns a separate option per plan: Quotes › Multiple options.

Persons

At the policy stage, depending on the identity type:

• TCKN: the date of birth (birthDate) or the first and last name (firstName, lastName). If neither is present, the request receives 422 insurance.validation.invalid with the field path insured[0].birthDate. Gender (gender) is optional.
• VKN: the company name (companyName).

For a company (VKN) policy, if the product in your connection does not support cancelling it, the cancellation result is insurance.policy.cancel_failed and the policy stays in force: Cancellation and Premium Refund.

Example

{
  "insuranceType": "MUSICAL_INSTRUMENT_PROTECTION",
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "birthDate": "<YYYY-MM-DD>",
      "email": "<email>",
      "phone": "<E.164 phone>"
    }
  ],
  "instrument": {
    "basketItemId": "guitar-1",
    "brand": "Example Brand",
    "model": "Example Model",
    "valueAmount": 4500000,
    "categoryCode": "<category code>",
    "serialNumber": "<serial number>"
  }
}

If the insured is a company, send insured like this:

"insured": [
  {
    "identityType": "VKN",
    "identityNumber": "<tax identity number>",
    "companyName": "<company name>",
    "email": "<email>",
    "phone": "<E.164 phone>"
  }
]

EVENT_ACCIDENT: schema version 1

Personal accident insurance for an event attendee, valid on the day of the event. It is resolved from a basket item with insuranceCategory: EVENT. The type object event is a single event ticket: a quote covers one ticket and one attendee. The price is calculated from the attendee's details, so the person fields are required at the quote stage.

event

• The policy is valid on the day it is issued and lasts at most one day. Get the quote on the event day.
• The day is a calendar day in Türkiye. A past day is rejected with 422 insurance.validation.invalid (reason: must_not_be_past), a future day with 422 insurance.quote.declined.
• The day is checked again at order and collection time. If the day has changed since the quote, the operation is rejected with insurance.quote.declined; get a new quote.
• Each ticket is a separate basket item and a separate quote.

Persons

Nationality (nationalityCountryCode) is optional; if not sent, TR is assumed.

Example

{
  "insuranceType": "EVENT_ACCIDENT",
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "birthDate": "<YYYY-MM-DD>",
      "email": "<email>",
      "phone": "<E.164 phone>"
    }
  ],
  "event": {
    "basketItemId": "concert-1",
    "coverageStartDate": "<today, YYYY-MM-DD>"
  }
}

MICROMOBILITY_ACCIDENT: schema version 1

Personal accident insurance for the rider of a rented scooter, valid on the day of the rental. It is resolved from a basket item with insuranceCategory: MICROMOBILITY. The type object rental is a single rental: a quote covers one rental and one rider. The price is calculated from the rider's details, so the person fields are required at the quote stage.

rental

• The policy is valid on the day it is issued and lasts at most one day.
• The day is a calendar day in Türkiye. A past day is rejected with 422 insurance.validation.invalid (reason: must_not_be_past), a future day with 422 insurance.quote.declined. If you sent the day and it has changed since the quote, the order is rejected with insurance.quote.declined.

Persons

Nationality (nationalityCountryCode) is optional; if not sent, TR is assumed.

Example

{
  "insuranceType": "MICROMOBILITY_ACCIDENT",
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "birthDate": "<YYYY-MM-DD>",
      "email": "<email>",
      "phone": "<E.164 phone>"
    }
  ],
  "rental": {
    "basketItemId": "ride-1"
  }
}

PERSONAL_ACCIDENT: schema version 1

Annual personal accident insurance for one person. This type is not linked to a basket item; it is sold only on the API path, without a basket item: Selling Without a Basket Item. The type object accident holds the insurance details and carries no basketItemId. The quote is obtained without personal data, from the start day only.

accident

• The day is a calendar day in Türkiye. A past start day receives 422 insurance.validation.invalid (reason: must_not_be_past) at quote time. If the start day has passed when the order is created, the order is rejected with insurance.quote.declined; get a new quote.
• The occupation code is checked against its counterpart at your connection's provider when the order is created. A code without a counterpart receives 422 insurance.reference.unknown at the order and no premium is collected. Get the valid codes from the reference endpoint.

Persons

Example

{
  "insuranceType": "PERSONAL_ACCIDENT",
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "birthDate": "<YYYY-MM-DD>",
      "email": "<email>",
      "phone": "<E.164 phone>"
    }
  ],
  "accident": {
    "coverageStartDate": "<YYYY-MM-DD>",
    "occupationCode": "<occupation code>",
    "beneficiaryName": "<beneficiary name>"
  }
}

MEDICAL_COMPLICATION: schema version 1

Insurance against complications of a medical procedure performed as part of health tourism. It is resolved from a basket item with insuranceCategory: HEALTH. The type object procedure is a single procedure: a quote covers one procedure and one patient. Persons are insured with a passport. The price is calculated from the insured's details, so the person and procedure fields are required at the quote stage.

procedure

• Days are calendar days in Türkiye. A procedure day outside the coverage period receives 422 insurance.validation.invalid (reason: out_of_range) with the field path procedure.procedureDate.
• If the start day has passed when the order is created, the order is rejected with insurance.quote.declined; get a new quote.
• If the product in your connection does not support cancelling this policy, a cancellation request returns 412 insurance.provider.not_integrated.

Persons

Example

{
  "insuranceType": "MEDICAL_COMPLICATION",
  "insured": [
    {
      "identityType": "PASSPORT",
      "identityNumber": "<passport number>",
      "firstName": "<first name>",
      "lastName": "<last name>",
      "gender": "MALE",
      "birthDate": "<YYYY-MM-DD>",
      "birthPlace": "<place of birth>",
      "email": "<email>",
      "phone": "<E.164 phone>"
    }
  ],
  "procedure": {
    "basketItemId": "treatment-1",
    "procedureCoverCode": "<procedure code>",
    "procedureDate": "<YYYY-MM-DD>",
    "facilityName": "Example Hospital",
    "startDate": "<YYYY-MM-DD>",
    "endDate": "<YYYY-MM-DD>"
  }
}

PET_HEALTH: schema version 1

Health insurance for cats and dogs. It is resolved from a basket item with insuranceCategory: PET; it is also sold without a basket item (Selling Without a Basket Item). The type object pet is a single animal. The price is calculated from the animal's and the owner's details, so the owner and animal fields are required at the quote stage.

pet

• Get the breed codes under the species: GET /api/v1/insurance/reference/PET_BREED?parentCode=CAT. Send a breed that matches the species.
• The day is a calendar day in Türkiye. A past start day receives 422 insurance.validation.invalid (reason: must_not_be_past) at quote time. If the start day has passed when the order is created, the order is rejected with insurance.quote.declined; get a new quote.
• Some products in your connections need the animal's colour. If you do not send petColor, only those products' options are excluded with the field path pet.petColor; the other options are returned: Quotes › Excluded options.
• If the product in your connection offers several plans, one quote request returns a separate option per plan: Quotes › Multiple options.

Persons

Example

{
  "insuranceType": "PET_HEALTH",
  "policyholder": {
    "identityType": "TCKN",
    "identityNumber": "<identity number>",
    "birthDate": "<YYYY-MM-DD>",
    "email": "<email>",
    "phone": "<E.164 phone>"
  },
  "pet": {
    "basketItemId": "pet-1",
    "coverageStartDate": "<YYYY-MM-DD>",
    "petName": "<animal's name>",
    "petSpecies": "CAT",
    "petBreedCode": "<breed code>",
    "petGender": "FEMALE",
    "petBirthDate": "<YYYY-MM-DD>",
    "petColor": "<colour>"
  }
}

On a quote obtained without a basket item, pet.basketItemId is not sent.

VEHICLE_TAG_PROTECTION: schema version 1

Protection for the vehicle's vehicle identification tag (UTTS): cover for the device, wrong fuel filling, and towing or recovery. It is resolved from a basket item with insuranceCategory: VEHICLE; it is also sold without a basket item. The type object vehicle is the device of a single vehicle. The quote is obtained without personal data or vehicle identifiers, from the start day only.

vehicle

• This version accepts only vehicles with a Turkish plate.
• The day is a calendar day in Türkiye. A past start day receives 422 insurance.validation.invalid (reason: must_not_be_past) at quote time. If the start day has passed when the order is created, the order is rejected with insurance.quote.declined; get a new quote.
• Formats of the chassis number and the installation code: Data Formats › Vehicle documents and identifiers.

Persons

Example

{
  "insuranceType": "VEHICLE_TAG_PROTECTION",
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "birthDate": "<YYYY-MM-DD>",
      "email": "<email>",
      "phone": "<E.164 phone>"
    }
  ],
  "vehicle": {
    "basketItemId": "car-1",
    "coverageStartDate": "<YYYY-MM-DD>",
    "plate": "<plate>",
    "chassisNumber": "<chassis number>",
    "tagInstallationCode": "<installation code>"
  }
}

MOTOR_GREEN_CARD: schema version 1

Green Card: the vehicle's liability insurance abroad. It is resolved from a basket item with insuranceCategory: VEHICLE or TRAVEL; it is also sold without a basket item. The type object vehicle is a single period of a single vehicle. The price is calculated from the insured's and the vehicle's details, so every field is required at the quote stage.

vehicle

registrationDocument:

• This version accepts only vehicles with a Turkish plate.
• If the vehicle class has no price for the period you chose, the quote is rejected with 422 insurance.quote.declined.
• The day is a calendar day in Türkiye. A past start day receives 422 insurance.validation.invalid (reason: must_not_be_past) at quote time. If the start day has passed when the order is created, the order is rejected with insurance.quote.declined; get a new quote.
• Once the policy is issued, you can download the Green Card certificate from the certificate endpoint.

Persons

Example

{
  "insuranceType": "MOTOR_GREEN_CARD",
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "birthDate": "<YYYY-MM-DD>",
      "email": "<email>",
      "phone": "<E.164 phone>"
    }
  ],
  "vehicle": {
    "basketItemId": "car-1",
    "plate": "<plate>",
    "registrationDocument": {
      "serial": "<serial code>",
      "number": "<registration number>"
    },
    "registrationDate": "<YYYY-MM-DD>",
    "seatCount": 5,
    "vehicleTypeCode": "<vehicle class code>",
    "startDate": "<YYYY-MM-DD>",
    "endDate": "<YYYY-MM-DD>"
  }
}

INBOUND_TRAVEL_HEALTH: schema version 1

Health insurance for a foreign visitor coming to Türkiye. It is a separate type from TRAVEL_HEALTH: the type object has the same name (trip), but its fields are this schema's. It is resolved from a basket item with insuranceCategory: TRAVEL; it is also sold without a basket item. The type object trip is a single period of a single visit; all insured persons are on the same policy. Persons are insured with a passport. The price is calculated from the persons' details, so the person fields are required at the quote stage.

trip

• The day is a calendar day in Türkiye. A past start day receives 422 insurance.validation.invalid (reason: must_not_be_past) at quote time. If the start day has passed when the order is created, the order is rejected with insurance.quote.declined; get a new quote.
• If a nationality (nationalityCountryCode) has no counterpart at your connection's provider, the quote receives 422 insurance.reference.unknown with the person's field path.
• If the product in your connection does not support cancelling this policy, a cancellation request returns 412 insurance.provider.not_integrated.

Persons

The contact details are the policyholder's; the insured persons' email and phone are optional.

Example

{
  "insuranceType": "INBOUND_TRAVEL_HEALTH",
  "policyholder": {
    "identityType": "PASSPORT",
    "identityNumber": "<passport number>",
    "firstName": "<first name>",
    "lastName": "<last name>",
    "gender": "FEMALE",
    "birthDate": "<YYYY-MM-DD>",
    "birthPlace": "<place of birth>",
    "nationalityCountryCode": "DE",
    "email": "<email>",
    "phone": "<E.164 phone>",
    "address": {
      "line": "<address line>"
    }
  },
  "insured": [
    {
      "identityType": "PASSPORT",
      "identityNumber": "<passport number>",
      "firstName": "<first name>",
      "lastName": "<last name>",
      "gender": "FEMALE",
      "birthDate": "<YYYY-MM-DD>",
      "birthPlace": "<place of birth>",
      "nationalityCountryCode": "DE",
      "address": {
        "line": "<address line>"
      }
    }
  ],
  "trip": {
    "basketItemId": "visit-1",
    "startDate": "<YYYY-MM-DD>",
    "endDate": "<YYYY-MM-DD>"
  }
}

FOREIGN_RESIDENT_HEALTH: schema version 1

Health insurance for a foreigner residing in Türkiye. This type is not linked to a basket item; it is sold only on the API path, without a basket item: Selling Without a Basket Item. The type object residence is the residence period and carries no basketItemId. The quote is obtained without personal data, from the start day only. The person is insured with a passport.

residence

• The day is a calendar day in Türkiye. A past start day receives 422 insurance.validation.invalid (reason: must_not_be_past) at quote time. If the start day has passed when the order is created, the order is rejected with insurance.quote.declined; get a new quote.
• The residence address is in Türkiye: insured[0].address.countryCode must be TR. With another country the order is rejected with insurance.quote.declined.
• If the nationality, the address country, the province or the district has no counterpart at your connection's provider, the order receives 422 insurance.reference.unknown with the field's path and no premium is collected.
• If the product in your connection does not support cancelling this policy, a cancellation request returns 412 insurance.provider.not_integrated.

Persons

Example

{
  "insuranceType": "FOREIGN_RESIDENT_HEALTH",
  "insured": [
    {
      "identityType": "PASSPORT",
      "identityNumber": "<passport number>",
      "firstName": "<first name>",
      "lastName": "<last name>",
      "gender": "MALE",
      "birthDate": "<YYYY-MM-DD>",
      "birthPlace": "<place of birth>",
      "fatherName": "<father's name>",
      "nationalityCountryCode": "DE",
      "email": "<email>",
      "phone": "<E.164 phone>",
      "address": {
        "countryCode": "TR",
        "cityCode": "34",
        "districtCode": "<district code>",
        "line": "<address line>"
      }
    }
  ],
  "residence": {
    "startDate": "<YYYY-MM-DD>",
    "endDate": "<YYYY-MM-DD>"
  }
}

ABROAD_STAY_HEALTH: schema version 1

Health insurance for the duration of studying or working abroad. It is a separate type from TRAVEL_HEALTH. It is resolved from a basket item with insuranceCategory: EDUCATION or TRAVEL; it is also sold without a basket item. The type object abroadStay is a single period with a single destination country; all insured persons are on the same policy. Persons are insured with a Turkish identity number. The price is calculated from the persons' details, so the person fields are required at the quote stage.

abroadStay

• The destination country cannot be Türkiye (TR); the quote is rejected with 422 insurance.quote.declined.
• If the destination country has no counterpart in the chosen region at your connection's provider, the quote receives 422 insurance.reference.unknown with the field path abroadStay.destinationCountryCode.
• The policyholder's address is in Türkiye: policyholder.address.countryCode must be TR. With another country the order is rejected with insurance.quote.declined.
• The day is a calendar day in Türkiye. A past start day receives 422 insurance.validation.invalid (reason: must_not_be_past) at quote time. If the start day has passed when the order is created, the order is rejected with insurance.quote.declined; get a new quote.

Persons

If the policyholder is also insured, they are listed in insured[] with relationship: SELF.

Example

{
  "insuranceType": "ABROAD_STAY_HEALTH",
  "policyholder": {
    "identityType": "TCKN",
    "identityNumber": "<identity number>",
    "birthDate": "<YYYY-MM-DD>",
    "email": "<email>",
    "phone": "<E.164 phone>",
    "address": {
      "countryCode": "TR",
      "cityCode": "06",
      "districtCode": "<district code>",
      "line": "<address line>"
    }
  },
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "birthDate": "<YYYY-MM-DD>",
      "relationship": "CHILD"
    }
  ],
  "abroadStay": {
    "basketItemId": "school-1",
    "startDate": "<YYYY-MM-DD>",
    "endDate": "<YYYY-MM-DD>",
    "coverageRegion": "EUROPE",
    "destinationCountryCode": "DE"
  }
}

MOTOR_THIRD_PARTY_LIABILITY: schema version 1

Compulsory motor third-party liability insurance. It is resolved from a basket item with insuranceCategory: VEHICLE; it is also sold without a basket item. Leads can be opened for this type too: Lead schemas. The type object vehicle is a single policy for a single vehicle. Which vehicle fields are needed is decided by the vehicle's registration scenario (registrationScenario). The price is calculated from the insured's and the vehicle's details, so every field is required at the quote stage.

vehicle

Fields marked with scenarios apply only in those scenarios, and the requirement is applied only then. If they are sent in another scenario, the request receives 422 insurance.validation.invalid (reason: not_applicable) with the field's path.

Registration scenarios

Prepare the quote step by step:

1. Determine the vehicle's registration scenario with the buyer and send it as registrationScenario.
2. Collect the insured's details with the scenario's identity type. If the identity type does not match the scenario, the quote receives 422 insurance.validation.invalid (reason: not_supported_for_registration_scenario) with the field path insured[0].identityType, and the request is not sent to the provider.
3. If the scenario is not RENEWAL, get the vehicle type from the VEHICLE_TYPE list; find the model from the list by vehicle type and year: first VEHICLE_BRAND, then VEHICLE_MODEL under the brand.
4. Fill in the scenario's vehicle fields as in the table and get the quote.

• For an insured with VKN, the company name (companyName) is required and the date of birth is not sent. With TCKN and PASSPORT, the date of birth is required.
• No coverage start day is sent for this type; the policy period is set by the product in your connection.
• In the NEW_REGISTRATION scenario, if the model year is not one of the years the product in your connection accepts, the quote receives 422 insurance.validation.invalid (reason: not_supported_by_provider) with the field path vehicle.modelYear.
• If the vehicle type or the model has no counterpart at your connection's provider, the quote receives 422 insurance.reference.unknown with the field's path.
• If the product in your connection accepts only Turkish mobile numbers, a quote with another number receives 422 insurance.quote.declined.
• For a policy issued with a passport or tax identity number, if the product in your connection does not support cancelling it, the cancellation results in insurance.policy.cancel_failed and the policy stays in force: Cancellation and Premium Refund.
• Formats of the foreign plate and the engine number: Data Formats.

Persons

Example

Renewal (RENEWAL):

{
  "insuranceType": "MOTOR_THIRD_PARTY_LIABILITY",
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "birthDate": "<YYYY-MM-DD>",
      "email": "<email>",
      "phone": "<E.164 phone>"
    }
  ],
  "vehicle": {
    "basketItemId": "car-1",
    "registrationScenario": "RENEWAL",
    "plate": "<plate>",
    "registrationDocument": {
      "serial": "<serial code>",
      "number": "<registration number>"
    }
  }
}

For a new registration (NEW_REGISTRATION) the plate province code is sent instead of a plate:

"vehicle": {
  "basketItemId": "car-1",
  "registrationScenario": "NEW_REGISTRATION",
  "plateCityCode": "34",
  "modelCode": "<model code>",
  "modelYear": 2026,
  "vehicleTypeCode": "<vehicle type code>",
  "engineNumber": "<engine number>",
  "chassisNumber": "<chassis number>"
}

For a dealer's short-term policy (DEALER_SHORT_TERM) the insured is sent with a tax identity number:

"insured": [
  {
    "identityType": "VKN",
    "identityNumber": "<tax identity number>",
    "companyName": "<company name>",
    "email": "<email>",
    "phone": "<E.164 phone>"
  }
]

MOTOR_COMPREHENSIVE: schema version 1

Comprehensive motor insurance. It is resolved from a basket item with insuranceCategory: VEHICLE; it is also sold without a basket item. Leads can be opened for this type too: Lead schemas. The type object vehicle is a single policy for a single vehicle. The price is calculated from the insured's and the vehicle's details, so the fields are sent at the quote stage.

The products in your connections need different vehicle fields. The schema covers all of them; only the fields every product needs are required in the schema. If an optional field that a product needs is missing, only that product's option is excluded: Additional product requirements.

vehicle

• One product in your connection may need the registration document, another the model year and the registration date. Options offered to vehicle owners living abroad additionally need the country of origin, the engine and chassis numbers, the model, the vehicle type and the driver's identity number. To get every option, send all the vehicle fields you can collect from your buyer. A missing field is returned with its path on the excluded option (e.g. vehicle.registrationDocument): Quotes › Excluded options.
• Each product in your connections returns its own option; one quote request can return several options: Quotes › Multiple options.
• This version accepts only vehicles with a Turkish plate.
• The day is a calendar day in Türkiye. A past start day receives 422 insurance.validation.invalid (reason: must_not_be_past) at quote time. If the start day has passed when the order is created, the order is rejected with insurance.quote.declined; get a new quote.
• If the vehicle type, the model or the country of origin has no counterpart at your connection's provider, that product's option is excluded with insurance.reference.unknown and the field's path.
• If the product in your connection accepts only Turkish mobile numbers, a quote with another number receives 422 insurance.quote.declined.

Persons

Example

{
  "insuranceType": "MOTOR_COMPREHENSIVE",
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "birthDate": "<YYYY-MM-DD>",
      "email": "<email>",
      "phone": "<E.164 phone>"
    }
  ],
  "vehicle": {
    "basketItemId": "car-1",
    "plate": "<plate>",
    "coverageStartDate": "<YYYY-MM-DD>",
    "registrationDocument": {
      "serial": "<serial code>",
      "number": "<registration number>"
    },
    "registrationDate": "<YYYY-MM-DD>",
    "modelYear": 2022,
    "vehicleTypeCode": "<vehicle type code>"
  }
}

MOTOR_EXCESS_LIABILITY: schema version 1

Voluntary excess motor liability insurance for a vehicle. It is resolved from a basket item with insuranceCategory: VEHICLE; it is also sold without a basket item. The type object vehicle is a single policy for a single vehicle. The price is calculated from the insured's and the vehicle's details and the chosen limit, so every field is required at the quote stage.

vehicle

• Get the limits from the GET /api/v1/insurance/reference/LIABILITY_LIMIT list. Show the display name (label) to the buyer and send the code in the request.
• This version accepts only vehicles with a Turkish plate.
• The day is a calendar day in Türkiye. A past start day receives 422 insurance.validation.invalid (reason: must_not_be_past) at quote time. If the start day has passed when the order is created, the order is rejected with insurance.quote.declined; get a new quote.
• If the limit, the usage, the vehicle type or the model has no counterpart at your connection's provider, the quote receives 422 insurance.reference.unknown with the field's path.
• If the product in your connection accepts only Turkish mobile numbers, a quote with another number receives 422 insurance.quote.declined.

Persons

Example

{
  "insuranceType": "MOTOR_EXCESS_LIABILITY",
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "birthDate": "<YYYY-MM-DD>",
      "email": "<email>",
      "phone": "<E.164 phone>"
    }
  ],
  "vehicle": {
    "basketItemId": "car-1",
    "plate": "<plate>",
    "registrationDocument": {
      "serial": "<serial code>",
      "number": "<registration number>"
    },
    "chassisNumber": "<chassis number>",
    "engineNumber": "<engine number>",
    "modelCode": "<model code>",
    "modelYear": 2022,
    "vehicleTypeCode": "<vehicle type code>",
    "vehicleUsageCode": "<usage code>",
    "coverageStartDate": "<YYYY-MM-DD>",
    "liabilityLimitCode": "<limit code>"
  }
}

COMPULSORY_EARTHQUAKE: schema version 1

Compulsory earthquake insurance (DASK) for a home. It is resolved from a basket item with insuranceCategory: HOME; it is also sold without a basket item. The type object property is a single policy for a single independent unit (home). The home's address is sent as a UAVT address code: UAVT address chain. The price is calculated from the insured's and the home's details, so the home fields are required at the quote stage.

property

lienholder:

Fields marked "BANK only" and "FINANCE only" apply only for that institution type and are required there. If they are sent for the other type, the request is rejected. If there is no lienholder, do not send lienholder.

• Checking of the UAVT address code: UAVT address chain.
• Building fields are raw values (year, floor count, square metres); do not convert them into ranges. A value the product in your connection does not accept (e.g. more floors than the product's limit) receives 422 insurance.validation.invalid (reason: not_supported_by_provider) with the field's path.
• The day is a calendar day in Türkiye. A past start day receives 422 insurance.validation.invalid (reason: must_not_be_past) at quote time. If the start day has passed when the order is created, the order is rejected with insurance.quote.declined; get a new quote.
• If the bank, branch, finance institution or the address district has no counterpart at your connection's provider, the request receives 422 insurance.reference.unknown with the field's path.
• If the product in your connection accepts only Turkish mobile numbers, a quote with another number receives 422 insurance.quote.declined.

Persons

Example

{
  "insuranceType": "COMPULSORY_EARTHQUAKE",
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "birthDate": "<YYYY-MM-DD>",
      "email": "<email>",
      "phone": "<E.164 phone>",
      "address": {
        "cityCode": "35",
        "districtCode": "<district code>",
        "line": "<address line>"
      }
    }
  ],
  "property": {
    "basketItemId": "home-1",
    "uavtAddressCode": "<UAVT address code>",
    "coverageStartDate": "<YYYY-MM-DD>",
    "areaSqm": 120,
    "floorCount": 5,
    "constructionType": "REINFORCED_CONCRETE_STEEL",
    "constructionYear": 2005,
    "priorDamage": "NONE",
    "usage": "RESIDENTIAL"
  }
}

If a bank financed the home, lienholder is sent like this:

"lienholder": {
  "institutionType": "BANK",
  "bankCode": "<bank code>",
  "bankBranchCode": "<branch code>",
  "branchCityCode": "35"
}

HOME_INSURANCE: schema version 1

Home insurance. It is resolved from a basket item with insuranceCategory: HOME; it is also sold without a basket item. The type object property is a single policy for a single independent unit (home). The home's address is sent as a UAVT address code: UAVT address chain. The price is calculated from the insured's and the home's details and the sums insured, so every field is required at the quote stage.

property

The lienholder fields are the same as for COMPULSORY_EARTHQUAKE (above); only the branch province (branchCityCode) is not in this schema, and if it is sent the request is rejected.

• Yes/no fields are JSON booleans (true, false) and all of them are required; text such as "true" is not accepted.
• If a sum insured is outside the limits, the quote receives 422 insurance.validation.invalid with the field's path: reason: must_be_at_most_100000000 at the upper limit, reason: must_be_at_least_<limit> at the lower limit.
• If the product in your connection takes the sums insured in whole lira, an amount with kuruş receives reason: not_supported_by_provider with the field's path. Send the sums insured in whole lira (a multiple of 100 minor units).
• No coverage start day is sent in this version; the policy period is set by the product in your connection.
• Checking of the UAVT address code: UAVT address chain.
• If the dwelling type, the floor, the bank, the branch or the finance institution has no counterpart at your connection's provider, the quote receives 422 insurance.reference.unknown with the field's path.
• If the product in your connection accepts only Turkish mobile numbers, a quote with another number receives 422 insurance.quote.declined.

Persons

Example

{
  "insuranceType": "HOME_INSURANCE",
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "birthDate": "<YYYY-MM-DD>",
      "email": "<email>",
      "phone": "<E.164 phone>"
    }
  ],
  "property": {
    "basketItemId": "home-1",
    "uavtAddressCode": "<UAVT address code>",
    "areaSqm": 120,
    "constructionYear": 2005,
    "dwellingTypeCode": "<dwelling type code>",
    "floorCode": "<floor code>",
    "contentsFireAmount": 50000000,
    "interiorDecorationAmount": 10000000,
    "glassBreakageAmount": 2000000,
    "vacantOverThreeMonths": false,
    "hasEarthquakePolicy": true,
    "inGatedSite": false,
    "hasAlarm": false,
    "hasCamera": false,
    "hasWindowBars": false,
    "hasFireExtinguisher": true,
    "hasSprinkler": false,
    "hasResidualCurrentDevice": true,
    "hasGasDetector": true,
    "isOwner": true,
    "includeWatercraft": false
  }
}

SUPPLEMENTARY_HEALTH: schema version 1

Supplementary health insurance. This type is not linked to a basket item; it is sold only on the API path, without a basket item: Selling Without a Basket Item. The type object health holds the details of the insurance and carries no basketItemId. A quote covers a single person, insured with a Turkish identity number. The health declaration (height, weight, pregnancy status) is in the insured's fields. The price is calculated from the insured's details, so the person fields are required at the quote stage.

health

Health declaration

• The quote returns only plans of the plan type chosen with planType. If the product in your connection offers plans from several insurance companies, one quote request returns a separate option per company and plan: Quotes › Multiple options.
• When pregnancyCover: true, insured[0].pregnancyStatus is required; if it is not sent, reason: required is returned. On a quote without pregnancy cover, a pregnancyStatus is rejected with reason: not_applicable.
• The health declaration is special-category personal data. It is sent only in the quote request; error responses carry only the field's path, never its value. Do not use a real person's details in tests.
• You can list an option's contracted health facilities by province: Quotes › Contracted facilities.
• Some options do not accept instalments. For such an option, if installmentCount is greater than 1, the premium collection is rejected with insurance.quote.declined.
• The insured's address is in Türkiye: insured[0].address.countryCode must be TR. With another country, the order is rejected with insurance.quote.declined.
• If the province, district or country of the address has no counterpart at your connection's provider, the request receives 422 insurance.reference.unknown with the field's path.
• First and last names are not needed.
• If the product in your connection accepts only Turkish mobile numbers, a quote with another number receives 422 insurance.quote.declined.

Persons

Example

{
  "insuranceType": "SUPPLEMENTARY_HEALTH",
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "birthDate": "<YYYY-MM-DD>",
      "email": "<email>",
      "phone": "<E.164 phone>",
      "heightCm": 170,
      "weightKg": 70,
      "address": {
        "countryCode": "TR",
        "cityCode": "06",
        "districtCode": "<district code>",
        "line": "<address line>"
      }
    }
  ],
  "health": {
    "planType": "INPATIENT_OUTPATIENT"
  }
}