CommunitySupport PortalYouTubeFree trialSign Up!

Countries

Retrieving all countries

get

Retrieves all countries assigned to the tenant. You can filter, sort and paginate the results with query parameters.

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Pattern: ^[a-z][a-z0-9]+$
Query parameters
pageNumberinteger · min: 1Optional

The page number to be retrieved where the size of the pages must be specified by the pageSize parameter. The number of the first page is 1.

Default: 1
pageSizeinteger · min: 1Optional

The number of documents being retrieved on the page.

Default: 60
sortstringOptional

Fields to sort the response data by, following the order of the parameters from left to right.

  • Can contain multiple fields in the format: fieldName:sortDirection, separated by commas.

  • The colon with the sort direction parameter is optional.

  • Descending order is used only if the sort direction equals desc or DESC.

  • Ascending order is assumed in all other cases.

While sorting by a localized field, the following rules apply:

  • If a localized field includes a language code, that language is used.
    Example: name.en:ASC → English (en) is used for sorting the name property.
    The language suffix takes precedence over the Accept-Language header.

  • If a localized field does not include a language code, the Accept-Language header is used.
    Example: name:ASC with Accept-Language: de → German (de) is used for sorting.

  • If a localized field has no language code and the Accept-Language header contains *,
    the default language from the configuration service is used.
    Example: name:ASC, Accept-Language: *, default language = pl → Polish (pl) is used.

  • If a localized field has no language code and there is no Accept-Language header,
    the default language from the configuration service is used.

Example: name,code:desc
namestringOptional

Country names. When specified, only countries containing the specified names will be returned.

Important: See how the Accept-Language header influences this parameter:

  • If The Accept-Language header is set to *, you need to specify a language in this parameter.

    For example, if the Accept-Language header is set to * and you want to find English names containing the word "Isle", this parameter should be set to "name.en=Isle"

  • If the Accept-Language header is set to a particular language or not specified, you do not need to specify a language in this parameter.

    For example, if the Accept-Language header is set to en and you want to find names containing the word "Isle", this parameter should be set to "name=Isle"

Note: When filtering the results with this field, the contains operator is used. The operator is case-insensitive.

codestringOptional

Country codes. When specified, only countries containing the specified code will be returned.

Note: When filtering the results with this field, the contains operator is used. The operator is case-insensitive.

activestringOptional

Country active status, expressed as true or false. When specified, only countries with the active status will be returned.

Note: When filtering the results with this field, the equals operator is used.

regionsstringOptional

Country region codes. When specified, only countries containing the specified region codes will be returned.

Note: When filtering the results with this field, the contains operator is used.

Header parameters
Accept-LanguagestringOptional

List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.

  • If the header is set to a particular language or a list of languages, all localized fields are retrieved as maps with the first matched language only.
  • If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
  • If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.
Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
X-Total-CountbooleanOptional

In order to get information how many entities meet a filter requirements, X-Total-Count header has been introduced. The header is optional and its default value is false. It the header is provided and it is true then total count is returned in the X-Total-Count response header. In both cases (X-Total-Count true, false or not provided), the response body has the same format (array of entities). In other words, the information about total count is returned on demand, depending of an existence of X-Total-Count header in a request. Therefore, the X-Total-Count header is not returned if an API consumer didn’t ask for it.

Default: false
X-VersionstringRequired

The X-Version header with value v2 is required for the endpoint.

Responses
200

The request was successful. A list of countries is returned.

application/json
get
/country/{tenant}/countries
GET /country/{tenant}/countries HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: text
Accept: */*

[
  {
    "code": "PL",
    "name": {
      "en": "Poland",
      "pl": "Polska"
    },
    "regions": [
      "Europe"
    ],
    "metadata": {
      "createdAt": "2022-03-31T13:18:02.379Z",
      "modifiedAt": "2022-03-31T13:18:02.379Z",
      "version": 1
    }
  }
]

Retrieving a country

get

Retrieves a country by the specified code.

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Pattern: ^[a-z][a-z0-9]+$
countryCodestringRequired

Two-letter country code.

Header parameters
Accept-LanguagestringOptional

List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.

Note: If not specified, localized fields will be retrieved in English.

Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
X-VersionstringRequired

The X-Version header with value v2 is required for the endpoint.

Responses
200

The request was successful. The requested country is returned.

application/json
get
/country/{tenant}/countries/{countryCode}
GET /country/{tenant}/countries/{countryCode} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: text
Accept: */*

{
  "code": "PL",
  "name": {
    "en": "Poland",
    "pl": "Polska"
  },
  "regions": [
    "Europe"
  ],
  "metadata": {
    "createdAt": "2022-03-31T13:18:02.379Z",
    "modifiedAt": "2022-03-31T13:18:02.379Z",
    "version": 1
  }
}

Update a country

patch

Updates a country. It is possible to update active field only. The field indicates whether the given country is active for the tenant or not. Only active countries are visible in the system.

Required scopes

  • country.country_manage

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

Pattern: ^[a-z][a-z0-9]+$
countryCodestringRequired

Two-letter country code.

Header parameters
X-VersionstringRequired

The X-Version header with value v2 is required for the endpoint.

Body
activebooleanOptional

The field indicates whether the given country is active for the tenant or not. Only active countries are visible in the system.

Responses
204

No Content

No content
patch
/country/{tenant}/countries/{countryCode}
PATCH /country/{tenant}/countries/{countryCode} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
X-Version: text
Content-Type: application/json
Accept: */*
Content-Length: 40

{
  "active": true,
  "metadata": {
    "version": 1
  }
}
No content
PreviousCountryNextRegions

Was this helpful?