List 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
    }
  }
}

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 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"

For a server-side filter, add 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

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.

Authorizations

x-api-key

string

header

required

Environment-specific API key created in the Unifystays portal

Headers

Query Parameters

string

Search by nationality name, country name, or ISO alpha-2 code (case-insensitive).

Example:

"ind"

sort_by

enum<string>

default:nationality_name

Field to sort by.

Available options:

nationality_name,

country_name,

iso_code

sort_order

enum<string>

default:ASC

Sort direction.

Available options:

ASC,

DESC

page

number

default:1

Page number (1-based).

Required range: x >= 1

Example:

1

limit

number

default:250

Results per page. Default 250 — intentionally high so most frontends can load the full list in one request.

Required range: 1 <= x <= 300

Example:

250

Response

200 - application/json

Nationalities fetched successfully

success

boolean

required

Example:

true

message

string

required

Example:

"Nationalities fetched successfully"

data

object

required

Show child attributes

⌘I

Overview

Destination & master data

Search & hotels

Bookings

Request Examples

Response Example

Use `iso_code` in Hotel Requests

Cache Key

Authorizations

Headers

Query Parameters

Response

​Request Examples

​Response Example

​Use iso_code in Hotel Requests

​Cache Key

Authorizations

Headers

Query Parameters

Response

Request Examples

Response Example

Use `iso_code` in Hotel Requests

Cache Key