Import guides

Tours

Tour departures first, then the seats booked on them.

A tour has two parts. The departure is the trip itself with its capacity; a booking is a seat on it. Push the departure first: a booking whose departure cannot be found is refused.

Tour departures`tour_departures`

POST/api/v1/imports/tour_departures

Upsert: re-sending the same external_id updates the existing row.

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}

A new row must carry

title

Fields(9)

external_idstring
source primary key → ExternalReference
titlestringrequired
starts_ondate
ends_ondate
currencycurrency
max_capacityinteger
inventory_stateenum
One of:openclosed_directon_requestmin_not_metsold_outcancelleddepartedcompleted
notesstring
supplier_external_idreference
the operator we bought the seat from

References

supplier_external_id → suppliers · matched by external_id, code · when missing skip

Reading it back

Once the agency works the record (confirms it, numbers the tickets, invoices it) this is what GET /api/v1/imports/{entity}/records/{external_id} answers, and what every webhook delivers. detail carries what only the agency can add after your push.

GET /api/v1/imports/tour_departures/records/TOUR-DEPARTURE-1001

200

{
  "entity": "tour_departures",
  "external_id": "TOUR-DEPARTURE-1001",
  "source_system": "crm",
  "type": "TourDeparture",
  "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
  "created_at": "2026-03-14T09:30:00Z",
  "updated_at": "2026-03-15T11:05:00Z",
  "currency": "EUR",
  "totals": {
    "cost": "1100.0",
    "sell": "1250.0"
  },
  "invoices": [
    {
      "id": "4b8e1f60-7c2d-4e9a-b3f5-0a6d2c9e8b71",
      "number": "LYD2026000000117",
      "status": "issued",
      "currency": "EUR",
      "total": "1250.0",
      "balance": "1250.0"
    }
  ],
  "detail": {
    "title": "Cappadocia Highlights",
    "inventory_state": "open",
    "starts_on": "2026-03-14",
    "ends_on": "2026-03-18",
    "max_capacity": 24,
    "supplier": "Lovelace Travel Partners"
  }
}

Request · dry run, every field

curl -X POST 'https://YOUR-CELL.lydira.com/api/v1/imports/tour_departures/validate' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90' \
  -d '{
  "source_system": "crm",
  "rows": [
    {
      "external_id": "TOUR-DEPARTURE-1001",
      "title": "Cappadocia Highlights",
      "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"
    }
  ]
}'

const response = await fetch(
  "https://YOUR-CELL.lydira.com/api/v1/imports/tour_departures/validate",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sek_YOUR_API_KEY",
      "Content-Type": "application/json",
      "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
    body: JSON.stringify({
      "source_system": "crm",
      "rows": [
        {
          "external_id": "TOUR-DEPARTURE-1001",
          "title": "Cappadocia Highlights",
          "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"
        }
      ]
    }),
  },
);

if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const data = await response.json();

import requests

response = requests.post(
    "https://YOUR-CELL.lydira.com/api/v1/imports/tour_departures/validate",
    headers={
        "Authorization": "Bearer sek_YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
    json={
      "source_system": "crm",
      "rows": [
        {
          "external_id": "TOUR-DEPARTURE-1001",
          "title": "Cappadocia Highlights",
          "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"
        }
      ]
    },
)
response.raise_for_status()
data = response.json()

require "net/http"
require "json"

uri = URI("https://YOUR-CELL.lydira.com/api/v1/imports/tour_departures/validate")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer sek_YOUR_API_KEY"
request["Content-Type"] = "application/json"
request["Idempotency-Key"] = "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90"
request.body = JSON.generate({
  source_system: "crm",
  rows: [
    {
      external_id: "TOUR-DEPARTURE-1001",
      title: "Cappadocia Highlights",
      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"
    }
  ]
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { it.request(request) }
raise response.body unless response.is_a?(Net::HTTPSuccess)
data = JSON.parse(response.body)

<?php
$ch = curl_init("https://YOUR-CELL.lydira.com/api/v1/imports/tour_departures/validate");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer sek_YOUR_API_KEY",
        "Content-Type: application/json",
        "Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "source_system" => "crm",
        "rows" => [
            [
                "external_id" => "TOUR-DEPARTURE-1001",
                "title" => "Cappadocia Highlights",
                "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",
            ],
        ],
    ]),
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Response

200

{
  "import": {
    "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "entity": "tour_departures",
    "source_system": "crm",
    "status": "ready",
    "company_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "stats": {
      "total": 1,
      "will_create": 1,
      "will_update": 0,
      "created": 0,
      "updated": 0,
      "skipped": 0,
      "invalid": 0,
      "failed": 0,
      "not_selected": 0
    },
    "error": null,
    "created_at": "2026-03-14T09:30:00Z",
    "links": {
      "self": "/api/v1/imports/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "rows": "/api/v1/imports/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/rows"
    },
    "mode": "validate",
    "async": false,
    "on_conflict": "skip",
    "pricing": "apply_rules"
  },
  "ignored_fields": [],
  "results": [
    {
      "row": 1,
      "external_id": "TOUR-DEPARTURE-1001",
      "status": "will_create"
    }
  ]
}

