POST
Creates an invited customer from the back-office. Send Authorization: Bearer <token> and a programId query parameter on the request, plus a step-up confirmation (not required for service users). A back-office invite comes in two shapes:
  • Plain customer — just email (and the step-up). The invitee onboards as a standalone customer. Set isCompany: true here to onboard a company (KYB) instead of an individual.
  • Sub-role member — set one of the sub-role flags below. The invitee onboards as a pseudo account funded from a real parent account, so a funding accountId is required.
Consumers inviting their own sub-users call the same route on the customer API, with a different request shape (sub-role only). This page documents the back-office request.

​
Sub-role flags

Setting any of these makes the invitee a funded sub-role member and requires accountId: Omit all four to invite a plain customer.

​
Company invites (KYB)

A plain invite can onboard a company instead of an individual by setting isCompany: true. The invitee is persisted as a company and then follows the normal KYB onboarding path (company KYC schema, company Sumsub applicant, corporate account) — company details such as the legal name and UBOs are collected in the later onboarding steps, exactly as for a self-signup company. The invite itself only sets the flag; the target program must have company/KYB onboarding configured. isCompany applies to plain invites only — combining it with any sub-role flag returns 400 (a sub-role invitee is always an individual). isCompany defaults to false.

​
Member details

Beyond email (always required) and accountId (required for a member), which member details you must supply depends on the member type:
  • some members need only email + accountId (they complete their own details, or inherit them from the funding account);
  • some need the member’s identity — firstName, lastName, dob, nationality;
  • some need a full profile, including address and phone.
You don’t have to track which is which: send what you have, and if a field is required for that member the API responds 400 naming it. Treat that response as authoritative.
address and phone may be taken from the funding account holder for some member types — in that case you don’t send them. If they’re required and not inherited, the 400 will say so.

​
Funding account (sub-role invites)

When any sub-role flag is set, accountId (a UUID) is required and names the parent account the invitee draws against. It’s validated before any user is created — it must:
  • exist,
  • be ACTIVE,
  • not itself be a pseudo account, and
  • be reachable by the caller — in the operator’s program, and within the operator’s own scope where their role is scoped to a subset of customers.
Failures are non-revealing: an account that doesn’t exist, isn’t in scope, or isn’t reachable all collapse to 400 account not found or not eligible, so the endpoint never discloses cross-tenant account existence. A program-wide operator additionally sees the distinct account is not active / account cannot be a pseudo account messages.

​
Deferring the invitation email

By default the invitee is emailed the moment you invite them: creating their identity sends a temporary password straight away. Send sendInvite: false to create the invite without telling them yet — useful when the application has to be prepared or reviewed before the customer hears anything.
Omitting sendInvite is identical to sending true — the invitee is emailed straight away, as before. Only an explicit false withholds it. Nothing else changes: the identity is created and the application record is built exactly as it would have been. Only the email is held back. Deliver the credential when you are ready with POST /applications/{applicationId}/reset, using the applicationId from the invite response. That re-issues the temporary password and emails it.
An invite created with sendInvite: false reaches the customer only through this call. Until you make it, the invitee has an account they know nothing about and cannot sign in to.
This route is not under the /v1 prefix.
That route is gated on customers.triage.reset. Operators who create deferred invites need it in addition to accessManagement.invite.customer, or they can create an invite they cannot send.
Deferring is the safer default for a slow onboarding. A temporary password expires a fixed number of days after it is issued, so an invite that sits unopened for a week can arrive already expired. Sending it when the application is ready starts that clock at the right moment.
Back-office only, and enforced. A consumer inviting their own sub-user who sends sendInvite — with either value — gets a 400. A consumer invite is always emailed immediately, because there is no operator behind it to send it later. A mis-cased sendinvite also returns 400, on either path.SSO programs reject sendInvite: false with a 400: they mint no Cognito identity, so no invitation email is ever sent and there would be nothing for the send route to deliver to afterwards.

​
Pay-in IBAN

payInIBAN is assigned to the invitee. Whether it applies is driven by the resolved onboarding role config: when the role enables pay-in (isPayInEnabled), payInIBAN is required — omitting it returns 400 payInIBAN is required when pay-in is enabled for this role. For roles without pay-in, the field is ignored.

​
SSO programs (client-ref authentication)

Some programs authenticate users through an external IdP and do not have Orenda mint a Cognito identity (e.g. potjestaging). These programs are flagged with usesClientRefAuthentication: true in their program config. When inviting into such a program:
  • clientReference is required — it becomes the invitee’s application identity (and is persisted on the application). Omitting it returns 400 clientReference is required for this program.
  • No Cognito user is created — the user pool lookup, duplicate-email check, and user creation are all skipped.
  • No step-up is needed — SSO callers are step-up exempt, so the confirmation object is not required on this path.
