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 thetag-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 oncode, and the match ignores case. - The new
PUTendpoints replace the whole resource. The legacyPATCHendpoints 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 arearchived,code,metadataandname. For a tag, they arearchivedandcode. - The legacy
archivequery parameter onDELETE /tag-groups/{tagGroupId}chose between archiving and deleting. In the new Tags API, you archive with aPUTrequest and delete withDELETE. Tags Sync archives tag groups and tags and does not delete them. - The legacy
archivedquery parameter onGET /tag-groupsand the legacyhiddenquery parameter onGET /tag-groups/{tagGroupId}/tagsreturned only archived or hidden records when set totrue. The newinclude_archivedparameter adds archived records to the active ones. To get only archived records, setinclude_archivedtotrueand filter the response byarchived: true. - Legacy lists returned all results in one array. The new responses return the result in
data. The tag lists also take thelimit,after,beforeandoffsetquery parameters, and you can sort withsorting_keysandsorting_order. - The legacy API had no company in the request.
GET /v0/tag-groupsneedscompany_idororganization_id,POST /v0/tag-groupsneedscompany_id, and each tag group has acompanyId. - The legacy
tagAttributesandattributeValuesbecome dimensions and dimension values. Each new tag has acodeand aname. UseotherDimensionValuesto send values for the other dimensions of the tag group. - The new
displayOrderof a tag group dimension is set by Pleo when you create it. The new tag has nodisplayOrder. - A company can have no more than five active tag groups.
- The new
GET /v0/tag-groupsendpoint can return the number of tags in each tag group. Setinclude_tags_counttotrue.
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:company_id query parameter. To include archived tag groups, add include_archived=true.
- OAuth 2.0
- API Key
data.
FAQs
Which API replaces the legacy Tag Groups API?
The Tags API replaces it.
/tag-groupsbecomes/v0/tag-groups.- Tags are in
/v0/tag-groups/{groupId}/tagsand/v0/tags/{tagId}. - The legacy API had no company in the request. In the new API,
GET /v0/tag-groupsneedscompany_idororganization_id.POST /v0/tag-groupsandGET /v0/tagsneedcompany_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,metadataandname. - Tag:
archivedandcode.
How do I archive or delete a tag group or tag?
- Archive with a
PUTrequest and"archived": true. - Delete with
DELETE. The legacyarchivequery parameter onDELETE /tag-groups/{tagGroupId}chose between the two. - Tags Sync archives tag groups and tags and does not delete them.
- The legacy
archivedandhiddenquery parameters returned only archived or hidden records when set totrue. The newinclude_archivedparameter adds archived records to the active ones. To get only archived records, setinclude_archivedtotrueand filter the response byarchived: 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
codeand ignores case. - A company can have no more than five active tag groups.