Invite a customer
Creates a user and their application. Called by your integration (a service user) or by an operator.
role says what the user becomes. Leave it out to invite a customer.
role | The user becomes | Also send |
|---|---|---|
| (left out) | A customer with their own account | |
(left out), with isCompany: true | A company | |
PREPAID_CARD_CUSTOMER, CARD_ONLY, CHILD | A sub-user, funded from a parent account | accountId |
EMPLOYEE | A cardholder on a corporate’s accounts: an employee | corporateCustomerId, accountIds |
A role set up for your program, for example CONSUMER_CARDHOLDER | A cardholder on a corporate’s accounts, with that role’s permissions | corporateCustomerId, accountIds |
You can only invite the roles your program has been given. The table lists every role this route understands, not the ones available to you. Inviting a role your program does not have returns 400. Speak to Orenda to find out which roles you have.
Step-up. An operator must send a confirmation (passkey or TOTP). A service user never needs one.
Programs that use a client reference must send clientReference on every invite.
The guide, Invite a customer, explains each kind of invite, what happens next, and how to act on each error.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
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
What your integration or an operator sends. Which of the user's details are required depends on the role and on your program; if one is missing, the 400 names it.
The user's email address. Must not already be in use in the program.
The user's first name. Send it for a cardholder on a corporate: it is printed on the card.
The user's last name. Send it for a cardholder on a corporate: it is printed on the card.
Date of birth, YYYY-MM-DD.
Two-letter country code, for example GB.
7 to 15 digits, with an optional + in front.
The user's address. country is a three-letter code. For some sub-user roles it is copied from the funding account's owner and can be left out.
Show child attributes
Show child attributes
IBAN assigned to the user for pay-in. Required when the role has pay-in switched on; otherwise ignored.
The user's id in your own identity provider, at most 36 characters. Required on every invite if your program uses a client reference, and it must be unique (409 if already used). Ignored on every other program.
36The parent account a sub-user is funded from. Required with PREPAID_CARD_CUSTOMER, CARD_ONLY and CHILD. Do not send it with EMPLOYEE or a role set up for your program. The account must be ACTIVE, in your program, and not itself funded from a parent.
Names of the optional accounts your program offers, to open for the user on top of the ones onboarding creates. A name your program does not offer returns 400. Example: ["Leefgeldrekening"].
Whether to email the user now. Default true.
Send false to create the invite without emailing them. When you are ready, send the email with POST /customers/{customerId}/reset, using the invite's applicationId as customerId. That route is not under /v1 and needs the customers.triage.reset permission.
On a program that uses a client reference, sendInvite: false returns 400: those programs never send an invitation email.
Send true to invite a company in place of an individual. Default false. Its details are collected during onboarding. Cannot be sent with a role. Your program must support company onboarding, and a caller acting for a custodian cannot send it.
What the user becomes. Leave it out to invite a customer.
PREPAID_CARD_CUSTOMER,CARD_ONLY,CHILD: a sub-user. SendaccountId.EMPLOYEE: an employee of a corporate. SendcorporateCustomerIdandaccountIds.- A role set up for your program, for example
CONSUMER_CARDHOLDER: a cardholder on a corporate's accounts. SendcorporateCustomerIdandaccountIds.
Your program must have the role. Write it exactly, in capitals with underscores. CORPORATE_MANAGER cannot be invited on this route.
64^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*$"CONSUMER_CARDHOLDER"
The corporate the cardholder belongs to. Required with EMPLOYEE or a role set up for your program. Must be a company in your program that has finished onboarding. Refused on any other invite.
The corporate's accounts the cardholder may use, at least one. Required with EMPLOYEE or a role set up for your program. Each must be an ACTIVE account of that corporate, and not one that is itself funded from a parent. If one is wrong the whole invite is refused, and the message does not say which. Refused on any other invite.
Step-up: a passkey or a TOTP code. Required from an operator. A service user leaves it out.
- Passkey
- TOTP
Show child attributes
Show child attributes