Hercle
REST
PUT/api/v1/end-users/businesses/{id}

Update Business End User

Updates an existing business end user with complete business information, related persons (directors, UBOs), and registration details.

Auth:Bearer <api_key>
Tags:Banking

Request

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

Path Parameters

NameTypeRequiredDescription
idstringYesIdentifier of the business end user, as returned by GET in id (a UUID); the providerEndUserId value returned by GET (eus_...) is also accepted
Example: 3f2b8c1e-7a4d-4e9b-9c61-2d5f8a0b7e43

Headers

NameTypeRequiredDescription
AuthorizationstringYesBearer API_KEY
Example: Bearer your_api_key_here
Content-TypestringYesapplication/json
Example: application/json

Request Body

Schema

FieldTypeDescriptionRequired
businessobjectBusiness information of the end userYes
businessPersonsarrayList of related persons (e.g. directors, UBOs) for the business. At least one person is required.Yes
ipAddressstringIPv4 address of the business end user: 7-15 characters, digits and dots only e.g. 192.168.1.100Yes
sectorstring
Business sector
Allowed values:
OTHER_PRODUCTS_SERVICES
BLOCKCHAIN
LICENSED_ALCOHOL_SERVICES
Yes

Business Object

Detailed business information including company registration and address details

FieldTypeDescriptionRequired
companyNamestringOfficial Company Name (3-140 characters). Can be built of multiple space separated segments. Regex: [a-zA-Z0-9\s',£€¥'':/«»"".?\-+()]+Yes
tradingNamestringTrading name of the business (3-140 characters). Can be built of multiple space separated segments. Regex: [a-zA-Z0-9\s',£€¥'':/«»"".?\-+()]+Yes
typestring
Type of business entity
Allowed values:
LIMITED
PARTNERSHIP
SOLE_TRADER
Yes
registrationNumberstringCompany registration number (3-140 characters)Yes
registrationDatestringCompany registration date in ISO 8601 format: YYYY-MM-DD e.g. 2020-12-31Yes
registeredAddressobjectRegistered address of the businessYes
tradingAddressobjectTrading address of the businessYes
websitestringCompany website URLNo
phonestringCompany phone numberNo

Business Address Object

Physical address information for registered and trading addresses

FieldTypeDescriptionRequired
line1stringPrimary address line (3-140 characters)Yes
line2stringSecondary address line (optional, 3-140 characters)No
citystringCity (3-140 characters)Yes
statestringState or region (optional, 2-140 characters)No
postalCodestringPostal or ZIP code (3-140 characters) e.g. 67999, 30-555, SW1A 1AAYes
countrystringCountry code. The two-letter code used to identify a country. ISO 3166-1 alpha-2 country code e.g. GB or USYes

Business Person Object

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

FieldTypeDescriptionRequired
personobjectPersonal details of the related personYes
typesarrayRoles of the person in the business e.g ["DIRECTOR", "UBO"]Yes
ownershipnumberOwnership percentage held by the person, between 0.01 and 100 e.g. 50Yes

Person Object

Personal information for individuals associated with the business

FieldTypeDescriptionRequired
firstNamestringFirst name (2-140 characters)Yes
middleNamestringMiddle name (optional, 2-140 characters)No
lastNamestringLast name (2-140 characters)Yes
dobstringDate of birth in ISO 8601 format: YYYY-MM-DD e.g. 2020-12-31Yes
birthCountrystringCountry of birth. The two-letter code used to identify a country. ISO 3166-1 alpha-2 country code e.g. GB or USNo
nationalityarrayCountry code of nationality. Array of ISO 3166-1 alpha-2 country codes e.g. ['GB', 'US']Yes
emailstringEmail address (5-255 characters)Yes
phonestringContact phone numberNo
addressobjectResidential address of the personYes
identificationDocumentobjectIdentification document details (optional)No

Identification Document Object

Identity verification document information

FieldTypeDescriptionRequired
typestring
Type of identification document
Allowed values:
PASSPORT
DRIVERS_LICENCE
NATIONAL_ID
WORK_PERMIT
Yes
numberstringIdentification document numberYes

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

FieldTypeDescription
idstringUnique identifier of the business end user (a UUID; end users migrated from earlier records keep their eus_... reference as id)
providerEndUserIdstring | nullBanking provider reference of the end user. Always null in this response; read it with GET /api/v1/end-users/businesses
businessobjectComplete business information as registered
businessPersonsarrayArray of business persons with full details
ipAddressstringAlways an empty string: the IP address is not stored for business end users
registrationStatusstringCurrent registration status (e.g., CREATED)
sectorstringBusiness sector
createdAtnumberUnix timestamp of creation (milliseconds)
updatedAtnumberUnix timestamp of last update (milliseconds); 0 if never updated

Business End User Response Object

Top-level response containing the updated business end user details

FieldTypeDescription
idstringUnique identifier of the business end user (a UUID; end users migrated from earlier records keep their eus_... reference as id)
providerEndUserIdstring | nullBanking provider reference of the end user. Always null in this response; read it with GET /api/v1/end-users/businesses
businessobjectComplete business information as registered
businessPersonsarrayArray of business persons with full details
ipAddressstringAlways an empty string: the IP address is not stored for business end users
registrationStatusstringCurrent registration status (e.g., CREATED)
sectorstringBusiness sector
createdAtnumberUnix timestamp of creation (milliseconds)
updatedAtnumberUnix timestamp of last update (milliseconds); 0 if never updated

Business Object

Detailed business information including company registration and address details

FieldTypeDescription
idstringUnique identifier of the business
companyNamestringOfficial Company Name. Can be built of multiple space separated segments. Regex: [a-zA-Z0-9\s',£€¥'':/«»"".?\-+()]+
tradingNamestringTrading name of the business. Can be built of multiple space separated segments. Regex: [a-zA-Z0-9\s',£€¥'':/«»"".?\-+()]+
typestring
Type of business entity
Allowed values:
LIMITED
PARTNERSHIP
SOLE_TRADER
registrationNumberstringCompany registration number
registrationDatestringCompany registration date in ISO 8601 format: YYYY-MM-DD e.g. 2020-12-31
registeredAddressobjectRegistered address of the business
tradingAddressobjectTrading address of the business
websitestringCompany website URL
phonestringCompany phone number

Business Address Object

Physical address information for registered and trading addresses

FieldTypeDescription
line1stringPrimary address line (3-140 characters)
line2stringSecondary address line (optional, 3-140 characters)
citystringCity (3-140 characters)
statestringState or region (optional, 2-140 characters)
postalCodestringPostal or ZIP code (3-140 characters) e.g. 67999, 30-555, SW1A 1AA
countrystringCountry 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

FieldTypeDescription
idstringUnique identifier of the business person
businessEndUserIdstringID of the business end user this person is associated with
personobjectPersonal details of the related person
typesarrayRoles of the person in the business e.g ["DIRECTOR", "UBO"]
ownershipnumberOwnership percentage held by the person e.g. 75. Stored with single precision, so a value such as 33.33 can come back as 33.33000183105469; round it on your side
createdAtnumberUnix timestamp of creation (milliseconds). Same value as the end user's createdAt
updatedAtnumberUnix timestamp of last update (milliseconds). Same value as the end user's updatedAt

Person Object

Personal information for individuals associated with the business

FieldTypeDescription
firstNamestringFirst name (2-140 characters)
middleNamestringMiddle name (optional, 2-140 characters)
lastNamestringLast name (2-140 characters)
dobstringDate of birth in ISO 8601 format: YYYY-MM-DD e.g. 2020-12-31
birthCountrystringCountry of birth. The two-letter code used to identify a country. ISO 3166-1 alpha-2 country code e.g. GB or US
nationalityarrayCountry code of nationality. Array of ISO 3166-1 alpha-2 country codes e.g. ['GB', 'US']
emailstringEmail address (5-255 characters)
phonestringContact phone number
addressobjectResidential address of the person
identificationDocumentobject | nullIdentification document details, or null when not provided

Identification Document Object

Identity verification document information

FieldTypeDescription
typestring
Type of identification document
Allowed values:
PASSPORT
DRIVERS_LICENCE
NATIONAL_ID
WORK_PERMIT
numberstringIdentification document number

Responses

Business end user successfully updated

200 application/json
{
  "id": "3f2b8c1e-7a4d-4e9b-9c61-2d5f8a0b7e43",
  "providerEndUserId": null,
  "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": "3f2b8c1e-7a4d-4e9b-9c61-2d5f8a0b7e43",
      "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": "",
  "registrationStatus": "CREATED",
  "sector": "OTHER_PRODUCTS_SERVICES",
  "createdAt": 1704067200000,
  "updatedAt": 1704067200000
}

API Tester

Test this endpoint directly against the sandbox environment

Get your API key from Hercle Sandbox

Identifier of the business end user, as returned by GET in id (a UUID); the providerEndUserId value returned by GET (eus_...) is also accepted

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