Retrieve information on existing team members of your organisation, delete team members, and invite new members. For more information, see the guides: [Manage team members](https://developer.revolut.com/docs/guides/manage-accounts/teams/manage-team-members).
openapi: 3.0.1
info:
version: '1.0'
title: Business Accounting Team members 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: Team members
description: 'Retrieve information on existing team members of your organisation, delete team members, and invite new members.
For more information, see the guides: [Manage team members](https://developer.revolut.com/docs/guides/manage-accounts/teams/manage-team-members).'
paths:
/team-members:
get:
summary: Retrieve a list of team members
operationId: getTeamMembers
description: 'Get information about all the team members of your business.
The results are paginated and sorted by the `created_at` date in reverse chronological order.
For more information, see the guides: [Manage team members](https://developer.revolut.com/docs/guides/manage-accounts/teams/manage-team-members).'
security:
- AccessToken:
- READ
tags:
- Team members
parameters:
- in: query
name: created_before
schema:
type: string
format: date-time
default: the date-time at which the request is made
description: 'Retrieves team members with `created_at` < `created_before`.
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.'
- name: limit
in: query
required: false
description: 'The maximum number of team members returned per page.
To get to the next page, make a new request and use the `created_at` date of the last team member returned in the previous response as the value for `created_before`.'
schema:
type: number
format: integer
default: 100
maximum: 1000
minimum: 1
responses:
'200':
description: Information about team members of the business
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TeamMember'
example:
- email: john.doe@example.com
id: 76969b71-a123-42dc-b874-a34688d7bba4
role_id: owner
state: active
first_name: John
last_name: Doe
created_at: '2022-09-07T09:19:31.592368Z'
updated_at: '2022-09-07T09:21:24.346670Z'
- email: john.smith@example.com
id: 168922e1-594f-4ca0-93b2-56b742f3936b
role_id: 024abb3d-06da-4701-9254-dfcc3da38385
state: active
created_at: '2022-09-07T09:19:32.592368Z'
updated_at: '2022-09-07T09:21:25.346670Z'
'400':
description: Bad pagination parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 2101
message: 'Parameter limit must be a valid integer in range: [1, 1000].'
'401':
description: 'Unauthorized
Returned when the request was not fulfilled because authentication has failed or has not been provided'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 401
message: The request should be authorized.
'403':
description: 'Action forbidden
Returned, for example, when you don''t have permissions necessary to retrieve team members'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 9002
message: This action is forbidden
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
summary: Invite a new member to your business
operationId: inviteTeamMember
description: 'Invite a new member to your business account.
When you invite a new team member to your business account, an invitation is sent to their email address that you provided in this request.
To join your business account, the new team member has to accept this invitation.
For more information, see the guides: [Manage team members](https://developer.revolut.com/docs/guides/manage-accounts/teams/manage-team-members).'
security:
- AccessToken:
- WRITE
tags:
- Team members
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
email:
type: string
description: The email address of the invited member.
format: email
role_id:
type: string
description: The ID of the [role](https://developer.revolut.com/docs/api/business#get-roles) to assign to the new member.
required:
- email
- role_id
example:
email: john.smith@example.com
role_id: 0098ac28-b92f-435e-a3a2-2829d3918dfb
responses:
'201':
description: Information about the new member
content:
application/json:
schema:
type: object
properties:
email:
type: string
description: The email address of the invited member.
format: email
id:
type: string
description: The ID of the invited member.
role_id:
type: string
description: The ID of the [role](https://developer.revolut.com/docs/api/business#get-roles) assigned to the member.
created_at:
type: string
format: date-time
description: The date and time when the member was created.
updated_at:
type: string
format: date-time
description: The date and time when the member was last updated.
required:
- email
- id
- role_id
- created_at
- updated_at
example:
email: john.smith@example.com
id: 76969b71-a123-42dc-b874-a34688d7bba4
role_id: 0098ac28-b92f-435e-a3a2-2829d3918dfb
created_at: '2022-09-07T09:19:31.592368Z'
updated_at: '2022-09-07T09:21:24.346670Z'
'400':
description: Bad request, for example, invalid role ID or invalid email address provided
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_role_id_uuid:
summary: Invalid role ID (UUID)
value:
code: 3053
message: Business role 0098ac28-b92f-435e-a3a2-2829d3918dfb not found
invalid_role_id_default:
summary: Invalid role ID (non-UUID)
value:
code: 3402
message: 'Invalid role: nonexistent_role_id'
invalid_email:
summary: Invalid email address
value:
code: 3000
message: 'Invalid email address: (masked) ****.*******.*******.***'
'401':
description: 'Unauthorized
Returned when the request was not fulfilled because authentication has failed or has not been provided'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 401
message: The request should be authorized.
'403':
description: 'Action forbidden
Returned, for example, when you don''t have permissions necessary to invite team members'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 9002
message: This action is forbidden
'422':
description: Team member with the given email cannot be invited
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
user_already_invited:
summary: Team member already invited
value:
code: 33005
message: Team member with given email has already been invited.
user_is_member_of_another_business:
summary: Team member cannot be invited
value:
code: 33008
message: Team member with given email cannot be invited.
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/team-members/{team_member_id}:
delete:
summary: Delete a team member
operationId: deleteTeamMember
description: 'Delete a specific member of your team.
:::note
This action does not delete the person’s Revolut Business user account – it only removes them from your team.
They will lose access to your Revolut Business account and team but can still log in to Revolut Business.
Their user account will remain linked to any other teams and accounts it’s associated with.
:::
For more information, see the guides: [Manage team members](https://developer.revolut.com/docs/guides/manage-accounts/teams/manage-team-members).'
security:
- AccessToken:
- WRITE
tags:
- Team members
parameters:
- name: team_member_id
description: The ID of the team member to delete.
in: path
required: true
schema:
type: string
format: uuid
example: 76969b71-a123-42dc-b874-a34688d7bba4
responses:
'204':
description: Team member was deleted
'401':
description: 'Unauthorized
Returned when the request was not fulfilled because authentication has failed or has not been provided'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 401
message: The request should be authorized.
'403':
description: 'Action forbidden
Returned, for example, when you don''t have permissions necessary to delete team members'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 9002
message: This action is forbidden
'404':
description: 'Not found
Returned when the team member that you''re trying to delete doesn''t exist.
This can happen when, for example, the team member has already been deleted, or the provided team member ID is incorrect.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 3006
message: Resource not found
'422':
description: Cannot modify owner
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 3547
message: Cannot modify owner
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/roles:
get:
summary: Retrieve team roles
operationId: getRoles
description: 'Get the list of roles for your business.
The results are paginated and sorted by the `created_at` date in reverse chronological order.
For more information, see the guides: [Manage team members](https://developer.revolut.com/docs/guides/manage-accounts/teams/manage-team-members).'
security:
- AccessToken:
- READ
tags:
- Team members
parameters:
- in: query
name: created_before
schema:
type: string
format: date-time
default: the date-time at which the request is made
description: 'Retrieves roles with `created_at` < `created_before`.
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.'
- name: limit
in: query
required: false
description: 'The maximum number of roles returned per page.
To get to the next page, make a new request and use the `created_at` date of the last role returned in the previous response as the value for `created_before`.'
schema:
type: number
format: integer
default: 100
maximum: 1000
minimum: 1
responses:
'200':
description: Information about roles of the business
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Role'
example:
- id: owner
name: Owner
created_at: '2023-09-07T09:21:12.962303Z'
updated_at: '2023-09-07T09:21:12.962303Z'
- id: member
name: Member
created_at: '2023-09-07T09:21:12.962303Z'
updated_at: '2023-09-07T09:21:12.962303Z'
- id: viewer
name: Viewer
created_at: '2023-09-07T09:21:12.962303Z'
updated_at: '2023-09-07T09:21:12.962303Z'
- id: a40b6121-350b-4d2e-9ba1-9dab61a18d46
name: Example custom role
created_at: '2023-09-07T09:21:12.963143Z'
updated_at: '2023-09-07T09:21:12.963143Z'
'400':
description: Bad pagination parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: '2101'
message: 'Parameter limit must be a valid integer in range: [1, 1000].'
'401':
description: 'Unauthorized
Returned when the request was not fulfilled because authentication has failed or has not been provided'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 401
message: The request should be authorized.
'403':
description: 'Action forbidden
Returned, for example, when you don''t have permissions necessary to retrieve roles'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 9002
message: This action is forbidden
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
TeamMemberState:
description: The state that the team member is in.
enum:
- created
- confirmed
- waiting
- active
- locked
- disabled
type: string
TeamMember:
type: object
properties:
id:
type: string
description: The ID of the team member.
format: uuid
email:
type: string
description: The email of the team member.
format: email
first_name:
type: string
description: The team member's first name.
last_name:
type: string
description: The team member's last name.
state:
$ref: '#/components/schemas/TeamMemberState'
role_id:
type: string
description: The ID of the team member's [role](https://developer.revolut.com/docs/api/business#get-roles). This can be a UUID or other default role such as `Owner`.
created_at:
type: string
description: The date and time the team member was created in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
format: date-time
updated_at:
type: string
description: The date and time the team member was last updated in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
format: date-time
required:
- id
- email
- state
- role_id
- created_at
- updated_at
Error:
type: object
properties:
code:
type: integer
description: The error code.
message:
type: string
description: The description of the error.
required:
- code
- message
Role:
type: object
properties:
id:
type: string
description: The ID of the role. This can be a UUID or other default role such as `OWNER`.
name:
type: string
description: The name of the role.
created_at:
type: string
description: The date and time the role was created in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
format: date-time
updated_at:
type: string
description: The date and time the role was last updated in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
format: date-time
required:
- id
- name
- created_at
- updated_at
securitySchemes:
AccessToken:
type: http
scheme: bearer
description: "Each Business API request must contain an authorization header in the following format to make a call: `Bearer <your_access_token>`.\n\nThe access token will be obtained the first time you set up your application and has an expiration of 40 minutes. \nDuring setup, a `refresh_token` will also be obtained which allows to obtain a new `access_token`.\n\n:::danger\nNever share your client-assertion JWT (JSON web token), `access_token` and `refresh_token` with anyone, as these can be used to access your banking data and initiate transactions.\n:::\n\nAccess tokens can be issued with four security scopes and require a JWT (JSON Web Token) signature to be obtained:\n- `READ`: Permissions for `GET` operations.\n- `WRITE`: Permissions to update counterparties, webhooks, and issue payment drafts.\n- `PAY`: Permissions to initiate or cancel transactions and currency exchanges. \n- `READ_SENSITIVE_CARD_DATA`: Permissions to retrieve sensitive card details.\n\n :::warning\n If you enable the `READ_SENSITIVE_CARD_DATA` scope for your access token, you must set up IP whitelisting. \n Failing to do so will prevent you from accessing **any** Business API endpoint. \n\n IP whitelisting means that you must specify an IP or a set of IPs which will be the only IPs from which requests to the API will be accepted. \n To do so:\n 1. Go to the Revolut Business web app [settings](https://business.revolut.com/settings) → **APIs** → **Business API**.\n 2. Select the corresponding API certificate.\n 3. In **Production IP whitelist**, provide the IP(s) which should be whitelisted.\n Make sure that the IPs you provide are **not** [local (i.e. private) IP addresses](https://www.okta.com/en-sg/identity-101/understanding-private-ip-ranges/). \n 4. Save the new settings.\n :::\n\nTo configure your JWT and obtain the refresh and first access tokens, complete the following steps:\n\n 1. [Sign up for a Revolut Business account](https://developer.revolut.com/docs/guides/manage-accounts/get-started/sign-up-for-revolut-business-account)\n 2. [Prepare your Sandbox environment](https://developer.revolut.com/docs/guides/manage-accounts/get-started/prepare-sandbox-environment)\n 3. [Make your first API request](https://developer.revolut.com/docs/guides/manage-accounts/get-started/make-your-first-api-request)"