Documentation

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.

Suggest Edits

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

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
  • 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 2 months ago