GBP Onboarding - API
Learn how to onboard individual and business customers to GBP via the Lorum API.
GBP onboarding does not require any currency_extra fields. All required information is taken from the existing customer record stored in Lorum.
Both individual and business onboarding are processed synchronously. Once the onboarding has been completed successfully, a webhook event is dispatched to notify your integration.
Before You Start
GBP onboarding requires the customer to have at least two address lines populated. Each address line must be 35 characters or fewer.
Before triggering onboarding, ensure the customer record contains at least two valid address lines that comply with the character limit.
Individual Customer
If the customer is approved in Lorum, call the onboarding endpoint directly via Onboard Customer:
POST /v1/customers/{customer_id}/onboarding/gbp
🛑 Error Codes
| Code | Cause | Fix |
|---|---|---|
invalid_customer_address | address.line_2 is missing, or line_1/line_2 contains invalid characters or exceeds 35 chars, see Validation Rules | Add/fix address fields and retry |
invalid_customer_name | display_name, first_name, or last_name contains invalid characters or exceeds 35 chars, see Validation Rules | Update name fields and retry |
Business Customer
Before GBP onboarding can be triggered, at least one shareholder must be linked to the business. The shareholder must exist in Lorum as an approved Individual Customer, but does not need to be onboarded to GBP. They simply need to be linked to the business as a shareholder.
Shareholder validation
During onboarding, Lorum selects the shareholder with the highest holding_percentage and validates their first_name and last_name against the applicable validation rules.
There is no minimum holding percentage threshold - any positive holding_percentage qualifies.
Add a shareholder
If a customer is approved, a shareholder can be added via the Add Shareholder
POST /v2/customers/businesses/{business_id}/shareholders
Already onboarded to USD or EUR?
If the business has already been onboarded to USD or EUR, its UBOs will already exist as linked shareholders. In that case, you can skip this step and trigger GBP onboarding directly.
Trigger Onboarding
Initiate onboarding via Onboard Customer:
POST /v1/customers/{customer_id}/onboarding/gbp
🛑 Error Codes
| Code | Cause | Fix |
|---|---|---|
no_shareholders | No shareholders on the business record | Add at least one shareholder and retry |
invalid_customer_address | address.line_2 is missing, or line_1/line_2 contains invalid characters or exceeds 35 chars, see Validation Rules | Add/fix address fields and retry |
invalid_customer_name | display_name or business_name contains invalid characters or exceeds 35 chars, see Validation Rules | Update business name and retry |
invalid_shareholder_name | Top shareholder's first_name or last_name contains invalid characters or exceeds 35 chars, see Validation Rules | Update shareholder name and retry |
Confirming Status (Both Customer Types)
Onboarding completes immediately. You can also confirm the status using the Get Customer Onboarding Status endpoint.
GET /v1/customers/{customer_id}/onboarding/gbp:
{
"customer_id": "...",
"currency": "GBP",
"status": "completed"
}
Once onboarding is confirmed, a GBP account can be created via the API.
Updated 24 days ago