sep-0009.md

Preamble

SEP: 0009
Title: Standard KYC Fields
Author: stellar.org
Status: Active
Created: 2018-07-27
Updated: 2022-05-13
Version 1.6.0

Simple Summary

This SEP defines a list of standard KYC and AML fields for use in Stellar ecosystem protocols. Issuers, banks, and other entities on Stellar should use these fields when sending or requesting KYC / AML information with other parties on Stellar. This is an evolving list, so please suggest any missing fields that you use.

This is a list of possible fields that may be necessary to handle many different use cases, there is no expectation that any particular fields be used for a particular application. The best fields to use in a particular case is determined by the needs of the KYC or AML application.

Encodings

ISO encodings are used for fields wherever possible. The table below lists the encodings used for different types of information.

Field Type	Number of characters	Format / Encoding
language	2	ISO 639-1
country	3	ISO 3166-1 alpha-3
date	10	ISO 8601 date-only format
phone number	varies	E.164
occupation	3	ISCO08

Field Naming Conventions

Where possible we use field names from schema.org. Words are separated with underlines as that convention has previously been established in Stellar protocols.

Dot Notation

Field names should always be used as strings. For example:

{
	"organization.name": "Stellar Development Foundation"
}

The dot notation is not an indication that the fields described should be contained in a nested object under a top-level key.

KYC / AML Fields

Natural Person KYC fields

Name	Type	Description
family_name or last_name	string	Family or last name
given_name or first_name	string	Given or first name
additional_name	string	Middle name or other additional name
address_country_code	country code	country code for current address
state_or_province	string	name of state/province/region/prefecture
city	string	name of city/town
postal_code	string	Postal or other code identifying user's locale
address	string	Entire address (country, state, postal code, street address, etc...) as a multi-line string
mobile_number	phone number	Mobile phone number with country code, in E.164 format
email_address	string	Email address
birth_date	date	Date of birth, e.g. 1976-07-04
birth_place	string	Place of birth (city, state, country; as on passport)
birth_country_code	country code	ISO Code of country of birth
bank_account_number	string	Number identifying bank account
bank_number	string	Number identifying bank in national banking system (routing number in US)
bank_phone_number	string	Phone number with country code for bank
bank_branch_number	string	Number identifying bank branch
clabe_number	string	Bank account number for Mexico
tax_id	string	Tax identifier of user in their country (social security number in US)
tax_id_name	string	Name of the tax ID (SSN or ITIN in the US)
occupation	number	Occupation ISCO code
employer_name	string	Name of employer
employer_address	string	Address of employer
language_code	language code	primary language
id_type	string	passport, drivers_license, id_card, etc...
id_country_code	country code	country issuing passport or photo ID as ISO 3166-1 alpha-3 code
id_issue_date	date	ID issue date
id_expiration_date	date	ID expiration date
id_number	string	Passport or ID number
photo_id_front	binary	Image of front of user's photo ID or passport
photo_id_back	binary	Image of back of user's photo ID or passport
notary_approval_of_photo_id	binary	Image of notary's approval of photo ID or passport
ip_address	string	IP address of customer's computer
photo_proof_residence	binary	Image of a utility bill, bank statement or similar with the user's name and address
sex	string	male, female, or other

Organization KYC fields

Name	Type	Description
organization.name	string	Full organiation name as on the incorporation papers
organization.VAT_number	string	Organization VAT number
organization.registration_number	string	Organization registration number
organization.registration_date	string	Date the organization was registered
organization.registered_address	string	Organization registered address
organization.number_of_shareholders	number	Organization shareholder number
organization.shareholder_name	string	Can be an organization or a person and should be queried recursively up to the ultimate beneficial owners (with KYC information for natural persons such as above)
organization.photo_incorporation_doc	binary	Image of incorporation documents
organization.photo_proof_address	binary	Image of a utility bill, bank statement with the organization's name and address
organization.address_country_code	country code	country code for current address
organization.state_or_province	string	name of state/province/region/prefecture
organization.city	string	name of city/town
organization.postal_code	string	Postal or other code identifying organization's locale
organization.director_name	string	Organization registered managing director (the rest of the information should be queried as an individual using the fields above)
organization.website	string	Organization website
organization.email	string	Organization contact email
organization.phone	string	Organization contact phone

Addresses

Address formatting varies widely from country to country and even within each country. See here for details. Rather than attempting to create a field for each possible part of an address in every country, this protocol takes a middle of the road approach. Address fields that are fairly universal can be encoded with the country_code, state_or_province, city, and postal_code fields. Full addresses, however, should be encoded as a single multi-line string in the address field. This allows any address in the world to be represented with a limited number of fields. If address parsing is necessary, parsing will be easier since the country, city, and postal code are already separate fields.

Changelog

• v1.6.0: Add clabe_number to Natural Person KYC fields (#1202).