Manage card invitations for team members pending onboarding

Use card invitations to pre-create cards for team members who have not yet onboarded. Once the team member completes onboarding, the card is automatically issued as per the configuration specified in the invitation.

Note

• This feature is not available in Sandbox.
• To use the Card invitations API, please contact Revolut API Support.

Card invitations enable your business to pre-create cards for team members who have not yet onboarded. This allows your business to prepare card access in advance, streamlining the onboarding process.

When a card invitation is successfully created, it remains in the created state until the designated team member completes onboarding and their team member state becomes active. When this happens, all card invitations in state created linked to that team member are automatically claimed, and the corresponding virtual cards are issued immediately. Successfully claimed invitations change their state to redeemed.

If the team member does not complete onboarding before the invitation's expiry date, the invitation automatically transitions to state expired, and no card will be issued.

Tip

• To issue cards for your team members that have already completed onboarding, use the Cards API instead.
• To request a physical card, use the Revolut Business app.

---

The Business API lets you issue and manage card invitations for new team members joining your business. You can:

• Create or cancel: Create a new invitation for a virtual card, or cancel a card invitation when it is no longer needed.
• Update: Update an active card invitation to modify settings for the card to be issued, such as the card's label, linked accounts, or spending controls.
• Get details: Retrieve the list of card invitations issued for your team, or retrieve a specific card invitation by its ID.

Create a card invitation​

To create a new card invitation, you must provide the following information:

Required details

• Request ID: The ID of the request, provided by you to help you identify the creation request in your system.

  Caution

  To ensure that a request to create a card invitation is not processed multiple times if there are network or system errors, the same request_id should be used for requests related to the same card invitation. For more details, see the Idempotency section.

• Holder ID: The ID of the team member to assign as the holder of the card that will be issued once the invitation is claimed.

• Virtual: Confirms that the card that should be issued will be virtual. Set it to true.

Optionally, you can also specify additional details for the card that should be issued, such as a distinct label, linked accounts, and spending limits and categories.

Optional details

• Label: Give the card a label that will be displayed in the UI and in transaction reporting, to help with recognition and reconciliation. If not provided, it will default to the card's type, which for card invitations created via the API is Virtual.

• Spending limits: Set one of the periodic (day/week/month/quarter/year/all time) limits and/or a non-periodic (single) spending limit.

• Spending period: Set dates after which the card becomes available or unavailable for spending and define what happens when the end date is reached.

• Categories: Limit the merchant categories available for spending. By default, all categories will be available. For the full list of categories, see the API reference → categories.

  Note

  If you restrict merchant categories, you cannot use merchant controls to allow specific merchants. However, you can still use merchant controls with categories to block specific merchants.
  If you set only categories or only merchant controls, each works independently.

• Merchant controls: Block or allow the card to only transact with specific merchants.

  Note

  If you restrict merchant categories, you cannot use merchant controls to allow specific merchants. However, you can still use merchant controls with categories to block specific merchants.
  If you set only categories or only merchant controls, each works independently.

  For more details, see the API reference.

• Countries: Restrict card use to specified countries, provided as 2-letter ISO 3166 codes.

• Accounts: Limit which accounts the card should be linked to, by providing their IDs. By default, all accounts will be linked.

For sample requests and responses:

See the API reference: Create a card invitation

Idempotency​

To ensure that a single card invitation creation is not processed multiple times if there are network or system errors, we deduplicate requests made with the same request ID within a 24-hour interval (counting from the first request). This is why you should use the same request ID for requests related to the same card invitation.

This also means that if the first request fails, this state is saved and returned in response to all the subsequent requests with the same request ID within the 24-hour deduplication period.
An exception is when the initial request fails for an unexpected reason. In such a case, you still get an error saying that the first execution was not successful, but you don't get the exact error message and code that might have been returned for that first execution, you only see that the idempotent replay failed.

While there is no specific requirement regarding the format of the request ID that you should use, we recommend using v4 UUIDs.

Update a card invitation​

Active card invitations – that is, invitations that have been successfully created but haven't been redeemed yet – can be updated.

For each active invitation, you can update the card's label and spend controls: the spending limits, spending period, merchant-level controls, merchant categories, and countries available for spending. The following rules apply when updating parameters:

• You can update a single parameter or multiple parameters at once.

• You cannot restrict categories and allow specific merchants at the same time. For more information, see: Create a card invitation → Optional details.

• To reset the categories to default or erase a spending limit, provide null as the value for the respective parameter.

