Create a person

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

IVMS101-compliant payload to create a natural or legal person

Option 1
Option 2

Create a natural person

kind

enum<string>

required

Available options:

natural

account_numbers

object[]

List of bank or wallet account numbers

Show child attributes

account_numbers.account_number

string

Represents a bank or virtual asset account number.

Required string length: 1 - 50

Example:

"HOLMESACC12345"

addresses

object[]

Physical or mailing addresses

Show child attributes

addresses.address_lines

string[] | null

Free format address lines. See IVMS101 Section 5.2.6.3.15 and constraint C8.

Required string length: 1 - 140

Example:

"[\"Company HQ\", \"Main Street\"]"

addresses.address_type

enum<string>

Identifies the nature of the address (geographic/home/business). See IVMS101 Section 5.2.6.3.1.

Available options:

GEOG,

HOME,

BIZZ

Example:

"GEOG"

addresses.building_name

string | null

Name of the building or house. See IVMS101 Section 5.2.6.3.6.

Required string length: 1 - 35

Example:

"Holmes Residence"

addresses.building_number

string | null

Number that identifies the position of a building on a street. See IVMS101 Section 5.2.6.3.5.

Required string length: 1 - 16

Example:

"221B"

addresses.country

string

ISO 3166-1 alpha-2 country code. See IVMS101 constraint C3 and Section 5.2.6.3.16.

Example:

"GB"

addresses.country_sub_division

string | null

Identifies a subdivision of a country (state/region/province). See IVMS101 Section 5.2.6.3.14.

Required string length: 1 - 35

Example:

"England"

addresses.department

string | null

Identification of a division of a large organisation or building. See IVMS101 Section 5.2.6.3.2.

Required string length: 1 - 35

Example:

"Compliance Department"

addresses.district_name

string | null

Subdivision within a country subdivision. See IVMS101 Section 5.2.6.3.13.

Required string length: 1 - 35

Example:

"Greater London"

addresses.floor

string | null

Floor or storey within a building. See IVMS101 Section 5.2.6.3.7.

Required string length: 1 - 70

Example:

"2nd Floor"

addresses.post_box

string | null

Numbered box in a post office. See IVMS101 Section 5.2.6.3.8.

Required string length: 1 - 16

Example:

"PO123"

addresses.postcode

string | null

Postal code. See IVMS101 Section 5.2.6.3.10.

Required string length: 1 - 16

Example:

"NW1 6XE"

addresses.room

string | null

Building room number. See IVMS101 Section 5.2.6.3.9.

Required string length: 1 - 35

Example:

"Room 221"

addresses.street_name

string | null

Name of a street or thoroughfare. See IVMS101 Section 5.2.6.3.4.

Required string length: 1 - 70

Example:

"Main Street"

addresses.sub_department

string | null

Identification of a sub-division. See IVMS101 Section 5.2.6.3.3.

Required string length: 1 - 35

Example:

"Risk Team"

addresses.town_location_name

string | null

Specific location name within the town. See IVMS101 Section 5.2.6.3.12.

Required string length: 1 - 35

Example:

"Westminster"

addresses.town_name

string

Name of built-up area. See IVMS101 Section 5.2.6.3.11.

Required string length: 1 - 35

Example:

"London"

name_identifiers

object[]

Official or alias names associated with this person

Show child attributes

name_identifiers.is_legal

boolean

Indicates if this is the legal name. See IVMS101 constraints C6/C5.

Example:

true

name_identifiers.kind

enum<string>

The nature of the name specified (legal, alias, birth, etc.). See IVMS101 Section 5.2.4.3.3.

Available options:

LEGL,

ALIA,

BIRT,

MAID,

MISC

Example:

"LEGL"

name_identifiers.primary_identifier

string

Primary identifier (surname or full name). See IVMS101 Section 5.2.4.3.1.

Required string length: 1 - 100

Example:

"Sherlock Holmes"

name_identifiers.secondary_identifier

string | null

Secondary identifier (forenames, initials). See IVMS101 Section 5.2.4.3.2.

Maximum string length: 100

Example:

"S. Holmes"

national_identifiers

object[]

National identifiers (e.g., passport, national ID)

Show child attributes

