Invite a sub-user or corporate manager

curl -X POST "https://api.next.orenda.finance/v1/access-management/customer-invites" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "katherine.johnson@example.com",
  "role": "CHILD",
  "accountId": "8f1a2b3c-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
  "confirmation": {
    "method": "totp",
    "totp": "123456",
    "accessToken": "eyJraWQiOiJ...your-access-token"
  }
}'

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

POST

access-management

customer-invites

curl -X POST "https://api.next.orenda.finance/v1/access-management/customer-invites" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "katherine.johnson@example.com",
  "role": "CHILD",
  "accountId": "8f1a2b3c-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
  "confirmation": {
    "method": "totp",
    "totp": "123456",
    "accessToken": "eyJraWQiOiJ...your-access-token"
  }
}'

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

A signed-in customer can invite two kinds of user:

a sub-user, who is funded from one of your accounts;
a corporate manager, who operates your company. Only a company can invite one.

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

The program comes from your token, so this call needs no x-program-id header and no programId query parameter.

What you can invite

role says what the user becomes. It is required.

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 the team that manages your program.

`role`	The user becomes	`accountId`
`PREPAID_CARD_CUSTOMER`	A sub-user with a prepaid card, funded from your account	Required
`CARD_ONLY`	A sub-user who only holds a card, funded from your account	Required
`CHILD`	A sub-user who is your child	Required
`CORPORATE_MANAGER`	A person who operates your company	Do not send

Write role exactly as shown, in capitals with underscores.

Response

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

The user is emailed straight away.

Invite a sub-user

Send the role, the account to fund them from, and your step-up confirmation. Every sub-user role takes the same request; only role changes. With a TOTP code:

curl -X POST "https://api.next.orenda.finance/v1/access-management/customer-invites" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "katherine.johnson@example.com",
    "role": "CHILD",
    "accountId": "8f1a2b3c-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
    "confirmation": {
      "method": "totp",
      "totp": "123456",
      "accessToken": "eyJraWQiOi…"
    }
  }'

With a passkey, and the user’s full details:

curl -X POST "https://api.next.orenda.finance/v1/access-management/customer-invites" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada.lovelace@example.com",
    "role": "PREPAID_CARD_CUSTOMER",
    "accountId": "8f1a2b3c-4d5e-4f6a-8b7c-9d0e1f2a3b4c",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "dob": "1985-12-10",
    "nationality": "GB",
    "phone": "+447700900123",
    "address": {
      "addressLine1": "12 Analytical Way",
      "city": "London",
      "state": "Greater London",
      "country": "GBR",
      "postalCode": "EC1A 1BB"
    },
    "confirmation": {
      "method": "passkey",
      "passkeySession": "AYABeJ…",
      "assertion": "{\"id\":\"q1n…\",\"response\":{…}}"
    }
  }'

The funding account

accountId is the account the sub-user is funded from. It must be one of your own accounts, ACTIVE, and a real account, not one that is itself funded from a parent. It is checked before anything is created.

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

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 a 400 that names it.

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

On some programs, address and phone are copied from your own details; a child usually takes the parent’s address. When a field is copied, you can leave it out. On some programs address is required on every invite unless it is copied. Leaving it out then returns 400 address is required for consumer invitations.

Invite a corporate manager

A corporate manager is a person who operates your company, for example a finance manager who needs to see the company’s accounts and order company cards. Send "role": "CORPORATE_MANAGER" and no accountId.

curl -X POST "https://api.next.orenda.finance/v1/access-management/customer-invites" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alan.turing@example.com",
    "role": "CORPORATE_MANAGER",
    "firstName": "Alan",
    "lastName": "Turing",
    "dob": "1980-06-23",
    "nationality": "GB",
    "phone": "+447700900456",
    "confirmation": {
      "method": "passkey",
      "passkeySession": "AYABeJ…",
      "assertion": "{\"id\":\"q1n…\",\"response\":{…}}"
    }
  }'

The manager goes through their own identity check, and gets no account and no card of their own. Once onboarded, they see every account, card and transaction your company has. Cards they order are issued on your company’s account, with the manager’s own name on them.

Who can invite a manager

Only a company can. The company is taken from your own sign-in; there is no field for it.

Your situation	Response
You are not a company	`400 Only a corporate customer can invite a corporate manager`
Your company has not finished onboarding	`400 The corporate must have completed onboarding before it can invite a corporate manager`
You hold more than one company	`400 Caller holds more than one corporate; cannot determine which one the manager acts for`

A manager is an individual, so a manager cannot invite another manager. Only the company can.

The manager’s `customerId` changes on completion

Your client needs to handle this. On GET /v2/applications, a corporate manager’s customerId is:

Onboarding stage	`customerId` returned	Why
Before completion	The manager’s own id	Their identity documents are filed against the person, not the company
After completion	The company’s id	So that every customer request returns the company’s data

