Use the Business API to manage team members and their roles.
About team members
Your team means a group of users who have access to your Revolut Business account. When you invite people to your business, it means that you add them to this team and assign them a role in the team.
The invited user receives an email with an invitation link. To join the team, the invitee has to accept the invitation.
You can use the API to retrieve the list of your team members.
Roles
A role is a defined set of permissions, for example, View cards, Manage users, etc.
Team members can have different roles in your team.
The creator of the business has a special role, Owner, which can only be assigned to one team member.
The Owner role is not transferable unless the existing owner leaves the team.
In such a case, this role must be transferred to another team member when terminating the leaving owner's account.
All the other roles can be assigned to multiple members. However, one member can have only one role assigned at a time.
All businesses have predefined roles, such as Admin or Member, but a business can also add custom roles through the Revolut Business app.
You can use the API to retrieve roles available for your business together with their IDs.
You decide which role to assign to the user when you invite them to the team. If you want to change it later, you can do so in the Revolut Business app or via the API using the Update a team member's role endpoint.
In the app, you can also see specific permissions assigned to a role, edit permissions, or edit roles.
Manage team members via API
The Business API lets you:
- Add team members to your Revolut Business account and assign them roles
- Retrieve the list of added team members
- Retrieve a single team member by ID
- Retrieve the list of roles for your business team members
- Update a team member's role
- Assign or remove a department from a team member
- Assign or remove a manager for a team member
- Suspend or unsuspend team members
- Delete team members
Invite a new member
To invite a new team member to your Revolut Business account, you must provide their email address and specify the role that should be assigned to this member.
In the response, you get the invited member's ID and email address, the ID of the role that should be assigned to the member and the date-times of creation and last update.
To see example requests and responses:
See the API reference: Invite a new member to your business
Retrieve a list of team members
You can list all the team members added to your Revolut Business account. You can also filter the team members by the date they were added to your account.
The results are paginated and sorted by the created_at date in reverse chronological order.
In the response, you get the member's details, such as their ID and email address, their first and last name, the state that the team member's user is in, the ID of the role assigned to the team member, and the date-times of creation and last update. The response also includes the IDs of the department and manager assigned to the team member, if present.
To see example requests and responses:
See the API reference: Retrieve a list of team members
Retrieve a team member
To get the details of a specific team member, make a GET request providing the team member's ID.
In the response, you get the same member details as in the list endpoint: their ID, email address, first and last name, state, role ID, and the date-times of creation and last update. The response also includes the IDs of the department and manager assigned to the team member, if present.
To see example requests and responses:
See the API reference: Retrieve a team member
Retrieve a list of roles for your business
You can list the roles that can be assigned to a team member of your Revolut Business account. You can also filter the roles by the date they were created.
The results are paginated and sorted by the created_at date in reverse chronological order.
In the response, for each role you get its ID, name, and the date-times of creation and last update.
To see example requests and responses:
See the API reference: Retrieve team roles
Use the Revolut Business app to create custom roles, see specific permissions assigned to a role, and edit permissions and roles.
Filtering and pagination
When retrieving team members or roles, you can also include the optional query parameters to:
- Modify the maximum number of items returned per page (by default, it's
100) - Retrieve only the items which were created before a date/date-time that you specify
For example, these parameters limit the number of team members to three and retrieve only the members added before 13th June 2023:
/team-members?limit=3&created_before=2023-06-13To get to the next page, make a new request and use the created_at date of the last returned item as created_before.
Update a team member's role
To change the role assigned to a team member, make a PUT request providing the team member's ID and the new role ID.
You cannot modify the business owner or assign the owner role to another team member.
On success, you get a 204 response with no additional content.
To see example requests and responses:
See the API reference: Update a team member's role
Assign or remove a department
To assign a department to a team member, make a PUT request providing the team member's ID and the new department ID.
To see example requests and responses:
See the API reference: Assign a department to a team member
To remove the department assignment, make a DELETE request to the same endpoint with the team member's ID.
To see example requests and responses:
See the API reference: Remove department from a team member
On success, you get a 204 response with no additional content.
For more information about managing departments, see Manage departments.
Assign or remove a manager
To assign a manager to a team member, make a PUT request providing the team member's ID and the manager_id. The manager must be an existing team member in the same business.
To see example requests and responses:
See the API reference: Assign a manager to a team member
To remove the manager assignment, make a DELETE request to the same endpoint with the team member's ID.
To see example requests and responses:
See the API reference: Remove manager from a team member
On success, you get a 204 response with no additional content.
Suspend and unsuspend a team member
Suspending a team member prevents them from accessing your Revolut Business account. You can unsuspend them at any time to restore their access.
To suspend a team member, make a POST request providing the team member's ID.
You cannot suspend the business owner. You cannot suspend or unsuspend a team member who hasn't accepted their invitation yet.
To see example requests and responses:
See the API reference: Suspend a team member
To unsuspend, use the unsuspend endpoint with the same team member's ID.
To see example requests and responses:
See the API reference: Unsuspend a team member
On success, you get a 204 response with no additional content.
Delete a team member
To delete a team member, you simply make a DELETE call providing this member's ID.
On successful deletion, you get a 204 response with no additional content.
To see example requests and responses:
See the API reference: Delete a team member
Sample flow: organisational restructure
The following script demonstrates a full organisational restructure using the Business API. It covers two phases: setting up a new department with a promoted team lead and new hires, then closing a department after employees leave.
The script also demonstrates suspending and unsuspending team members: the backfill member was invited in advance but suspended until their start date, and departing members in the closing department are suspended before being removed.
Replace the placeholder IDs and names with real values from your business before running it.
import requests
# =============================================
# Configuration
# =============================================
API_URL = "https://sandbox-b2b.revolut.com/api/1.0"
API_TOKEN = "YOUR_ACCESS_TOKEN"
HEADERS = {"Authorization": f"Bearer {API_TOKEN}", "Content-Type": "application/json"}
# Existing team member being promoted to head the new department
PROMOTED_MEMBER_ID = "11111111-1111-1111-1111-111111111111"
# Their new manager (another existing team member)
NEW_MANAGER_ID = "22222222-2222-2222-2222-222222222222"
# New hire who will backfill the promoted member's previous role
BACKFILL_MEMBER_ID = "33333333-3333-3333-3333-333333333333"
# Department being closed
CLOSING_DEPT_ID = "cccccccc-cccc-cccc-cccc-cccccccccccc"
# Emails of new hires joining the new department
NEW_TEAM_EMAILS = [
"dana.white@example.com",
"edward.black@example.com",
"fiona.green@example.com",
]
NEW_MEMBER_ROLE_ID = "member" # Retrieve available roles with GET /roles
HEAD_ROLE_ID = "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
NEW_DEPT_NAME = "Platform Engineering"
def api(method, path, body=None):
"""Make an API request and return the JSON response (or None for 204)."""
resp = requests.request(method, f"{API_URL}{path}", headers=HEADERS, json=body)
if not resp.ok:
print(f"ERROR {resp.status_code} {method} {path}: {resp.text}")
resp.raise_for_status()
return resp.json() if resp.content else None
def fmt_name(m):
"""Return 'First Last' or fall back to email if names are null."""
name = f"{m.get('first_name') or ''} {m.get('last_name') or ''}".strip()
return name or m["email"]
# Build a lookup of role IDs to names
roles = api("GET", "/roles?limit=1000")
role_names = {r["id"]: r["name"] for r in roles}
# =============================================
# Phase 1: New department and team growth
# =============================================
print(f"=== Phase 1: Setting up {NEW_DEPT_NAME} ===")
# 1. Create the new department
dept = api("POST", "/departments", {"name": NEW_DEPT_NAME})
dept_id = dept["id"]
print(f"Created department '{NEW_DEPT_NAME}' with ID: {dept_id}")
# 2. Assign an existing team member to the new department, then promote them to head it
# Save their current role and department so we can backfill later.
promoted = api("GET", f"/team-members/{PROMOTED_MEMBER_ID}")
previous_role_id = promoted.get("role_id")
previous_dept_id = promoted.get("department_id")
api("PUT", f"/team-members/{PROMOTED_MEMBER_ID}/department", {"department_id": dept_id})
print(f"Assigned {fmt_name(promoted)} to '{NEW_DEPT_NAME}'")
api("PUT", f"/team-members/{PROMOTED_MEMBER_ID}/role", {"role_id": HEAD_ROLE_ID})
print(f"Promoted {fmt_name(promoted)} to {role_names[HEAD_ROLE_ID]}")
manager = api("GET", f"/team-members/{NEW_MANAGER_ID}")
api("PUT", f"/team-members/{PROMOTED_MEMBER_ID}/manager", {"manager_id": NEW_MANAGER_ID})
print(f"Assigned {fmt_name(manager)} as manager to {fmt_name(promoted)}")
# 3. Invite new hires and assign them to the department
for email in NEW_TEAM_EMAILS:
member = api("POST", "/team-members", {"email": email, "role_id": NEW_MEMBER_ROLE_ID})
api("PUT", f"/team-members/{member['id']}/department", {"department_id": dept_id})
api("PUT", f"/team-members/{member['id']}/manager", {"manager_id": PROMOTED_MEMBER_ID})
print(f"- Invited {email}")
print(f"Invited {len(NEW_TEAM_EMAILS)} team members to '{NEW_DEPT_NAME}'")
# 4. Backfill the promoted member's previous role
# Unsuspend the backfill member (they were invited but hadn't started yet)
backfill = api("GET", f"/team-members/{BACKFILL_MEMBER_ID}")
api("POST", f"/team-members/{BACKFILL_MEMBER_ID}/unsuspend")
print(f"Unsuspended {fmt_name(backfill)}")
api("PUT", f"/team-members/{BACKFILL_MEMBER_ID}/role", {"role_id": previous_role_id})
if previous_dept_id:
api("PUT", f"/team-members/{BACKFILL_MEMBER_ID}/department", {"department_id": previous_dept_id})
print(f"Backfilled role '{role_names[previous_role_id]}' with {fmt_name(backfill)} (replacement for {fmt_name(promoted)})")
# =============================================
# Phase 2: Department closure
# =============================================
closing = api("GET", f"/departments/{CLOSING_DEPT_ID}")
print(f"\n=== Phase 2: Closing '{closing['name']}' ===")
# 5. Suspend all team members in the closing department
members = api("GET", "/team-members?limit=1000")
closing_members = [m for m in members if m.get("department_id") == CLOSING_DEPT_ID]
for m in closing_members:
api("POST", f"/team-members/{m['id']}/suspend")
print(f"Suspended {fmt_name(m)}")
# 6. Remove suspended members from the department and delete them
for m in closing_members:
api("DELETE", f"/team-members/{m['id']}/department")
api("DELETE", f"/team-members/{m['id']}/manager")
api("DELETE", f"/team-members/{m['id']}")
print(f"Removed {fmt_name(m)}")
# 7. Delete the department
api("DELETE", f"/departments/{CLOSING_DEPT_ID}")
print(f"Deleted department '{closing['name']}'")Sample output:
=== Phase 1: Setting up 'Platform Engineering' ===
Created department 'Platform Engineering' with ID: 9b3f7a2c-1d4e-4f5b-8a6c-7d8e9f0a1b2c
Assigned Alice Johnson to 'Platform Engineering'
Promoted Alice Johnson to Head of Department
Assigned Bob Smith as manager to Alice Johnson
- Invited dana.white@example.com
- Invited edward.black@example.com
- Invited fiona.green@example.com
Invited 3 team members to 'Platform Engineering'
Unsuspended Carol White
Backfilled role 'Member' with Carol White (replacement for Alice Johnson)
=== Phase 2: Closing 'Public Relations' ===
Suspended Dave Brown
Suspended Eve Green
Removed Dave Brown
Removed Eve Green
Deleted department 'Public Relations'The API does not support creating or deleting roles. To create custom roles, edit or delete existing ones, use the Revolut Business app.
What's next
- See how to manage cards for your team.
- See how to manage departments for your team members.