API reference

Reference data

Use these endpoints to look up countries and the regions (states, provinces, and so on) within a country. GetCountry returns the global list of countries with each country's internal CountryID, two- and three-character ISO codes, and currency. GetState returns the regions of the country you identify by its CountryID.

The advanced profile has two similar lookups with different inputs and outputs. GetAdvancedContactCountry returns only each country's name and two-character code. GetAdvancedContactState takes the two-character country code (CountryCode) instead of a CountryID, and returns a StateCode and a StateName for each region, for example ALABAMA in both.

#List countries

POST/API/v4/General/GetCountry

Returns a global list of countries. For each country, the response includes the internal Xtrm identifier (CountryID), the full name (CountryName), the two-character ISO 3166-1 alpha-2 code (CountryISO2), the three-character ISO code (CountryCode), and the ISO 4217 code of the currency associated with the country (Currency).

Use the CountryID as input to GetState to list the regions within a country. CountryISO2 is the two-character country abbreviation that other calls take, for example the CountryISO2 parameter of GetBankWithdrawTypes.

Note

Send an empty JSON object {} as the request body.

Note

CountryCode means different things in different lookups. In GetCountry it is the three-character code (for example USA). In GetAdvancedContactCountry and GetAdvancedContactState it is the two-character code (for example US), which GetCountry returns as CountryISO2.

Response fields

  • GetCountryResponseobject

    Wrapper object for the response.

    Child parameters1
    • GetCountryResultobject

      Result of the operation.

      Child parameters2
      • Countryobject[]

        List of countries.

        Child parameters5
        • CountryIDinteger

          The unique internal Xtrm identifier for the country. Pass it as CountryID to GetState.

        • CountryNamestring

          The full recognized name of the country, for example United States of America.

        • CountryISO2string

          The two-character ISO 3166-1 alpha-2 country abbreviation, for example US.

        • CountryCodestring

          The three-character ISO 3166-1 alpha-3 country code, for example USA.

        • Currencystring

          The three-letter ISO 4217 code of the currency associated with the country, for example USD. Added in release 4.92.1.

      • OperationStatusobject

        Outcome of the operation.

        Child parameters2
        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

        • Successboolean

          Whether the operation succeeded (true) or failed (false).

Related: List regions for a country ID · List countries for an advanced profile · List bank transfer types for a country · Create an individual recipient · Create a business recipient

#List regions for a country ID

POST/API/v4/General/GetState

Returns the list of regions (states, provinces, regions, and so on) for a particular country. Identify the country by its internal CountryID, which you get from GetCountry. Each region is returned by its full administrative name (StateName).

Body parameters

  • GetStateobjectRequired

    Wrapper object for the operation.

    Child parameters1
    • requestobjectRequired

      Wrapper object for the request fields.

      Child parameters2
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • CountryIDstringRequired

        The unique internal Xtrm identifier for the country, as a string, for example "1". Get it from the CountryID field returned by GetCountry.

Response fields

  • GetStateResponseobject

    Wrapper object for the response.

    Child parameters1
    • GetStateResultobject

      Result of the operation.

      Child parameters2
      • Stateobject[]

        List of regions within the requested country.

        Child parameters1
        • StateNamestring

          The full administrative name of the region, state, or province, for example Alabama.

      • OperationStatusobject

        Outcome of the operation.

        Child parameters2
        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

        • Successboolean

          Whether the operation succeeded (true) or failed (false).

Related: List countries · List regions for an advanced profile