• Cards without labels are not allowed. If you erase the existing label with null, it will set the label to its default value according to the card type.

Caution

Some spend control parameters can affect one another. When updating spend controls, review the resulting settings in the response to ensure they reflect the configuration you intended.

A sample request looks like this:

curl -X PATCH https://b2b.revolut.com/api/1.0/card-invitations/{card_invitation_id} \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer <your access token>" \
  -d '{
  "label": "New label",
  "spending_limits": {
    "single": null
  },
  "categories": [
    "services",
    "shopping",
    "furniture"
  ]
}'

For more details and example requests and responses:

See the API reference: Update card invitation details

Note

A card invitation cannot be reassigned to another team member. If you need to change the holder ID, cancel the invitation, and create a new one instead, with the correct team member as holder.

Retrieve card invitations​

The Business API lets you retrieve all card invitations issued for your business. This means invitations created via API, but also those created from the Revolut Business app, including those for physical cards.

When you retrieve the card invitations, for each invitation, you get its details, such as the invitation ID, current state, expiry date (for invitations in state created), and the details of the card that should be created when the invitation is successfully claimed. If the invitation has been redeemed, the details include the card's ID.

You can:

• Retrieve all the card invitations in your account
• Retrieve a specific card invitation

Retrieve a list of card invitations​

You can list all the card invitations issued for your business. You can also filter the invitations by their creation date.

The results are paginated and sorted by the created_at date in reverse chronological order.

For more details and example requests and responses:

See the API reference: Retrieve a list of card invitations

Filtering and pagination​

When retrieving card invitations, you can also include the optional query parameters to:

• Modify the maximum number of card invitations returned per page (by default, it's 100).
• Retrieve only the card invitations which were created before a date/date-time that you specify.

For example, these parameters limit the number of card invitations to three, and retrieve only the invitations created before 13th December 2025:

/card-invitations?limit=3&created_before=2025-12-13

To get to the next page, make a new request and use the created_at date of the last returned card invitation as created_before.

Retrieve a specific card invitation​

You can also retrieve a single specific card invitation by its ID to look up its details.

For more details and example requests and responses:

See the API reference: Retrieve card invitation details

Cancel a card invitation​

At times, you might want to cancel a card invitation when it is no longer needed. For example, when the invited employee is hired for a different position than originally intended and no longer needs a card, or when the invitation was issued by mistake. Once the card invitation is cancelled, it will transition to state expired.

Caution

Cancelling a card invitation cannot be undone. Once a card invitation is cancelled, it cannot be reactivated. If you still need it, you must create a new invitation.

To cancel a card invitation, provide its ID. You can get this ID by retrieving a list of card invitations for your business.

On success, the card invitation moves to state expired and can no longer be redeemed.

For more details and example requests and responses:

See the API reference: Cancel a card invitation

Card invitation state​

When a card invitation is created successfully, it enters state created. At this point, it awaits onboarding completion by the team member specified as holder.

From this state, it can transition into one of the three final states:

Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

To understand what each invitation state means, refer to this table:

	State in API	State description
	created	The invitation has been created and is waiting for the team member to finish onboarding so it can be claimed. At this stage, you can update the invitation to modify the card's settings.
	redeemed	The team member has completed onboarding, the invitation has been claimed, and the card has been automatically issued to the team member as per the configuration specified in the invitation. This is a final state – at this point, the invitation can no longer be redeemed or modified.
	failed	The invitation claim attempt has failed. This can happen, for example, when: The team member specified as holder is terminated before the invitation's expiry date The team member has accepted the invitation, but the card cannot be created for some reason. This is a final state – at this point, the invitation can no longer be redeemed or modified.
	expired	The invitation expires before the team member has completed onboarding, or The invitation is cancelled manually. This is a final state – at this point, the invitation can no longer be redeemed or modified. If you still need to issue a card to this team member, create a new card invitation, or wait until they complete onboarding first, and create a card for them the standard way.

Glossary​

Onboarding​

First log-in to the Revolut Business account.

→ To complete onboarding means for the team member to log in for the first time to the Revolut Business account they were invited to. This is equivalent to accepting the invitation.

Claiming an invitation​

Claiming an invitation, or redeeming an invitation, means successful team member onboarding followed by immediate card issuance as per the configuration specified in the invitation.

→ To claim an invitation or to redeem an invitation means for the team member to successfully onboard and have the corresponding card issued immediately after.