national_identifiers.country_of_issue

string | null

ISO 3166-1 alpha-2 country code of the issuing authority. See IVMS101 constraint C3.

Example:

"GB"

national_identifiers.identifier_type

string

Specifies the type of the national identifier. See IVMS101 Section 5.2.8.3.2.

Required string length: 1 - 35

Example:

"LEIX"

national_identifiers.national_identifier

string

An identifier issued by an appropriate issuing authority. See IVMS101 Section 5.2.8.3.1.

Required string length: 1 - 35

Example:

"GB123456789"

national_identifiers.registration_authority

string | null

Registration authority code; 8-character. See IVMS101 Sections C9/C10.

Required string length: 8

Example:

"RA000001"

person

object

Core details about the natural person

Show child attributes

person.country_of_residence

string | null

ISO 3166-1 alpha-2 country code of residence. See IVMS101 constraint C3 and Section 5.2.2.3.6. ISO 3166-1 alpha-2 country code

Example:

"GB"

person.customer_identification

string | null

A distinct identifier that uniquely identifies the person to the institution in context. See IVMS101 Section 5.2.2.3.4.

Maximum string length: 50

Example:

"HOLMES001"

person.date_of_birth

string<date> | null

Date of birth; must be a historic date per constraint C2. See IVMS101 Section 5.2.7.

Example:

"1854-01-06"

person.place_of_birth

string | null

Place of birth (town/city/subdivision/country). See IVMS101 Section 5.2.7.3.2.

Required string length: 1 - 100

Example:

"Baker Street, London"

Response

Created

Person was created successfully.

account_numbers

object[]

required

Account numbers (bank or wallet identifiers).

Show child attributes

account_numbers.account_number

string

Represents a bank or virtual asset account number.

Required string length: 1 - 50

Example:

"HOLMESACC12345"

Example:

[
  {
    "account_number": "GB29NWBK60161331926819"
  }
]

addresses

object[]

required

Registered or physical addresses.

Show child attributes

addresses.address_lines

string[] | null

Free format address lines. See IVMS101 Section 5.2.6.3.15 and constraint C8.

Required string length: 1 - 140

Example:

"[\"Company HQ\", \"Main Street\"]"

addresses.address_type

enum<string>

Identifies the nature of the address (geographic/home/business). See IVMS101 Section 5.2.6.3.1.

Available options:

GEOG,

HOME,

BIZZ

Example:

"GEOG"

addresses.building_name

string | null

Name of the building or house. See IVMS101 Section 5.2.6.3.6.

Required string length: 1 - 35

Example:

"Holmes Residence"

addresses.building_number

string | null

Number that identifies the position of a building on a street. See IVMS101 Section 5.2.6.3.5.

Required string length: 1 - 16

Example:

"221B"

addresses.country

string

ISO 3166-1 alpha-2 country code. See IVMS101 constraint C3 and Section 5.2.6.3.16.

Example:

"GB"

addresses.country_sub_division

string | null

Identifies a subdivision of a country (state/region/province). See IVMS101 Section 5.2.6.3.14.

Required string length: 1 - 35

Example:

"England"

addresses.department

string | null

Identification of a division of a large organisation or building. See IVMS101 Section 5.2.6.3.2.

Required string length: 1 - 35

Example:

"Compliance Department"

addresses.district_name

string | null

Subdivision within a country subdivision. See IVMS101 Section 5.2.6.3.13.

Required string length: 1 - 35

Example:

"Greater London"

addresses.floor

string | null

Floor or storey within a building. See IVMS101 Section 5.2.6.3.7.

Required string length: 1 - 70

Example:

"2nd Floor"

addresses.post_box

string | null

Numbered box in a post office. See IVMS101 Section 5.2.6.3.8.

Required string length: 1 - 16

Example:

"PO123"

addresses.postcode

string | null

Postal code. See IVMS101 Section 5.2.6.3.10.

Required string length: 1 - 16

Example:

"NW1 6XE"

addresses.room

string | null

Building room number. See IVMS101 Section 5.2.6.3.9.

Required string length: 1 - 35

Example:

"Room 221"

addresses.street_name

string | null

Name of a street or thoroughfare. See IVMS101 Section 5.2.6.3.4.

