curl --request POST \
  --url https://api.faraday.range.org/v1/persons \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_numbers": [
    {
      "account_number": "0x10ADD26fb2D17dA265e0567B8F56cb4687979fbE"
    }
  ],
  "addresses": [
    {
      "address_type": "HOME",
      "country": "CH",
      "street_name": "Reichenbach Falls",
      "town_name": "Meiringen"
    }
  ],
  "kind": "natural",
  "name_identifiers": [
    {
      "primary_identifier": "James Moriarty",
      "type": "LEGL"
    }
  ],
  "national_identifiers": [
    {
      "country": "CH",
      "identifier_type": "RAID",
      "national_identifier": "987654321"
    }
  ],
  "person": {
    "country_of_residence": "CH",
    "customer_identification": "MORIARTY-001",
    "date_of_birth": "1985-02-10",
    "place_of_birth": "Bern"
  }
}
'

{
  "account_numbers": [
    {
      "account_number": "GB29NWBK60161331926819"
    }
  ],
  "addresses": [
    {
      "address_type": "GEOG",
      "country": "GB",
      "town_name": "London"
    }
  ],
  "created_at": "2025-07-29T14:45:00",
  "id": "d2fd3b17-1fcd-4c4f-bc0e-3b6f858a5e5d",
  "name_identifiers": [
    {
      "is_legal": true,
      "kind": "LEGL",
      "primary_identifier": "Acme Corp"
    }
  ],
  "national_identifiers": [
    {
      "country_of_issue": "GB",
      "identifier_type": "tax_id",
      "national_identifier": "123456789"
    }
  ],
  "person": {
    "kind": "natural",
    "person": {
      "country_of_residence": "GB",
      "customer_identification": "HOLMES001",
      "date_of_birth": "1854-01-06",
      "place_of_birth": "Baker Street, London"
    }
  }
}

Persons

Create a person

Creates a new IVMS101-compliant person entity.

The payload must be either a natural or legal person structure, and must include:

Person core information
Name identifiers
National identifiers
Account numbers
Addresses

On success this endpoint returns the full assembled PersonRecord.

Specification

See the IVMS101 standard for full field definitions and compliance details.

Validation

If the input fails schema or custom validation, returns 422.

Errors

Any database or internal failure results in a 500 error.

POST

/

v1

/

persons

curl --request POST \
  --url https://api.faraday.range.org/v1/persons \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_numbers": [
    {
      "account_number": "0x10ADD26fb2D17dA265e0567B8F56cb4687979fbE"
    }
  ],
  "addresses": [
    {
      "address_type": "HOME",
      "country": "CH",
      "street_name": "Reichenbach Falls",
      "town_name": "Meiringen"
    }
  ],
  "kind": "natural",
  "name_identifiers": [
    {
      "primary_identifier": "James Moriarty",
      "type": "LEGL"
    }
  ],
  "national_identifiers": [
    {
      "country": "CH",
      "identifier_type": "RAID",
      "national_identifier": "987654321"
    }
  ],
  "person": {
    "country_of_residence": "CH",
    "customer_identification": "MORIARTY-001",
    "date_of_birth": "1985-02-10",
    "place_of_birth": "Bern"
  }
}
'

{
  "account_numbers": [
    {
      "account_number": "GB29NWBK60161331926819"
    }
  ],
  "addresses": [
    {
      "address_type": "GEOG",
      "country": "GB",
      "town_name": "London"
    }
  ],
  "created_at": "2025-07-29T14:45:00",
  "id": "d2fd3b17-1fcd-4c4f-bc0e-3b6f858a5e5d",
  "name_identifiers": [
    {
      "is_legal": true,
      "kind": "LEGL",
      "primary_identifier": "Acme Corp"
    }
  ],
  "national_identifiers": [
    {
      "country_of_issue": "GB",
      "identifier_type": "tax_id",
      "national_identifier": "123456789"
    }
  ],
  "person": {
    "kind": "natural",
    "person": {
      "country_of_residence": "GB",
      "customer_identification": "HOLMES001",
      "date_of_birth": "1854-01-06",
      "place_of_birth": "Baker Street, London"
    }
  }
}

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

addresses

object[]

Physical or mailing addresses

Show child attributes

name_identifiers

object[]

Official or alias names associated with this person

Show child attributes

national_identifiers

object[]

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

Show child attributes

person

object

Core details about the natural person

Show child attributes

Response

Created

Person was created successfully.

account_numbers

object[]

required

Account numbers (bank or wallet identifiers).

Show child attributes

Example:

[
  {
    "account_number": "GB29NWBK60161331926819"
  }
]

addresses

object[]

required

Registered or physical addresses.

Show child attributes

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"

id

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

Example:

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

national_identifiers

object[]

required

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

Show child attributes

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

Last modified on February 9, 2026

List persons Get a person by blockchain address