International Address Submission Best Practices

Submit international addresses to the RiskOS™ API using ISO-standard country codes, state mappings, and geocoding best practices.

It is important to follow ISO standard formats and logical country-state correspondences when submitting an international address via the API to ensure accurate geocoding and delivery.

📘
Note:

Electronic Know Your Customer (eKYC) services for international address verification in Australia, China, Hong Kong, and New Zealand require additional provisioning and may incur extra costs. To enable eKYC international verification for your account, complete the following steps:

Contact Socure support to inquire about enabling and provisioning eKYC services on your account.

Review and accept any additional terms of service for the eKYC international address verification product.

Provide any requested information to complete the provisioning process.

eKYC services will only function on your account once the provisioning process is complete.

For international verification in Australia, China, Hong Kong, and New Zealand, please fill out a sub processor form.

Country codes

The country code must be a valid ISO 3166-1 alpha-2 code. For example:

US for United States
CA for Canada
GB for United Kingdom
FR for France
MX for Mexico

State and province codes

State and province codes should only be submitted for countries where they are officially defined and used for mail delivery. They must be in ISO 3166-2 format. Below are some examples:

US addresses should include the complete state code. For example, CA for California, TX for Texas.
Canadian addresses should include the two-letter province code. For example, ON for Ontario, BC for British Columbia.
UK addresses should not include a state or province code since the UK does not use them for mail delivery.
Mexican addresses should include the uppercase three-letter province code. For example, JAL for Jalisco, SLP for San Luis Potosi.

Non-ISO state and province names

Some countries utilize non-ISO standards for state and province codes in mailing addresses. Below are some examples:

For Austrian addresses, use the numerical state code instead of the state name. For example, use "9" for Wien, Austria.
For Ecuadorian addresses, use the state code lettering (usually a single character) instead of the state name. For example, use "T" for Tungurahua, Ecuador.

Putting it all together

Below are some example requests that meet ISO standard formats for international addresses.

{
  "id": "au-verify-001",
  "timestamp": "2026-04-08T00:00:00Z",
  "workflow": "verify_kyc",
  "data": {
    "individual": {
      "given_name": "Ava",
      "family_name": "Brown",
      "date_of_birth": "1984-05-17",
      "national_id": "PA0940443",
      "phone_number": "+614123456789",
      "address": {
        "line_1": "200 Broadway Av",
        "locality": "West Beach",
        "major_admin_division": "SA",
        "postal_code": "5024",
        "country": "AU"
      }
    }
  }
}

{
  "id": "br-verify-001",
  "timestamp": "2026-04-08T00:00:00Z",
  "workflow": "verify_kyc",
  "data": {
    "individual": {
      "given_name": "Lucas",
      "family_name": "Oliveira",
      "date_of_birth": "1974-08-17",
      "national_id": "1234567890-2",
      "phone_number": "+5511984565666",
      "address": {
        "line_1": "Rua Visconde de Porto Seguro 1238",
        "major_admin_division": "SP",
        "postal_code": "04642-000",
        "country": "BR"
      }
    }
  }
}

{
  "id": "ca-verify-001",
  "timestamp": "2026-04-08T00:00:00Z",
  "workflow": "verify_kyc",
  "data": {
    "individual": {
      "given_name": "Lee",
      "family_name": "Melnykova",
      "date_of_birth": "1985-03-30",
      "national_id": "437561291",
      "phone_number": "+14167773322",
      "address": {
        "line_1": "123 Lakeshore Rd",
        "line_2": "Apt 405",
        "locality": "Toronto",
        "major_admin_division": "ON",
        "postal_code": "M5V 3N8",
        "country": "CA"
      }
    }
  }
}

{
  "id": "eu-verify-001",
  "timestamp": "2026-04-08T00:00:00Z",
  "workflow": "verify_kyc",
  "data": {
    "individual": {
      "given_name": "Priyanka",
      "family_name": "Sears",
      "date_of_birth": "1981-12-23",
      "national_id": "15625436FE",
      "phone_number": "+33143935555",
      "address": {
        "line_1": "12 Rue de L'Abbé Grégoire",
        "locality": "Paris",
        "major_admin_division": "75",
        "postal_code": "75006",
        "country": "FR"
      }
    }
  }
}

{
  "id": "hk-verify-001",
  "timestamp": "2026-04-08T00:00:00Z",
  "workflow": "verify_kyc",
  "data": {
    "individual": {
      "given_name": "Chi-Keung",
      "family_name": "Wong",
      "date_of_birth": "1961-12-23",
      "national_id": "286730672532",
      "phone_number": "+85212345678",
      "address": {
        "line_1": "150 Kennedy Road",
        "line_2": "Flat 25, 12/F, Acacia Building",
        "locality": "Wan Chai",
        "major_admin_division": "HK",
        "postal_code": "999077",
        "country": "HK"
      }
    }
  }
}

{
  "id": "in-verify-001",
  "timestamp": "2026-04-08T00:00:00Z",
  "workflow": "verify_kyc",
  "data": {
    "individual": {
      "given_name": "Rahul",
      "family_name": "Sharma",
      "date_of_birth": "1981-12-23",
      "national_id": "456712340098",
      "phone_number": "+911234567890",
      "address": {
        "line_1": "Flat No. 100, Triveni Apartments",
        "locality": "Pitam Pura",
        "major_admin_division": "DL",
        "postal_code": "110034",
        "country": "IN"
      }
    }
  }
}

{
  "id": "mx-verify-001",
  "timestamp": "2026-04-08T00:00:00Z",
  "workflow": "verify_kyc",
  "data": {
    "individual": {
      "given_name": "Juan",
      "family_name": "Guerra",
      "date_of_birth": "1970-06-15",
      "national_id": "700615-GHASSS-01",
      "phone_number": "+525551226699",
      "address": {
        "line_1": "Av. Paseo de la Reforma 123",
        "locality": "Colonia Juárez",
        "major_admin_division": "CMX",
        "postal_code": "06600",
        "country": "MX"
      }
    }
  }
}

{
  "id": "es-verify-001",
  "timestamp": "2026-04-08T00:00:00Z",
  "workflow": "verify_kyc",
  "data": {
    "individual": {
      "given_name": "María",
      "family_name": "Rodríguez López",
      "date_of_birth": "1982-04-11",
      "national_id": "BAA000589",
      "phone_number": "+3412345678",
      "address": {
        "line_1": "Calle Aduana, 29",
        "major_admin_division": "MD",
        "postal_code": "28070",
        "country": "ES"
      }
    }
  }
}

{
  "id": "uk-verify-001",
  "timestamp": "2026-04-08T00:00:00Z",
  "workflow": "verify_kyc",
  "data": {
    "individual": {
      "given_name": "Mayuri",
      "family_name": "Salinas",
      "date_of_birth": "1982-04-11",
      "national_id": "ZZ123456C",
      "phone_number": "+442078301234",
      "address": {
        "line_1": "62 Abbey Gardens Westminster",
        "line_2": "Flat 18",
        "locality": "London",
        "postal_code": "SW7 2BJ",
        "country": "GB"
      }
    }
  }
}

Updated 3 months ago

Did this page help you?