ISO Jurisdiction Code Migration

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
- In case a country does not have any subdivisions, an empty array will be returned

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. In case a country does not have any subdivisions, the jurisdiction_code will accept a two letter country code.

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"  
            }  
        ]  
    }  
}

If the submitted jurisdiction_code does not include a subdivision while this is required for the relevant country, the following error will be presented:

{
  "errors":	[  
				"subdivision is required for country"
  ]
}

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. In case a country does not have any subdivisions, the jurisdiction_code will accept a two letter country code.

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"  
            }  
        ]  
    }  
}

ISO Jurisdiction Code Migration

📘
Note:

Terminology

Overview of supported ISO codes

Create customer

📘
Note:

Create entity customer

Get Participants

Patch a Participant

📘Note:

Terminology

Overview of supported ISO codes

Create customer

📘Note:

Create entity customer

Get Participants

Patch a Participant

📘
Note:

📘
Note: