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" \
-H "language: en"
{
"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 canonical nationality list for guest selection 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" \
-H "language: en"
{
"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 populate a guest-nationality selector. The returned
For a server-side filter, add
Use
When a traveler selects a nationality, send only its ISO alpha-2
Cache successful responses only. For a typical dropdown, cache
iso_code is the canonical value to send in hotel search and room availability
requests, regardless of how individual suppliers represent nationality
internally.
Cache successful responses for up to 30 days. Load the full list for the
guest selector, then refresh it when the 30-day lifetime expires.
Request Examples
Request 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" \
-H "language: en"
search:
curl "$UNIFYSTAYS_BASE_URL/master-data/nationalities?search=ind&limit=20" \
-H "x-api-key: $UNIFYSTAYS_API_KEY" \
-H "language: en"
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
}
}
}
Use iso_code in Hotel Requests
When a traveler selects a nationality, send only its ISO alpha-2 iso_code.
Do not send the numeric id, nationality name, country name, or iso_code_3.
{
"nationality": "IN"
}
The value must be an ISO alpha-2 code returned by this endpoint.
Supplier-specific codes and alpha-3 codes can fail hotel-search or room
availability validation.
Cache Key
Include all query values and environment in the cache key:environment + language + search + sort_by + sort_order + page + limit
data.items for
the default request and filter that list locally. Use data.meta to request
additional pages only when they exist.
The OpenAPI section below provides the complete request and response field
reference.Authorizations
Environment-specific API key created in the Unifystays portal
Headers
Query Parameters
Search by nationality name, country name, or ISO alpha-2 code (case-insensitive).
Example:
"ind"
Field to sort by.
Available options:
nationality_name, country_name, iso_code Sort direction.
Available options:
ASC, DESC Page number (1-based).
Required range:
x >= 1Example:
1
Results per page. Default 250 — intentionally high so most frontends can load the full list in one request.
Required range:
1 <= x <= 300Example:
250