Required string length: 1 - 70

Example:

"Main Street"

addresses.sub_department

string | null

Identification of a sub-division. See IVMS101 Section 5.2.6.3.3.

Required string length: 1 - 35

Example:

"Risk Team"

addresses.town_location_name

string | null

Specific location name within the town. See IVMS101 Section 5.2.6.3.12.

Required string length: 1 - 35

Example:

"Westminster"

addresses.town_name

string

Name of built-up area. See IVMS101 Section 5.2.6.3.11.

Required string length: 1 - 35

Example:

"London"

Example:

[
  {
    "address_type": "GEOG",
    "country": "GB",
    "town_name": "London"
  }
]

created_at

string<date-time>

required

Timestamp when the person was created (UTC).

Example:

"2025-07-29T14:45:00"

string<uuid>

required

Unique identifier of the person record.

Example:

"d2fd3b17-1fcd-4c4f-bc0e-3b6f858a5e5d"

name_identifiers

object[]

required

List of name identifiers (e.g., legal name, aliases).

Show child attributes

name_identifiers.is_legal

boolean

Indicates if this is the legal name. See IVMS101 constraints C6/C5.

Example:

true

name_identifiers.kind

enum<string>

The nature of the name specified (legal, alias, birth, etc.). See IVMS101 Section 5.2.4.3.3.

Available options:

LEGL,

ALIA,

BIRT,

MAID,

MISC

Example:

"LEGL"

name_identifiers.primary_identifier

string

Primary identifier (surname or full name). See IVMS101 Section 5.2.4.3.1.

Required string length: 1 - 100

Example:

"Sherlock Holmes"

name_identifiers.secondary_identifier

string | null

Secondary identifier (forenames, initials). See IVMS101 Section 5.2.4.3.2.

Maximum string length: 100

Example:

"S. Holmes"

Example:

[
  {
    "is_legal": true,
    "kind": "LEGL",
    "primary_identifier": "Acme Corp"
  }
]

national_identifiers

object[]

required

National identifiers (e.g., passport, tax ID).

Show child attributes

national_identifiers.country_of_issue

string | null

ISO 3166-1 alpha-2 country code of the issuing authority. See IVMS101 constraint C3.

Example:

"GB"

national_identifiers.identifier_type

string

Specifies the type of the national identifier. See IVMS101 Section 5.2.8.3.2.

Required string length: 1 - 35

Example:

"LEIX"

national_identifiers.national_identifier

string

An identifier issued by an appropriate issuing authority. See IVMS101 Section 5.2.8.3.1.

Required string length: 1 - 35

Example:

"GB123456789"

national_identifiers.registration_authority

string | null

Registration authority code; 8-character. See IVMS101 Sections C9/C10.

Required string length: 8

Example:

"RA000001"

Example:

[
  {
    "country_of_issue": "GB",
    "identifier_type": "tax_id",
    "national_identifier": "123456789"
  }
]

person

object

required

The core person object (either natural or legal).

Option 1
Option 2

Show child attributes

person.kind

enum<string>

required

Available options:

natural

person.person

object

required

Represents a uniquely distinguishable individual; one single person with KYC-related attributes. See IVMS101 Section 5.2.2.3.

Show child attributes

person.person.country_of_residence

string | null

ISO 3166-1 alpha-2 country code of residence. See IVMS101 constraint C3 and Section 5.2.2.3.6. ISO 3166-1 alpha-2 country code

Example:

"GB"

person.person.customer_identification

string | null

A distinct identifier that uniquely identifies the person to the institution in context. See IVMS101 Section 5.2.2.3.4.

Maximum string length: 50

Example:

"HOLMES001"

person.person.date_of_birth

string<date> | null

Date of birth; must be a historic date per constraint C2. See IVMS101 Section 5.2.7.

Example:

"1854-01-06"

person.person.place_of_birth

string | null

Place of birth (town/city/subdivision/country). See IVMS101 Section 5.2.7.3.2.

Required string length: 1 - 100

Example:

"Baker Street, London"

Overview

Architecture

Integration Guide

Product Information

API Reference

Specification

Validation

Errors

Authorizations

Body

Response