openapi: 3.0.1
info:
version: '1.0'
title: Business Accounting Labels 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: Labels
description: 'Manage accounting labels and label groups for your business.
Create, retrieve, update, and delete label groups and labels that can be added to your financial records such as [expenses](https://developer.revolut.com/docs/guides/manage-accounts/accounts-and-transactions/retrieve-expenses).
For more information, see the guides: [Manage accounting settings](https://developer.revolut.com/docs/guides/manage-accounts/accounting/manage-accounting-settings), and [Manage labels and label groups](https://developer.revolut.com/docs/guides/manage-accounts/accounting/manage-labels-and-label-groups).
See also the Revolut Help Centre: [Expenses](https://help.revolut.com/business/help/managing-my-business/expenses/).'
paths:
/label-groups:
post:
summary: Create a new label group
operationId: createLabelGroup
description: 'Add a new group of labels that can be applied to your financial records, such as expenses.
:::note
- This operation is not supported for [externally managed label groups](https://developer.revolut.com/docs/guides/manage-accounts/accounting/manage-labels-and-label-groups#externally-managed-settings).
- You can have up to 5 label groups at a time per business.
:::
For more details, see the guides: [Manage accounting settings](https://developer.revolut.com/docs/guides/manage-accounts/accounting/manage-accounting-settings) and [Manage labels and label groups](https://developer.revolut.com/docs/guides/manage-accounts/accounting/manage-labels-and-label-groups).'
security:
- AccessToken:
- WRITE
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateLabelGroupRequest'
examples:
department_labels:
summary: Label group for Department
value:
name: Department
labels:
- name: Sales & Account Management
- name: Product Management
- name: Design & UX
- name: Customer Success
- name: Engineering
- name: Research & Development
- name: Operations
- name: Quality Assurance
- name: Data Science & Analytics
- name: Executive & Leadership
team_labels:
summary: Label group for Team
value:
name: Team
labels:
- name: Brand Design & Creative Services
- name: Enterprise Sales (Europe)
- name: Cloud Infrastructure & DevOps
- name: Growth & Performance Marketing
- name: Mobile App Development
responses:
'201':
description: 'Resource created
On successful creation, the response returns only the ID of the new resource (i.e. the label group), even if the resource has more properties.
To get all the details of the label group, use the returned resource ID with a [GET request](https://developer.revolut.com/docs/api/business#get-label-group).'
$ref: '#/components/responses/ResourceCreatedResponse'
'400':
description: 'Bad Request
Returned, for example, when a required parameter is missing or malformatted.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
examples:
param_required:
summary: Required parameter is missing
value:
error_id: 69bc43d4-0ebf-4f7c-88e0-ebb7a1441a18
code: 2101
message: '''labels'' is required'
bad_param_type:
summary: Incorrect parameter type
value:
error_id: 69bc4467-8042-446f-b362-675e2921d71c
code: 2101
message: '''labels'' must be an array'
invalid_json:
summary: Invalid JSON
value:
error_id: 69bc1985-1313-42f0-8c0b-3673c665f135
code: 2101
message: Request body is not valid JSON
param_value_too_short:
summary: Parameter value too short
value:
error_id: 7acc6073-5290-45f8-8956-c79d487ef1e5
code: 2101
message: '''name'' must be at least 1 character'
param_value_too_long:
summary: Parameter value too long
value:
error_id: c4da2d3c-1cd8-4bbc-ac43-233575e471b7
code: 2101
message: '''name'' must be at most 100 characters'
param_value_missing:
summary: Parameter value too long
value:
error_id: c4da2d3c-1cd8-4bbc-ac43-233575e471b7
code: 2101
message: '''labels'' must not be empty'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
description: 'Conflict
Request conflicts with the current state of the resource.
Returned, for example, when a label group with the provided name already exists.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
example:
error_id: 69bc49bc-4e57-4768-ab6e-f281da25aa2b
code: 3506
message: Label group with name 'My Unique Label Group' already exists
'422':
description: "Unprocessable entity - label group cannot be created due to business rules \n\nReturned, for example, when you have an accounting software integration connected to your Revolut Business account, and labels are managed by that integration.\n\nThe request is well-formed and the server understands it, but the operation cannot be performed because the resource state doesn't permit it.\nRetrying the same request won't succeed."
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
examples:
cannot_modify_externally_managed_resource:
summary: Labels and label groups are managed by integration, cannot be created manually
value:
error_id: e950c41e-cfd6-4e04-bd79-2d57a3951774
code: 3514
message: Labels are managed by your connected accounting integration and cannot be modified manually
group_limit_exceeded:
summary: Label groups limit exceeded
value:
error_id: 69bc3507-cfd6-4e04-bd79-2d57a3951774
code: 3591
message: Maximum of 5 label groups per business reached
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
tags:
- Labels
get:
summary: Retrieve a list of label groups
operationId: getLabelGroups
description: 'Get available label groups based on the provided query criteria.
The label groups are sorted by the `created_at` date in reverse chronological order, and they''re **paginated**.
For more details, see the guides: [Manage accounting settings](https://developer.revolut.com/docs/guides/manage-accounts/accounting/manage-accounting-settings) and [Manage labels and label groups](https://developer.revolut.com/docs/guides/manage-accounts/accounting/manage-labels-and-label-groups).'
security:
- AccessToken:
- READ
parameters:
- name: limit
in: query
required: false
description: 'The page size, that is, the maximum number of label groups to return per page.
To get the next page of results, use `page_token`.'
schema:
type: integer
minimum: 1
maximum: 500
default: 100
example: 10
- $ref: '#/components/parameters/PageToken'
responses:
'200':
description: List of label groups
content:
application/json:
schema:
type: object
properties:
next_page_token:
$ref: '#/components/schemas/PageToken'
label_groups:
description: List of label groups.
type: array
items:
$ref: '#/components/schemas/LabelGroupResponse'
required:
- label_groups
examples:
results_with_next_page:
summary: Results exceed page size (when limit=5) & next page available
value:
next_page_token: MjAyNi0wMS0wMVQwOToxMzoxNS40MDZaN2RhNTFjZGY0LTZiYjctNDRkNi04OWU1LTc2OWEzZGYxZDc5ZA
label_groups:
- id: f0e1d2c3-b4a5-4678-9012-3456789abcde
name: Department
created_at: '2026-03-19T07:15:00.000000Z'
updated_at: '2026-03-19T08:45:22.111444Z'
- id: f09ad1ad3-a1c0-4c09-b8f8-24b439e72690
name: Employee
created_at: '2026-03-11T10:33:51.121090Z'
updated_at: '2026-03-11T10:33:51.121090Z'
- id: a1b2c3d4-e5f6-4a5b-bc6d-7e8f9a0b1c2d
name: Project
created_at: '2026-02-01T08:00:00.000000Z'
updated_at: '2026-02-01T08:00:00.000000Z'
- id: 5f4e3d2c-1b0a-4987-8765-43210fedcba9
name: Location
created_at: '2026-01-15T10:20:30.123456Z'
updated_at: '2026-03-10T14:45:12.987654Z'
- id: 98765432-abcd-ef01-2345-67890abcdef0
name: Task
created_at: '2025-12-20T11:11:11.000Z'
updated_at: '2026-03-15T09:30:00.555222Z'
results_single_page:
summary: Results fit within page size, no more pages available
value:
label_groups:
- id: f0e1d2c3-b4a5-4678-9012-3456789abcde
name: Department
created_at: '2026-03-19T07:15:00.000000Z'
updated_at: '2026-03-19T08:45:22.111444Z'
- id: f09ad1ad3-a1c0-4c09-b8f8-24b439e72690
name: Employee
created_at: '2026-03-11T10:33:51.121090Z'
updated_at: '2026-03-11T10:33:51.121090Z'
- id: a1b2c3d4-e5f6-4a5b-bc6d-7e8f9a0b1c2d
name: Project
created_at: '2026-02-01T08:00:00.000000Z'
updated_at: '2026-02-01T08:00:00.000000Z'
- id: 5f4e3d2c-1b0a-4987-8765-43210fedcba9
name: Location
created_at: '2026-01-15T10:20:30.123456Z'
updated_at: '2026-03-10T14:45:12.987654Z'
- id: 98765432-abcd-ef01-2345-67890abcdef0
name: Task
created_at: '2025-12-20T11:11:11.000Z'
updated_at: '2026-03-15T09:30:00.555222Z'
'400':
description: 'Bad Request
Returned, for example, when a required parameter is missing or malformatted.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
examples:
bad_param_type:
summary: Incorrect query parameter type
value:
error_id: 29146977-8042-446f-b362-af224b14c830
code: 2101
message: Query parameter 'limit' must be an integer
param_value_too_low:
summary: Query parameter value too low
value:
error_id: b5a51cd1-9d0f-4074-adae-675e2921d71c
code: 2101
message: Query parameter 'limit' must be at least 1
param_value_too_high:
summary: Query parameter value too high
value:
error_id: fa12f45e-4633-4f78-8d40-42dadc380511
code: 2101
message: Query parameter 'limit' must be at most 500
multiple_values_not_allowed:
summary: Multiple values provided for a single-value query parameter
value:
error_id: c4da2d3c-1cd8-4bbc-ac43-233575e471b7
code: 2101
message: Query parameter 'limit' must have a single value
param_cannot_be_empty:
summary: Query parameter provided without a value
value:
error_id: fa12f45e-0ebf-4f7c-88e0-3673c665f135
code: 2101
message: Query parameter 'limit' must not be empty
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
tags:
- Labels
/label-groups/{group_id}:
get:
summary: Retrieve label group details
operationId: getLabelGroup
description: 'Get the details of a specific label group based on the label group ID.
The details include the label group name, as well as when the label group was added to your settings, and when it was last updated.
For more details, see the guides: [Manage accounting settings](https://developer.revolut.com/docs/guides/manage-accounts/accounting/manage-accounting-settings) and [Manage labels and label groups](https://developer.revolut.com/docs/guides/manage-accounts/accounting/manage-labels-and-label-groups).'
security:
- AccessToken:
- READ
parameters:
- name: group_id
in: path
description: The ID of the label group to retrieve.
required: true
schema:
type: string
format: uuid
example: 09ad1ad3-a1c0-4c09-b8f8-24b439e72690
responses:
'200':
description: Label group details
content:
application/json:
schema:
$ref: '#/components/schemas/LabelGroupResponse'
example:
id: 09ad1ad3-a1c0-4c09-b8f8-24b439e72690
name: Department
created_at: '2026-03-11T10:33:51.121090Z'
updated_at: '2026-03-11T10:33:51.121090Z'
'400':
description: 'Bad Request
Returned, for example, when a required parameter is missing or malformatted.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
examples:
bad_param_format:
summary: Incorrect path parameter format
value:
error_id: f70973ea-c939-41f8-a106-1656ab5fae2f
code: 2101
message: Path parameter 'id' must be a valid UUID
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: 'Not found
Returned when the label group that you''re trying to retrieve cannot be found.
This can happen, for example, when the label group has been deleted, or the provided label group ID is incorrect.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
example:
error_id: cbb15721-5f51-4588-a959-7494bb7ba827
code: 3006
message: Label group with id 8945879d-6854-4e10-88d6-ce92c5f010ac not found
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
tags:
- Labels
patch:
summary: Update label group settings
operationId: updateLabelGroup
description: 'Update the name for a specific label group, based on its ID.
:::note
This operation is not supported for [externally managed label groups](https://developer.revolut.com/docs/guides/manage-accounts/accounting/manage-labels-and-label-groups#externally-managed-settings).
:::
For more details, see the guides: [Manage accounting settings](https://developer.revolut.com/docs/guides/manage-accounts/accounting/manage-accounting-settings) and [Manage labels and label groups](https://developer.revolut.com/docs/guides/manage-accounts/accounting/manage-labels-and-label-groups).'
security:
- AccessToken:
- WRITE
parameters:
- name: group_id
in: path
description: The ID of the label group to update.
required: true
schema:
type: string
format: uuid
example: 09ad1ad3-a1c0-4c09-b8f8-24b439e72690
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateLabelGroupRequest'
example:
name: 20% VAT
responses:
'204':
description: Label group updated
'400':
description: 'Bad Request
Returned, for example, when a required parameter is missing or malformatted.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
examples:
param_required:
summary: Body is empty
value:
error_id: f1059c4b-4278-45d3-a17f-bd433ab33c15
code: 2101
message: Request body must not be empty
bad_param_format:
summary: Incorrect parameter format
value:
error_id: f70973ea-c939-41f8-a106-1656ab5fae2f
code: 2101
message: Path parameter 'id' must be a valid UUID
invalid_json:
summary: Invalid JSON
value:
error_id: 36f3cec5-b4b9-431f-9c28-afd3899bc64f
code: 2101
message: Request body is not valid JSON
param_value_too_short:
summary: Parameter value too short
value:
error_id: 32fd0697-2f3f-4308-b25d-c9230f99c589
code: 2101
message: '''name'' must be at least 1 character'
param_value_too_long:
summary: Parameter value too long
value:
error_id: d8d919b5-d667-4058-9bb3-17b6f7bcd6c8
code: 2101
message: '''name'' must be at most 20 characters'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: 'Not found
Returned when the label group that you''re trying to update cannot be found.
This can happen, for example, when the label group doesn''t exist, or the provided label group ID is incorrect.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
example:
error_id: ca73d8a4-a5cb-4f03-9a95-4d53aa1731b0
code: 3006
message: Label group with id be6c9d90-df25-458a-b559-be61896c94b8 not found
'409':
description: 'Conflict
Request conflicts with the current state of the resource.
Returned, for example, when a label group with the provided name already exists.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
example:
error_id: 8c08b656-4e57-4768-ab6e-f281da25aa2b
code: 3506
message: Label group with name 'My Unique Label Group' already exists
'422':
description: "Unprocessable entity - label group cannot be updated due to business rules \n\nReturned, for example, when you have an accounting software integration connected to your Revolut Business account, and label groups are managed by that integration.\n\nThe request is well-formed and the server understands it, but the operation cannot be performed because the resource state doesn't permit it.\nRetrying the same request won't succeed."
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
examples:
cannot_update_externally_managed_resource:
summary: Labels and label groups are managed by integration, cannot be updated
value:
error_id: e950c41e-cfd6-4e04-bd79-2d57a3951774
code: 3514
message: Labels are managed by your connected accounting integration and cannot be modified manually
state_mismatch:
summary: Label group is no longer available
value:
error_id: f1059c4b-4278-45d3-a17f-bd433ab33c15
code: 3100
message: Invalid request
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
tags:
- Labels
delete:
summary: Delete a label group
operationId: deleteLabelGroup
description: "Delete a specific label group, based on its ID.\n\n:::note\nThis operation is not supported for [externally managed label groups](https://developer.revolut.com/docs/guides/manage-accounts/accounting/manage-labels-and-label-groups#externally-managed-settings).\n:::\n\nOnce the label group is deleted, it will not be returned by the API or in the Revolut Business app, and:\n- You will not be able to apply labels from the group to new financial records (e.g. expenses). \n- Existing records that have not been completed and that contain labels from this group will be marked as invalid, and you'll need to update them to use different labels.\n- Completed records will not be affected by the change. \n\nA successful response does not get any content in return.\n\nFor more details, see the guides: [Manage accounting settings](https://developer.revolut.com/docs/guides/manage-accounts/accounting/manage-accounting-settings) and [Manage labels and label groups](https://developer.revolut.com/docs/guides/manage-accounts/accounting/manage-labels-and-label-groups)."
security:
- AccessToken:
- WRITE
parameters:
- name: group_id
description: The ID of the label group to delete.
in: path
required: true
schema:
type: string
format: uuid
example: 09ad1ad3-a1c0-4c09-b8f8-24b439e72690
responses:
'204':
description: Label group deleted
'400':
description: 'Bad Request
Returned, for example, when a required parameter is missing or malformatted.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
examples:
bad_param_format:
summary: Incorrect path parameter format
value:
error_id: f70973ea-c939-41f8-a106-1656ab5fae2f
code: 2101
message: Path parameter 'id' must be a valid UUID
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: 'Not found
Returned when the label group that you''re trying to delete cannot be found.
This can happen, for example, when the label group doesn''t exist, or the provided label group ID is incorrect.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
example:
error_id: ca73d8a4-a5cb-4f03-9a95-4d53aa1731b0
code: 3006
message: Label group with id be6c9d90-df25-458a-b559-be61896c94b8 not found
'422':
description: "Unprocessable entity - label group cannot be deleted due to business rules \n\nReturned, for example, when you have an accounting software integration connected to your Revolut Business account, and label groups are managed by that integration.\n\nThe request is well-formed and the server understands it, but the operation cannot be performed because the resource state doesn't permit it.\nRetrying the same request won't succeed."
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
examples:
cannot_delete_externally_managed_resource:
summary: Labels and label groups are managed by integration, cannot be deleted
value:
error_id: e950c41e-cfd6-4e04-bd79-2d57a3951774
code: 3514
message: Labels are managed by your connected accounting integration and cannot be modified manually
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
tags:
- Labels
/label-groups/{group_id}/labels:
post:
summary: Create a new label
operationId: createLabel
description: "Add a new label to a label group. \n\n:::note\nThis operation is not supported for [externally managed labels](https://developer.revolut.com/docs/guides/manage-accounts/accounting/manage-labels-and-label-groups#externally-managed-settings).\n:::\n\nThe labels are used for accounting and can be applied to your financial records, such as expenses.\n\nFor more details, see the guides: [Manage accounting settings](https://developer.revolut.com/docs/guides/manage-accounts/accounting/manage-accounting-settings) and [Manage labels and label groups](https://developer.revolut.com/docs/guides/manage-accounts/accounting/manage-labels-and-label-groups)."
security:
- AccessToken:
- WRITE
parameters:
- name: group_id
in: path
description: The ID of the label group to which to add the new label.
required: true
schema:
type: string
format: uuid
example: 09ad1ad3-a1c0-4c09-b8f8-24b439e72690
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateLabelRequest'
example:
name: Communications
responses:
'201':
description: 'Resource created
On successful creation, the response returns only the ID of the new resource (i.e. the label), even if the resource has more properties.
To get more details, use the ID of the parent label group to [get all the labels from the label group](https://developer.revolut.com/docs/api/business#get-labels).'
$ref: '#/components/responses/ResourceCreatedResponse'
'400':
description: 'Bad Request
Returned, for example, when a required parameter is missing or malformatted.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorWithId'
examples:
param_required:
summary: Required parameter is missing
value:
# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/revolut/refs/heads/main/openapi/revolut-labels-api-openapi.yml