curl "$UNIFYSTAYS_BASE_URL/master-data/nationalities?sort_by=nationality_name&sort_order=ASC&page=1&limit=250" \
-H "x-api-key: $UNIFYSTAYS_API_KEY"
{
"success": true,
"message": "Nationalities fetched successfully",
"data": {
"items": [
{
"id": 101,
"nationality_name": "Indian",
"country_name": "India",
"iso_code": "IN",
"iso_code_3": "IND",
"dial_code": "+91"
}
],
"meta": {
"total": 195,
"page": 1,
"limit": 250,
"totalPages": 1
}
}
}
Destination & master data
List Nationalities
Load the nationality list for the guest selector and cache it for 30 days.
GET
/
master-data
/
nationalities
curl "$UNIFYSTAYS_BASE_URL/master-data/nationalities?sort_by=nationality_name&sort_order=ASC&page=1&limit=250" \
-H "x-api-key: $UNIFYSTAYS_API_KEY"
{
"success": true,
"message": "Nationalities fetched successfully",
"data": {
"items": [
{
"id": 101,
"nationality_name": "Indian",
"country_name": "India",
"iso_code": "IN",
"iso_code_3": "IND",
"dial_code": "+91"
}
],
"meta": {
"total": 195,
"page": 1,
"limit": 250,
"totalPages": 1
}
}
}
Use this endpoint to fill a guest-nationality dropdown before you search. The
Filter on the server by nationality name, country name or code:
Use
For a typical dropdown, cache
iso_code of the chosen item is the one value to send as nationality in Search Hotels and in the room availability call that follows. Unifystays maps it to whatever each supplier expects, so you never deal with supplier-specific codes.
Why nationality matters
Suppliers can return different rates and availability depending on the guest’s nationality. For that reason Unifystays prices every search for one nationality and treats a search for a different nationality as a different search with its own prices.- Ask for the nationality of the traveller who will stay, and send it on every search.
- If you leave
nationalityout of a search, it defaults toIN. That is a real value, not a neutral one, so do not rely on the default. - Send the same nationality when you request room options for a hotel from that search. A price shown for one nationality is not a promise for another.
Cache successful responses for up to 30 days. Load the full list once for
the guest selector, filter it locally, and refresh it when the cache expires.
Request examples
Load the full, alphabetically sorted list for a guest form:curl "$UNIFYSTAYS_BASE_URL/master-data/nationalities?sort_by=nationality_name&sort_order=ASC&page=1&limit=250" \
-H "x-api-key: $UNIFYSTAYS_API_KEY"
curl "$UNIFYSTAYS_BASE_URL/master-data/nationalities?search=ind&limit=20" \
-H "x-api-key: $UNIFYSTAYS_API_KEY"
Response example
{
"success": true,
"message": "Nationalities fetched successfully",
"data": {
"items": [
{
"id": 101,
"nationality_name": "Indian",
"country_name": "India",
"iso_code": "IN",
"iso_code_3": "IND",
"dial_code": "+91"
}
],
"meta": {
"total": 195,
"page": 1,
"limit": 250,
"totalPages": 1
}
}
}
Request fields
| Field | What it means | How to use it |
|---|---|---|
search | Optional text matched against nationality name, country name and ISO alpha-2 code (case-insensitive). | Skip it and filter locally if you load the whole list. |
sort_by | nationality_name (default), country_name or iso_code. | Use nationality_name for a dropdown. |
sort_order | ASC (default) or DESC. | |
page | Page number, starting at 1. | Only needed if meta.totalPages is above 1. |
limit | Items per page, 1 to 300. Default 250. | Keep the default to get the full list in one request. |
Response field guide
| Field | What it means | How to use it |
|---|---|---|
data.items[].iso_code | ISO 3166-1 alpha-2 code, for example IN. | Store this and send it as nationality. |
data.items[].nationality_name | The demonym, for example “Indian”. | Show it in the dropdown. |
data.items[].country_name | Country name. | Secondary label or search text. |
data.items[].iso_code_3 | ISO alpha-3 code, or null. | Display only. Never send it as nationality. |
data.items[].dial_code | Phone dial code such as +91, or null. | Optional phone-prefix helper. Not used for pricing. |
data.items[].id | Internal row ID. | Do not send it anywhere. |
data.meta.total | Number of matches across all pages. | |
data.meta.page, data.meta.limit | Page and page size applied. | |
data.meta.totalPages | Number of pages. | Request more pages only when above 1. |
Use iso_code in hotel requests
{
"nationality": "IN"
}
Send only the alpha-2
iso_code returned by this endpoint. An unknown code
fails search validation with HTTP 400. Alpha-3 codes, supplier codes,
nationality names and the numeric id are not accepted.Cache key
Include every query value and the environment, and cache successful responses only:environment + search + sort_by + sort_order + page + limit
data.items for the default request and filter that list locally.
Next step
Pick a destination with Destination Autocomplete, then call Search Hotels. The OpenAPI section below lists every parameter and response field.Authorizations
Environment-specific API key created in the Unifystays portal
Headers
Query Parameters
Optional filter. Matches nationality name, country name or ISO alpha-2 code (case-insensitive, 1-100 characters). Omit it to load the full list and filter in your own UI.
Example:
"ind"
Field to sort by: nationality_name (default), country_name or iso_code.
Available options:
nationality_name, country_name, iso_code Sort direction: ASC (default) or DESC.
Available options:
ASC, DESC Page number, starting at 1. Only needed when the list is larger than limit; check meta.totalPages.
Required range:
x >= 1Example:
1
Results per page (1-300, default 250). The default is high so most frontends can load the full list in one request.
Required range:
1 <= x <= 300Example:
250