Tour bookings`tour_bookings`

POST/api/v1/imports/tour_bookings

Create-once: re-sending the same external_id skips rather than duplicating.

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}

A new row must carry

nameparty_sizedeparture_external_id

Who the booking bills

Send customer_external_id when you know the customer; it always wins. Otherwise Lydira finds the customer from the billing details, or opens one. Email, phone and names are never matched on, and a found customer only has its blank fields filled.

Corporate (a legal name or a 10-digit tax number): tax_number → legal_name

Individual: tax_number → passport_number

Bill-to fields:bill_to_typebill_to_legal_namebill_to_tax_numberbill_to_tax_officebill_to_passport_numberbill_to_first_namebill_to_last_namebill_to_emailbill_to_phonebill_to_address_linebill_to_districtbill_to_citybill_to_zipbill_to_country

Each row's result carries payer: which customer it was bound to, by which identity (by), whether one was opened (on /validate, would be opened), and a warning when none could be. Its outcome is one of:

external_idmatchedcreatedwould_createnone

Sample request billed by its bill-to (no customer key)

curl -X POST 'https://YOUR-CELL.lydira.com/api/v1/imports/tour_bookings/validate' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90' \
  -d '{
  "source_system": "crm",
  "rows": [
    {
      "external_id": "TOUR-BOOKING-1001-B",
      "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
        }
      ],
      "departure_external_id": "TOUR-DEPARTURE-1001",
      "bill_to_legal_name": "Lovelace Seyahat A.Ş.",
      "bill_to_tax_number": "1234567890",
      "bill_to_tax_office": "Beşiktaş",
      "bill_to_address_line": "Nispetiye Cad. No:12",
      "bill_to_city": "İstanbul",
      "bill_to_country": "TR"
    }
  ]
}'

const response = await fetch(
  "https://YOUR-CELL.lydira.com/api/v1/imports/tour_bookings/validate",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sek_YOUR_API_KEY",
      "Content-Type": "application/json",
      "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
    body: JSON.stringify({
      "source_system": "crm",
      "rows": [
        {
          "external_id": "TOUR-BOOKING-1001-B",
          "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
            }
          ],
          "departure_external_id": "TOUR-DEPARTURE-1001",
          "bill_to_legal_name": "Lovelace Seyahat A.Ş.",
          "bill_to_tax_number": "1234567890",
          "bill_to_tax_office": "Beşiktaş",
          "bill_to_address_line": "Nispetiye Cad. No:12",
          "bill_to_city": "İstanbul",
          "bill_to_country": "TR"
        }
      ]
    }),
  },
);

if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const data = await response.json();

import requests