Nothing else in your client changes. Read the customerId from the manager’s application, use it in the path as you already do, and accounts, cards, transactions and payments all return the company’s data. applicationId always holds the manager’s own id. On an invited application it equals their own customerId, so you can still find it after the switch.

Step-up authentication

An invite needs a second factor: a confirmation object carrying either a passkey or a TOTP code.

TOTP
Passkey

Send the 6-digit code from your authenticator app with your access_token, the same 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`	`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 yours	`401`

Nothing is created when step-up fails.

If your program signs in through SSO

When your users sign in through an external identity provider, there is no Orenda passkey or authenticator to confirm with, so step-up is not needed. Send the invite without confirmation:

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

This changes if your program is moved onto passkey step-up. From then on a passkey confirmation is required, and a TOTP code is refused with 422 SCA_INVALID_METHOD. The team that manages your program can tell you which applies.

What you cannot do here

You want to	Here	Where it is done
Invite a customer (an invite with no `role`), or a company	`400`	By your program’s operator or integration, on the Management API
Invite an `EMPLOYEE`, or a role set up for your program’s cardholders, for example `CONSUMER_CARDHOLDER`	`400`	By your program’s operator or integration, on the Management API
Hold back the invitation email (`sendInvite`)	`400`	Management API only
Invite at all, on a program that uses a client reference	`400 This program does not support consumer self-service invites`	Management API only

Your client may still meet an employee or cardholder signed in. Like a corporate manager, once onboarded their GET /v2/applications reports the company’s customerId (see above), but they see only the accounts they were given and only their own cards.

A program that uses a client reference signs its users in with its own identity provider, and Orenda creates no sign-in for them. That is a different setting from SSO step-up above. The team that manages your program can tell you whether it applies.

Errors at a glance

Status	When
`400`	The request is wrong, or your program cannot take the invite. See below
`401`	No bearer token, or a TOTP `accessToken` that is not yours
`403`	Your role lacks `accessManagement.invite.customer`
`409`	A user with that email already exists in the program
`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 or in the wrong format
role is missing, or not written in capitals with underscores
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 is missing or cannot be used
isCompany: true or sendInvite was sent
you invited a manager, and you are not a company that has finished onboarding
the role is one that only an operator or integration can invite, for example EMPLOYEE

400 because of your program. Your request is fine; speak to the team that manages your program:

your program does not have the role you asked for
your program uses a client reference

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

Authorizations

Authorization

string

header

required

The user's access_token from authentication. The program and environment come from the token.

Body

application/json

What a signed-in customer sends. role is required. Which of the user's details are required depends on the role and on your program; if one is missing, the 400 names it.

string<email>

required

The user's email address. Must not already be in use in the program.

role

enum<string>

required

What the user becomes. PREPAID_CARD_CUSTOMER, CARD_ONLY and CHILD invite a sub-user and need accountId. CORPORATE_MANAGER invites a manager of your company. Your program must have the role. Write it exactly, in capitals with underscores.

Available options:

PREPAID_CARD_CUSTOMER,

CARD_ONLY,

CHILD,

CORPORATE_MANAGER

Example:

"CHILD"

firstName

string

The user's first name.

lastName

string

The user's last name.

dob

string

Date of birth, YYYY-MM-DD.

nationality

string

Two-letter country code, for example GB.

phone

string

7 to 15 digits, with an optional + in front.

address

object

The user's address. country is a three-letter code. On some programs it is copied from your own details and can be left out.

Show child attributes

accountId

string<uuid>

The account a sub-user is funded from. Required for a sub-user. Must be one of your own accounts, ACTIVE, and not itself funded from a parent. Do not send it for CORPORATE_MANAGER.

confirmation

Passkey · object

Step-up: a passkey or a TOTP code. Leave it out only if your program signs in through SSO.

Passkey
TOTP

Show child attributes

Response

The invitation was created.

success

boolean

Example:

true

message

string

Example:

"Customer invitation processed successfully"

data

object

Show child attributes

Get started

Guides

Invite a sub-user or corporate manager

What you can invite

Response

Invite a sub-user

The funding account

The user’s details

Invite a corporate manager

Who can invite a manager

The manager’s `customerId` changes on completion

Step-up authentication

If your program signs in through SSO

What you cannot do here

Errors at a glance

Authorizations

Body

Response

​What you can invite

​Response

​Invite a sub-user

​The funding account

​The user’s details

​Invite a corporate manager

​Who can invite a manager

​The manager’s customerId changes on completion

​Step-up authentication

​If your program signs in through SSO

​What you cannot do here

​Errors at a glance

Authorizations

Body

Response

What you can invite

Response

Invite a sub-user

The funding account

The user’s details

Invite a corporate manager

Who can invite a manager

The manager’s `customerId` changes on completion

Step-up authentication

If your program signs in through SSO

What you cannot do here

Errors at a glance