A country in the T-Gate platform represents one of the geographical regions in which the platform operates. Countries act as the top-level entity in the address hierarchy: every city belongs to a country, and every branch and company resolves its address through a country.

For more details on the hierarchical structure and how different entities relate to each other, please refer to General → High Level Structure Guides.

Model Attributes

A country is rendered through two different shapes depending on where it appears in the API:

Listing endpoint (GET /partner_portal/v1/countries) returns the lookup form: id, name_en, name_ar, name.
Embedded form — when a country is nested inside another resource (for example inside an address attached to a branch or company) — returns name_en, name_ar, dial_code, short_code.

The combined set of attributes a country can carry is:

Attribute	Description	Type
id	The unique identifier of that table entity. Returned only by the countries listing endpoint.	Integer
name_en	Country name in English.	String
name_ar	Country name in Arabic.	String
name	Localized country name returned according to the request's `Accept-Language` header. Resolves to `name_en` for `en` and to `name_ar` for `ar`. Returned only by the listing endpoint.	String
dial_code	The international dialing code of the country (e.g. `+966` for Saudi Arabia). Returned only when the country is embedded inside another resource.	String
short_code	The country code of the country (e.g. `SA`, `EG`). Returned only when the country is embedded inside another resource.	String

📘
name VS name_en / name_ar
The listing endpoint always includes both name_en and name_ar so consumers can render either translation regardless of the current request locale.
The name attribute is a convenience field resolved on the server side from the Accept-Language header. Applications that already maintain their own localization layer can ignore it and read name_en / name_ar directly.
Note that name is not included in the embedded form of a country — when reading a country nested inside another resource, applications should fall back to name_en / name_ar.

📘
dial_code and short_code
dial_code and short_code only appear when the country is embedded inside another resource. If your integration needs these values up front (for example, to render dial codes in a phone-number input), retrieve them from the embedded country object on an existing branch/company/address rather than expecting them on the countries listing endpoint.

🌍
Country Ordering
When listed via GET /partner_portal/v1/countries, countries are returned with Saudi Arabia pinned to the top, followed by the remaining countries sorted alphabetically by name in the active locale (name_en for en, name_ar for ar).
This ordering is applied by T-Gate and does not need to be reproduced on the client side.

Cities

Each country has many cities, and every city belongs to exactly one country. Cities are retrieved through a separate endpoint (GET /partner_portal/v1/cities) which accepts a country_id filter to scope the result set to a single country.

The country payload itself does not embed its list of cities — applications that need both should call the cities endpoint with the relevant country_id.