Put business people

PUT/v1/activation/business-people

Idempotency-Key requiredAccepts bearer

Submit the business's representative and owners — part of business_verification

Replaces the whole record (BusinessPeople) and sets submittedAt.Show more

Replaces the whole record (BusinessPeople) and sets submittedAt. On the CAPPED flow business_verification is done only when the registration is confirmed (or the hosted KYB documents are approved), the signatory matched (POST /v1/activation/signatory-checks) and this record is submitted with representative set and owners non-empty or noOwnerAt25Percent true. owners holds at most 10 natural persons, each with sharePercent 25 to 100, together at most 100 (400 VALIDATION details.field owners); noOwnerAt25Percent true with owners non-empty is 400 VALIDATION details.field noOwnerAt25Percent. idNumberLast4 is the last four characters only (UK National Insurance, US SSN, UAE Emirates ID, Canadian SIN where asked); a longer value is 400 VALIDATION details.field representative.idNumberLast4 and is never stored; India leaves it absent (the PAN already checked stands for it). The date of birth and home address are personal data: kept for the KYB record only, never logged, and audited without their values (activation.business_people_submitted). Once the tenant is LIVE the record is changed by operations: 409 CONFLICT details.reason REGISTRATION_LOCKED. On the NINE_STEP flow 409 CONFLICT details.reason FLOW_NOT_CAPPED (the hosted KYB collects them there). Human session only; Owner only. Idempotency-Key required. this PUT is "Submit for verification". The pre-checks come first: where the country has a register (IN, GB, AE, US, CA) the registration must be confirmed (409 CONFLICT REGISTRATION_NOT_CONFIRMED) and the signatory matched (409 CONFLICT SIGNATORY_NOT_MATCHED), and nothing is stored or sent while either is open. business_verification turns done ONLY when the provider's verdict is verified; meanwhile ActivationState.businessVerification reads in_progress, in_review, needs_more (with the outstanding requirements) or rejected. After needs_more the Owner fixes the listed fields and PUTs the whole record again, which resumes the case. While the case is in_review a PUT is 409 CONFLICT VERIFICATION_IN_REVIEW, once verified 409 CONFLICT ALREADY_VERIFIED, once rejected 409 CONFLICT VERIFICATION_REJECTED (contact support); nothing changes. representative.idNumber (write-only) carries the full identity number only when the provider asks for it (requirement representative.id_number): it is sent to the provider and never stored, logged, audited or answered; idNumberLast4 is then set from it. Each owner may likewise carry dateOfBirth, address and a write-only idNumber when the provider asks for them (requirement fields owners[i].dateOfBirth, owners[i].address, owners[i].idNumber; none is needed at the first submission); an owner's idNumber is forwarded the same way and only its last four characters are kept (owners[i].idNumberLast4, read-only). No provider routed for the country is 501 NOT_IMPLEMENTED KYB_UNAVAILABLE (details.country); a provider that cannot be reached is 502 UPSTREAM_UNAVAILABLE (retryable; the record is kept, the case is not opened; PUT again). The verdict arrives by the provider's signed callback or the periodic reconcile, never by this call; the console re-reads GET /v1/activation.

Headers

Idempotency-KeystringRequired
Mandatory on mutations: **48h TTL**; replay with same body-hash returns the original response with Idempotency-Replayed true; same key + different body is 409 IDEMPOTENCY_CONFLICT; in-flight duplicate…Show more
Mandatory on mutations: **48h TTL**; replay with same body-hash returns the original response with Idempotency-Replayed true; same key + different body is 409 IDEMPOTENCY_CONFLICT; in-flight duplicate is 409 IDEMPOTENCY_IN_PROGRESS.

Request bodyBusinessPeople

representativeone of 2Required
ownersarray of BusinessOwnerRequired
6 child attributes
- fullNamestringRequired
- sharePercentintegerRequired
- dateOfBirthstring · dateOptional
- addressBusinessAddressOptional
  A business address as the GST register states it
  5 child attributes
  - line1stringRequired
  - citystringRequired
  - regionstringRequired
    State or region
  - postalCodestringRequired
  - countrystringRequired
    ISO 3166-1 alpha-2
- idNumberstringOptional
  The owner's full identity number (US SSN, UK National Insurance number, Canadian SIN, UAE Emirates ID), sent only when the provider asks for it (requirement field owners[i].idNumber).Show more
  The owner's full identity number (US SSN, UK National Insurance number, Canadian SIN, UAE Emirates ID), sent only when the provider asks for it (requirement field owners[i].idNumber). Write-only: forwarded to the provider and never stored, logged, audited or answered.
- idNumberLast4stringOptional
  The last four characters of the idNumber last sent, set by the server; ignored on PUT
noOwnerAt25PercentbooleanRequired
True when no natural person owns 25 percent or more; owners must then be empty
submittedAtstring · date-timeOptional
When the record was last submitted; null until then

Responses

200The record as storedBusinessPeople
400VALIDATION — owners over the limits (details.field owners), noOwnerAt25Percent with owners, or more than the last four characters of an identity numberApiErrorResponse
401
UNAUTHENTICATED — missing or expired token.Show more
UNAUTHENTICATED — missing or expired token. Declared on every operation because `security` is declared globally at the document root: every route is authenticated, so every route can answer 401.
ApiErrorResponse
403ApiErrorResponse
405
VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show more
VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
ApiErrorResponse
409ApiErrorResponse
413
VALIDATION — the request body is larger than the surface's limit.Show more
VALIDATION — the request body is larger than the surface's limit. Not retryable as sent: shrink the body. Declared on every operation that takes a request body. details carries exactly one key, maxBodyBytes (integer): the limit that applies to this surface, in bytes.
ApiErrorResponse
414
VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show more
VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
ApiErrorResponse
415
VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes).Show more
VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes). The public edge refuses it before the platform sees it (details.reason UNSUPPORTED_MEDIA_TYPE, details.source edge). Not retryable as sent: send Content-Type application/json. Declared on every operation that takes a JSON request body.
ApiErrorResponse
500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
501Not retryable.ApiErrorResponse
502Retryable: PUT again (details.provider names the provider).ApiErrorResponse

Errors you should handle

Branch on code and honour retryable — never on the HTTP status alone.

400	VALIDATION The owners' shares add up to more than 100 percent.	not retryable
401	UNAUTHENTICATED The bearer token is expired. Re-authenticate and retry.	not retryable
403	PERMISSION_DENIED Reading wallets needs the finance:read permission.	not retryable
405	VALIDATION This method is not served.	not retryable
409	CONFLICT This tenant is on the nine-step activation. The hosted business verification collects the owners there.	not retryable
409	IDEMPOTENCY_CONFLICT Idempotency-Key 7f0c33d1-9a1e-4d2c-9f77-1c0f2b3a4d55 was used with a different body; never executed	not retryable
409	IDEMPOTENCY_IN_PROGRESS A request with this Idempotency-Key is still executing	retryable
413	VALIDATION The request body is larger than this API accepts (262144 bytes).	not retryable
414	VALIDATION The request URI is longer than 8 KiB.	not retryable
415	VALIDATION Send application/json.	not retryable
500	INTERNAL An unexpected error occurred. Quote the traceId to support.	retryable
501	NOT_IMPLEMENTED The capped activation flow is not available on this deployment.	not retryable
502	UPSTREAM_UNAVAILABLE Business verification is not answering right now. Try again in a minute.	retryable