Request sub-account

Requests a new sub-account under the declared parent client, with one default virtual IBAN named by friendlyName and purpose. The request is validated and recorded, then handed to onboarding, which creates the sub-account, reviews it and allocates the IBAN; the response is 202 with the request resource, whose status moves from Pending through Accepted to Active, Rejected or Failed. Follow it with GET /sub-account-requests/{id} or the sub-account-request webhook events. The parent must be a primary client in Client status. A legal entityType requires legalName, jurisdictionOfIncorporationCountryCode and gicsCode; Individual requires givenName, familyName and dateOfBirth. Onboarding rejects a request that matches an existing sub-account of the same parent, in any status: for an individual the same givenName, familyName and dateOfBirth, for a legal entity the same legalName, country and city. The match ignores case and leading or trailing spaces. Retries with the same idempotencyKey and the same details return 200 with the original request. 409 is returned for a key reused with different details, or a byte-identical resubmission under a new key.

Body Params
string
required
length ≥ 1

Required; the parent client, which must be a primary client this credential may act for

string
enum
required

Required; one of LimitedCompany, PublicLimitedCompany, SoleTrader, Charity, LimitedPartnership, LimitedLiabilityPartnership, Trust, Partnership, LimitedLiabilityCompany, OtherLegalEntity, Individual. A legal type uses the legal entity fields, Individual the personal ones

string
required
length between 0 and 200

Legal entities only; the registered name

string
required
length between 2 and 2

Legal entities only; ISO 3166-1 alpha-2

int32
required
> 0

Legal entities only; the GICS sub-industry code

string | null
date | null
tradingNames
array of strings
required

Legal entities only; optional trading names

tradingNames*
string
required
length between 0 and 100

Individuals only

string
required
length between 0 and 100

Individuals only

boolean

Individuals only; whether the family name is written first (default false)

date
required

Individuals only; required

string | null

Individuals only; ISO 3166-1 alpha-2

citizenshipCountryCodes
array of strings | null

Individuals only; ISO 3166-1 alpha-2 codes

citizenshipCountryCodes
string
required
length between 0 and 400

Required; the registered or residential address

string
required
length between 0 and 400

Required; payments from the sub-account carry it as the payer's street

string
required
length between 0 and 200
string | null
string | null

Optional; at most 30 characters

string
required
length between 2 and 2

Required; ISO 3166-1 alpha-2

string | null

Name for the default virtual IBAN; at most 100 characters

string | null

Why the sub-account needs the account; shown to the onboarding team; at most 4000 characters

transactionActivitySubTypes
array of int32s | null

Optional; the transaction activity sub-type codes for the default virtual IBAN, from GET /reference/transaction-activity-sub-types; no duplicates

transactionActivitySubTypes
string
required
length between 0 and 100

Caller-generated key that makes the request retry-safe; at most 100 characters. Retrying with the same key and the same details returns 200 with the original request. Reusing a key with different details is rejected with 409 whose body carries existingRequestId

Headers
string
required

Fresh RFC 9449 proof JWT (ES256) signed with the client's DPoP key, binding this request's method and URL to the access token; generate a new proof per request

string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

Language
Credentials
OAuth2
URL
LoadingLoading…
Response
Choose an example:
application/json
application/problem+json