Hotel stays

Hotel stays`hotel_stays`

POST/api/v1/imports/hotel_stays

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

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}

A new row must carry

check_in_oncheck_out_on

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

With no bill-to, the individual payer is the first traveller: travelers[0]

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/hotel_stays/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": "HOTEL-STAY-1001-B",
      "check_in_on": "2026-03-14",
      "check_out_on": "2026-03-18",
      "currency": "EUR",
      "guest_count": 2,
      "supplier_external_id": "SUPPLIER-1001",
      "status": "draft",
      "notes": "Imported from the source system.",
      "rate_basis": "net",
      "margin_mode": "percent",
      "option_date": "2026-03-20T18:00",
      "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": "MRS",
          "frequent_flyer_number": "TK123456789"
        }
      ],
      "rooms": [
        {
          "name": "Deluxe Sea View",
          "room_type": "double",
          "capacity": 2,
          "occupancy": 2,
          "nightly_rate": "180.00",
          "cost_rate": "1250.00",
          "single_supplement_amount": "60.00",
          "single_supplement_currency": "EUR"
        }
      ],
      "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/hotel_stays/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": "HOTEL-STAY-1001-B",
          "check_in_on": "2026-03-14",
          "check_out_on": "2026-03-18",
          "currency": "EUR",
          "guest_count": 2,
          "supplier_external_id": "SUPPLIER-1001",
          "status": "draft",
          "notes": "Imported from the source system.",
          "rate_basis": "net",
          "margin_mode": "percent",
          "option_date": "2026-03-20T18:00",
          "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": "MRS",
              "frequent_flyer_number": "TK123456789"
            }
          ],
          "rooms": [
            {
              "name": "Deluxe Sea View",
              "room_type": "double",
              "capacity": 2,
              "occupancy": 2,
              "nightly_rate": "180.00",
              "cost_rate": "1250.00",
              "single_supplement_amount": "60.00",
              "single_supplement_currency": "EUR"
            }
          ],
          "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/hotel_stays/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": "HOTEL-STAY-1001-B",
          "check_in_on": "2026-03-14",
          "check_out_on": "2026-03-18",
          "currency": "EUR",
          "guest_count": 2,
          "supplier_external_id": "SUPPLIER-1001",
          "status": "draft",
          "notes": "Imported from the source system.",
          "rate_basis": "net",
          "margin_mode": "percent",
          "option_date": "2026-03-20T18:00",
          "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": "MRS",
              "frequent_flyer_number": "TK123456789"
            }
          ],
          "rooms": [
            {
              "name": "Deluxe Sea View",
              "room_type": "double",
              "capacity": 2,
              "occupancy": 2,
              "nightly_rate": "180.00",
              "cost_rate": "1250.00",
              "single_supplement_amount": "60.00",
              "single_supplement_currency": "EUR"
            }
          ],
          "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/hotel_stays/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: "HOTEL-STAY-1001-B",
      check_in_on: "2026-03-14",
      check_out_on: "2026-03-18",
      currency: "EUR",
      guest_count: 2,
      supplier_external_id: "SUPPLIER-1001",
      status: "draft",
      notes: "Imported from the source system.",
      rate_basis: "net",
      margin_mode: "percent",
      option_date: "2026-03-20T18:00",
      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: "MRS",
          frequent_flyer_number: "TK123456789"
        }
      ],
      rooms: [
        {
          name: "Deluxe Sea View",
          room_type: "double",
          capacity: 2,
          occupancy: 2,
          nightly_rate: "180.00",
          cost_rate: "1250.00",
          single_supplement_amount: "60.00",
          single_supplement_currency: "EUR"
        }
      ],
      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/hotel_stays/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" => "HOTEL-STAY-1001-B",
                "check_in_on" => "2026-03-14",
                "check_out_on" => "2026-03-18",
                "currency" => "EUR",
                "guest_count" => 2,
                "supplier_external_id" => "SUPPLIER-1001",
                "status" => "draft",
                "notes" => "Imported from the source system.",
                "rate_basis" => "net",
                "margin_mode" => "percent",
                "option_date" => "2026-03-20T18:00",
                "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" => "MRS",
                        "frequent_flyer_number" => "TK123456789",
                    ],
                ],
                "rooms" => [
                    [
                        "name" => "Deluxe Sea View",
                        "room_type" => "double",
                        "capacity" => 2,
                        "occupancy" => 2,
                        "nightly_rate" => "180.00",
                        "cost_rate" => "1250.00",
                        "single_supplement_amount" => "60.00",
                        "single_supplement_currency" => "EUR",
                    ],
                ],
                "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.

