> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unifystays.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Nationalities
> Load the canonical nationality list for guest selection and cache it for 30 days.
Use this endpoint to populate a guest-nationality selector. The returned
`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:
```bash theme={null}
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"
```
For a server-side filter, add `search`:
```bash theme={null}
curl "$UNIFYSTAYS_BASE_URL/master-data/nationalities?search=ind&limit=20" \
-H "x-api-key: $UNIFYSTAYS_API_KEY" \
-H "language: en"
```
## Response Example
```json theme={null}
{
"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`.
```json theme={null}
{
"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:
```text theme={null}
environment + language + search + sort_by + sort_order + page + limit
```
Cache successful responses only. For a typical dropdown, cache `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.
## OpenAPI
````yaml reference/openapi.json GET /master-data/nationalities
openapi: 3.0.0
info:
title: Unifystays API
description: >-
One unified hotel API across suppliers. Integrate once, then enable and
manage suppliers from the Unifystays portal.
version: '1.0'
contact: {}
servers:
- url: https://api-sandbox.unifystays.com
description: Sandbox
- url: https://api.unifystays.com
description: Production
security:
- x-api-key: []
tags: []
paths:
/master-data/nationalities:
get:
tags:
- Master Data
summary: List nationalities
description: >-
Returns a paginated list of all active nationalities. Default limit is
250 so most frontends can load the full list in a single request for use
in dropdown/autocomplete widgets. Search supports nationality name,
country name, and ISO alpha-2 code.
**Hotel search usage:** pass the returned `iso_code` as the
`nationality` field in `POST /hotels/search`.
**Caching:** Cache successful responses for up to 30 days. Include the
environment and all query parameters in the cache key.
operationId: NationalityController_listNationalities
parameters:
- name: search
required: false
in: query
description: >-
Search by nationality name, country name, or ISO alpha-2 code
(case-insensitive).
schema:
example: ind
type: string
- name: sort_by
required: false
in: query
description: Field to sort by.
schema:
default: nationality_name
type: string
enum:
- nationality_name
- country_name
- iso_code
- name: sort_order
required: false
in: query
description: Sort direction.
schema:
default: ASC
type: string
enum:
- ASC
- DESC
- name: page
required: false
in: query
description: Page number (1-based).
schema:
minimum: 1
default: 1
example: 1
type: number
- name: limit
required: false
in: query
description: >-
Results per page. Default 250 — intentionally high so most frontends
can load the full list in one request.
schema:
minimum: 1
maximum: 300
default: 250
example: 250
type: number
- name: language
description: Enter language code(ex. en)
in: header
schema: {}
responses:
'200':
description: Nationalities fetched successfully
content:
application/json:
schema:
$ref: '#/components/schemas/NationalityListResponseDto'
components:
schemas:
NationalityListResponseDto:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: Nationalities fetched successfully
data:
$ref: '#/components/schemas/NationalityListDataDto'
required:
- success
- message
- data
NationalityListDataDto:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/NationalityResponseDto'
meta:
$ref: '#/components/schemas/PaginationMetaDto'
required:
- items
- meta
NationalityResponseDto:
type: object
properties:
id:
type: number
example: 101
nationality_name:
type: string
description: Demonym — displayed in dropdowns and sent to providers.
example: Indian
country_name:
type: string
example: India
iso_code:
type: string
description: ISO 3166-1 alpha-2 code. Pass this as `nationality` in hotel search.
example: IN
iso_code_3:
type: object
description: ISO 3166-1 alpha-3 code.
example: IND
dial_code:
type: object
description: International dial code.
example: '+91'
required:
- id
- nationality_name
- country_name
- iso_code
PaginationMetaDto:
type: object
properties:
total:
type: number
example: 195
page:
type: number
example: 1
limit:
type: number
example: 250
totalPages:
type: number
example: 1
required:
- total
- page
- limit
- totalPages
securitySchemes:
x-api-key:
type: apiKey
in: header
name: x-api-key
description: Environment-specific API key created in the Unifystays portal
````