Guides
Import entities
What you can push into Lydira, what each type holds, and a body you can post as it stands.
GET /api/v1/imports/entities, which is the authoritative version and moves with the product. Read it at runtime rather than hardcoding a field list, and use the /validate twin before the real write.external_idis required on every row. It is your own key in your own system, and it is what makes a retry safe.- Dry-run is the same code path.
POST …/validateruns it with nothing persisted, so green there means green on the real thing. - A bad row fails alone. The rest of the batch still imports, and the failed row comes back with a per-field reason.
Writable
Endpoints
- validatePOST /api/v1/imports/customers/validate
- importPOST /api/v1/imports/customers
- feedGET /api/v1/imports/customers/records
- read_backGET /api/v1/imports/customers/records/{external_id}
Fields(16)
external_idstringsource primary key → ExternalReference
namestringrequiredPIIcustomer_typeenumindividualcorporateemailemailPIIphonephonePIIlegal_namestringtax_numbertax_numbertax_officestringaddress_linestringPIIaddress_districtstringPIIaddress_citystringPIIaddress_statestringPIIaddress_zipstringPIIpreferred_currencycurrencycodestringnotesstringPIIfree text; imported as a customer note
{
"rows": [
{
"external_id": "CUSTOMER-1001",
"name": "Ada Lovelace",
"customer_type": "individual",
"email": "ada@example.com",
"phone": "+905551112233",
"legal_name": "Lovelace Seyahat A.Ş.",
"tax_office": "Beşiktaş",
"address_line": "Nispetiye Cad. No:12",
"address_district": "Beşiktaş",
"address_city": "İstanbul",
"address_state": "",
"address_zip": "34340",
"preferred_currency": "EUR",
"code": "AC-1001",
"notes": "Imported from the source system."
}
]
}Endpoints
- validatePOST /api/v1/imports/suppliers/validate
- importPOST /api/v1/imports/suppliers
- feedGET /api/v1/imports/suppliers/records
- read_backGET /api/v1/imports/suppliers/records/{external_id}
Fields(16)
external_idstringnamestringrequiredsupplier_typeenuminteger-backed enum — resolved against TravelSupplier.supplier_types
otherairlinehoteldmccruisetour_operatorinsuranceactivitytransferrailcar_rentalconsolidatorgdsvisacharteragencycateringtechnicalproductiondecorationvenuephoto_videoentertainmentsecuritystaffingcodestringiata_codestringemailemailphonephonecountry_codestringtax_numbertax_numbertax_officestringaddress_linestringPIIaddress_districtstringPIIaddress_citystringPIIaddress_statestringPIIaddress_zipstringPIIwebsitestring
{
"rows": [
{
"external_id": "SUPPLIER-1001",
"name": "Ada Lovelace",
"supplier_type": "hotel",
"code": "AC-1001",
"iata_code": "TK",
"email": "ada@example.com",
"phone": "+905551112233",
"country_code": "TR",
"tax_office": "Beşiktaş",
"address_line": "Nispetiye Cad. No:12",
"address_district": "Beşiktaş",
"address_city": "İstanbul",
"address_state": "",
"address_zip": "34340",
"website": "https://example.com"
}
]
}Endpoints
- validatePOST /api/v1/imports/leads/validate
- importPOST /api/v1/imports/leads
- feedGET /api/v1/imports/leads/records
- read_backGET /api/v1/imports/leads/records/{external_id}
Fields(12)
external_idstringnamestringrequiredPIIemailemailPIIphonephonePIIstageenuminboxqualifiednurturingproposalwonlostsourcetaxonomytaxonomy: lead_source
estimated_valuemoneycurrencycurrencyparty_sizeintegerdestinationsstringcustomer_external_idreferencelinks to an imported customer
notesstringPII
References
customer_external_id→ customers · matched by external_id, email · when missing skip
{
"rows": [
{
"external_id": "LEAD-1001",
"name": "Ada Lovelace",
"email": "ada@example.com",
"phone": "+905551112233",
"stage": "inbox",
"source": "website_form",
"estimated_value": "1250.00",
"currency": "EUR",
"party_size": 2,
"destinations": "Roma, Floransa",
"customer_external_id": "CUSTOMER-1001",
"notes": "Imported from the source system."
}
]
}Endpoints
- validatePOST /api/v1/imports/tour_departures/validate
- importPOST /api/v1/imports/tour_departures
- feedGET /api/v1/imports/tour_departures/records
- read_backGET /api/v1/imports/tour_departures/records/{external_id}
Fields(9)
external_idstringsource primary key → ExternalReference
titlestringrequiredstarts_ondateends_ondatecurrencycurrencymax_capacityintegerinventory_stateenumopenclosed_directon_requestmin_not_metsold_outcancelleddepartedcompletednotesstringsupplier_external_idreferencethe operator we bought the seat from
References
supplier_external_id→ suppliers · matched by external_id, code · when missing skip
{
"rows": [
{
"external_id": "TOUR-DEPARTURE-1001",
"title": "Title",
"starts_on": "2026-03-14",
"ends_on": "2026-03-18",
"currency": "EUR",
"max_capacity": 2,
"inventory_state": "open",
"notes": "Imported from the source system.",
"supplier_external_id": "SUPPLIER-1001"
}
]
}Endpoints
- validatePOST /api/v1/imports/car_rentals/validate
- importPOST /api/v1/imports/car_rentals
- feedGET /api/v1/imports/car_rentals/records
- read_backGET /api/v1/imports/car_rentals/records/{external_id}
Fields(20)
external_idstringvehicle_classstringpickup_locationstringdropoff_locationstringpickup_atdatetimereturn_atdatetimepax_countintegercurrencycurrencycustomer_external_idreferencesupplier_external_idreferencestatusenumdraftoptionconfirmedoutreturnedcancelledno_shownotesstringrate_basisenumnet ⇒ cost typed / sell derived; commissionable ⇒ the reverse
netcommissionablemargin_modeenumpercent ⇒ the margin was typed as a %; amount ⇒ as a flat figure
percentamountoption_datedatetransaction_datedateişlem tarihi — the FX anchor for every cost line
invoice_datedatecost_lineslistcost-side pricing lines for the "car_rental" pricing context
sell_lineslistsell-side pricing lines for the "car_rental" pricing context
travelerslistPIIguests; auto-saved to the customer's traveller directory
References
{
"rows": [
{
"external_id": "CAR-RENTAL-1001",
"vehicle_class": "compact",
"pickup_location": "IST Airport",
"dropoff_location": "Beyoğlu, İstanbul",
"pickup_at": "2026-03-14T09:30:00+03:00",
"return_at": "2026-03-14T12:45:00+03:00",
"pax_count": 2,
"currency": "EUR",
"customer_external_id": "CUSTOMER-1001",
"supplier_external_id": "SUPPLIER-1001",
"status": "draft",
"notes": "Imported from the source system.",
"rate_basis": "net",
"margin_mode": "percent",
"option_date": "2026-03-14",
"transaction_date": "2026-03-14",
"invoice_date": "2026-03-18",
"cost_lines": [
{
"kind": "daily_rate",
"amount": "1250.00",
"label": "Imported line",
"currency": "EUR",
"vat_rate": "20",
"tax_inclusive": true,
"quantity": 1
}
],
"sell_lines": [
{
"kind": "package_price",
"amount": "1250.00",
"label": "Imported line",
"currency": "EUR",
"vat_rate": "20",
"tax_inclusive": true,
"quantity": 1
}
],
"travelers": [
{
"first_name": "Ada",
"last_name": "Lovelace",
"nationality": "TR",
"national_id": "10000000146",
"passport_number": "U01234567",
"passport_country": "TR",
"passport_expiry": "2031-06-30",
"date_of_birth": "1988-04-21",
"gender": "female",
"frequent_flyer_number": "TK123456789"
}
]
}
]
}Endpoints
- validatePOST /api/v1/imports/cruises/validate
- importPOST /api/v1/imports/cruises
- feedGET /api/v1/imports/cruises/records
- read_backGET /api/v1/imports/cruises/records/{external_id}
Fields(20)
external_idstringship_namestringembark_ondatedisembark_ondatecabin_countintegerguest_countintegercurrencycurrencycustomer_external_idreferencesupplier_external_idreferencestatusenumdraftoptionconfirmedsailingcompletedcancellednotesstringrate_basisenumnet ⇒ cost typed / sell derived; commissionable ⇒ the reverse
netcommissionablemargin_modeenumpercent ⇒ the margin was typed as a %; amount ⇒ as a flat figure
percentamountoption_datedatetransaction_datedateişlem tarihi — the FX anchor for every cost line
invoice_datedatecost_lineslistcost-side pricing lines for the "cruise" pricing context
sell_lineslistsell-side pricing lines for the "cruise" pricing context
travelerslistPIIguests; auto-saved to the customer's traveller directory
cabin_categorystring
References
{
"rows": [
{
"external_id": "CRUISE-1001",
"ship_name": "MSC Fantasia",
"embark_on": "2026-03-14",
"disembark_on": "2026-03-18",
"cabin_count": 2,
"guest_count": 2,
"currency": "EUR",
"customer_external_id": "CUSTOMER-1001",
"supplier_external_id": "SUPPLIER-1001",
"status": "draft",
"notes": "Imported from the source system.",
"rate_basis": "net",
"margin_mode": "percent",
"option_date": "2026-03-14",
"transaction_date": "2026-03-14",
"invoice_date": "2026-03-18",
"cost_lines": [
{
"kind": "cabin_fare",
"amount": "1250.00",
"label": "Imported line",
"currency": "EUR",
"vat_rate": "20",
"tax_inclusive": true,
"quantity": 1
}
],
"sell_lines": [
{
"kind": "package_price",
"amount": "1250.00",
"label": "Imported line",
"currency": "EUR",
"vat_rate": "20",
"tax_inclusive": true,
"quantity": 1
}
],
"travelers": [
{
"first_name": "Ada",
"last_name": "Lovelace",
"nationality": "TR",
"national_id": "10000000146",
"passport_number": "U01234567",
"passport_country": "TR",
"passport_expiry": "2031-06-30",
"date_of_birth": "1988-04-21",
"gender": "female",
"frequent_flyer_number": "TK123456789"
}
],
"cabin_category": "balcony"
}
]
}Endpoints
- validatePOST /api/v1/imports/hotel_stays/validate
- importPOST /api/v1/imports/hotel_stays
- feedGET /api/v1/imports/hotel_stays/records
- read_backGET /api/v1/imports/hotel_stays/records/{external_id}
Fields(18)
external_idstringcheck_in_ondaterequiredcheck_out_ondaterequiredcurrencycurrencyguest_countintegercustomer_external_idreferencesupplier_external_idreferencestatusenumdraftoptionconfirmedin_housechecked_outcancelledno_shownotesstringrate_basisenumnet ⇒ cost typed / sell derived; commissionable ⇒ the reverse
netcommissionablemargin_modeenumpercent ⇒ the margin was typed as a %; amount ⇒ as a flat figure
percentamountoption_datedatetransaction_datedateişlem tarihi — the FX anchor for every cost line
invoice_datedatecost_lineslistcost-side pricing lines for the "hotel" pricing context
sell_lineslistsell-side pricing lines for the "hotel" pricing context
travelerslistPIIguests; auto-saved to the customer's traveller directory
roomslista room with a `nightly_rate` contributes a room_rate SELL line × nights
References
{
"rows": [
{
"external_id": "HOTEL-STAY-1001",
"check_in_on": "2026-03-14",
"check_out_on": "2026-03-18",
"currency": "EUR",
"guest_count": 2,
"customer_external_id": "CUSTOMER-1001",
"supplier_external_id": "SUPPLIER-1001",
"status": "draft",
"notes": "Imported from the source system.",
"rate_basis": "net",
"margin_mode": "percent",
"option_date": "2026-03-14",
"transaction_date": "2026-03-14",
"invoice_date": "2026-03-18",
"cost_lines": [
{
"kind": "room_rate",
"amount": "1250.00",
"label": "Imported line",
"currency": "EUR",
"vat_rate": "20",
"tax_inclusive": true,
"quantity": 1
}
],
"sell_lines": [
{
"kind": "package_price",
"amount": "1250.00",
"label": "Imported line",
"currency": "EUR",
"vat_rate": "20",
"tax_inclusive": true,
"quantity": 1
}
],
"travelers": [
{
"first_name": "Ada",
"last_name": "Lovelace",
"nationality": "TR",
"national_id": "10000000146",
"passport_number": "U01234567",
"passport_country": "TR",
"passport_expiry": "2031-06-30",
"date_of_birth": "1988-04-21",
"gender": "female",
"frequent_flyer_number": "TK123456789"
}
],
"rooms": [
{
"name": "Deluxe Sea View",
"room_type": "double",
"capacity": 2,
"occupancy": 2,
"nightly_rate": "180.00",
"single_supplement_amount": "60.00",
"single_supplement_currency": "EUR"
}
]
}
]
}Endpoints
- validatePOST /api/v1/imports/tickets/validate
- importPOST /api/v1/imports/tickets
- feedGET /api/v1/imports/tickets/records
- read_backGET /api/v1/imports/tickets/records/{external_id}
Fields(17)
external_idstringsource primary key → ExternalReference
pnrstringgds_pnrstringcurrencycurrencysettlement_channelenumwho we pay — drives the airline payable + BSP recon
bspdirectwebcardconsolidatorprepaidfare_typestringtaxonomy `fare_type` (normal, award, …)
miles_usedintegerreservation_giver_namestringissuing_systemstringoption_datedateticketing deadline; set ⇒ the sale opens as `option` rather than `draft`
transaction_datedateişlem tarihi — the FX anchor for every cost line
invoice_datedatenotesstringlegslistshared itinerary; int/dom + one-way/round-trip are derived from the airports
passengerslistrequiredPIIone Ticket each; identities are auto-saved to the customer's traveller directory
customer_external_idreferencesupplier_external_idreferencethe settlement supplier (airline / consolidator) we pay
References
{
"rows": [
{
"external_id": "TICKET-1001",
"pnr": "ABC123",
"gds_pnr": "ABC123",
"currency": "EUR",
"settlement_channel": "bsp",
"fare_type": "normal",
"miles_used": 2,
"reservation_giver_name": "Ada Lovelace",
"issuing_system": "amadeus",
"option_date": "2026-03-14",
"transaction_date": "2026-03-14",
"invoice_date": "2026-03-18",
"notes": "Imported from the source system.",
"legs": [
{
"airline_code": "TK",
"flight_number": "1985",
"departure_airport": "IST",
"arrival_airport": "FCO",
"departure_at": "2026-03-14T09:30:00+03:00",
"arrival_at": "2026-03-14T12:45:00+03:00",
"cabin_class": "economy",
"booking_class": "L",
"fare_basis": "LLXOW",
"baggage_allowance": "1PC",
"status": "confirmed"
}
],
"passengers": [
{
"first_name": "Ada",
"last_name": "Lovelace",
"nationality": "TR",
"national_id": "10000000146",
"passport_number": "U01234567",
"passport_country": "TR",
"passport_expiry": "2031-06-30",
"date_of_birth": "1988-04-21",
"gender": "female",
"frequent_flyer_number": "TK123456789",
"name": "Ada Lovelace",
"type": "adult",
"ticket_number": "235-1234567890",
"cost_lines": [
{
"kind": "base_fare",
"amount": "1250.00",
"label": "Imported line",
"currency": "EUR",
"vat_rate": "20",
"tax_inclusive": true,
"quantity": 1
}
],
"sell_lines": [
{
"kind": "package_price",
"amount": "1250.00",
"label": "Imported line",
"currency": "EUR",
"vat_rate": "20",
"tax_inclusive": true,
"quantity": 1
}
]
}
],
"customer_external_id": "CUSTOMER-1001",
"supplier_external_id": "SUPPLIER-1001"
}
]
}Endpoints
- validatePOST /api/v1/imports/tour_bookings/validate
- importPOST /api/v1/imports/tour_bookings
- feedGET /api/v1/imports/tour_bookings/records
- read_backGET /api/v1/imports/tour_bookings/records/{external_id}
Fields(13)
external_idstringsource primary key → ExternalReference
namestringrequiredPIIlead passenger / party name
party_sizeintegerrequiredcurrencycurrencyphonephonePIIstatusenumpendingconfirmedcancellednotesstringtransaction_datedateişlem tarihi — the FX anchor for every line
invoice_datedatecost_lineslistcost-side pricing lines for the "tour" pricing context
sell_lineslistsell-side pricing lines for the "tour" pricing context
customer_external_idreferencedeparture_external_idreferencerequiredthe departure this seat is on — import it first
References
customer_external_id→ customers · matched by external_id, email · when missing skipdeparture_external_id→ tour_departures · matched by external_id · when missing error
{
"rows": [
{
"external_id": "TOUR-BOOKING-1001",
"name": "Ada Lovelace",
"party_size": 2,
"currency": "EUR",
"phone": "+905551112233",
"status": "pending",
"notes": "Imported from the source system.",
"transaction_date": "2026-03-14",
"invoice_date": "2026-03-18",
"cost_lines": [
{
"kind": "ticket_price",
"amount": "1250.00",
"label": "Imported line",
"currency": "EUR",
"vat_rate": "20",
"tax_inclusive": true,
"quantity": 1
}
],
"sell_lines": [
{
"kind": "package_price",
"amount": "1250.00",
"label": "Imported line",
"currency": "EUR",
"vat_rate": "20",
"tax_inclusive": true,
"quantity": 1
}
],
"customer_external_id": "CUSTOMER-1001",
"departure_external_id": "TOUR-DEPARTURE-1001"
}
]
}Endpoints
- validatePOST /api/v1/imports/transfers/validate
- importPOST /api/v1/imports/transfers
- feedGET /api/v1/imports/transfers/records
- read_backGET /api/v1/imports/transfers/records/{external_id}
Fields(21)
external_idstringpickup_atdatetimerequiredpickup_locationstringrequireddropoff_locationstringrequiredcurrencycurrencypax_countintegercustomer_external_idreferencesupplier_external_idreferencestatusenumbookedassigneden_routecompletedcancelledno_shownotesstringrate_basisenumnet ⇒ cost typed / sell derived; commissionable ⇒ the reverse
netcommissionablemargin_modeenumpercent ⇒ the margin was typed as a %; amount ⇒ as a flat figure
percentamounttransaction_datedateişlem tarihi — the FX anchor for every cost line
invoice_datedatecost_lineslistcost-side pricing lines for the "transfer" pricing context
sell_lineslistsell-side pricing lines for the "transfer" pricing context
travelerslistPIIguests; auto-saved to the customer's traveller directory
duration_minutesintegerairline_codestringinbound/outbound flight the transfer meets
flight_numberstringflight_datedate
References
{
"rows": [
{
"external_id": "TRANSFER-1001",
"pickup_at": "2026-03-14T09:30:00+03:00",
"pickup_location": "IST Airport",
"dropoff_location": "Beyoğlu, İstanbul",
"currency": "EUR",
"pax_count": 2,
"customer_external_id": "CUSTOMER-1001",
"supplier_external_id": "SUPPLIER-1001",
"status": "booked",
"notes": "Imported from the source system.",
"rate_basis": "net",
"margin_mode": "percent",
"transaction_date": "2026-03-14",
"invoice_date": "2026-03-18",
"cost_lines": [
{
"kind": "vehicle_fare",
"amount": "1250.00",
"label": "Imported line",
"currency": "EUR",
"vat_rate": "20",
"tax_inclusive": true,
"quantity": 1
}
],
"sell_lines": [
{
"kind": "package_price",
"amount": "1250.00",
"label": "Imported line",
"currency": "EUR",
"vat_rate": "20",
"tax_inclusive": true,
"quantity": 1
}
],
"travelers": [
{
"first_name": "Ada",
"last_name": "Lovelace",
"nationality": "TR",
"national_id": "10000000146",
"passport_number": "U01234567",
"passport_country": "TR",
"passport_expiry": "2031-06-30",
"date_of_birth": "1988-04-21",
"gender": "female",
"frequent_flyer_number": "TK123456789"
}
],
"duration_minutes": 2,
"airline_code": "TK",
"flight_number": "1985",
"flight_date": "2026-03-14"
}
]
}Endpoints
- validatePOST /api/v1/imports/operator_invoices/validate
- importPOST /api/v1/imports/operator_invoices
- feedGET /api/v1/imports/operator_invoices/records
- read_backGET /api/v1/imports/operator_invoices/records/{external_id}
Fields(11)
external_idstringlegacy_numberstringrequiredissued_ondaterequireddue_ondatetotal_amountmoneyrequiredamount_paidmoneyalready collected before cutover; imported as a brought-forward receipt
paid_ondatewhen `amount_paid` was collected; defaults to the invoice date
currencycurrencybill_to_namestringcustomer_external_idreferencenotesstring
References
customer_external_id→ customers · matched by external_id, email · when missing error
{
"rows": [
{
"external_id": "OPERATOR-INVOICE-1001",
"legacy_number": "2025-000431",
"issued_on": "2026-03-14",
"due_on": "2026-03-18",
"total_amount": "1250.00",
"amount_paid": "1250.00",
"paid_on": "2026-03-14",
"currency": "EUR",
"bill_to_name": "Lovelace Seyahat A.Ş.",
"customer_external_id": "CUSTOMER-1001",
"notes": "Imported from the source system."
}
]
}Endpoints
- validatePOST /api/v1/imports/supplier_bills/validate
- importPOST /api/v1/imports/supplier_bills
- feedGET /api/v1/imports/supplier_bills/records
- read_backGET /api/v1/imports/supplier_bills/records/{external_id}
Fields(10)
external_idstringnumberstringrequiredreceived_atdaterequireddue_ondatetotal_amountmoneyrequiredamount_paidmoneyalready paid before cutover; imported as a brought-forward payment
paid_ondatewhen `amount_paid` was paid; defaults to the bill date
currencycurrencysupplier_external_idreferencenotesstring
References
supplier_external_id→ suppliers · matched by external_id, code · when missing error
{
"rows": [
{
"external_id": "SUPPLIER-BILL-1001",
"number": "TR-2025-000431",
"received_at": "2026-03-14",
"due_on": "2026-03-18",
"total_amount": "1250.00",
"amount_paid": "1250.00",
"paid_on": "2026-03-14",
"currency": "EUR",
"supplier_external_id": "SUPPLIER-1001",
"notes": "Imported from the source system."
}
]
}Read and broadcast only
POST to one answers 422 entity_not_writable.chartersCharterseventsEventsvisa_casesVisa cases