This booking is billed per guest, so the fee is split across the guests by their sell, as on the agency's booking form. Do not send it as a service_fee item in sell_lines: every sell line lands on the first guest, so that row is refused.

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

The markup and the discount

Both are the whole booking's, as on the agency's booking form. Send markup (a figure) or markup_percent (of the booking's cost), and discount (a positive figure) or discount_percent (of everything the booking sells); a percentage wins over the figure beside it. The markup is split across the guests by their cost (by their sell when the booking carries no cost) and folded into each guest's fare on the invoice; the discount is split by what each guest owes. A negative value fails the row.

They are written in the form's order: markup, service fee, discount. A percentage service-fee rule and discount_percent both count the markup. A stay's room can carry its nightly cost_rate, spread across the room's guests like nightly_rate, so the markup follows each guest's own cost.

Do not send them as markup or discount items in sell_lines: every sell line lands on the first guest, so that row is refused.

A booking with nothing to split one across is saved without it, and the row carries the warning: markup_dropped, discount_dropped

Fields:markupmarkup_percentdiscountdiscount_percent

Fields(41)

external_idstring
check_in_ondaterequired
check_out_ondaterequired
currencycurrency
guest_countinteger
customer_external_idreference
supplier_external_idreference
custom_fieldsobject
the account's own fields on the booking, by key
statusenum
One of:draftoptionconfirmedin_housechecked_outcancelledno_show
notesstring
rate_basisenum
net ⇒ cost typed / sell derived; commissionable ⇒ the reverse
One of:netcommissionable
margin_modeenum
percent ⇒ the margin was typed as a %; amount ⇒ as a flat figure
One of:percentamount
option_datedate
transaction_datedate
işlem tarihi — the FX anchor for every cost line
invoice_datedate
cost_linesobject[]
cost-side pricing lines for the "hotel" pricing context
Each item
- kindstringrequired
  Values the app uses:room_ratecity_taxtourism_feeresort_feebreakfasthalf_boardfull_boardall_inclusive_supplementparkingextra_bedkonaklama_vergisiservice_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 "hotel" pricing context
Each item
- kindstringrequired
  Values the app uses:package_pricemarkupservice_feesupplier_commissioncancellation_feeinsurance_premiumdiscountrefund_allowanceroom_ratecity_taxtourism_feeresort_feebreakfasthalf_boardfull_boardall_inclusive_supplementparkingextra_bedkonaklama_vergisisupplier_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
markupmoney
the agency's hidden markup on the whole booking, in its currency: split across the guests by their cost (by their sell when the booking carries no cost) and folded into each guest's fare on the invoice
markup_percentdecimal
the markup as a percentage of the booking's cost; wins over markup
discountmoney
the whole booking's discount (iskonto), a positive figure: split across the guests by what each owes, after the markup and the service fee
discount_percentdecimal
the discount as a percentage of everything the booking sells, the markup and the service fee included; wins over discount
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
travelersobject[]PII
guests; auto-saved to the customer's traveller directory
Each item
- first_namestringPII
- last_namestringPII
- nationalitystring
- national_idstringPII
- passport_numberstringPII
- passport_countrystring
- passport_expirydate
- date_of_birthdatePII
- genderstring
  Values the app uses:MRMRSMISSMSTR
- frequent_flyer_numberstring
- custom_fieldsobject
  the account's own fields on the guest, by key
roomsobject[]
a room with a nightly_rate contributes a room_rate SELL line × nights
Each item
- namestring
- room_typestring
  Your account's hotel_room_type list; it starts with:singletwindoubletriplequadsuitecabin
- capacityinteger
- occupancyinteger
- nightly_ratemoney
- cost_ratemoney
  the room's nightly cost: a room_rate COST line × nights, spread across its guests like the sell
- single_supplement_amountmoney
- single_supplement_currencycurrency
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
supplier_external_id → suppliers · matched by external_id, code · when missing skip

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/hotel_stays' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY'

const response = await fetch(
  "https://YOUR-CELL.lydira.com/api/v1/imports/entities/hotel_stays",
  {
    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/hotel_stays",
    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/hotel_stays")
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/hotel_stays");
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": "hotel_stays",
  "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": [
      {
        "key": "employee_no",
        "label": "Employee no",
        "type": "text",
        "required": "never",
        "applies_to": "all",
        "pii": true
      }
    ]
  }
}

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.

Traveller fields go on each traveller, under that item's own custom_fields.

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

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/hotel_stays/records/HOTEL-STAY-1001

200

{
  "entity": "hotel_stays",
  "external_id": "HOTEL-STAY-1001",
  "source_system": "crm",
  "type": "HotelStay",
  "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",
    "supplier": "Lovelace Travel Partners",
    "custom_fields": {
      "project_code": "PRJ-2026-001",
      "trip_reason": "meeting"
    },
    "check_in_on": "2026-03-14",
    "check_out_on": "2026-03-18",
    "rooms": [
      {
        "name": "Deluxe Sea View",
        "room_type": "double",
        "board_basis": "bed_breakfast",
        "booked_pax": 2,
        "capacity": 2
      }
    ]
  }
}

