openapi: 3.0.1
info:
version: '1.0'
title: Business Accounting Card invitations API
description: "As a Revolut Business customer with a Business Account, you can use the Business API to automate your own business processes.\nSave time, reduce your costs, and avoid errors by using the Business API. \n\n:::tip[Before you get started]\nTo learn more about the Business API and its features, check the [**user guides**](https://developer.revolut.com/docs/guides/manage-accounts/introduction).\n\nYou can reach them at any time from the main navigation bar **→ Guides → Business**.\n:::\n\nYou can view accounts, manage counterparties, make payments or currency exchanges without manual effort in the Web UI:\n\n- Accounting: [Account management](https://developer.revolut.com/docs/api/business#get-account), [Accounting settings](https://developer.revolut.com/docs/api/business#tag-accounting), [Expense management](https://developer.revolut.com/docs/api/business#get-expense), [Transactions](https://developer.revolut.com/docs/api/business#get-transactions) \n- Payments: \n - [Counterparty management](https://developer.revolut.com/docs/api/business#get-counterparties)\n - Payment management: [Payment drafts](https://developer.revolut.com/docs/api/business#delete-payment-draft), [Payout links](https://developer.revolut.com/docs/api/business#get-payout-link), [Transfers](https://developer.revolut.com/docs/api/business#tag-transfers)\n - [Foreign exchange](https://developer.revolut.com/docs/api/business#tag-foreign-exchange)\n- Business team: [Card management](https://developer.revolut.com/docs/api/business#delete-card), [Card invitation management](https://developer.revolut.com/docs/api/business#update-card-invitation), [Team member management](https://developer.revolut.com/docs/api/business#delete-team-member)\n- Developer tools: [Sandbox simulations](https://developer.revolut.com/docs/api/business#tag-simulations), [Webhook management](https://developer.revolut.com/docs/api/business#tag-webhooks-v2)\n\nTo see the reference for the specific endpoints and operations of this API, browse the menu on the left.\n\n### Test the Business API\n\nYou can test the Business API in Postman by forking this collection:\n\n[](https://www.postman.com/revolut-api/workspace/revolut-developers/overview)"
contact: {}
servers:
- url: https://b2b.revolut.com/api/1.0
description: Production server (uses live data)
- url: https://sandbox-b2b.revolut.com/api/1.0
description: Sandbox server (uses test data)
tags:
- name: Card invitations
description: 'Use card invitations to pre-create cards for [team members](https://developer.revolut.com/docs/guides/manage-accounts/teams/manage-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.
You can also retrieve and update the invitations, or cancel them if they''re no longer needed.
:::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).
:::
For more information, see the guides: [Manage card invitations](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-card-invitations).'
paths:
/card-invitations:
servers:
- url: https://b2b.revolut.com/api/1.0
description: Production server (uses live data)
post:
summary: Create a card invitation
operationId: createCardInvitation
description: 'Create an invitation for a virtual [team member card](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards#different-types-of-cards) for a new, not-yet-onboarded team member.
When the team member completes onboarding before the invitation''s expiry date, the invitation will automatically be claimed, and the card will then be issued for the team member immediately.
:::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).
:::
For more information, see the guides: [Manage card invitations](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-card-invitations).'
security:
- AccessToken:
- WRITE
tags:
- Card invitations
requestBody:
description: Card to create an invitation for
required: true
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: 'A unique ID of the request that you provide.
There is no strict requirement on the format of this ID, but we suggest using v4 UUIDs.
:::warning
This ID is used to prevent duplicate card creation requests in case of a lost connection or client error, so make sure you use the same `request_id` for requests related to the same card invitation.
The deduplication is limited to 24 hours counting from the first request using a given ID.
:::
For more information, see the guides: [Manage card invitations - Idempotency](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-card-invitations#idempotency).'
maxLength: 40
expiry_period:
type: string
description: "The period after which the card invitation expires if it hasn't been claimed or cancelled. \nMust be specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) duration format.\nThe duration is counted from the card invitation creation.\n- **Minimum duration:** 1 day (`P1D`)\n- **Maximum duration:** 90 days (`P90D`)\n- **Default duration:** 90 days (`P90D`)"
pattern: ^P\d+D$
default: P90D
example: P3D
holder_id:
type: string
format: uuid
description: 'The ID of the team member who will be assigned as the holder of the card after the invitation is claimed.
:::tip
To retrieve a team member''s ID, use the [`GET /team-members` operation](https://developer.revolut.com/docs/api/business#get-team-members).
:::'
virtual:
type: boolean
enum:
- true
description: "Specifies the type of the card. \nMust be set to `true`, as with the API, you can create only virtual cards.\n\n:::tip\nTo create physical cards, use the [Revolut Business app](https://business.revolut.com).\n:::"
label:
type: string
description: 'The label for the card to be issued, displayed in the UI to help distinguish between cards.
If not specified, the default label will be set according to the card''s type.
For card invitations created via API, it''s always `Virtual`.'
minLength: 1
maxLength: 30
default: Virtual
spending_limits:
description: 'All spending limits set for the card.
You can have at most 1 periodic (day/week/month/quarter/all-time) and 1 non-periodic (single transaction) limit at a time.
If you try to specify 2 periodic limits at a time, it will result in an error.'
type: object
$ref: '#/components/schemas/SpendingLimitsSchema'
spending_period:
description: 'The controls for the card''s spending period.
They let you set the dates when the card becomes available or unavailable for spending, and define what happens after the end date.
If specified, you must provide at least one of these:
- `start_date`
- `end_date` together with `end_date_action`
The dates provided must be in the future.'
type: object
allOf:
- $ref: '#/components/schemas/SpendingPeriodSchema'
categories:
type: array
description: 'The list of merchant categories to be available for card spending.
If not specified, all categories will be allowed.
:::note
The `categories` and `merchant_controls` parameters have the following restrictions:
- If you set `categories`, you **cannot** set `merchant_controls.control_type` to `allow`.
- You **can** set `merchant_controls.control_type` to `block`.
- You may also set **either** `categories` or `merchant_controls` independently, or **set neither**.
- Both parameters can be used together **only** if `merchant_controls.control_type` is `block`.
:::'
items:
$ref: '#/components/schemas/BusinessMerchantCategory'
merchant_controls:
description: "The merchant-level controls for card spending.\n\nThey let you block or allow the card to only transact with specific merchants: \n- `allow`: permits only the specified merchants (cannot be used if the `categories` parameter is set).\n- `block`: blocks the specified merchants (can be used with or without `categories`)."
type: object
$ref: '#/components/schemas/MerchantControlsSchema'
countries:
description: Restricts card use to specified countries, provided as 2-letter [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) codes.
type: array
items:
type: string
pattern: ^[A-Z]{2}$
example: GB
accounts:
type: array
description: 'The list of accounts to link to the card.
If not specified, all accounts will be linked.
To retrieve account IDs, use the [`GET /accounts` operation](https://developer.revolut.com/docs/api/business#get-accounts).'
items:
type: string
format: uuid
required:
- request_id
- holder_id
- virtual
examples:
card_invitation_minimal_example:
$ref: '#/components/examples/cardInvitationMinCreate'
card_invitation_full_example:
$ref: '#/components/examples/cardInvitationMaxCreate'
responses:
'200':
description: Successfully created card invitation
content:
application/json:
schema:
$ref: '#/components/schemas/CardInvitationCreatedResponse'
examples:
card_invitation_response:
$ref: '#/components/examples/cardInvitationCreatedDetails'
'400':
description: "Bad Request\n\nReturned, for example, when your request is malformed, missing required fields, or when it contains fields that cannot co-exist or unsupported values.\n\nIf the invalid value is an array item, the error might indicate the array index of this faulty item, counting from `0`. \nFor example, if you provide the list of countries, such as `\"countries\": [\"GB\", \"USA\", ...]`, the first item (`GB`) has index `0`, the second item (`USA`) has index `1`, and so on.\nIn the example, `USA` is invalid, because it should be a 2-letter code.\nIn such a case, the error will indicate that `countries[1]` is invalid, thus pointing to the second item in the array, i.e. `USA`."
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missing_required_field:
summary: Merchant controls are missing merchant IDs
value:
code: 3000
message: merchant_ids is empty
categories_and_allowed_merchants_cannot_coexist:
summary: Cannot set both categories and allowed merchants
value:
code: 2101
message: Allowed merchant categories must be empty when merchant controls of type ALLOW is present
expiry_period_too_long:
summary: Expiry period is too long (max.90 days)
value:
code: 3000
message: expiry_period must be between PT24H and PT2160H
invalid_json:
summary: Invalid request body
value:
code: 3000
message: 'Cannot parse request: invalid JSON'
wrong_spending_period_date:
summary: Wrong spending period date
value:
code: 2101
message: Spending period start_date must be in the future
invalid_account_id:
summary: Invalid account ID
value:
code: 2101
message: Invalid account ids provided=[0f187658-8c07-491f-9129-ae567b829137]
invalid_country_code:
$ref: '#/components/examples/cardErrorBadCountryCode'
'401':
description: 'Unauthorised
Returned, for example, when the credentials you used to make the request are invalid.
For more information, see the **Authorization** section.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorUnauthorized'
examples:
unauthorized:
$ref: '#/components/examples/errorUnauthorized'
'404':
description: 'Team member not found
Returned when the team member specified as cardholder in `holder_id` does not exist.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 3042
message: Team member not found
'422':
description: 'Unprocessable Entity
For example, you try to set more than one periodic limit at a time, create an invitation for a deleted team member, or an unexpected error occurred when the initial request with the same `request_id` was sent.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorUnprocessableEntity'
examples:
multiple_periodic_limits:
summary: Only one periodic spending limit at a time is allowed
value:
code: 33000
message: Only one periodic limit can be set on a card
inactive_team_member:
summary: Team member not in supported state, e.g. team member was deleted
value:
message: Card invitations are only allowed for users in created state
unexpected_error:
summary: Unexpected error on initial request
value:
code: 33009
message: 'Idempotent replay failed: first execution was not successful'
'429':
description: Concurrent requests with the same idempotency key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 3162
message: Parallel requests conflict. Please synchronize your requests. request_id=5baa6989-ae59-4668-bb09-042fca180518
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
get:
summary: Retrieve a list of card invitations
operationId: getCardInvitations
description: 'Get the list of all card invitations in your organisation.
The results are paginated and sorted by the `created_at` date in reverse chronological order.
:::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).
:::
For more information, see the guides: [Manage card invitations](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-card-invitations).'
security:
- AccessToken:
- READ
tags:
- Card invitations
parameters:
- name: created_before
in: query
required: false
description: 'Retrieves only card invitations created before this timestamp (`created_at` < `created_before`).
Used for pagination.
The default value is the current date and time at which you are calling the endpoint.
Provided in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.'
schema:
type: string
format: date-time
default: the date-time at which the request is made
example: '2025-10-15T14:30:00Z'
- name: limit
in: query
required: false
description: 'The maximum number of card invitations to return per page.
To get to the next page, make a new request and use the `created_at` date of the last card invitation returned in the previous response as the value for `created_before`.'
schema:
type: number
format: integer
minimum: 1
maximum: 100
default: 100
- name: state
in: query
required: false
description: "Retrieves card invitations filtered by the specified state(s).\nTo specify multiple values, follow this pattern: `state={VALUE1}&state={VALUE2}`. \nIf not provided, all states are returned."
schema:
type: array
items:
$ref: '#/components/schemas/CardInvitationState'
style: form
explode: false
example: state=created&state=redeemed
responses:
'200':
description: The list of card invitations for your business
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CardInvitationsResponse'
examples:
list_of_card_invitations:
$ref: '#/components/examples/cardInvitationsList'
'400':
description: 'Bad request
Returned, for example, when you provide invalid query parameters.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_limit_parameter:
summary: Invalid limit parameter
value:
code: 2101
message: 'Parameter limit must be a valid integer in range: [1, 100].'
invalid_created_before_format:
summary: Invalid created_before format
value:
code: 2101
message: Parameter created_before must be a valid timestamp
invalid_state_parameter:
summary: Invalid state parameter
value:
code: 2101
message: 'Invalid card invitation state: active'
'401':
description: 'Unauthorised
Returned, for example, when the credentials you used to make the request are invalid.
For more information, see the **Authorization** section.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorUnauthorized'
examples:
unauthorized:
$ref: '#/components/examples/errorUnauthorized'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/card-invitations/{card_invitation_id}:
servers:
- url: https://b2b.revolut.com/api/1.0
description: Production server (uses live data)
get:
summary: Retrieve card invitation details
operationId: getCardInvitation
description: 'Get the details of a specific card invitation, based on its ID.
:::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).
:::
For more information, see the guides: [Manage card invitations](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-card-invitations).'
security:
- AccessToken:
- READ
tags:
- Card invitations
parameters:
- name: card_invitation_id
in: path
required: true
description: The ID of the card invitation.
schema:
type: string
format: uuid
example: 4016b891-bb50-4bd2-8a1b-adb74f4aacdd
responses:
'200':
description: Information about the card invitation
content:
application/json:
schema:
$ref: '#/components/schemas/CardInvitationResponse'
examples:
invitation_created:
$ref: '#/components/examples/cardInvitationCreatedDetails'
invitation_redeemed:
$ref: '#/components/examples/cardInvitationRedeemedDetails'
invitation_expired:
$ref: '#/components/examples/cardInvitationExpiredDetails'
invitation_failed:
$ref: '#/components/examples/cardInvitationFailedDetails'
invitation_failed_team_member_deleted:
$ref: '#/components/examples/cardInvitationFailedNoHolderDetails'
'400':
description: 'Bad request
Returned, for example, when you provide an invalid card invitation ID in the path.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_id:
$ref: '#/components/examples/cardErrorBadId'
'401':
description: 'Unauthorised
Returned, for example, when the credentials you used to make the request are invalid.
For more information, see the **Authorization** section.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorUnauthorized'
examples:
unauthorized:
$ref: '#/components/examples/errorUnauthorized'
'404':
description: Card invitation doesn't exist
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 1214
message: Card invitation not found
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
patch:
summary: Update card invitation settings
operationId: updateCardInvitation
description: 'Update settings for a specific card invitation, based on its ID.
You can update successfully created invitations that have not been claimed yet (`state=created`).
:::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).
:::
:::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.
:::
For more information, see the guides: [Manage card invitations](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-card-invitations).'
security:
- AccessToken:
- WRITE
tags:
- Card invitations
parameters:
- name: card_invitation_id
in: path
required: true
description: The ID of the card invitation.
schema:
type: string
format: uuid
example: 4016b891-bb50-4bd2-8a1b-adb74f4aacdd
requestBody:
required: true
content:
application/json:
schema:
properties:
label:
type: string
description: "The label of the card.\n\nCards without labels are not allowed.\nIf set to `null`, the default label will be set according to the card's type.\n\n:::tip[Default labels]\nFor virtual cards, the default label is `Virtual`.\nFor physical cards, depending on the type, it can be, for example, `Standard` or `Metal`. \n\nAs these values depend on available card types, they are subject to change over time.\n:::"
minLength: 1
maxLength: 30
default: Default label according to card's type
spending_limits:
description: 'All spending limits to be set for the card.
You can have at most 1 periodic (day/week/month/quarter/all-time) and 1 non-periodic (single transaction) limit at a time.
If you try to specify 2 periodic limits at a time, it will result in an error.
Use `null` as the value for a specific limit to erase that limit.
Use `null` as the value for the `spending_limits` object to erase all limits.'
type: object
$ref: '#/components/schemas/SpendingLimitsSchema'
spending_period:
description: 'The controls for the card''s spending period.
They let you set or modify the dates when the card should become available or unavailable for spending, and define what happens after the end date.
If specified, you must provide at least one of these:
- `start_date`
- `end_date` together with `end_date_action`
The spending period dates must be in the future.
The dates are inclusive.
This means that:
- If you set the `start_date` to `2026-03-31`, the card will become active on that day.
- If you set the `end_date` to `2027-12-31`, the card will be active through that day, and will be locked/terminated starting on 1st Jan 2028.
:::note
You can update the spending period settings in a few ways, depending on your use case:
- To remove the start date, but keep the end date settings, provide the current `spending_period` settings without the `start_date`.
- To remove the start date when no end date is set, provide the `spending_period.start_date` set to `null`.
- To remove **all** spending period settings, provide `spending_period` set to `null`.
If you wish to erase a spending period end date, you can do this in a similar way, applying the steps to `spending_period.end_date` and `spending_period.end_date_action`.
:::'
type: object
allOf:
- $ref: '#/components/schemas/SpendingPeriodSchema'
categories:
type: array
description: 'The list of merchant categories to be available for card spending.
Use `null` to erase the value and reset to empty (all categories will be allowed).
:::note
The `categories` and `merchant_controls` parameters have the following restrictions:
- If you set `categories`, you **cannot** set `merchant_controls.control_type` to `allow`.
- You **can** set `merchant_controls.control_type` to `block`.
- You may also set **either** `categories` or `merchant_controls` independently, or **set neither**.
- Both parameters can be used together **only** if `merchant_controls.control_type` is `block`.
:::'
items:
$ref: '#/components/schemas/BusinessMerchantCategory'
merchant_controls:
description: 'The merchant-level controls for card spending.
They let you block or allow the card to only transact with specific merchants:
- `allow`: permits only the specified merchants (cannot be used if the `categories` parameter is set).
- `block`: blocks the specified merchants (can be used with or without `categories`).'
type: object
$ref: '#/components/schemas/MerchantControlsSchema'
countries:
description: The list of countries where the card can be used, provided as 2-letter [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) codes.
type: array
items:
type: string
pattern: ^[A-Z]{2}$
example: GB
accounts:
type: array
description: 'The list of accounts to link to the card.
If not specified, all accounts will be linked.
To retrieve account IDs, use the [`GET /accounts` operation](https://developer.revolut.com/docs/api/business#get-accounts).'
items:
type: string
format: uuid
examples:
update_all_properties:
summary: Update all properties
value:
label: New card label
spending_limits:
single:
amount: 100
currency: GBP
month:
amount: 300
currency: GBP
spending_period:
start_date: '2025-12-20'
end_date: '2027-12-20'
end_date_action: lock
categories:
- services
- shopping
- furniture
merchant_controls:
control_type: block
merchant_ids:
- 46df0a1b-3678-4ded-9cf5-9f4da1b5019d
- e8a87432-f71e-4deb-be84-969a02792929
- 3f09819f-63d1-473a-966c-54d8b9f43a93
countries:
- GB
- SG
- ES
accounts:
- f52c6c84-26b9-4e95-bbcf-99ed6523fb51
- 9ae4345a-5ee5-496b-b776-241fcc5a5ba4
erase_spending_period_start_date:
summary: Erase spending period start date and update end date
value:
spending_period:
start_date: null
end_date: '2027-12-20'
end_date_action: terminate
erase_all_spending_limits:
summary: Erase all spending limits
value:
spending_limits: null
erase_single_transaction_limit:
summary: Erase the single-transaction limit
value:
spending_limits:
single: null
allow_specific_merchants:
summary: Allow only specific merchants
value:
categories: []
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/revolut/refs/heads/main/openapi/revolut-card-invitations-api-openapi.yml