Get Business End Users Paginated

Returns a paginated list of business end users 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 -G https://publicapi.sandbox.hercle.financial/api/v1/end-users/businesses?pageSize={pageSize} \
  -H "Authorization: Bearer eyJhb..." \

Query Parameters

Name	Type	Required	Description
pageSize	number	Yes	Number of items per page (must be between 5 and 50) Example: `10`
from	string	No	Start date in ISO 8601 format (e.g., 2024-01-01T00:00:00Z) Example: `2025-12-01T00:00:00Z`
to	string	No	End date in ISO 8601 format (e.g., 2024-12-31T23:59:59Z) Example: `2025-12-30T23:59:59Z`
paginationToken	string	No	Token for fetching the next page of results

Headers

Name	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Response

Success Response Schema

Business end users retrieved successfully

Field	Type	Description
`payload`	array	Array of business end user objects
`paginationToken`	string	Token for retrieving the next page of results

Payload Business End User Object

Field	Type	Description
`id`	string	Unique identifier of the business end user
`business`	object	Complete business information (see Business Object)
`businessPersons`	array	Array of related persons - directors, UBOs (see Business Person Object)
`ipAddress`	string	IP address used during registration
`registrationStatus`	string	Current status (e.g., ACTIVE, PENDING, REJECTED)
`sector`	string	Business sector (e.g., OTHER_PRODUCTS_SERVICES)
`createdAt`	number	Unix timestamp of creation (milliseconds)
`updatedAt`	number	Unix timestamp of last update (milliseconds)

Business Object

Field	Type	Description
`id`	string	Unique identifier of the business
`companyName`	string	Official company name
`tradingName`	string	Trading name of the business
`type`	string	Type of business entity (e.g., LIMITED, PARTNERSHIP, SOLE_TRADER)
`registrationNumber`	string	Company registration number
`registrationDate`	string	Company registration date (YYYY-MM-DD)
`registeredAddress`	object	Registered business address (see Address Object)
`tradingAddress`	object	Trading business address (see Address Object, can be null)
`website`	string	Company website URL
`phone`	string	Company phone number

Address Object

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

Business Person Object

Field	Type	Description
`id`	string	Business person ID
`businessEndUserId`	string	Associated business end user ID
`person`	object	Personal details of the related person (see Person Object)
`types`	array	Roles in business (e.g., ["DIRECTOR", "UBO"])
`ownership`	number	Ownership percentage (e.g., 75, 50.5)
`createdAt`	number	Unix timestamp of creation (milliseconds)
`updatedAt`	number	Unix timestamp of last update (milliseconds)

Person Object

Field	Type	Description
`firstName`	string	First name
`middleName`	string	Middle name
`lastName`	string	Last name
`email`	string	Email address
`phone`	string	Contact phone number
`dob`	string	Date of birth (YYYY-MM-DD)
`birthCountry`	string	Country of birth (ISO 3166-1 alpha-2)
`nationality`	array	Array of nationality codes (ISO 3166-1 alpha-2, e.g., ["GB", "US"])
`address`	object	Residential address (see Address Object)
`identificationDocument`	object	Identification document details (see Identification Document Object)

Identification Document Object

Field	Type	Description
`type`	string	Document type (e.g., PASSPORT, DRIVING_LICENSE, ID_CARD)
`number`	string	Document number

Responses

Business end users retrieved successfully

200 application/json

{
  "payload": [
    {
      "id": "eus_abc123def456ghi789",
      "business": {
        "id": "bus_xyz123abc456",
        "companyName": "Acme Corporation Ltd",
        "tradingName": "Acme Trading Co",
        "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 Trade Avenue",
          "line2": "Floor 5",
          "city": "London",
          "state": "England",
          "postalCode": "EC1A 1BB",
          "country": "GB"
        },
        "website": "https://acmecorp.com",
        "phone": "+442071234567"
      },
      "businessPersons": [
        {
          "id": "bp_xyz789abc123def456",
          "businessEndUserId": "eus_abc123def456ghi789",
          "person": {
            "firstName": "John",
            "middleName": "William",
            "lastName": "Smith",
            "email": "john.smith@acmecorp.com",
            "phone": "+447700900123",
            "dob": "1980-05-20",
            "birthCountry": "GB",
            "nationality": [
              "GB"
            ],
            "address": {
              "line1": "789 Residential Road",
              "line2": "Apt 10",
              "city": "London",
              "state": "England",
              "postalCode": "W1A 1AA",
              "country": "GB"
            },
            "identificationDocument": {
              "type": "PASSPORT",
              "number": "AB123456C"
            }
          },
          "types": [
            "DIRECTOR",
            "UBO"
          ],
          "ownership": 75,
          "createdAt": 1699963800000,
          "updatedAt": 1699963800000
        }
      ],
      "ipAddress": "192.168.1.100",
      "registrationStatus": "CREATED",
      "sector": "OTHER_PRODUCTS_SERVICES",
      "createdAt": 1699963800000,
      "updatedAt": 1699963800000
    }
  ],
  "paginationToken": ""
}

API Tester

Test this endpoint directly against the sandbox environment

API Key

Get your API key from Hercle Sandbox

Query Parameters

pageSize

Required

Number of items per page (must be between 5 and 50)

from

Start date in ISO 8601 format (e.g., 2024-01-01T00:00:00Z)

End date in ISO 8601 format (e.g., 2024-12-31T23:59:59Z)

paginationToken

Token for fetching the next page of results

Request URL

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