response = requests.post(
    "https://YOUR-CELL.lydira.com/api/v1/imports/tour_bookings/validate",
    headers={
        "Authorization": "Bearer sek_YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
    json={
      "source_system": "crm",
      "rows": [
        {
          "external_id": "TOUR-BOOKING-1001-B",
          "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
            }
          ],
          "departure_external_id": "TOUR-DEPARTURE-1001",
          "bill_to_legal_name": "Lovelace Seyahat A.Ş.",
          "bill_to_tax_number": "1234567890",
          "bill_to_tax_office": "Beşiktaş",
          "bill_to_address_line": "Nispetiye Cad. No:12",
          "bill_to_city": "İstanbul",
          "bill_to_country": "TR"
        }
      ]
    },
)
response.raise_for_status()
data = response.json()

require "net/http"
require "json"

uri = URI("https://YOUR-CELL.lydira.com/api/v1/imports/tour_bookings/validate")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer sek_YOUR_API_KEY"
request["Content-Type"] = "application/json"
request["Idempotency-Key"] = "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90"
request.body = JSON.generate({
  source_system: "crm",
  rows: [
    {
      external_id: "TOUR-BOOKING-1001-B",
      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
        }
      ],
      departure_external_id: "TOUR-DEPARTURE-1001",
      bill_to_legal_name: "Lovelace Seyahat A.Ş.",
      bill_to_tax_number: "1234567890",
      bill_to_tax_office: "Beşiktaş",
      bill_to_address_line: "Nispetiye Cad. No:12",
      bill_to_city: "İstanbul",
      bill_to_country: "TR"
    }
  ]
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { it.request(request) }
raise response.body unless response.is_a?(Net::HTTPSuccess)
data = JSON.parse(response.body)

<?php
$ch = curl_init("https://YOUR-CELL.lydira.com/api/v1/imports/tour_bookings/validate");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer sek_YOUR_API_KEY",
        "Content-Type: application/json",
        "Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "source_system" => "crm",
        "rows" => [
            [
                "external_id" => "TOUR-BOOKING-1001-B",
                "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,
                    ],
                ],
                "departure_external_id" => "TOUR-DEPARTURE-1001",
                "bill_to_legal_name" => "Lovelace Seyahat A.Ş.",
                "bill_to_tax_number" => "1234567890",
                "bill_to_tax_office" => "Beşiktaş",
                "bill_to_address_line" => "Nispetiye Cad. No:12",
                "bill_to_city" => "İstanbul",
                "bill_to_country" => "TR",
            ],
        ],
    ]),
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

The service fee

A row without service_fee gets the fee the agency's service-fee rules write. A row with one states the agency's fee for the whole booking, in the booking's currency, and the rules write nothing. Or send service_fee_percent: the fee as a percentage, from 0 to 100, of the booking's sale before fee and discount, as on the agency's booking form (10 on a 1,200.00 sale is 120.00). Send one of the two: a row with both, or with a percentage outside 0 to 100, is refused. A 0 in either is no fee of yours, so the rules write theirs. service_fee_vat_rate states its VAT (0 for exempt); leave it out and the law decides, else the agency's standard rate. service_fee_waived: true stops the rules for this booking while a fee you send still stands; an amendment can switch it on or off until the booking is invoiced. The fee itself, amount or percentage, cannot be amended.

A tour booking is priced as a whole: the fee is its one line. A service_fee item in sell_lines works too.

A booking with no sell to split the fee across yet is saved without it, and the row carries the warning: service_fee_dropped

Fields:service_feeservice_fee_percentservice_fee_vat_rateservice_fee_waived

Fields(32)

external_idstring
source primary key → ExternalReference
namestringrequiredPII
lead passenger / party name
party_sizeintegerrequired
currencycurrency
phonephonePII
statusenum
One of:pendingconfirmedcancelled
notesstring
transaction_datedate
işlem tarihi — the FX anchor for every line
invoice_datedate
custom_fieldsobject
the account's own fields on the booking, by key
cost_linesobject[]
cost-side pricing lines for the "tour" pricing context
Each item
- kindstringrequired
  Values the app uses:ticket_priceguide_feeequipment_rentalpermit_feetipservice_feesupplier_refundinsurance_premium
- amountmoneyrequired
- labelstring
- currencycurrency
- vat_ratedecimal
  percent (20 ⇒ 20% KDV); omit to take the kind's default