Request · dry run, every field

curl -X POST 'https://YOUR-CELL.lydira.com/api/v1/imports/hotel_stays/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": "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",
      "custom_fields": {
        "project_code": "PRJ-2026-001",
        "trip_reason": "meeting"
      },
      "status": "draft",
      "notes": "Imported from the source system.",
      "rate_basis": "net",
      "margin_mode": "percent",
      "option_date": "2026-03-20T18:00",
      "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
        }
      ],
      "markup": "1250.00",
      "markup_percent": "10",
      "discount": "1250.00",
      "discount_percent": "5",
      "service_fee": "1250.00",
      "service_fee_vat_rate": "20",
      "service_fee_waived": true,
      "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": "MRS",
          "frequent_flyer_number": "TK123456789",
          "custom_fields": {
            "employee_no": "E-10442"
          }
        }
      ],
      "rooms": [
        {
          "name": "Deluxe Sea View",
          "room_type": "double",
          "capacity": 2,
          "occupancy": 2,
          "nightly_rate": "180.00",
          "cost_rate": "1250.00",
          "single_supplement_amount": "60.00",
          "single_supplement_currency": "EUR"
        }
      ]
    }
  ]
}'

const response = await fetch(
  "https://YOUR-CELL.lydira.com/api/v1/imports/hotel_stays/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": "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",
          "custom_fields": {
            "project_code": "PRJ-2026-001",
            "trip_reason": "meeting"
          },
          "status": "draft",
          "notes": "Imported from the source system.",
          "rate_basis": "net",
          "margin_mode": "percent",
          "option_date": "2026-03-20T18:00",
          "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
            }
          ],
          "markup": "1250.00",
          "markup_percent": "10",
          "discount": "1250.00",
          "discount_percent": "5",
          "service_fee": "1250.00",
          "service_fee_vat_rate": "20",
          "service_fee_waived": true,
          "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": "MRS",
              "frequent_flyer_number": "TK123456789",
              "custom_fields": {
                "employee_no": "E-10442"
              }
            }
          ],
          "rooms": [
            {
              "name": "Deluxe Sea View",
              "room_type": "double",
              "capacity": 2,
              "occupancy": 2,
              "nightly_rate": "180.00",
              "cost_rate": "1250.00",
              "single_supplement_amount": "60.00",
              "single_supplement_currency": "EUR"
            }
          ]
        }
      ]
    }),
  },
);

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/hotel_stays/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": "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",
          "custom_fields": {
            "project_code": "PRJ-2026-001",
            "trip_reason": "meeting"
          },
          "status": "draft",
          "notes": "Imported from the source system.",
          "rate_basis": "net",
          "margin_mode": "percent",
          "option_date": "2026-03-20T18:00",
          "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
            }
          ],
          "markup": "1250.00",
          "markup_percent": "10",
          "discount": "1250.00",
          "discount_percent": "5",
          "service_fee": "1250.00",
          "service_fee_vat_rate": "20",
          "service_fee_waived": True,
          "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": "MRS",
              "frequent_flyer_number": "TK123456789",
              "custom_fields": {
                "employee_no": "E-10442"
              }
            }
          ],
          "rooms": [
            {
              "name": "Deluxe Sea View",
              "room_type": "double",
              "capacity": 2,
              "occupancy": 2,
              "nightly_rate": "180.00",
              "cost_rate": "1250.00",
              "single_supplement_amount": "60.00",
              "single_supplement_currency": "EUR"
            }
          ]
        }
      ]
    },
)
response.raise_for_status()
data = response.json()

