Skip to main content
The legacy Tag Groups API has been deprecated. This guide covers how to migrate to the new Tags API. 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. It describes the sync process that the new Tags API supports.

New to the New Tags API?

API Overview

What tag groups, tags and dimensions are, and how the new API is structured.

API Scopes

Required scopes: tag-groups:read and tag-groups:write.

Tags Sync Overview

How Accounting Dimensions become tag groups and tags in Pleo.

OAuth 2.0 Guide

End-to-end OAuth 2.0 workflow guide for Pleo integrations.

Standalone API Key Guide

End-to-end guide for authenticating with standalone API keys.

Getting Started

You need API credentials with the tag-groups:read 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.

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

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.

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

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

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

Example

The legacy request returns the active tag groups of the company:
The new request needs the company_id query parameter. To include archived tag groups, add include_archived=true.
The response contains the tag groups in data.

FAQs

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.