For normal (non-SSO) programs, clientReference is ignored and a Cognito user is created as usual.

​
Step-up authentication

Every invite by a human caller is gated by a mandatory step-up: include a confirmation object — either passkey or TOTP. This applies to back-office invites too. For TOTP, the access token must belong to the acting inviter (else 401).
Service users (machine-to-machine) are exempt — there is no human to answer the challenge, so they omit confirmation entirely. The same holds on the SSO path above.
Start a passkey challenge via POST /v1/auth/passkey/challenge to get a passkeySession and fido2options, complete it on the device, then send:
The method is explicit. An incomplete pair (for example totp without accessToken) returns 400; supplying no confirmation on a non-exempt session returns 422 SCA_MISSING, and no user is created. A pin confirmation is rejected with 422 SCA_INVALID_METHOD. Setting a sub-role flag without an accountId returns 400 accountId is required when inviting a sub-role.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
programId
string
required

The program the request acts on. Required on every endpoint. The operator's role bounds which programs they may pass; the program itself is selected by the request, not read from the token.

Body

application/json

Sent by a back-office caller. Includes a confirmation step-up object — back-office invites are challenged like any other. A plain invite needs only email; setting a sub-role flag (isPrepaidCardCustomer / isCardOnly / isSpouse / isChild) makes accountId required and names the funding parent account the invitee draws against. Sub-roles are mutually exclusive — set at most one flag (zero = plain customer); two or more returns 400. A plain (non-sub-role) invite may set isCompany: true to onboard a company (KYB); combining isCompany: true with any sub-role flag returns 400.

​
email
string<email>
required
​
confirmation
Passkey · object
required

Discriminated step-up (SCA) credential. passkey and totp are accepted on this endpoint (a pin confirmation is rejected with 422 SCA_INVALID_METHOD).

​
payInIBAN
string

Pay-in IBAN assigned to the invitee. Required when the resolved onboarding role enables pay-in (isPayInEnabled); ignored for roles without pay-in.

​
clientReference
string

External identity reference (max 36 chars). Required only for SSO programs (program config usesClientRefAuthentication: true, e.g. potjestaging) — there it becomes the application identity and is rejected with 400 if missing. Ignored for normal Cognito programs.

Maximum string length: 36
​
accountId
string<uuid>

Funding parent account the invitee draws against. Required when any sub-role flag is set. Validated up front: must exist, be ACTIVE, not be a pseudo account, and be reachable by the caller (in the caller's program; for custodians, under the inviting custodian).

​
additionalAccounts
string[]

Optional. Aliases of the program's optional accounts to create for the invitee, in addition to the account(s) created automatically at onboarding. Each alias must be a configured, non-onboarding account for the program (validated against program config); an unknown alias returns 400. Example: ["Leefgeldrekening"] — for a program whose control account is created automatically and whose allowance account is optional.

​
sendInvite
boolean
default:true

Whether the invitation email goes out now (default true) or is deferred until an operator explicitly sends it.

The invitation email is Cognito's: creating the identity normally emails a temporary password straight away. sendInvite: false creates the identity silently instead — the invitee is told nothing, and the application record is built exactly as it would have been. Deliver the credential later with POST /applications/{applicationId}/reset — note this route is not under the /v1 prefix — which re-issues the temporary password and emails it; that also restarts the password's validity window, so deferring never ships an expired credential.

Back-office only, and enforced: a consumer inviting their own sub-user who sends sendInvite — with EITHER value — gets a 400. A consumer invite is always emailed immediately, because there is no operator behind it to send it later. A mis-cased spelling (sendinvite) also returns 400, on either path.

Not available on programs that authenticate via an external identity provider (usesClientRefAuthentication): no invitation email is ever sent there and nothing exists for the send path to deliver to, so sendInvite: false returns 400.

Omitting the field is identical to sending true. The invite response is unchanged — the caller already knows whether it withheld the email, because it is the one that asked.

​
isCompany
boolean
default:false

Onboard the invitee as a company (KYB) rather than an individual (default false). Persisted onto the application and read by the whole downstream onboarding chain (KYB vs KYC schema, company Sumsub applicant/level, corporate account holder); company details (legal name, UBOs) are collected later by the normal KYB steps. Only valid on a plain invite — isCompany: true together with any sub-role flag returns 400. The target program must have company/KYB onboarding configured.

​
isPrepaidCardCustomer
boolean
​
isCardOnly
boolean
​
isSpouse
boolean
​
isChild
boolean

Response

Invitation processed

​
success
boolean
Example:

true

​
data
object