require "net/http"
require "json"

uri = URI("https://YOUR-CELL.lydira.com/api/v1/imports/hotel_stays/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: "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",
      custom_fields: {
        project_code: "PRJ-2026-001",
        trip_reason: "meeting"
      },
      status: "draft",
      notes: "Imported from the source system.",
      rate_basis: "net",
      margin_mode: "percent",
      option_date: "2026-03-20T18:00",
      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
        }
      ],
      markup: "1250.00",
      markup_percent: "10",
      discount: "1250.00",
      discount_percent: "5",
      service_fee: "1250.00",
      service_fee_vat_rate: "20",
      service_fee_waived: true,
      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: "MRS",
          frequent_flyer_number: "TK123456789",
          custom_fields: {
            employee_no: "E-10442"
          }
        }
      ],
      rooms: [
        {
          name: "Deluxe Sea View",
          room_type: "double",
          capacity: 2,
          occupancy: 2,
          nightly_rate: "180.00",
          cost_rate: "1250.00",
          single_supplement_amount: "60.00",
          single_supplement_currency: "EUR"
        }
      ]
    }
  ]
})

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/hotel_stays/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" => "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",
                "custom_fields" => [
                    "project_code" => "PRJ-2026-001",
                    "trip_reason" => "meeting",
                ],
                "status" => "draft",
                "notes" => "Imported from the source system.",
                "rate_basis" => "net",
                "margin_mode" => "percent",
                "option_date" => "2026-03-20T18:00",
                "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,
                    ],
                ],
                "markup" => "1250.00",
                "markup_percent" => "10",
                "discount" => "1250.00",
                "discount_percent" => "5",
                "service_fee" => "1250.00",
                "service_fee_vat_rate" => "20",
                "service_fee_waived" => true,
                "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" => "MRS",
                        "frequent_flyer_number" => "TK123456789",
                        "custom_fields" => [
                            "employee_no" => "E-10442",
                        ],
                    ],
                ],
                "rooms" => [
                    [
                        "name" => "Deluxe Sea View",
                        "room_type" => "double",
                        "capacity" => 2,
                        "occupancy" => 2,
                        "nightly_rate" => "180.00",
                        "cost_rate" => "1250.00",
                        "single_supplement_amount" => "60.00",
                        "single_supplement_currency" => "EUR",
                    ],
                ],
            ],
        ],
    ]),
]);

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

Response

200

{
  "import": {
    "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "entity": "hotel_stays",
    "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": "HOTEL-STAY-1001",
      "status": "will_create",
      "payer": {
        "outcome": "external_id",
        "customer_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18"
      }
    }
  ]
}

On this page

Hotel stays`hotel_stays`

Endpoints

A new row must carry

Your account's own fields (custom_fields)

Reading it back

The flow

On this page

Hotel stayshotel_stays

Endpoints

A new row must carry

Your account's own fields (custom_fields)

Reading it back

The flow

Hotel stays`hotel_stays`