> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pleo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate to the New Tags API

> Migration guide from the legacy Tag Groups API (/tag-groups) to the Tags API (/v0/tag-groups and /v0/tags). Use it if your integration manages tag groups and tags. To archive a tag group, send a PUT, which replaces the whole resource.

The legacy Tag Groups API has been deprecated. This guide covers how to migrate to the [new Tags API](https://developers.pleo.io/reference/tags-overview.md). The new Tags API covers both tag groups and tags.

If you used the legacy Tag Groups API to keep the tag groups and tags of a company in step with an Accounting System, see the [Tags Sync Workflow Guide](https://developers.pleo.io/docs/current/guides/accounting-integrations/imports/tags-sync-workflow-guide.md). It describes the sync process that the new Tags API supports.

> **Use this page to answer:**

### Which API replaces the legacy Tag Groups API?

The Tags API replaces it.

* `/tag-groups` becomes `/v0/tag-groups`.
* Tags are in `/v0/tag-groups/{groupId}/tags` and `/v0/tags/{tagId}`.
* The legacy API had no company in the request. In the new API, `GET /v0/tag-groups` needs `company_id` or `organization_id`. `POST /v0/tag-groups` and `GET /v0/tags` need `company_id`. Endpoints that use a tag group ID or a tag ID need neither.

### How do updates differ in the Tags API?

The new `PUT` endpoints replace the whole resource. The legacy `PATCH` endpoints changed only the fields that you sent. Send all the required fields on every update:

* **Tag group:** `archived`, `code`, `metadata` and `name`.
* **Tag:** `archived` and `code`.

### How do I archive or delete a tag group or tag?

* Archive with a `PUT` request and `"archived": true`.
* Delete with `DELETE`. The legacy `archive` query parameter on `DELETE /tag-groups/{tagGroupId}` chose between the two.
* Tags Sync archives tag groups and tags and does not delete them.
* The legacy `archived` and `hidden` query parameters returned only archived or hidden records when set to `true`. The new `include_archived` parameter adds archived records to the active ones. To get only archived records, set `include_archived` to `true` and filter the response by `archived: true`.

### What identifier does the Tags API use to match tag groups and tags?

* Every tag group and tag now has a `code`, which is the identifier from the external system.
* Tags Sync matches on `code` and ignores case.
* A company can have no more than five active tag groups.

> **Sources for the Tags API:**
>
> * OpenAPI reference: the endpoint pages under the [Tags API Overview](https://developers.pleo.io/reference/tags-overview.md). Use them for paths, parameters and required fields.
> * How-tos: [How to Sync Tag Groups with Accounting Dimensions](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/imports/tags/how-to-sync-tag-groups-with-accounting-dimensions.md), [How to Sync Tags with Dimension Values](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/imports/tags/how-to-sync-tags-with-dimension-values.md) and [How to Select Dimensions for Tags Sync](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/imports/tags/how-to-select-dimensions-for-tags-sync.md).
> * If a how-to and the reference disagree, trust the how-to. How-tos record tested behaviour.

> This page is the canonical source for migrating from the legacy Tag Groups API to the Tags API. For the current Tags API reference, see the API Reference section.

Terminology: Legacy and New

This guide calls the deprecated API the **legacy Tag Groups API** and its replacement the **new Tags API**.

The legacy Tag Groups API is under `https://openapi.pleo.io/v1/`. The new Tags API is under `https://external.pleo.io`, and its endpoints start with `/v0/`.

The legacy API describes the columns of a tag group as **attributes**. The new API calls them **dimensions**.

## New to the New Tags API?

> [card] [API Overview](https://developers.pleo.io/reference/tags-overview.md)
>
> What tag groups, tags and dimensions are, and how the new API is structured.

> [card] [API Scopes](https://developers.pleo.io/reference/scopes-2.md)
>
> Required scopes: `tag-groups:read` and `tag-groups:write`.

> [card] [Tags Sync Overview](https://developers.pleo.io/docs/current/platform/accounting-integrations/imports/tags/tags-sync-overview.md)
>
> How Accounting Dimensions become tag groups and tags in Pleo.

> [card] [OAuth 2.0 Guide](https://developers.pleo.io/docs/current/guides/oauth-workflow-guide.md)
>
> End-to-end OAuth 2.0 workflow guide for Pleo integrations.

> [card] [Standalone API Key Guide](https://developers.pleo.io/docs/current/guides/standalone-api-keys-workflow-guide.md)
>
> End-to-end guide for authenticating with standalone API keys.

## Getting Started

You need API credentials with the [`tag-groups:read`](https://developers.pleo.io/reference/scopes-2) scope to read tag groups and tags. You also need the `tag-groups:write` scope to create, update or delete them.

The new Tags API takes the company as the `company_id` query parameter on the endpoints that list or create tag groups, and on `GET /v0/tags`. You can use `organization_id` instead on `GET /v0/tag-groups` to list the tag groups of an organisation. The endpoints that use a tag group ID or a tag ID do not need a company. If you manage more than one company, handle each company on its own. For more information, see [Multi-Entity and API Scope](https://developers.pleo.io/docs/current/platform/multi-entity/multi-entity-and-api-scope.md).

## Endpoint Mapping

The table below maps the endpoints of the legacy Tag Groups API to the endpoints of the new Tags API.

* `—` : endpoint is not available in the legacy Tag Groups API

| Legacy Tag Groups API | New Tags API | Description |
| :- | :- | :- |
| [`GET /tag-groups`](https://developers.pleo.io/reference/pleo-deprecated/tag-groups/get-all-tag-groups-belonging-to-the-specified-company) | [`GET /v0/tag-groups`](https://developers.pleo.io/reference/tags-api/tag-groups/returns-all-tag-groups-for-given-company) | Returns the tag groups of a company. |
| [`POST /tag-groups`](https://developers.pleo.io/reference/pleo-deprecated/tag-groups/create-a-new-tag-group) | [`POST /v0/tag-groups`](https://developers.pleo.io/reference/tags-api/tag-groups/creates-a-new-tag-group-resource) | Creates a tag group. |
| [`GET /tag-groups/{tagGroupId}`](https://developers.pleo.io/reference/pleo-deprecated/tag-groups/get-a-tag-group) | [`GET /v0/tag-groups/{groupId}`](https://developers.pleo.io/reference/tags-api/tag-groups/returns-the-tag-group-resource-by-id) | Returns one tag group. |
| [`PATCH /tag-groups/{tagGroupId}`](https://developers.pleo.io/reference/pleo-deprecated/tag-groups/update-a-tag-group) | [`PUT /v0/tag-groups/{groupId}`](https://developers.pleo.io/reference/tags-api/tag-groups/updates-the-tag-group-resource-by-id) | Updates a tag group. The new endpoint replaces the whole resource. |
| [`DELETE /tag-groups/{tagGroupId}`](https://developers.pleo.io/reference/pleo-deprecated/tag-groups/delete-or-archive-a-tag-group) | [`PUT /v0/tag-groups/{groupId}`](https://developers.pleo.io/reference/tags-api/tag-groups/updates-the-tag-group-resource-by-id) or [`DELETE /v0/tag-groups/{groupId}`](https://developers.pleo.io/reference/tags-api/tag-groups/deletes-the-tag-group-resource-by-id) | To archive a tag group, send `"archived": true` in a `PUT` request. To delete it, use `DELETE`. |
| [`GET /tag-groups/{tagGroupId}/tags`](https://developers.pleo.io/reference/pleo-deprecated/tag-groups/get-all-tags-for-a-specified-tag-group) | [`GET /v0/tag-groups/{groupId}/tags`](https://developers.pleo.io/reference/tags-api/tags/returns-tags-for-given-tag-group) | Returns the tags of a tag group. |
| [`POST /tag-groups/{tagGroupId}/tags`](https://developers.pleo.io/reference/pleo-deprecated/tag-groups/create-a-new-tag) | [`POST /v0/tag-groups/{groupId}/tags`](https://developers.pleo.io/reference/tags-api/tags/creates-a-new-tag-sub-resource-under-the-given-tag-group) | Creates a tag in a tag group. |
| [`GET /tag-groups/{tagGroupId}/tags/{tagId}`](https://developers.pleo.io/reference/pleo-deprecated/tag-groups/get-a-tag-from-a-tag-group) | [`GET /v0/tags/{tagId}`](https://developers.pleo.io/reference/tags-api/tags/returns-tag-by-id) | Returns one tag. The new endpoint does not need the tag group ID. |
| [`PATCH /tag-groups/{tagGroupId}/tags/{tagId}`](https://developers.pleo.io/reference/pleo-deprecated/tag-groups/update-a-tag) | [`PUT /v0/tags/{tagId}`](https://developers.pleo.io/reference/tags-api/tags/updates-tag-by-id) | Updates a tag. The new endpoint replaces the whole resource. |
| [`DELETE /tag-groups/{tagGroupId}/tags/{tagId}`](https://developers.pleo.io/reference/pleo-deprecated/tag-groups/delete-a-tag) | [`DELETE /v0/tags/{tagId}`](https://developers.pleo.io/reference/tags-api/tags/deletes-tag-by-id) | Deletes a tag. To archive a tag instead, send `"archived": true` in a `PUT` request. |
| — | [`GET /v0/tags`](https://developers.pleo.io/reference/tags-api/tags/search-tags) | Searches the tags of a company. |
| — | [`GET /v0/tag-groups/{groupId}/dimensions`](https://developers.pleo.io/reference/tags-api/tag-groups/get-a-list-of-tag-group-dimensions) | Returns the dimensions of a tag group. The legacy API returned them as `tagAttributes`. |
| — | [`POST /v0/tag-groups/{groupId}/dimensions`](https://developers.pleo.io/reference/tags-api/tag-groups/creates-a-new-tag-group-dimension) | Creates a dimension in a tag group. |
| — | [`GET /v0/tag-groups/{groupId}/dimensions/{dimensionId}`](https://developers.pleo.io/reference/tags-api/tag-groups/get-a-tag-group-dimension) | Returns one dimension. |
| — | [`PUT /v0/tag-groups/{groupId}/dimensions/{dimensionId}`](https://developers.pleo.io/reference/tags-api/tag-groups/update-a-tag-group-dimension) | Updates a dimension. |
| — | [`DELETE /v0/tag-groups/{groupId}/dimensions/{dimensionId}`](https://developers.pleo.io/reference/tags-api/tag-groups/delete-a-tag-group-dimension) | Deletes a dimension. |
| — | [`GET /v0/tags/{tagId}/dimensions`](https://developers.pleo.io/reference/tags-api/tags/fetches-dimension-values) | Returns the dimension values of a tag. The legacy API returned them as `attributeValues`. |
| — | [`GET /v0/tags/{tagId}/dimensions/{dimensionId}`](https://developers.pleo.io/reference/tags-api/tags/gets-a-dimension-value) | Returns one dimension value of a tag. |
| — | [`POST /v0/tags/{tagId}/dimensions/{dimensionId}`](https://developers.pleo.io/reference/tags-api/tags/creates-a-dimension-value) | Creates a dimension value for a tag. |
| — | [`PUT /v0/tags/{tagId}/dimensions/{dimensionId}`](https://developers.pleo.io/reference/tags-api/tags/updates-a-dimension-value) | Updates a dimension value of a tag. |
| — | [`DELETE /v0/tags/{tagId}/dimensions/{dimensionId}`](https://developers.pleo.io/reference/tags-api/tags/deletes-a-dimension-value) | Deletes a dimension value of a tag. |

## Key Differences

* Every tag group and tag now has a `code`. It is the identifier from the external system. Tags Sync matches tag groups and tags on `code`, and the match ignores case.
* The new `PUT` endpoints replace the whole resource. The legacy `PATCH` endpoints changed only the fields that you sent. When you update a tag group or a tag, send all the required fields. For a tag group, these are `archived`, `code`, `metadata` and `name`. For a tag, they are `archived` and `code`.
* The legacy `archive` query parameter on `DELETE /tag-groups/{tagGroupId}` chose between archiving and deleting. In the new Tags API, you archive with a `PUT` request and delete with `DELETE`. Tags Sync archives tag groups and tags and does not delete them.
* The legacy `archived` query parameter on `GET /tag-groups` and the legacy `hidden` query parameter on `GET /tag-groups/{tagGroupId}/tags` returned only archived or hidden records when set to `true`. The new `include_archived` parameter adds archived records to the active ones. To get only archived records, set `include_archived` to `true` and filter the response by `archived: true`.
* Legacy lists returned all results in one array. The new responses return the result in `data`. The tag lists also take the `limit`, `after`, `before` and `offset` query parameters, and you can sort with `sorting_keys` and `sorting_order`.
* The legacy API had no company in the request. `GET /v0/tag-groups` needs `company_id` or `organization_id`, `POST /v0/tag-groups` needs `company_id`, and each tag group has a `companyId`.
* The legacy `tagAttributes` and `attributeValues` become dimensions and dimension values. Each new tag has a `code` and a `name`. Use `otherDimensionValues` to send values for the other dimensions of the tag group.
* The new `displayOrder` of a tag group dimension is set by Pleo when you create it. The new tag has no `displayOrder`.
* A company can have no more than five active tag groups.
* The new `GET /v0/tag-groups` endpoint can return the number of tags in each tag group. Set `include_tags_count` to `true`.

Hidden tags and columns

The legacy `hidden` field on a tag is replaced by `archived`. The legacy `hidden` field on a tag attribute is replaced by `visible` on the dimension. The value of `visible` is the opposite of `hidden`.

## Field Mapping

### Tag group

The table below maps the fields of the legacy tag group to the fields of the new tag group.

* `—` : field is not available on the legacy model
* `*` : data is the same but represented differently

| Legacy field | New field | Description |
| :- | :- | :- |
| id | `id` | The unique identifier that Pleo generates for the tag group. |
| name | `name` | The name of the tag group. |
| archived | `archived` | Whether the tag group is archived. |
| tagAttributes | Dimensions **\*** | The columns of the tag group. In the new API, you read and write them on the dimension endpoints. |
| — | `code` | The identifier of the tag group in the external system. |
| — | `companyId` | The unique identifier of the company that the tag group belongs to. |
| — | `metadata` | A place to store extra information about the tag group. |
| — | `createdAt` | The date and time that Pleo created the tag group. |
| — | `updatedAt` | The date and time that the tag group was last updated. |
| — | `totalTagsCount` | The number of tags in the tag group. Pleo returns it when you set `include_tags_count` to `true`. |

### Tag group attribute and dimension

The table below maps the fields of a legacy tag attribute to the fields of a new dimension.

* `—` : field is not available on the legacy model
* `*` : data is the same but represented differently

| Legacy field | New field | Description |
| :- | :- | :- |
| id | `id` | The unique identifier that Pleo generates for the dimension. |
| name | `name` | The name of the dimension. |
| displayOrder | `displayOrder` | The position of the dimension. Pleo sets it when you create the dimension. |
| hidden | `visible` **\*** | The value is the opposite. `hidden: true` is `visible: false`. |
| — | `code` | The identifier of the dimension in the external system. |
| — | `groupId` | The unique identifier of the tag group that the dimension belongs to. |
| — | `createdAt` | The date and time that Pleo created the dimension. |
| — | `updatedAt` | The date and time that the dimension was last updated. |

### Tag

The table below maps the fields of the legacy tag to the fields of the new tag.

* `—` : field is not available on the legacy model
* `*` : data is the same but represented differently

| Legacy field | New field | Description |
| :- | :- | :- |
| id | `id` | The unique identifier that Pleo generates for the tag. |
| tagGroupId | `groupId` | The unique identifier of the tag group that the tag belongs to. |
| attributeValues | `name`, `code` and dimension values **\*** | The values of the tag. In the new API, the tag has a `code` and a `name`. You read and write the values of the other dimensions on the dimension value endpoints. |
| hidden | `archived` **\*** | Whether the tag can be used. Hidden tags are archived tags. |
| displayOrder | — | The new tag has no display order. |
| — | `code` | The identifier of the tag in the external system. |
| — | `createdAt` | The date and time that Pleo created the tag. |
| — | `updatedAt` | The date and time that the tag was last updated. |

## Example

The legacy request returns the active tag groups of the company:

```bash theme={null}
GET https://openapi.pleo.io/v1/tag-groups
```

The new request needs the `company_id` query parameter. To include archived tag groups, add `include_archived=true`.

> [tab] OAuth 2.0
>
> ```bash theme={null}
> curl -X GET "https://external.pleo.io/v0/tag-groups?company_id=12abc3d4-e567-890e-1234-abc56e78fabc" \
>   -H "Authorization: Bearer <access_token>"
> ```

> [tab] API Key
>
> ```bash theme={null}
> curl --request GET \
>   -u "pls_1ab2cd3e4f5g6h7a89b012c34de56f78_gabc90:" \
>   -H "Accept: application/json;charset=UTF-8" \
>   "https://external.pleo.io/v0/tag-groups?company_id=12abc3d4-e567-890e-1234-abc56e78fabc" \
>   | jq
> ```

The response contains the tag groups in `data`.

[Returns all tag groups for given company →](https://developers.pleo.io/reference/tags-api/tag-groups/returns-all-tag-groups-for-given-company.md)
