Register Individual End User

Registers a new individual end user (natural person) for banking services with personal details, identification, and registration information.

Auth:Bearer <api_key>

Tags:BankingSandbox

This endpoint is only available in the Sandbox environment. It will not work in production.

Request

cURL

curl -X POST https://publicapi.sandbox.hercle.financial/api/v1/end-users/individuals \
  -H "Authorization: Bearer eyJhb..." \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

Headers

Name	Type	Required	Description
Authorization	string	Yes	Bearer API_KEY Example: `Bearer your_api_key_here`
Content-Type	string	Yes	application/json Example: `application/json`

Request Body

Schema

Field	Type	Description	Required
`person`	object	Personal details of the individual end user	Yes
`ipAddress`	string	IP address used when registering the individual end user	Yes

Person Object

Personal information of the individual end user including name, contact details, address, and identification

Field	Type	Description	Required
`firstName`	string	First name (1-100 characters)	Yes
`lastName`	string	Last name (1-100 characters)	Yes
`middleName`	string	Middle name (optional)	No
`dob`	string	Date of birth in ISO 8601 format: YYYY-MM-DD e.g. 1990-05-20	Yes
`nationality`	array	Array of nationality codes (ISO 3166-1 alpha-2, e.g., ["IT"])	Yes
`birthCountry`	string	Country of birth. ISO 3166-1 alpha-2 country code e.g. IT (optional)	No
`phone`	string	Contact phone number in E.164 format e.g. +393331234567	Yes
`email`	string	Email address	Yes
`address`	object	Residential address of the person	Yes
`identificationDocument`	object	Identification document details	Yes

Address Object

Residential address of the individual

Field	Type	Description	Required
`line1`	string	Primary address line (3-140 characters)	Yes
`line2`	string	Secondary address line (optional)	No
`city`	string	City	Yes
`state`	string	State or province (optional)	No
`postalCode`	string	Postal or ZIP code	Yes
`country`	string	Country code. ISO 3166-1 alpha-2 country code e.g. GB or US	Yes

Identification Document Object

Identity verification document information

Field	Type	Description	Required
`type`	string	Type of identification document Allowed values: `PASSPORT` `NATIONAL_ID` `DRIVERS_LICENCE` `WORK_PERMIT`	Yes
`number`	string	Identification document number	Yes

Example

{
  "person": {
    "firstName": "Mario",
    "lastName": "Rossi",
    "dob": "1990-05-20",
    "nationality": [
      "IT"
    ],
    "birthCountry": "IT",
    "phone": "+393331234567",
    "email": "mario.rossi@example.com",
    "address": {
      "line1": "Via Roma 10",
      "city": "Milano",
      "postalCode": "20100",
      "country": "IT",
      "state": "MI"
    },
    "identificationDocument": {
      "number": "AX1234567",
      "type": "PASSPORT"
    }
  },
  "ipAddress": "192.168.1.1"
}

Response

Success Response Schema

Individual end user successfully registered

Field	Type	Description
`id`	string	Unique identifier of the individual end user
`person`	object	Personal details as registered
`registrationStatus`	string	Current registration status (e.g., PENDING)
`createdAt`	number	Unix timestamp of creation (milliseconds)
`updatedAt`	number	Unix timestamp of last update (milliseconds)

Individual End User Response Object

Top-level response containing the registered individual end user details

Field	Type	Description
`id`	string	Unique identifier of the individual end user
`person`	object	Personal details as registered
`registrationStatus`	string	Current registration status (e.g., PENDING)
`createdAt`	number	Unix timestamp of creation (milliseconds)
`updatedAt`	number	Unix timestamp of last update (milliseconds)

Person Object

Personal information as registered

Field	Type	Description
`firstName`	string	First name (1-100 characters)
`lastName`	string	Last name (1-100 characters)
`middleName`	string	Middle name (optional)
`dob`	string	Date of birth in ISO 8601 format: YYYY-MM-DD e.g. 1990-05-20
`nationality`	array	Array of nationality codes (ISO 3166-1 alpha-2, e.g., ["IT"])
`birthCountry`	string	Country of birth. ISO 3166-1 alpha-2 country code e.g. IT (optional)
`phone`	string	Contact phone number in E.164 format e.g. +393331234567
`email`	string	Email address
`address`	object	Residential address of the person
`identificationDocument`	object	Identification document details

Address Object

Residential address information

Field	Type	Description
`line1`	string	Primary address line (3-140 characters)
`line2`	string	Secondary address line (optional)
`city`	string	City
`state`	string	State or province (optional)
`postalCode`	string	Postal or ZIP code
`country`	string	Country code. ISO 3166-1 alpha-2 country code e.g. GB or US

Identification Document Object

Identity verification document information

Field	Type	Description
`type`	string	Type of identification document Allowed values: `PASSPORT` `NATIONAL_ID` `DRIVERS_LICENCE` `WORK_PERMIT`
`number`	string	Identification document number

Responses

Individual end user successfully registered

200 application/json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "person": {
    "firstName": "Mario",
    "lastName": "Rossi",
    "email": "mario.rossi@example.com",
    "nationality": [
      "IT"
    ],
    "address": {
      "line1": "Via Roma 10",
      "city": "Milano",
      "country": "IT"
    },
    "identificationDocument": {
      "number": "AX1234567",
      "type": "PASSPORT"
    }
  },
  "registrationStatus": "PENDING",
  "createdAt": 1678886400000,
  "updatedAt": 1678886400000
}

API Tester

Test this endpoint directly against the sandbox environment

API Key

Get your API key from Hercle Sandbox

Request Body

Request URL

https://publicapi.sandbox.hercle.financial/api/v1/end-users/individuals