Reservation Create
POST
/api/v1/generic-api-service/flight/reservation/create
The reservation create endpoint creates a flight reservation for the selected offer(s). It uses the searchId together with the chosen flight/cabin/brand identifiers, passenger details, contact and receipt information, and payment details to generate a booking, and returns the order and issued e-ticket(s). It supports both one-way and round-trip.
- cURL
- Request
- Response
- Request Details
- Response Details
- Errors
curl --location 'https://test-api.etscore.com/api/v1/generic-api-service/flight/reservation/create' \
--header 'Accept-Language: en-US' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
"searchId": "5029md2matl3schcom2vbsvk4g7j4vc6",
"clientRef": "EtscoreFlight212",
"checkout": "2026-08-17",
"offers": {
"departure": {
"flightId": "pz-f3b3640e-6059-4267-bc81-114de4aa238c",
"offerId": "XBAG-a86713d6a71445a285ca7267732f1608",
"departureBrandKey": "XBAG"
},
"return": {
"flightId": "pz-f51fb2fb-bb16-40c1-8286-7aeddff29f08",
"offerId": "XBAG-d990183ea2b1476a9c1122bbdcf70189",
"returnBrandKey": "XBAG"
}
},
"contactInfo": {
"email": "[email protected]",
"mobilePhoneNumber": "905000000000"
},
"passengers": [
{
"paxType": "ADULT",
"male": true,
"name": "OMER",
"surname": "ERGAN",
"birthDate": "1990-02-09",
"passportCountry": "TR",
"nationalityIdNo": "<national-id>",
"notTCCitizen": false,
"passportNo": "U12345678",
"passportNationality": "TR",
"passportExpireDate": "2035-01-01",
"mealType": "STANDARD",
"passengerId": 1
}
],
"paymentInfo": {
"paymentType": "Debit",
"totalAmount": "116.50",
"currency": "EUR"
}
}'
{
"searchId": "5029md2matl3schcom2vbsvk4g7j4vc6",
"clientRef": "EtscoreFlight212",
"checkout": "2026-08-17",
"offers": {
"departure": {
"flightId": "pz-f3b3640e-6059-4267-bc81-114de4aa238c",
"offerId": "XBAG-a86713d6a71445a285ca7267732f1608",
"departureBrandKey": "XBAG"
},
"return": {
"flightId": "pz-f51fb2fb-bb16-40c1-8286-7aeddff29f08",
"offerId": "XBAG-d990183ea2b1476a9c1122bbdcf70189",
"returnBrandKey": "XBAG"
}
},
"passengers": [
0: {
"paxType": "ADULT",
"male": true,
"name": "OMER",
"surname": "ERGAN",
"birthDate": "1990-02-09",
"passportCountry": "TR",
"nationalityIdNo": "<national-id>",
"notTCCitizen": false,
"passportNo": "U12345678",
"passportNationality": "TR",
"passportExpireDate": "2035-01-01",
"mealType": "STANDARD",
"passengerId": 1
}
],
"receiptInfos": {
"receiptName": "ETSTUR",
"notTCCitizen": false,
"name": "OMER",
"surname": "ERGAN",
"email": "[email protected]",
"taxNumber": "<tax-number>",
"nationalID": "<national-id>",
"taxOffice": "Büyük Mükellefler V.D.",
"isCompany": false,
"address1": "Merdivenköy Mh. Nur Sk. No:1/8 C Blok Kadıköy / İSTANBUL",
"address2": "Merdivenköy Mh. Nur Sk. No:1/8 C Blok Kadıköy / İSTANBUL",
"zipCode": "34000",
"city": "İstanbul",
"country": "TURKEY",
"companyName": "ETSTUR",
"notTCCompany": false,
"needReceiptFlag": false,
"electronicReceipt": true,
"privateCompany": false,
"receiptId": 0
},
"paymentInfo": {
"paymentType": "Debit",
"totalAmount": "116.50",
"currency": "EUR"
}
}
{
"success": true,
"orderStatus": "TICKET",
"orderId": 49661695,
"clientRef": "EtscoreFlight212",
"etickets": [
0: {
"pnr": "42ED16",
"airlineCode": "VF",
"eticketNo": "2042452443067",
"status": "TICKETED"
}
]
}
| Name | Type | Required | Description |
|---|---|---|---|
| searchId | string | Yes | The search.id returned by the Flight Search service. |
| clientRef | string | No | Your own reference for the booking (client-side identifier). |
| checkout | string | No | Checkout/booking date in yyyy-MM-dd format. |
| offers | object | Yes | The selected offer(s) grouped by leg: departure (outbound) and, for round-trip, return. |
| offers/departure | object | Yes | Selected outbound leg offer. |
| offers/departure/flightId | string | Yes | Selected outbound flight identifier (flights/id from search). |
| offers/departure/offerId | string | Yes | Selected outbound offer/cabin price identifier (offers/id). |
| offers/departure/departureBrandKey | string | Yes | Selected outbound fare brand code (e.g. XBAG). |
| offers/return | object | No | Selected return leg offer. Provide for round-trip bookings. |
| offers/return/flightId | string | No | Selected return flight identifier. Provide for round-trip bookings. |
| offers/return/offerId | string | No | Selected return offer/cabin price identifier. |
| offers/return/returnBrandKey | string | No | Selected return fare brand code. |
| contactInfo | object | Yes | Contact details for the booking. |
| contactInfo/email | string | Yes | Contact email address. |
| contactInfo/mobilePhoneNumber | string | Yes | Contact mobile phone number (including country code). |
| passengers | object-array | Yes | List of passengers. |
| passengers/paxType | string | Yes | Passenger type (e.g. ADULT, CHILD, INFANT). |
| passengers/male | boolean | Yes | Passenger gender: true for male, false for female. |
| passengers/name | string | Yes | Passenger given name. |
| passengers/surname | string | Yes | Passenger surname. |
| passengers/birthDate | string | Yes | Date of birth in yyyy-MM-dd. Required when the offer's restrictions demand it. |
| passengers/passportCountry | string | Yes | ISO country code of the passport (e.g. TR). |
| passengers/nationalityIdNo | string | No | National identity number of the passenger (required for only domestic TR flights). |
| passengers/notTCCitizen | boolean | No | true if the passenger is not a Turkish citizen. |
| passengers/passportNo | string | Yes | Passport number. Required for international flights when the offer's restrictions demand travel documents (docsRequired). |
| passengers/passportNationality | string | Yes | ISO country code of the passport's issuing nationality (e.g. TR). |
| passengers/passportExpireDate | string | Yes | Passport expiry date in yyyy-MM-dd format. Required when passDueDateRequired is true. |
| passengers/mealType | string | No | Requested meal preference for the passenger (e.g. STANDARD). |
| passengers/passengerId | integer | No | Client-side identifier for the passenger within the request. Echoed back in the response to correlate issued tickets with each passenger. |
| receiptInfos | object | No | Invoice/receipt (billing) information. |
| receiptInfos/receiptName | string | No | Name shown on the receipt. |
| receiptInfos/name | string | No | Receipt owner's given name. |
| receiptInfos/surname | string | No | Receipt owner's surname. |
| receiptInfos/email | string | No | Receipt email address. |
| receiptInfos/taxNumber | string | No | Tax number (for companies). |
| receiptInfos/nationalID | string | No | National identity number (for individuals). |
| receiptInfos/taxOffice | string | No | Tax office name. |
| receiptInfos/isCompany | boolean | No | Whether the receipt is issued to a company. |
| receiptInfos/address1 | string | No | Billing address line 1. |
| receiptInfos/address2 | string | No | Billing address line 2. |
| receiptInfos/zipCode | string | No | Postal / ZIP code. |
| receiptInfos/city | string | No | Billing city. |
| receiptInfos/country | string | No | Billing country. |
| receiptInfos/companyName | string | No | Company name (when isCompany is true). |
| receiptInfos/notTCCitizen | boolean | No | true if the receipt owner is not a Turkish citizen. |
| receiptInfos/notTCCompany | boolean | No | true if the company is not Turkey-based. |
| receiptInfos/needReceiptFlag | boolean | No | Whether a receipt is requested. |
| receiptInfos/electronicReceipt | boolean | No | Whether the receipt is electronic. |
| receiptInfos/privateCompany | boolean | No | Whether the company is a private company. |
| receiptInfos/receiptId | int | No | Identifier of an existing saved receipt (0 for a new one). |
| paymentInfo | object | Yes | Payment details for the reservation. |
| paymentInfo/paymentType | string | Yes | Payment method (e.g. Debit). |
| paymentInfo/totalAmount | string | Yes | Total amount to be charged. |
| paymentInfo/currency | string | Yes | Currency of the payment (e.g. EUR). |
| Name | Type | Required | Description |
|---|---|---|---|
| success | boolean | Yes | Indicates whether the reservation was created successfully. |
| orderStatus | string | Yes | Status of the order (e.g. TICKET when tickets are issued). |
| orderId | int | Yes | Unique order identifier generated for the reservation. |
| clientRef | string | No | The client reference sent in the request, echoed back. |
| etickets | object-array | Yes | List of issued e-tickets. |
| etickets/pnr | string | Yes | Passenger Name Record (booking reference). |
| etickets/airlineCode | string | Yes | Airline code the ticket was issued on (e.g. VF). |
| etickets/eticketNo | string | Yes | Electronic ticket number. |
| etickets/status | string | Yes | Ticket status (e.g. TICKETED). |
Errors specific to Reservation Create (16 codes). Common gateway and authentication errors apply to all endpoints and are listed once in the central reference.
🔎
Validation— fix the request and retry
| Group | Code | Message | Description |
|---|---|---|---|
| Validation | 904128 | Inventory validation error. | Returned when the request payload fails schema validation or required fields are missing. Correct the request parameters and send the request again. |
| Validation | 904200 | Flight service validation error: {0} | Returned during flight operations when validation on the remote flight provider side fails. Correct the request parameters and send the request again. |
| Validation | 904205 | Payment amount mismatch. Expected: {0}, Requested: {1} | Returned when the submitted payment amount does not match the price calculated by the flight service. Verify the price and resubmit with the correct amount. |
| Validation | 904206 | Flight price validation error. | Returned when flight price validation fails due to inconsistent or invalid pricing data. Perform a new search and verify pricing. |
| Validation | 904210 | Client reference already exists in the system: {0} | Returned when creating a reservation with a client reference ID that has already been used. Provide a unique clientReferenceId for each reservation. |
| Validation | 904217 | Payment currency ({1}) does not match your sales channel currency ({0}). Please use the correct currency. | Returned when the currency in the payment request differs from the configured sales channel currency. Use the channel designated currency. |
| Validation | 904222 | Flight price validation failed. Payment information is required to complete the booking. | Returned when payment or passenger price structure is missing in the reservation request. Supply required payment details and retry. |
| Validation | 904223 | Flight price validation failed. Unable to verify the flight price. Please try again. | Returned when price validation is unable to verify details for the selected flight fare. Re-fetch flight details and retry. |
| Validation | 904224 | Flight price validation failed. Unable to calculate the expected price. Please perform a new search. | Returned when the expected fare cannot be computed from the stored search session. Perform a new flight search. |
| Validation | 904228 | Payment currency does not match the sales channel currency. | Returned when the payment currency in the reservation does not match the sales channel currency configuration. |
Not found— verify the identifier
| Group | Code | Message | Description |
|---|---|---|---|
| Not found | 904218 | No flight provider found for the sales channel. Email: {0} | Returned when no active flight provider is configured or matched for the given sales channel account. Contact your administrator. |
Timeout— restart the flow or session
| Group | Code | Message | Description |
|---|---|---|---|
| Timeout | 904221 | Flight price validation failed. Search session is invalid or expired. Please perform a new search. | Returned when searchId is missing or expired in the booking request. Perform a new search and provide a valid searchId. |
Rate limit— slow down and retry later
| Group | Code | Message | Description |
|---|---|---|---|
| Rate limit | 901010 | You have exceeded the limit of requests sent per unit time. You can send {1} requests in {0} seconds. | Returned when the rate limit configured for your sales channel / IP is exceeded. Slow down your request rate and retry after the specified window. |
System— retry with backoff; contact support if persistent
| Group | Code | Message | Description |
|---|---|---|---|
| System | 904003 | Unexpected error occured. | Returned when an unexpected system error occurs while processing the flight request. Retry after a short wait; if the issue persists, contact Etscore support. |
| System | 904201 | Flight service system error: {0} | Returned when an internal system error occurs within the remote flight provider service. Retry with backoff; contact support if persistent. |
| System | 904220 | Currency exchange rate is currently unavailable. Please try again later. | Returned when exchange rates cannot be obtained or computed for the requested transaction currencies. Retry after a short wait. |
Common errors not shown here. Gateway, authentication and header errors apply to every endpoint. → See the central Error Codes reference.