- tax_inclusiveboolean
  true ⇒ the amount includes VAT. A hotel stay or a charter takes one VAT mode: the lines' flags decide it, lines stating both are refused, and every line follows the booking's mode afterwards
- quantityinteger
sell_linesobject[]
sell-side pricing lines for the "tour" pricing context
Each item
- kindstringrequired
  Values the app uses:package_pricemarkupservice_feesupplier_commissioncancellation_feeinsurance_premiumdiscountrefund_allowanceticket_priceguide_feeequipment_rentalpermit_feetipsupplier_refund
- amountmoneyrequired
- labelstring
- currencycurrency
- vat_ratedecimal
  percent (20 ⇒ 20% KDV); omit to take the kind's default
- tax_inclusiveboolean
  true ⇒ the amount includes VAT. A hotel stay or a charter takes one VAT mode: the lines' flags decide it, lines stating both are refused, and every line follows the booking's mode afterwards
- quantityinteger
service_feemoney
the agency's fee for the whole booking, in its currency; split across the guests like the booking form's. Sent, the account's service-fee rules write nothing
service_fee_percentdecimal
the fee as a percentage (0-100) of the booking's sale before fee and discount, instead of service_fee; split like it
service_fee_vat_ratedecimal
the fee's VAT, percent (0 ⇒ exempt); omit it and the law decides, else the seller's standard rate
service_fee_waivedboolean
true: the account's service-fee rules write no fee on this booking
customer_external_idreference
departure_external_idreferencerequired
the departure this seat is on — import it first
bill_to_typeenum
omit to infer: a legal name or a 10-digit tax number ⇒ corporate
One of:corporateindividual
bill_to_legal_namestring
bill_to_tax_numbertax_numberPII
VKN for a corporate payer, TCKN for an individual; matched digits-only
bill_to_tax_officestring
bill_to_passport_numberstringPII
individual only; used when there is no TCKN
bill_to_first_namestringPII
bill_to_last_namestringPII
bill_to_emailemailPII
stored on a NEW cari; never used to match
bill_to_phonephonePII
stored on a NEW cari; never used to match
bill_to_address_linestringPII
bill_to_districtstringPII
bill_to_citystringPII
bill_to_zipstringPII
bill_to_countrystring
ISO-2 code, e.g. TR

References

customer_external_id → customers · matched by external_id, email · when missing skip
departure_external_id → tour_departures · matched by external_id · when missing error

Your account's own fields (custom_fields)

Each agency adds its own fields in Settings → Custom fields: a project code, a trip reason, an employee number. They differ from account to account, so this page cannot list them. Your integration asks the API for them.

GET /api/v1/imports/entities/{key} answers, under custom_fields, the fields your key's account has on this entity: record for the record itself, traveler for each traveller. Each one names its key (what the row sends), its type, whether it is required, which customers it applies_to and, for a choice, its options. Read it when you build the mapping and again when the agency says it changed a field: it is the account's live list.

Request · the account's fields

curl -X GET 'https://YOUR-CELL.lydira.com/api/v1/imports/entities/tour_bookings' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY'

const response = await fetch(
  "https://YOUR-CELL.lydira.com/api/v1/imports/entities/tour_bookings",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sek_YOUR_API_KEY",
    },
  },
);

if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const data = await response.json();

import requests

response = requests.get(
    "https://YOUR-CELL.lydira.com/api/v1/imports/entities/tour_bookings",
    headers={
        "Authorization": "Bearer sek_YOUR_API_KEY",
    },
)
response.raise_for_status()
data = response.json()

require "net/http"
require "json"

uri = URI("https://YOUR-CELL.lydira.com/api/v1/imports/entities/tour_bookings")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer sek_YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { it.request(request) }
raise response.body unless response.is_a?(Net::HTTPSuccess)
data = JSON.parse(response.body)

<?php
$ch = curl_init("https://YOUR-CELL.lydira.com/api/v1/imports/entities/tour_bookings");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer sek_YOUR_API_KEY",
    ],
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Response · custom_fields (excerpt)

