Invite a customer

One call creates the user and their application:

POST https://api.next.orenda.finance/v1/access-management/customer-invites?programId=<programId>
Authorization: Bearer <token>
Content-Type: application/json

This page is the guide. Every field and every error is listed in the API reference, Invite a customer.

This page covers invites sent by your integration or by an operator. A signed-in customer inviting their own sub-users or a corporate manager uses the same route on the Customer API, with a different request.

Who calls it

	Service user (your integration)	Operator (a person)
Token	From the service-user credential (Authentication)	From `POST /v1/auth/login` + 2FA
`programId` query parameter	Required	Required
Step-up `confirmation`	Not needed. Leave it out	Required: passkey or TOTP
Permission	`accessManagement.invite.customer`	Same

Most integrations use a service user, so the examples on this page are written for one. An operator sends the same body and adds a confirmation; see Step-up for operators.

What you can invite

role says what the user becomes. Leave it out to invite a customer.

You can only invite the roles your program has been given. The table below lists every role this route understands, not the ones available to you. Many programs have only one of them, and some have none. Inviting a role your program does not have returns 400. To find out which roles you have, or to have one added, speak to Orenda.

`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	`accountId`
`EMPLOYEE`	A cardholder on a corporate: an employee	`corporateCustomerId`, `accountIds`
A role set up for your program, for example `CONSUMER_CARDHOLDER`	A cardholder on a corporate, with that role’s permissions	`corporateCustomerId`, `accountIds`

Write role exactly as shown, in capitals with underscores. consumer_cardholder is refused. CORPORATE_MANAGER cannot be invited here. A corporate invites its own managers on the Customer API.

Response

Every successful invite returns:

{
  "success": true,
  "message": "Customer invitation processed successfully",
  "data": { "applicationId": "d6354344-a847-49cd-9e41-530d720e7a21" }
}

applicationId identifies the user’s application, and is also their customerId. Use it to:

follow their onboarding (Search GET /v1/applications, or the customer status webhook);
submit KYC for them (POST /v1/applications/{applicationId}/kyc);
order a card for a cardholder on a corporate, as forCustomerId (Issue cards).

When you read the application back, onboardingRole holds the role when it is one set up for your program, and parent.relation names the user’s relation to the corporate (EMPLOYEE, CONSUMER_CARDHOLDER).

Step-up for operators

An invite creates an account, so an operator must confirm it with a second factor: a confirmation object carrying either a passkey or a TOTP code. A service user never needs this. Leave confirmation out.

curl -X POST "https://api.next.orenda.finance/v1/access-management/customer-invites?programId=acme" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "grace.hopper@example.com",
    "confirmation": {
      "method": "totp",
      "totp": "123456",
      "accessToken": "eyJraWQiOi…"
    }
  }'

TOTP
Passkey

Send the 6-digit code from the operator’s authenticator app, with the operator’s accessToken. This is the access token returned by the operator’s sign-in, not the ID token you send as the bearer:

"confirmation": {
  "method": "totp",
  "totp": "123456",
  "accessToken": "eyJraWQiOi…"
}

Start a challenge with POST /v1/auth/passkey/challenge, complete it on the device, then send:

"confirmation": {
  "method": "passkey",
  "passkeySession": "c14102b0-…",
  "assertion": "{\"id\":\"…\",\"response\":{…}}"
}

What went wrong	Response
No `confirmation` from an operator	`422 SCA_MISSING`
Half a pair, for example `totp` without `accessToken`	`400 Invalid confirmation: accessToken: Required`
Any other method, for example `pin`	`422 SCA_INVALID_METHOD`
A TOTP `accessToken` that is not the operator’s	`401`
An expired or wrong code or session	`400`, `401` or `422`, with the reason in `message`

Nothing is created when step-up fails.

Customer

curl -X POST "https://api.next.orenda.finance/v1/access-management/customer-invites?programId=acme" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "grace.hopper@example.com" }'

The user onboards as a customer with their own account. Which of their details you need to send depends on your program; see The user’s details.

Company

Add isCompany: true to invite a company in place of an individual.

curl -X POST "https://api.next.orenda.finance/v1/access-management/customer-invites?programId=acme" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "founder@acme.example.com", "isCompany": true }'

The company goes through business verification (KYB). Its legal name, owners and documents are collected during onboarding, not in the invite.

Your program must support company onboarding, or the invite returns 400 This program does not support company (KYB) onboarding.
isCompany: true cannot be sent with a role. Every role invites an individual.
A caller acting for a custodian cannot invite a company.

Sub-users

A sub-user is an individual funded from one of the parent customer’s accounts. PREPAID_CARD_CUSTOMER, CARD_ONLY and CHILD are sub-user roles. They all take the same request; only role changes.

curl -X POST "https://api.next.orenda.finance/v1/access-management/customer-invites?programId=acme" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "katherine.johnson@example.com",
    "role": "PREPAID_CARD_CUSTOMER",
    "accountId": "8f1a2b3c-4d5e-4f6a-8b7c-9d0e1f2a3b4c"
  }'

The funding account

accountId is the parent account the sub-user is funded from. It is checked before anything is created. The account must:

exist and be ACTIVE,
be a real account, not one that is itself funded from a parent, and
be in your program. For a caller acting for a custodian, it must also be under that custodian.

What went wrong	Response
`accountId` left out	`400`, message containing `accountId is required when inviting role "…"`
Account not found, or not one you may use	`400 account not found or not eligible`
Account found but not active	`400 account is not active`
Account is itself funded from a parent	`400 account cannot be a pseudo account`

For security, the second message does not say whether the account exists.

Cardholders on a corporate

For programs where a corporate holds the account and other people hold cards on it. The cardholder is an individual with no account of their own. You say which corporate they belong to and which of its accounts they may use. There are two kinds of role:

EMPLOYEE, for the corporate’s staff.
A role set up for your program, for cardholders who are not staff. For example CONSUMER_CARDHOLDER, for consumers who hold a card on a corporate’s account.

Both take the same request; only role changes.

curl -X POST "https://api.next.orenda.finance/v1/access-management/customer-invites?programId=acme" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada.lovelace@example.com",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "role": "CONSUMER_CARDHOLDER",
    "corporateCustomerId": "f3e6f586-2f70-4741-993c-337fa717406e",
    "accountIds": ["c7e97733-5b05-458b-8a3d-90fafd067513"]
  }'

If your program uses a client reference, add clientReference as well.

Rules

Rule	If broken
`corporateCustomerId` must be a company in your program that has finished onboarding	`400`
`accountIds` must list at least one `ACTIVE` account of that corporate, and not one that is itself funded from a parent	`400 delegatedAccountIds must name active accounts of the corporate`
Do not send a funding `accountId` or `isCompany: true`	`400`
Send `corporateCustomerId` and `accountIds` only with these roles	`400` on any other invite
The role must be one your program has	`400 This program does not support role "CONSUMER_CARDHOLDER"`
The role must be fully set up	`400 role "CONSUMER_CARDHOLDER" is not configured for invites against a corporate`

If one account in accountIds is wrong, the whole invite is refused, and the message does not say which one. The last error in the table is a problem with your program’s setup, not with your request: tell Orenda the role and the program. Send firstName and lastName: they are printed on the card. Your program may or may not insist on them at invite time, so do not rely on a 400 to catch a missing name. Only your integration or an operator can invite these roles. A signed-in customer cannot.

What the cardholder sees

Once onboarded:

Their own cards only. Another cardholder’s card on the same account is refused (422 CARD_ACCESS_NOT_PERMITTED). What they may do with their own card depends on the permissions of their role.
The accounts in accountIds and no others. They see every transaction on those accounts, including other cardholders’ card spending.

What happens next

After the invite, the next steps are yours:

Submit the cardholder’s KYC (POST /v1/applications/{applicationId}/kyc).
Order their card on the corporate’s account, with forCustomerId: <applicationId>. You can do this as soon as the invite returns.
Once KYC is approved, the cardholder signs in, accepts the legal agreements and uses the card.

From then on, the cardholder’s own requests report the corporate’s customerId, and webhooks for their card carry the corporate’s customerId and clientReference. So identify these users in your own system by the applicationId from the invite, and match card webhooks by cardId.

The user’s details

email is always required. Whether you also need to send firstName, lastName, dob, nationality, phone and address depends on the role and on your program. Send what you have. If a required detail is missing, the API returns 400 <field> is required for this invite.

curl -X POST "https://api.next.orenda.finance/v1/access-management/customer-invites?programId=acme" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "katherine.johnson@example.com",
    "role": "CHILD",
    "accountId": "8f1a2b3c-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
    "firstName": "Katherine",
    "lastName": "Johnson",
    "dob": "2012-08-26",
    "nationality": "US",
    "phone": "+17575550123",
    "address": {
      "addressLine1": "10 Mercury Way",
      "city": "Hampton",
      "state": "VA",
      "country": "USA",
      "postalCode": "23666"
    }
  }'

Field	Format
`dob`	`YYYY-MM-DD`
`nationality`	Two-letter country code, for example `GB`
`address.country`	Three-letter country code, for example `GBR`. A two-letter code is refused
`phone`	7 to 15 digits, with an optional `+` in front

For some sub-user roles, address and phone are copied from the funding account’s owner. In that case you can leave them out.

Optional extras

Additional accounts

additionalAccounts opens extra accounts for the user, on top of the ones onboarding creates. List the names of the optional accounts your program offers.

{ "email": "grace.hopper@example.com", "additionalAccounts": ["Leefgeldrekening"] }

A name your program does not offer returns 400, and the message lists the names it does.

Pay-in IBAN

payInIBAN is assigned to the user. If the role has pay-in switched on, it is required, and leaving it out returns 400 payInIBAN is required when pay-in is enabled for this role. Otherwise it is ignored.

{ "email": "grace.hopper@example.com", "payInIBAN": "NL91ABNA0417164300" }

Holding back the invitation email

Normally the user is emailed a temporary password as soon as you invite them. Send sendInvite: false to create the invite without emailing them yet. This is useful when you need to prepare or review the application first.

{ "email": "not.yet@example.com", "sendInvite": false }

When you are ready, send the email with POST /customers/{customerId}/reset, using the applicationId from the invite as customerId.

Until you make that call, the user has an account they do not know about and cannot sign in to.

The reset route is not under /v1, and it needs the customers.triage.reset permission as well as accessManagement.invite.customer.
A temporary password expires a fixed number of days after it is sent. Holding the email back until the application is ready means the user does not receive one that has already expired.
Leaving sendInvite out is the same as sending true.

Programs that use a client reference

Some programs sign their users in with their own identity provider, and Orenda does not create a sign-in for them. Ask Orenda whether yours is one. If it is:

Send clientReference on every invite, whatever the role. It is the user’s id in your identity provider, at most 36 characters, and it becomes their identity with Orenda.
It must be unique. Using one twice returns 409 An application already exists for this clientReference.
No invitation email is sent. sendInvite: false returns 400.
Only your integration or an operator can invite. Customers cannot invite on these programs.

curl -X POST "https://api.next.orenda.finance/v1/access-management/customer-invites?programId=acme" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "grace.hopper@example.com", "clientReference": "firebase-uid-of-grace" }'

Leaving clientReference out returns 400 clientReference is required for this program. On every other program the field is ignored.

Field names are case-sensitive

role, isCompany and sendInvite must be written exactly. A mis-cased name is refused: { "Role": "CHILD" } returns 400 Unknown field "Role" — did you mean "role"?.

Errors at a glance

Status	When
`400`	See the two lists below
`401`	No bearer token, or a TOTP `accessToken` that is not the operator’s
`403`	The caller’s role lacks `accessManagement.invite.customer`, or the program is outside the caller’s scope
`404`	`programId` names a program that is not set up
`409`	A user with that email already exists in the program, or that `clientReference` is already in use
`422`	`SCA_MISSING` or `SCA_INVALID_METHOD`; or a service the invite depends on refused it (`PROVIDER_ERROR`)

400 because of the request. Fix the request and send it again:

a field is missing, mis-cased or in the wrong format
role is not written in capitals with underscores, or is one of the reserved names PROGRAM_CUSTOMER, DEFAULT, GUARDIAN, CUSTODIAN
role is CORPORATE_MANAGER: a manager reaches the whole corporate, so the corporate invites them itself
a retired role field was sent (isPrepaidCardCustomer, isCardOnly, isSpouse, isChild, isCorporateManager, isEmployee): the message names the role to send instead
a detail the role needs is missing
the funding account, the corporate, or an account in accountIds cannot be used
isCompany: true sent with a role, or by a caller acting for a custodian
clientReference missing, or sendInvite: false, on a program that uses a client reference
a name in additionalAccounts that your program does not offer
no programId in the query

400 because of your program’s setup. Your request is fine; speak to Orenda:

Message	Meaning
`This program does not support role "…"`	Your program does not have that role
`role "…" is not configured for invites against a corporate`	The role exists but is not fully set up
`This program has no onboarding configuration for this invite; invitations are not supported`	Your program is not set up for invites
`This program does not support company (KYB) onboarding`	Your program is not set up for companies

When a request breaks more than one rule, message lists them all, separated by ; .A few messages use Orenda’s internal names: a wrong account in accountIds is reported as delegatedAccountIds, and an account funded from a parent is called a pseudo account. Act on the status and the rest of the message.

Get started

Oversight

Customer operations

Batch payments

Configuration

Who calls it

What you can invite

Response

Step-up for operators

Customer

Company

Sub-users

The funding account

Cardholders on a corporate

Rules

What the cardholder sees

What happens next

The user’s details

Optional extras

Additional accounts

Pay-in IBAN

Holding back the invitation email

Programs that use a client reference

Field names are case-sensitive

Errors at a glance

​Who calls it

​What you can invite

​Response

​Step-up for operators

​Customer

​Company

​Sub-users

​The funding account

​Cardholders on a corporate

​Rules

​What the cardholder sees

​What happens next

​The user’s details

​Optional extras

​Additional accounts

​Pay-in IBAN

​Holding back the invitation email

​Programs that use a client reference

​Field names are case-sensitive

​Errors at a glance

Who calls it

What you can invite

Response

Step-up for operators

Customer

Company

Sub-users

The funding account

Cardholders on a corporate

Rules

What the cardholder sees

What happens next

The user’s details

Optional extras

Additional accounts

Pay-in IBAN

Holding back the invitation email

Programs that use a client reference

Field names are case-sensitive

Errors at a glance