# Manage labels and label groups Labels and label groups help you categorize and track your business spending for accounting purposes. You can apply these labels to financial records such as [expenses](/docs/guides/manage-accounts/accounts-and-transactions/retrieve-expenses) to provide granular tracking, for example, for departments, projects, or locations. :::note [Label considerations] - **Hierarchy**: Labels must always belong to a specific **label group**. - **Capacity**: You can have up to **5 label groups** per business at any time. - **Group limits**: A single label group can contain up to **200 labels** upon creation. More labels can be added later individually. - **Mutability**: [Externally managed](#externally-managed-settings) labels and label groups **cannot be modified** via the API. ::: To manage label groups via the Business API, you must use an access token with the following [scopes](/docs/guides/manage-accounts/get-started/make-your-first-api-request#3-consent-to-the-application): | Operation | Required Scope | | :---------------------------------------------------------------------------------------------------------------- | :------------- | | [Retrieve label groups](#retrieve-label-groups) | `READ` | | [Create](#create-a-label-group), [update](#update-a-label-group), or [delete](#delete-a-label-group) label groups | `WRITE` | | [Retrieve labels](#retrieve-labels-from-a-label-group) from a specific label group | `READ` | | [Create](#create-a-label), [update](#update-a-label), or [delete](#delete-a-label) labels | `WRITE` | :::note The `WRITE` operations are not supported for [externally managed labels and label groups](#externally-managed-settings). ::: ## Manage label groups ### Create a label group :::note This operation is not supported for [externally managed label groups](#externally-managed-settings). ::: To add a new label group, you must provide the following details: - **Group name:** A unique name for the label group that helps to understand its application. - **Labels:** The list of labels to create with this group, provided as an array of label objects (max. 200), each with the following details: - **Label name:** The name of the label to create. You must add at least one label. Empty label groups are not allowed. :::note On success, the response returns only the ID of the created label group. To get all the details, use that ID to [retrieve a specific label group](#retrieve-a-specific-label-group). ::: For more details and sample requests and responses: [See the API reference: Create a label group](/docs/api/business#create-label-group) :::tip If you need to add more labels later, use the dedicated endpoint to [create a label](#create-a-label). ::: ### Retrieve label groups You can use the API to retrieve label groups available for your business. When you retrieve the label groups, for each label group, you get its details, such as the label group ID and name, as well as when it was created and when it was last updated. You can: - [Retrieve all the label groups](#retrieve-a-list-of-label-groups) available in your settings - [Retrieve a specific label group](#retrieve-a-specific-label-group) #### Retrieve a list of label groups When you list all the label groups available for your business, the results are [paginated](#pagination) and sorted by the `created_at` date in reverse chronological order. To get the next page of results, use the `next_page_token` value. :::note The response returns only the group details (ID, name, dates of creation and latest update), and the next page token if available. It does not return the labels assigned to the group. To [fetch the list of labels from a label group](#retrieve-labels-from-a-label-group), use the dedicated endpoint. ::: For more details and sample requests and responses: [See the API reference: Retrieve a list of label groups](/docs/api/business#get-label-groups) #### Retrieve a specific label group You can also retrieve a specific label group by its ID to look up its name, as well as dates of creation and last update. :::note The response returns only the group details (ID, name, dates of creation and latest update). It does not return the labels assigned to the group. To [fetch the list of labels from a label group](#retrieve-labels-from-a-label-group), use the dedicated endpoint. ::: For more details and sample requests and responses: [See the API reference: Retrieve a label group](/docs/api/business#get-label-group) ### Update a label group :::note This operation is not supported for [externally managed label groups](#externally-managed-settings). ::: You can use the PATCH request to update the name for a specific label group. This can be useful, for example, when there's a typing error in the name, or when the group name no longer accurately reflects the purpose. :::note Batch updates for labels through label group settings are not supported. If you need to update the labels in a group, you can: - [Add](#create-a-label) a new label to the group - [Update](#update-a-label) the name for an existing label in the group - [Delete](#delete-a-label) an existing label in the group ::: On successful update, you get a `204` response with no additional content. For more details and sample requests and responses: [See the API reference: Update a label group](/docs/api/business#update-label-group) ### Delete a label group :::note This operation is not supported for [externally managed label groups](#externally-managed-settings). ::: To delete a label group, simply make a DELETE call providing the ID of this label group. :::warning [Deletion consequences for financial records] Once a label group is deleted, it is removed from the Revolut Business app. Existing uncompleted records with labels from this label group will be marked as **invalid**, and you must manually update them to use active labels. Completed records are not affected. ::: On successful deletion, you get a `204` response with no additional content. For more details and sample requests and responses: [See the API reference: Delete a label group](/docs/api/business#delete-label-group) --- ## Manage labels ### Create a label :::note This operation is not supported for [externally managed labels](#externally-managed-settings). ::: To add a new label, you must provide the following details: :::details [Required details] - **Group ID:** The ID of the group in which to create the new label. - **Name:** The unique name of the new label to create. ::: :::note On success, the response returns only the ID of the created label. To get all the details, [retrieve labels from the label group](#retrieve-labels-from-a-label-group). ::: For more details and sample requests and responses: [See the API reference: Create a label](/docs/api/business#create-label) ### Retrieve labels from a label group You can use the API to retrieve labels available for your business and belonging to a specific label group. When you retrieve the labels, for each label, you get its details, such as the label ID and name, as well as when it was created and when it was last updated. The results are [paginated](#pagination) and sorted by the `created_at` date in reverse chronological order. To get the next page of results, use the `next_page_token` value. For more details and sample requests and responses: [See the API reference: Retrieve a list of labels](/docs/api/business#get-labels) ### Update a label :::note This operation is not supported for [externally managed labels](#externally-managed-settings). ::: You can use the PATCH request to update the name for a specific label. This can be useful, for example, when there's a typing error in the name, or when the label name no longer accurately reflects the purpose. On successful update, you get a `204` response with no additional content. For more details and sample requests and responses: [See the API reference: Update a label](/docs/api/business#update-label) ### Delete a label :::note This operation is not supported for [externally managed labels](#externally-managed-settings). ::: To delete a label, simply make a DELETE call providing the ID of this label. :::warning [Deletion consequences for financial records] Once a label is deleted, it is removed from the Revolut Business app. Existing records with the deleted label that are pending completion will be marked as **invalid**, and they will require a manual update to a valid label. Complete records are not affected. See an example of an incomplete expense with accounting settings that have been deleted, now marked as invalid → ![img](/img/manage-accounts/accounting-invalid-expense.png) ::: On successful deletion, you get a `204` response with no additional content. For more details and sample requests and responses: [See the API reference: Delete a label](/docs/api/business#delete-label) --- ## Pagination - **Page size**: The API returns a maximum of 500 results per request (default: 100). You can increase or decrease the page size, i.e. the maximum number of results returned per page, by explicitly setting the `limit` parameter. - **Sorting**: Results are sorted by the `created_at` date in reverse chronological order. - **Next Page**: If the results exceed the page size, the response includes `next_page_token`. To fetch the next page of results, make a new request providing this value of `next_page_token` in the `page_token` query parameter. ## Externally managed settings If an accounting software [integration](https://www.revolut.com/business/integrations/) is connected, labels and label groups are typically managed within that external platform. In this state, the labels and label groups are **read-only** via the API, and manual modification attempts will return an error. :::tip To find out if your labels are managed externally, check the [Revolut Business settings](https://business.revolut.com/settings). 1. Go to **Settings** → **Accounting** → [**Labels**](https://business.revolut.com/settings/accounting/labels). 2. Look for a **+ New** button above the labels. - If you see the button, this means that your labels can be modified via the API. - If you don't see the button, your labels are managed externally by the connected integration and cannot be modified (created/updated/deleted) via the API. The name of the connected integration appears near the top, together with information when it was last synced. | Editable | Read-only | | ----------------------------------------------------------- | ---------------------------------------------------------- | | ![img](/img/manage-accounts/accounting-labels-editable.png) | ![img](/img/manage-accounts/accounting-labels-managed.png) | ::: ## See also - [Accounting settings - overview](/docs/guides/manage-accounts/accounting/manage-accounting-settings) - [Manage accounting categories](/docs/guides/manage-accounts/accounting/manage-accounting-categories) - [Manage tax rates](/docs/guides/manage-accounts/accounting/manage-tax-rates) - Revolut Help Centre: [Expenses](/docs/guides/manage-accounts/accounts-and-transactions/retrieve-expenses)