ISO Jurisdiction Code Migration
Recommendations and helpful tips for migration to ISO standards for Country and Subdivision Codes
Zero Hash is migrating to ISO standards for Country and Subdivision Codes to streamline implementation and avoid any ambiguity around country names. Note that this relates to country of residence, citizenship and optionally id issuing authority.
This guide should be used as an integration reference. For questions please contact your Relationship Manager.
Note:
The sunset of the current fields marked as deprecated will happen in the future. We will give a 30 day notice to make sure you have enough time to properly migrate to the new fields.
Terminology
| Term | Definition |
|---|---|
| ISO 3166-1-A2 | Two-letter country codes defined in ISO 3166-1-A2 (e.g. US → United States, SG → Singapore). |
| ISO 3166-2 | ISO 3166-2 is part of the ISO 3166 standard, and defines codes for identifying the principal subdivisions (e.g., provinces or states) of all countries coded in ISO 3166-1-A2 (e.g. US-NY → New York in the United States). |
Overview of supported ISO codes
GET /jurisdiction/countries
- Returns a list of ISO 3166-1-A2 countries
- Country code & country name
Example
[
{"code": "AU", "name": "Australia"},
{"code": "BS", "name": "Bahamas"},
{"code": "US", "name": "United States of America"}
]
GET /jurisdiction/subdivisions?country={{country_code}}
- Returns a list of ISO 3166-2 subdivisions for the provided country (example used is BS)
- ISO 3166-2 subdivision code & subdivision name
Example
[
{"code": "BS-AK", "name": "Acklins"},
{"code": "BS-BY", "name": "Berry Islands"},
]
GET /jurisdiction/subdivisions?country=BTC
- The request above is an example of a bad request as BTC is not a country code
- We will show the following error if an invalid country code is used
- Please use a country code as specified by GET /jurisdiction/countries
Example-bad-request
{
"errors": [
"Given country code BTC is not valid, country code should be one of ISO 3166-1-A2 countries"
]
}
Create customer
POST /participants/customers/new
Endpoints currently supporting name-based country and state input shall continue to do so until further notice, however these endpoints will now support ISO 3166 codes.
Documentation will be updated to show support for ISO 3166 input only, new platforms will be instructed to use ISO codes and existing platforms will be requested to migrate before the legacy name-based country & state input is completely deprecated.
Note:
We will provide legacy fields in the response even if you use ISO 3166 fields in the request and vice-versa. The legacy fields will be removed in the final stages of the migration.
Sample request:
{
"first_name": "Leslie",
"last_name": "Knope",
"date_of_birth": "1975-01-18",
"email": "[email protected]",
"phone_number": "+12345678909",
"address_one": "123 Main St.",
"city": "Pawnee",
"zip": "46001",
"jurisdiction_code": "US-IN", // NEW; ISO 3166-2
"citizenship_code": "US", // NEW; ISO 3166-1-A2
"id_issuing_authority": "US", // NEW; ISO 3166-1-A2 - optional
"tax_id": "123456789",
"signed_timestamp": 1717676518666,
"kyc": "pass",
"kyc_timestamp": 1717676518666,
"sanction_screening": "pass",
"sanction_screening_timestamp": 1717676518666
}
Sample response:
{
"message": {
"first_name": "Leslie",
"last_name": "Knope",
"email": "[email protected]",
"address_one": "123 Main St.",
"address_two": "",
"city": "Pawnee",
"zip": "46001",
"date_of_birth": "1975-01-18",
"id_number_type": "ssn",
"id_number": "123456789",
"non_us_other_type": "",
"country": "United States", // will be deprecated
"state": "IN", // will be deprecated
"jurisdiction_code": "US-IN", // NEW; ISO 3166-2
"citizenship": "United States", // will be deprecated
"citizenship_code": "US", // NEW; ISO 3166-1-A2
"id_issuing_authority": "US", // NEW; ISO 3166-1-A2 - optional
"signed_timestamp": 1717676518666,
"risk_rating": "",
"metadata": {},
"platform_code": "JVO6AD",
"participant_code": "XX87VE",
"tax_id": "123456789",
"kyc": "pass",
"kyc_timestamp": 1717676518666,
"onboarded_location": "",
"sanction_screening": "pass",
"sanction_screening_timestamp": 1717676518666,
"idv": "unknown",
"liveness_check": "unknown",
"phone_number": "+12345678909",
"employment_status": "unknown",
"industry": "unknown",
"source_of_funds": "unknown",
"signed_agreements": [
{
"region": "us",
"signed_timestamp": 1717676518,
"type": "user_agreement"
}
]
}
}
Create entity customer
POST /participants/entity/new
For the entity customer, as well as the control_persons and beneficial_owners:
Country, state, citizenship and id_issuing_authority, will all be replaced by ISO codes.
Similar to retail customers.
Get Participants
GET /participants
After you create a participant, Zero Hash returns a participant_code which can be used to retrieve details about the participant. Without any query parameters GET /participants will return all participants linked to the platform.
Query parameter:
| Key | Value |
|---|---|
| participant_code | The participant_code, retrieved either in the API response, or from GET /participants/{{email}} |
Sample request
GET /participants?participant_code=XX87VE
Sample response
{
"message": [
{
"participant_code": "XX87VE",
"participant_name": "Leslie Knope",
"email": "[email protected]",
"status": "approved",
"reason_code": null,
"country": "United States", // will be deprecated
"state": "IN", // will be deprecated
"jurisdiction_code": "US-IN", // NEW; ISO 3166-2
"updated_at": 1719928977177,
}
],
"page": 1,
"page_size": 200,
"total_pages": 1,
"count": 1
}
Patch a Participant
PATCH /participants/customers/{participant_code}
Updating a participant will leverage the same logic as creating a participant.
Name-based country and state shall be supported until further notice. In addition to this the PATCH endpoint will support ISO 3166 codes.
Documentation will be updated to show support for ISO 3166 input only, new platforms will be instructed to use ISO codes and existing platforms will be requested to migrate before the legacy name-based country & state input is completely deprecated.
Sample request:
{
"address_one": "45 Rockefeller Plaza",
"city": "New York",
"zip": "10111",
"jurisdiction_code": "US-NY", // NEW; ISO 3166-2
"platform_updated_at": 1715910455000
}
Sample response
{
"message": {
"first_name": "Leslie",
"last_name": "Knope",
"address_one": "45 Rockefeller Plaza",
"address_two": "",
"country": "United States", // will be deprecated
"state": "NY", // will be deprecated
"jurisdiction_code": "US-NY", // NEW; ISO 3166-2
"city": "New York",
"zip": "10111",
"email": "[email protected]",
"date_of_birth": "1975-01-18",
"id_number_type": "ssn",
"id_number": "123456789",
"non_us_other_type": "",
"id_issuing_authority": "US", // NEW; ISO 3166-1-A2 - optional
"signed_timestamp": 1717676518666,
"risk_rating": "",
"platform_code": "JVO6AD",
"participant_code": "XX87VE",
"platform_updated_at": 1715910455000,
"tax_id": "123456789",
"citizenship": "United States", // will be deprecated
"citizenship_code": "US", // NEW; ISO 3166-1-A2
"kyc": "pass",
"kyc_timestamp": 1717676518666,
"onboarded_location": "",
"sanction_screening": "pass",
"sanction_screening_timestamp": 1717676518666,
"idv": "unknown",
"liveness_check": "unknown",
"phone_number": "+12345678909",
"employment_status": "unknown",
"industry": "unknown",
"source_of_funds": "unknown",
"signed_agreements": [
{
"region": "us",
"signed_timestamp": 1717676518,
"type": "user_agreement"
}
]
}
}
Updated 13 days ago