ISO 3166 Conversions
In certain endpoints, Zero Hash requires a non-null and valid ISO 3166-2 value. If you do not have these values in your systems already that conform to our standard, this page will instruct you on ways to make that conversion before passing us a valid value.
General
Zero Hash has requirements on the format of certain geography-related fields in our API endpoints. We adhere to the ISO 3166 standard. Platforms, however, may not have the data structured exactly to our standards. This page will help Platforms more easily transform data into Zero Hash's standards prior to hitting our endpoints.
Applicable Endpoints
- POST /participants/customers/new
- ISO 3166-2 formatted fields:
jurisdiction_code
- ISO 3166-1 formatted fields
citizenship_code
- ISO 3166-2 formatted fields:
- PATCH /participants/customers/{participant_code}
- ISO 3166-2 formatted fields:
jurisdiction_code
- ISO 3166-1 formatted fields
citizenship_code
- ISO 3166-2 formatted fields:
- POST /participants/entity/new
- ISO 3166-2 formatted fields:
jurisdiction_code
- ISO 3166-1 formatted fields
citizenship_code
- ISO 3166-2 formatted fields:
- POST /participants/beneficiaries/new
- ISO 3166-2 formatted fields:
jurisdiction_code
- ISO 3166-1 formatted fields
citizenship_code
- ISO 3166-2 formatted fields:
- PATCH /participants/beneficiaries/{participant_code}
- ISO 3166-2 formatted fields:
jurisdiction_code
- ISO 3166-1 formatted fields
citizenship_code
- ISO 3166-2 formatted fields:
Applicable Integration Guides
The following integration guides contain steps that require the submission of ISO 3166 structured data:
External API Resources to Help Make the Conversion
We recommend to use the following external API's:
Google Geocoding API Example
General
- In this example, you are trying to submit a Customer via the Zero Hash POST /participants/customers/new endpoint
- You have the postal code and the country of a Customer that lives in Chicago, Illinois:
- Postal Code:
60654
- Country:
United States
- Postal Code:
- You now need to use the Google Geocoding API to generate a ISO 3166-2
jurisdiction_code
Step 1: Making the Geocoding API Request
First, you need to make a request to the Google Maps Geocoding API using the provided postal code and country.
GET https://maps.googleapis.com/maps/api/geocode/json?address=60654,United States&key=YOUR_API_KEY
Step 2: Example Code to Get Subdivision
Here’s an example in Python to make the API call and extract the ISO 3166-2 code for the subdivision:
import requests
def get_subdivision(postal_code, country, api_key):
url = f"https://maps.googleapis.com/maps/api/geocode/json?address={postal_code},{country}&key={api_key}"
response = requests.get(url)
data = response.json()
if data['status'] == 'OK':
for component in data['results'][0]['address_components']:
if 'administrative_area_level_1' in component['types']:
return f"US-{component['short_name']}" # ISO 3166-2 format
return None
# Example usage
api_key = 'YOUR_API_KEY'
subdivision_code = get_subdivision("60654", "United States", api_key)
print(subdivision_code) # Should output 'US-IL'
Step 3: Incorporating the Result into the POST Request
Now that you have the subdivision code (e.g., US-IL), you can include it in your POST request. Here’s how the final JSON payload would look:
{
"first_name": "John",
"last_name": "Smith",
"email": "[email protected]",
"phone_number": "9545551234",
"address_one": "1 Main St.",
"address_two": "Suite 1000",
"city": "Chicago",
"state": "IL",
"zip": "60654",
"country": "United States",
"date_of_birth": "1985-09-02",
"citizenship": "United States",
"tax_id": "123456789",
"risk_rating": "low",
"kyc": "pass",
"kyc_timestamp": 1630623005000,
"sanction_screening": "pass",
"sanction_screening_timestamp": 1630623005000,
"idv": "pass",
"liveness_check": "pass",
"signed_timestamp": 1630623005000,
"jurisdiction_code": "US-IL", // Added jurisdiction_code field
"metadata": {},
"signed_agreements": [
{
"type": "user_agreement",
"region": "us",
"signed_timestamp": 1712008721000
}
]
}
Updated about 1 month ago