REST

POST/api/v1/end-users/businesses

Register Business End User

Registers a new business end user with complete business information, related persons (directors, UBOs), and registration details.

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/businesses \
  -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
`business`	object	Business information of the end user	Yes
`businessPersons`	array	List of related persons (e.g. directors, UBOs) for the business. At least one person is required.	Yes
`ipAddress`	string	IP address used when registering the business end user	Yes
`sector`	string	Business sector Allowed values: `OTHER_PRODUCTS_SERVICES` `BLOCKCHAIN` `LICENSED_ALCOHOL_SERVICES`	Yes

Business Object

Detailed business information including company registration and address details

Field	Type	Description	Required
`companyName`	string	Official Company Name. Can be built of multiple space separated segments. Regex: [a-zA-Z0-9\s',£€¥'':/«»"".?\-+()]+	Yes
`tradingName`	string	Trading name of the business. Can be built of multiple space separated segments. Regex: [a-zA-Z0-9\s',£€¥'':/«»"".?\-+()]+	Yes
`type`	string	Type of business entity Allowed values: `LIMITED` `PARTNERSHIP` `SOLE_TRADER`	Yes
`registrationNumber`	string	Company registration number	Yes
`registrationDate`	string	Company registration date in ISO 8601 format: YYYY-MM-DD e.g. 2020-12-31	Yes
`registeredAddress`	object	Registered address of the business	Yes
`tradingAddress`	object	Trading address of the business	Yes
`website`	string	Company website URL	No
`phone`	string	Company phone number	No

Business Address Object

Physical address information for registered and trading addresses

Field	Type	Description	Required
`line1`	string	Primary address line. Space and hyphen are allowed between the characters. Max length 50. Regex: ^[a-zA-Z0-9 .'\-/,)(⁰°#"][a-zA-Z0-9]+[a-zA-Z0-9 .'\-/,)(⁰°#"]$	Yes
`line2`	string	Secondary address line (optional). Space and hyphen are allowed between the characters. Max length 50. Regex: ^[a-zA-Z0-9 .'\-/,)(⁰°#"][a-zA-Z0-9]+[a-zA-Z0-9 .'\-/,)(⁰°#"]$	No
`city`	string	City. Space and hyphen are allowed between the characters. Max length 50. Regex: ^[a-zA-Z0-9 .'\-/,][a-zA-Z0-9]+[a-zA-Z0-9 .'\-/,]$	Yes
`state`	string	State or region. Space and hyphen are allowed between the characters. Max length 35. Regex: ^[a-zA-Z0-9 .'\-/,)(+][a-zA-Z0-9]+[a-zA-Z0-9 .'\-/,)(+]$	No
`postalCode`	string	Postal or ZIP code. The format and presence of this field may vary depending on the country. Space and hyphen are allowed between the characters. Please trim spaces at the end e.g. 67999, 30-555, SW1A 1AA	Yes
`country`	string	Country code. The two-letter code used to identify a country. ISO 3166-1 alpha-2 country code e.g. GB or US	Yes

Business Person Object

Information about individuals related to the business (directors, UBOs) with ownership details

Field	Type	Description	Required
`person`	object	Personal details of the related person	Yes
`types`	array	Roles of the person in the business e.g ["DIRECTOR", "UBO"]	Yes
`ownership`	number	Ownership percentage held by the person e.g. 50	Yes

Person Object

Personal information for individuals associated with the business

Field	Type	Description	Required
`firstName`	string	First name	Yes
`middleName`	string	Middle name	No
`lastName`	string	Last name	Yes
`dob`	string	Date of birth in ISO 8601 format: YYYY-MM-DD e.g. 2020-12-31	Yes
`birthCountry`	string	Country of birth. The two-letter code used to identify a country. ISO 3166-1 alpha-2 country code e.g. GB or US	No
`nationality`	array	Country code of nationality. Array of ISO 3166-1 alpha-2 country codes e.g. ['GB', 'US']	Yes
`email`	string	Email address	Yes
`phone`	string	Contact phone number	No
`address`	object	Residential address of the person	Yes
`identificationDocument`	object	Identification document details	Yes

Identification Document Object

Identity verification document information

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

Example

{
  "business": {
    "companyName": "Example Corp Ltd",
    "tradingName": "Example Trading",
    "type": "LIMITED",
    "registrationNumber": "12345678",
    "registrationDate": "2020-01-15",
    "registeredAddress": {
      "line1": "123 Business Street",
      "line2": "Suite 100",
      "city": "London",
      "state": "England",
      "postalCode": "SW1A 1AA",
      "country": "GB"
    },
    "tradingAddress": {
      "line1": "456 Trading Avenue",
      "line2": "Floor 5",
      "city": "London",
      "state": "England",
      "postalCode": "SW1A 2BB",
      "country": "GB"
    },
    "website": "https://example.com",
    "phone": "+441234567890"
  },
  "businessPersons": [
    {
      "person": {
        "firstName": "John",
        "middleName": "William",
        "lastName": "Doe",
        "dob": "1985-03-20",
        "birthCountry": "GB",
        "nationality": [
          "GB"
        ],
        "email": "john.doe@example.com",
        "phone": "+441234567891",
        "address": {
          "line1": "789 Residential Road",
          "line2": "Apt 10",
          "city": "London",
          "state": "England",
          "postalCode": "SW1A 3CC",
          "country": "GB"
        },
        "identificationDocument": {
          "type": "PASSPORT",
          "number": "AB123456C"
        }
      },
      "types": [
        "DIRECTOR",
        "UBO"
      ],
      "ownership": 75
    }
  ],
  "ipAddress": "192.168.1.100",
  "sector": "OTHER_PRODUCTS_SERVICES"
}

Response

Success Response Schema

Business end user successfully registered

Field	Type	Description
`id`	string	Unique identifier of the business end user
`business`	object	Complete business information as registered
`businessPersons`	array	Array of business persons with full details
`ipAddress`	string	IP address used during registration
`registrationStatus`	string	Current registration status (e.g., CREATED)
`sector`	string	Business sector
`createdAt`	number	Unix timestamp of creation (milliseconds)
`updatedAt`	number	Unix timestamp of last update (milliseconds)

Business End User Response Object

Top-level response containing the registered business end user details

Field	Type	Description
`id`	string	Unique identifier of the business end user
`business`	object	Complete business information as registered
`businessPersons`	array	Array of business persons with full details
`ipAddress`	string	IP address used during registration
`registrationStatus`	string	Current registration status (e.g., CREATED)
`sector`	string	Business sector
`createdAt`	number	Unix timestamp of creation (milliseconds)
`updatedAt`	number	Unix timestamp of last update (milliseconds)

Business Object

Detailed business information including company registration and address details

Field	Type	Description
`id`	string	Unique identifier of the business
`companyName`	string	Official Company Name. Can be built of multiple space separated segments. Regex: [a-zA-Z0-9\s',£€¥'':/«»"".?\-+()]+
`tradingName`	string	Trading name of the business. Can be built of multiple space separated segments. Regex: [a-zA-Z0-9\s',£€¥'':/«»"".?\-+()]+
`type`	string	Type of business entity Allowed values: `LIMITED` `PARTNERSHIP` `SOLE_TRADER`
`registrationNumber`	string	Company registration number
`registrationDate`	string	Company registration date in ISO 8601 format: YYYY-MM-DD e.g. 2020-12-31
`registeredAddress`	object	Registered address of the business
`tradingAddress`	object	Trading address of the business
`website`	string	Company website URL
`phone`	string	Company phone number

Business Address Object

Physical address information for registered and trading addresses

Field	Type	Description
`line1`	string	Primary address line. Space and hyphen are allowed between the characters. Max length 50. Regex: ^[a-zA-Z0-9 .'\-/,)(⁰°#"][a-zA-Z0-9]+[a-zA-Z0-9 .'\-/,)(⁰°#"]$
`line2`	string	Secondary address line (optional). Space and hyphen are allowed between the characters. Max length 50. Regex: ^[a-zA-Z0-9 .'\-/,)(⁰°#"][a-zA-Z0-9]+[a-zA-Z0-9 .'\-/,)(⁰°#"]$
`city`	string	City. Space and hyphen are allowed between the characters. Max length 50. Regex: ^[a-zA-Z0-9 .'\-/,][a-zA-Z0-9]+[a-zA-Z0-9 .'\-/,]$
`state`	string	State or region. Space and hyphen are allowed between the characters. Max length 35. Regex: ^[a-zA-Z0-9 .'\-/,)(+][a-zA-Z0-9]+[a-zA-Z0-9 .'\-/,)(+]$
`postalCode`	string	Postal or ZIP code. The format and presence of this field may vary depending on the country. Space and hyphen are allowed between the characters. Please trim spaces at the end e.g. 67999, 30-555, SW1A 1AA
`country`	string	Country code. The two-letter code used to identify a country. ISO 3166-1 alpha-2 country code e.g. GB or US

Business Person Object

Information about individuals related to the business (directors, UBOs) with ownership details

Field	Type	Description
`id`	string	Unique identifier of the business person
`businessEndUserId`	string	ID of the business end user this person is associated with
`person`	object	Personal details of the related person
`types`	array	Roles of the person in the business e.g ["DIRECTOR", "UBO"]
`ownership`	number	Ownership percentage held by the person e.g. 75
`createdAt`	number	Unix timestamp of creation (milliseconds)
`updatedAt`	number	Unix timestamp of last update (milliseconds)

Person Object

Personal information for individuals associated with the business

Field	Type	Description
`firstName`	string	First name
`middleName`	string	Middle name
`lastName`	string	Last name
`dob`	string	Date of birth in ISO 8601 format: YYYY-MM-DD e.g. 2020-12-31
`birthCountry`	string	Country of birth. The two-letter code used to identify a country. ISO 3166-1 alpha-2 country code e.g. GB or US
`nationality`	array	Country code of nationality. Array of ISO 3166-1 alpha-2 country codes e.g. ['GB', 'US']
`email`	string	Email address
`phone`	string	Contact phone number
`address`	object	Residential address of the person
`identificationDocument`	object	Identification document details

Identification Document Object

Identity verification document information

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

Responses

Business end user successfully registered

201 application/json

{
  "id": "eus_abc123xyz456",
  "business": {
    "id": "bus_xyz789abc",
    "companyName": "Example Corp Ltd",
    "tradingName": "Example Trading",
    "type": "LIMITED",
    "registrationNumber": "12345678",
    "registrationDate": "2020-01-15",
    "registeredAddress": {
      "line1": "123 Business Street",
      "line2": "Suite 100",
      "city": "London",
      "state": "England",
      "postalCode": "SW1A 1AA",
      "country": "GB"
    },
    "tradingAddress": {
      "line1": "456 Trading Avenue",
      "line2": "Floor 5",
      "city": "London",
      "state": "England",
      "postalCode": "SW1A 2BB",
      "country": "GB"
    },
    "website": "https://example.com",
    "phone": "+441234567890"
  },
  "businessPersons": [
    {
      "id": "bp_xyz789abc123",
      "businessEndUserId": "eus_abc123xyz456",
      "person": {
        "firstName": "John",
        "middleName": "William",
        "lastName": "Doe",
        "dob": "1985-03-20",
        "birthCountry": "GB",
        "nationality": [
          "GB"
        ],
        "email": "john.doe@example.com",
        "phone": "+441234567891",
        "address": {
          "line1": "789 Residential Road",
          "line2": "Apt 10",
          "city": "London",
          "state": "England",
          "postalCode": "SW1A 3CC",
          "country": "GB"
        },
        "identificationDocument": {
          "type": "PASSPORT",
          "number": "AB123456C"
        }
      },
      "types": [
        "DIRECTOR",
        "UBO"
      ],
      "ownership": 75,
      "createdAt": 1704067200000,
      "updatedAt": 1704067200000
    }
  ],
  "ipAddress": "192.168.1.100",
  "registrationStatus": "CREATED",
  "sector": "OTHER_PRODUCTS_SERVICES",
  "createdAt": 1704067200000,
  "updatedAt": 1704067200000
}

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/businesses