200

{
  "key": "tour_bookings",
  "custom_fields": {
    "record": [
      {
        "key": "project_code",
        "label": "Project code",
        "type": "text",
        "required": "always",
        "applies_to": "all"
      },
      {
        "key": "trip_reason",
        "label": "Trip reason",
        "type": "select",
        "required": "listed_customers",
        "applies_to": "listed_customers",
        "options": [
          {
            "value": "meeting",
            "label": "Meeting"
          },
          {
            "value": "fair",
            "label": "Trade fair"
          }
        ],
        "customers": [
          {
            "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
            "external_id": "CUST-17",
            "required": true
          }
        ]
      }
    ],
    "traveler": []
  }
}

What each type takes

type	value in the row
`text`	`"PRJ-2026-001"`
`long_text`	`"Fair delegation, second group"`
`number`	`12.5`
`date`	`"2026-03-14"`
`boolean`	`true`
`select`	`"meeting"`
`multi_select`	`["meeting", "fair"]`

number takes a number or a numeric string; date an ISO date; select one option value (or its label); multi_select a list of them.

required and applies_to

requiredneveralwayslisted_customers
listed_customers: required only for the customers marked required in customers.
applies_toalllisted_customers
listed_customers: the field is accepted only on those customers' records.

Send the values as one JSON object by key. An unknown key, a value of the wrong type or a missing required field fails the row and names the key. On an amendment (on_conflict: update) the object merges by key: a key you leave out is kept, a key sent as null is removed. A field the agency prints on the customer's documents cannot change once the record is invoiced.

They come back the same way: under detail.custom_fields in the read-back and the webhook body (and on each passenger of a ticket). A field marked personal comes back only to a key whose role can read personal data, and never in a webhook.

Reading it back

GET /api/v1/imports/tour_bookings/records/TOUR-BOOKING-1001

200

{
  "entity": "tour_bookings",
  "external_id": "TOUR-BOOKING-1001",
  "source_system": "crm",
  "type": "TourBooking",
  "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
  "created_at": "2026-03-14T09:30:00Z",
  "updated_at": "2026-03-15T11:05:00Z",
  "status": "confirmed",
  "locked": true,
  "lock_reason": "invoiced",
  "currency": "EUR",
  "totals": {
    "cost": "1100.0",
    "sell": "1250.0"
  },
  "invoices": [
    {
      "id": "4b8e1f60-7c2d-4e9a-b3f5-0a6d2c9e8b71",
      "number": "LYD2026000000117",
      "status": "issued",
      "currency": "EUR",
      "total": "1250.0",
      "balance": "1250.0"
    }
  ],
  "detail": {
    "voucher_number": "VCH-2026-000412",
    "supplier_confirmation_no": "CNF-77821",
    "party_size": 2,
    "departure_title": "Cappadocia Highlights",
    "departure_starts_on": "2026-03-14",
    "departure_state": "open",
    "custom_fields": {
      "project_code": "PRJ-2026-001",
      "trip_reason": "meeting"
    }
  }
}

Request · dry run, every field

curl -X POST 'https://YOUR-CELL.lydira.com/api/v1/imports/tour_bookings/validate' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90' \
  -d '{
  "source_system": "crm",
  "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",
      "custom_fields": {
        "project_code": "PRJ-2026-001",
        "trip_reason": "meeting"
      },
      "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
        }
      ],
      "service_fee": "1250.00",
      "service_fee_vat_rate": "20",
      "service_fee_waived": true,
      "customer_external_id": "CUSTOMER-1001",
      "departure_external_id": "TOUR-DEPARTURE-1001"
    }
  ]
}'

const response = await fetch(
  "https://YOUR-CELL.lydira.com/api/v1/imports/tour_bookings/validate",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sek_YOUR_API_KEY",
      "Content-Type": "application/json",
      "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
    body: JSON.stringify({
      "source_system": "crm",
      "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",
          "custom_fields": {
            "project_code": "PRJ-2026-001",
            "trip_reason": "meeting"
          },
          "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
            }
          ],
          "service_fee": "1250.00",
          "service_fee_vat_rate": "20",
          "service_fee_waived": true,
          "customer_external_id": "CUSTOMER-1001",
          "departure_external_id": "TOUR-DEPARTURE-1001"
        }
      ]
    }),
  },
);

