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
/API/v4/General/GetCountryReturns 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
GetCountryResponseobjectWrapper object for the response.
Child parameters1
GetCountryResultobjectResult of the operation.
Child parameters2
Countryobject[]List of countries.
Child parameters5
CountryIDintegerThe unique internal Xtrm identifier for the country. Pass it as
CountryIDtoGetState.CountryNamestringThe full recognized name of the country, for example
United States of America.CountryISO2stringThe two-character ISO 3166-1 alpha-2 country abbreviation, for example
US.CountryCodestringThe three-character ISO 3166-1 alpha-3 country code, for example
USA.CurrencystringThe three-letter ISO 4217 code of the currency associated with the country, for example
USD. Added in release 4.92.1.
OperationStatusobjectOutcome of the operation.
Child parameters2
Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.SuccessbooleanWhether 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
/API/v4/General/GetStateReturns 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
GetStateobjectRequiredWrapper object for the operation.
Child parameters1
requestobjectRequiredWrapper object for the request fields.
Child parameters2
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.CountryIDstringRequiredThe unique internal Xtrm identifier for the country, as a string, for example
"1". Get it from theCountryIDfield returned byGetCountry.
Response fields
GetStateResponseobjectWrapper object for the response.
Child parameters1
GetStateResultobjectResult of the operation.
Child parameters2
Stateobject[]List of regions within the requested country.
Child parameters1
StateNamestringThe full administrative name of the region, state, or province, for example
Alabama.
OperationStatusobjectOutcome of the operation.
Child parameters2
Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.SuccessbooleanWhether the operation succeeded (
true) or failed (false).
Related: List countries · List regions for an advanced profile