Reference Data¶

The Reference Data endpoints return the values that YIP accepts for the country and nationality fields used when onboarding or altering employees. Use them to map your own values to a recognised country name or ISO 3166-1 alpha-2 code before submitting a request.

(Please see Sovereign OpenAPI documentation for detailed schema)

Countries¶

To retrieve the list of accepted countries, utilise the GET request with the following URL:

GET Request URL

https://api.yip.services/v1.0/reference/countries

The response is a JSON object mapping each ISO 3166-1 alpha-2 code to its country name:

application/json

{
    "AA": "Alderney",
    "AF": "Afghanistan",
    "AX": "Aland Islands",
    "AL": "Albania",
    "DZ": "Algeria",
    "AD": "Andorra"
}

Nationalities¶

To retrieve the list of accepted nationalities, utilise the GET request with the following URL:

GET Request URL

https://api.yip.services/v1.0/reference/nationalities

The response follows the same code to name format as the countries endpoint and lists the values accepted for the nationality field.

Last update: July 30, 2026
Created: July 30, 2026