if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const data = await response.json();

import requests

response = requests.post(
    "https://YOUR-CELL.lydira.com/api/v1/imports/tour_bookings/validate",
    headers={
        "Authorization": "Bearer sek_YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
    json={
      "source_system": "crm",
      "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",
          "custom_fields": {
            "project_code": "PRJ-2026-001",
            "trip_reason": "meeting"
          },
          "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
            }
          ],
          "service_fee": "1250.00",
          "service_fee_vat_rate": "20",
          "service_fee_waived": True,
          "customer_external_id": "CUSTOMER-1001",
          "departure_external_id": "TOUR-DEPARTURE-1001"
        }
      ]
    },
)
response.raise_for_status()
data = response.json()

require "net/http"
require "json"

uri = URI("https://YOUR-CELL.lydira.com/api/v1/imports/tour_bookings/validate")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer sek_YOUR_API_KEY"
request["Content-Type"] = "application/json"
request["Idempotency-Key"] = "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90"
request.body = JSON.generate({
  source_system: "crm",
  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",
      custom_fields: {
        project_code: "PRJ-2026-001",
        trip_reason: "meeting"
      },
      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
        }
      ],
      service_fee: "1250.00",
      service_fee_vat_rate: "20",
      service_fee_waived: true,
      customer_external_id: "CUSTOMER-1001",
      departure_external_id: "TOUR-DEPARTURE-1001"
    }
  ]
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { it.request(request) }
raise response.body unless response.is_a?(Net::HTTPSuccess)
data = JSON.parse(response.body)

<?php
$ch = curl_init("https://YOUR-CELL.lydira.com/api/v1/imports/tour_bookings/validate");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer sek_YOUR_API_KEY",
        "Content-Type: application/json",
        "Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "source_system" => "crm",
        "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",
                "custom_fields" => [
                    "project_code" => "PRJ-2026-001",
                    "trip_reason" => "meeting",
                ],
                "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,
                    ],
                ],
                "service_fee" => "1250.00",
                "service_fee_vat_rate" => "20",
                "service_fee_waived" => true,
                "customer_external_id" => "CUSTOMER-1001",
                "departure_external_id" => "TOUR-DEPARTURE-1001",
            ],
        ],
    ]),
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Response

200

{
  "import": {
    "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "entity": "tour_bookings",
    "source_system": "crm",
    "status": "ready",
    "company_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "stats": {
      "total": 1,
      "will_create": 1,
      "will_update": 0,
      "created": 0,
      "updated": 0,
      "skipped": 0,
      "invalid": 0,
      "failed": 0,
      "not_selected": 0
    },
    "error": null,
    "created_at": "2026-03-14T09:30:00Z",
    "links": {
      "self": "/api/v1/imports/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "rows": "/api/v1/imports/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/rows"
    },
    "mode": "validate",
    "async": false,
    "on_conflict": "skip",
    "pricing": "apply_rules"
  },
  "ignored_fields": [],
  "results": [
    {
      "row": 1,
      "external_id": "TOUR-BOOKING-1001",
      "status": "will_create",
      "payer": {
        "outcome": "external_id",
        "customer_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18"
      }
    }
  ]
}

The flow

Dry-run. POST …/validate runs the same path and writes nothing.
Send. The same body without /validate. A bad row fails alone and names its field.
Read back. GET /api/v1/imports/{entity}/records/{external_id} answers with your own key.
Listen. Webhooks tell you when the agency changes the record.

Conventions →Webhooks →

On this page

Tour departurestour_departures

Endpoints

A new row must carry

Reading it back

Tour bookingstour_bookings

Endpoints

A new row must carry

Your account's own fields (custom_fields)

Reading it back

The flow

Tour departures`tour_departures`

Tour bookings`tour_bookings`