Requests and responses

This page covers request body formats, the response envelope, pagination, date and amount formats, and how to interpret HTTP status codes.

Request bodies#

Endpoints use one of two body formats. The reference page for each endpoint says which one applies.

Format	Content-Type	Used by
Form fields	`application/x-www-form-urlencoded` or `multipart/form-data`	Login, room list, coupon validation, countries
JSON	`application/json`	Booking push (`BookingPushRQ`), payment start
Query string	—	All `GET` endpoints

Array fields in form bodies are repeated with square brackets: childAges[]=7&childAges[]=12. JSON bodies must be UTF-8.

Response envelope#

Responses are JSON. Most carry a success flag; lists come back with count and items:

List response (truncated)

{
    "success": true,
    "count": 3,
    "items": [
        {
            "id": 1,
            "titleCode": "TRY",
            "symbol": "₺",
            "price": 1
        },
        {
            "id": 2,
            "titleCode": "EUR",
            "symbol": "€",
            "price": 47.85000000000000142108547152020037174224853515625
        }
    ]
}

Failed business-rule checks return success: false plus an error description, in one of two shapes:

message shape

{
    "success": false,
    "message": "online_cupon_is_not_found"
}

errorCode shape (room list)

{
    "success": false,
    "errorMessage": "Invalid parameters.",
    "errorCode": 10022
}

Exceptions: the contact-details endpoint returns a bare object without the envelope, and the booking push returns a BookingPushRS object. Both are shown in the reference.

HTTP status codes#

Code	When	What to do
200	Request processed (success or business-rule error)	Inspect `success`, `message` / `errorCode`.
401	Token missing, malformed or unknown	Log in again; see Authentication.
404	A path parameter does not match a record (e.g. `/hotel/{hotelID}/…`, `/payment/type/{paymentType}`)	Check the ID.
405	Wrong HTTP method	Use the method given in the reference (countries and room list are `POST`).
500	Unexpected server error	Retry after a short delay; if it persists, open a support ticket with the request.

Pagination#

List endpoints (/external/currencies, /external/languages, /external/online/social/media, /external/stock/packages) are paginated by page number:

Parameter	Description	Default
`limit`	Records per page.	`20`
`page`	Page number, starting at 1.	`1`
`offset`	Records to skip. If given, `page` is ignored.	—
`order`	Sort field; prefix with `-` for descending (`-id`). Allowed fields are listed per endpoint.	—

count is the total number of records; the list is exhausted when page × limit ≥ count.

Dates, times and amounts#

Type	Format	Example
Request date	`YYYY-MM-DD`	`2026-08-18`
Availability date	`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS`	`2026-08-18T12:00:00`
Nightly rate date (response)	`DD.MM.YYYY` (the `tarih` field)	`18.08.2026`
Availability day range (response)	`YYYY-MM-DD HH:MM:SS`, 12:00 to 12:00 next day	`2026-08-18 12:00:00`
Amount	Two-decimal string, dot separator	`"965.00"`
Currency	ISO 4217; from the hotel’s online channel settings	`TRY`
Time zone	The hotel’s time zone	Europe/Istanbul

The check-out date is not part of the stay: 18–20 August is two nights. Do not add amounts with float; use a decimal library or integer minor units.

Language#

The room list takes a language field (ISO 639-1: tr, en, de…) and returns room names, feature titles and error messages in that language. The package list expects a languageID; IDs come from the Languages endpoint.

Last updated: 8 September 2026Found a mistake? Let us know