# 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 increase your account's card limits, please contact [Revolut API Support](mailto:api-requests@revolut.com). ::: Card invitations enable your business to pre-create cards for team members who have not yet [onboarded](#onboarding). 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`](/docs/api/business#get-team-members) becomes `active`. When this happens, all card invitations in state `created` linked to that team member are automatically [claimed](#claiming-an-invitation), 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](/docs/guides/manage-accounts/cards/manage-cards) instead. - To request a physical card, use the [Revolut Business app](https://business.revolut.com/login). ::: --- The Business API lets you issue and manage card invitations for new team members joining your business. You can: - **Create or cancel**: [Create](#create-a-card-invitation) a new invitation for a virtual card, or [cancel](#cancel-a-card-invitation) a card invitation when it is no longer needed. - **Update**: [Update an active card invitation](#update-a-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](#retrieve-a-list-of-card-invitations) issued for your team, or [retrieve a specific card invitation](#retrieve-a-specific-card-invitation) by its ID. ## Create a card invitation To create a new card invitation, you must provide the following information: ::::details [Required details] - **Request ID**: The ID of the request, provided by you to help you identify the creation request in your system. :::warning 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](#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. ::::details [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](/docs/api/business#create-card-invitation) → `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](/docs/api/business#create-card-invitation). - **Countries**: Restrict card use to specified countries, provided as 2-letter [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) 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](/docs/api/business#create-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](#claiming-an-invitation) 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](#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](/docs/api/business#update-card-invitation#request) value according to the card type. :::warning 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: ```shell curl -X PATCH https://b2b.revolut.com/api/1.0/card-invitations/{card_invitation_id} \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer " \ -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 settings](/docs/api/business#update-card-invitation) :::note A card invitation cannot be reassigned to another team member. If you need to change the holder ID, [cancel](#cancel-a-card-invitation) the invitation, and [create](#create-a-card-invitation) 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](#create-a-card-invitation), 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. If the team member assigned as cardholder has been deleted since the card invitation has been created, holder ID is not returned. You can: - [Retrieve all the card invitations](#retrieve-a-list-of-card-invitations) in your account - [Retrieve a specific card invitation](#retrieve-a-specific-card-invitation) ### Retrieve a list of card invitations You can list all the card invitations [issued](#create-a-card-invitation) for your business. You can also [filter](#filtering-and-pagination) the invitations by their creation date. The results are [paginated](#filtering-and-pagination) 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](/docs/api/business#get-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](#create-a-card-invitation). For more details and example requests and responses: [See the API reference: Retrieve card invitation details](/docs/api/business#get-card-invitation) ## 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`. :::warning 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](#create-a-card-invitation). ::: To cancel a card invitation, provide its ID. You can get this ID by [retrieving a list of card invitations](#retrieve-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](/docs/api/business#cancel-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](#create-a-card-invitation). From this state, it can transition into one of the three final states: ```mermaid flowchart TD A[CREATED] -->|Wait for team member to finish onboarding| B{Invitation claimed before expiry?} B -->|No| C{Team member deleted?} B -->|Yes| D{Claim successful?} C -->|No| E[EXPIRED] C -->|Yes| F[FAILED] D -->|No| F D -->|Yes| G[REDEEMED] ``` To understand what each invitation state means, refer to this table: | | State in API | State description | | -------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | :104/Success: | `created` | The invitation has been created and is waiting for the team member to finish [onboarding](#onboarding) so it can be [claimed](#claiming-an-invitation). At this stage, you can [update the invitation](#update-a-card-invitation) to modify the card's settings. | | :CheckSuccess: | `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](#create-a-card-invitation) specified in the invitation. This is a final state – at this point, the invitation can no longer be redeemed or modified. | | :CrossCircle: | `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. | | :16/Delete: | `expired` | - :TimeOutline: The invitation expires before the team member has completed onboarding, or
- :Reverted: The invitation is [cancelled](#cancel-a-card-invitation) 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](#create-a-card-invitation), or wait until they complete onboarding first, and [create a card](/docs/guides/manage-accounts/cards/manage-cards#create-a-virtual-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](#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.