> ## 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.

# How to Sync Tags with Dimension Values

export const SyncTagsDiagram = () => {
  const [isDark, setIsDark] = useState(false);
  useEffect(() => {
    const check = () => setIsDark(document.documentElement.classList.contains("dark"));
    check();
    const observer = new MutationObserver(check);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class"]
    });
    return () => observer.disconnect();
  }, []);
  const nodeFill = isDark ? "#212222" : "#EEF4F4";
  const nodeStroke = isDark ? "#848989" : "#E1E6E6";
  const nodeTextStyle = isDark ? ",color:#EEF4F4" : ",color:#131414";
  const linkStyle = isDark ? "" : "linkStyle default stroke:#848989,stroke-width:1px;";
  const diagram = `
%%{init: {"themeVariables": {"fontSize": "32px"}}}%%
flowchart LR
    T1["1. Iterate Over Tag Groups"] --> T2["2. Retrieve Dimension Values"] --> T3["3. Retrieve All Tags"] --> T4["4. Resolve Duplicates"] --> T5["5. Match by Code"]
    T5 -->|No match| T6["6. Create Tag"]
    T5 -->|Match found| T7["7. Unarchive or Update"]
    T6 --> T8["8. Archive Unmatched"]
    T7 --> T8

click T1 "#1-iterate-over-each-selected-tag-group"
click T2 "#2-retrieve-dimension-values-from-the-accounting-system"
click T3 "#3-retrieve-all-tags-from-pleo-for-the-tag-group"
click T4 "#4-resolve-duplicate-tags"
click T5 "#5-match-dimension-values-to-tags-by-code"
click T6 "#6-create-tags-for-new-dimension-values"
click T7 "#7-unarchive-or-update-existing-tags"
click T8 "#8-archive-tags-with-no-matching-active-dimension-value"

style T1 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style T2 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style T3 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style T4 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style T5 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style T6 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style T7 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style T8 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
${linkStyle}
`;
  return <Mermaid chart={diagram} />;
};

export const TagsSyncWorkflowDiagramTopNav = ({highlight}) => {
  const [isDark, setIsDark] = useState(false);
  useEffect(() => {
    const check = () => setIsDark(document.documentElement.classList.contains("dark"));
    check();
    const observer = new MutationObserver(check);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class"]
    });
    return () => observer.disconnect();
  }, []);
  const nodeFill = isDark ? "#212222" : "#EEF4F4";
  const nodeStroke = isDark ? "#848989" : "#E1E6E6";
  const nodeTextStyle = isDark ? ",color:#EEF4F4" : ",color:#131414";
  const subgraphFill = isDark ? "#131414" : "#ffffff";
  const subgraphStroke = isDark ? "#848989" : "#6B7070";
  const subgraphTextStyle = isDark ? ",color:#EEF4F4" : ",color:#6B7070";
  const linkStyle = isDark ? "" : "linkStyle default stroke:#848989,stroke-width:1px;";
  const highlightStyle = highlight ? `style ${highlight} stroke:#FEB6FE,stroke-width:2px` : "";
  const shape = (id, label) => `${id}["${label}"]`;
  const diagram = `
%%{init: {"themeVariables": {"fontSize": "18px"}}}%%
flowchart LR

subgraph AS["Accounting System"]
    ${shape("source", "Dimensions & Dimension Values")}
end

subgraph Pleo["Pleo API's"]
    ${shape("A", "1.Select Dimensions for Sync")}
    ${shape("B", "2.Sync Tag Groups with Dimensions")}
    ${shape("C", "3.Sync Tags with Dimension Values")}
    A --> B --> C
end

source --> A

click A "/docs/current/how-tos/accounting-integrations/imports/tags/how-to-select-dimensions-for-tags-sync"
click B "/docs/current/how-tos/accounting-integrations/imports/tags/how-to-sync-tag-groups-with-accounting-dimensions"
click C "/docs/current/how-tos/accounting-integrations/imports/tags/how-to-sync-tags-with-dimension-values"

style A white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style B white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style C white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style source white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style AS fill:${subgraphFill},stroke:${subgraphStroke}${subgraphTextStyle}
style Pleo fill:${subgraphFill},stroke:${subgraphStroke}${subgraphTextStyle}

${highlightStyle}
${linkStyle}
`;
  return <Mermaid chart={diagram} />;
};

export const WhatComesNext = ({children, href}) => <div className="mt-4">
    <a href={href} className="btn-primary">
      {children} →
    </a>
  </div>;

export const RememberCallout = ({title, children}) => <div className="callout-box callout-remember">
    <div className="callout-row">
      <span className="callout-icon">
        <svg width="22" height="22" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="currentColor"><path d="M229.66,98.34,172.39,155.8c11.46,22.93-1.72,45.86-10.11,57a8,8,0,0,1-12,.83L42.34,105.76A8,8,0,0,1,43,93.85c29.65-23.92,57.4-10,57.4-10l57.27-57.46a8,8,0,0,1,11.31,0L229.66,87A8,8,0,0,1,229.66,98.34Z" opacity="0.2" /><path d="M235.32,81.37,174.63,20.69a16,16,0,0,0-22.63,0L98.37,74.49c-10.66-3.34-35-7.37-60.4,13.14a16,16,0,0,0-1.29,23.78L85,159.71,42.34,202.34a8,8,0,0,0,11.32,11.32L96.29,171l48.29,48.29A16,16,0,0,0,155.9,224c.38,0,.75,0,1.13,0a15.93,15.93,0,0,0,11.64-6.33c19.64-26.1,17.75-47.32,13.19-60L235.33,104A16,16,0,0,0,235.32,81.37ZM224,92.69h0l-57.27,57.46a8,8,0,0,0-1.49,9.22c9.46,18.93-1.8,38.59-9.34,48.62L48,100.08c12.08-9.74,23.64-12.31,32.48-12.31A40.13,40.13,0,0,1,96.81,91a8,8,0,0,0,9.25-1.51L163.32,32,224,92.68Z" /></svg>
      </span>
      <div>
        {title && <div className="callout-title">
            {title}
          </div>}
        <div className="callout-body">
          {children}
        </div>
      </div>
    </div>
  </div>;

<TagsSyncWorkflowDiagramTopNav highlight="C" />

<div className="border-[1px] rounded-none p-4 bg-[#ffffff] border-[#FEB6FE] dark:bg-[#131414] dark:border-[#FEB6FE]">
  <SyncTagsDiagram />
</div>

This how-to explains how an integration synchronises Tags within each Tag Group in Pleo with the Dimension Values from the Accounting System.

Syncing Tags is the third and final step in the Tags Sync workflow.

Tags in Pleo correspond to Dimension Values in the Accounting System. This step ensures bookkeepers always have accurate, current Dimension Values available when coding expenses.

Your integration must:

* Retrieve Dimension Values from the AS for each selected Dimension
* Retrieve all Tags (active and archived) from Pleo for each Tag Group
* Create, unarchive, update, or archive Tags as needed
* Resolve duplicate Tags when multiple Tags share the same code

## Prerequisites

Before you begin:

* You're familiar with the [Tags Sync Overview](/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-overview) and the [Integration Design for Syncing Tags](/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-sync-tags)
* Your integration is authenticated using one of the [supported authentication methods](/docs/current/integration-design/auth/integration-design-auth-overview#authentication-policy-overview)
* Your integration can call Pleo's Tags API endpoints
* [Tag Groups have been synchronised with Dimensions](/docs/current/how-tos/accounting-integrations/imports/tags/how-to-sync-tag-groups-with-accounting-dimensions)

## Scenario

This how-to continues from [How to Sync Tag Groups with Accounting Dimensions](/docs/current/how-tos/accounting-integrations/imports/tags/how-to-sync-tag-groups-with-accounting-dimensions).

The four active Tag Groups from that step (**Department**, **Project**, **Finance**, and **Cost Centre**) are the input for this sync. This how-to uses the **Department** Tag Group to illustrate each step.

The table below shows the starting state for the Department Tag Group before this sync runs.

| Tag (Pleo)  | Pleo Status | Dimension Value (AS) | AS Status      |
| ----------- | ----------- | -------------------- | -------------- |
| Engineering | Active      | Engineering (ENG)    | Active         |
| Marketing   | Archived    | Marketing (MKT)      | Active         |
| Sales       | Active      | —                    | Does not exist |
| —           | —           | Operations (OPS)     | Active         |

## Steps

### 1. Iterate Over Each Selected Tag Group

For each active Tag Group in Pleo (corresponding to a selected Dimension), perform the following steps.

**Example Pseudo:**

```pseudo theme={null}
activeTagGroups = fetchTagGroupsFromPleo(includeArchived: false)

for tagGroup in activeTagGroups:
    syncTagsForTagGroup(tagGroup)
```

#### Example Result

| Tag Group   | Pleo Status | Process Tags? |
| ----------- | ----------- | :-----------: |
| Department  | Active      |     ✓ Yes     |
| Project     | Active      |     ✓ Yes     |
| Finance     | Active      |     ✓ Yes     |
| Cost Centre | Active      |     ✓ Yes     |

The following steps use **Department** as the example.

***

### 2. Retrieve Dimension Values from the Accounting System

For the current Tag Group, fetch the Dimension Values from the AS for the matching Dimension.

Include all values: active, archived, blocked, expired, or deactivated. The sync logic determines what to do with each.

**Example Pseudo:**

```pseudo theme={null}
dimensionValues = fetchDimensionValuesFromAS(dimension.code)
```

#### Example Response

The response format depends on your Accounting System. The following is a representative example for the Department Dimension:

```json theme={null}
{
  "dimensionValues": [
    { "code": "ENG", "name": "Engineering", "status": "active" },
    { "code": "MKT", "name": "Marketing",   "status": "active" },
    { "code": "OPS", "name": "Operations",  "status": "active" }
  ]
}
```

#### Example Result

| Dimension Value   | AS Status | Include in Sync? |
| ----------------- | --------- | :--------------: |
| Engineering (ENG) | Active    |       ✓ Yes      |
| Marketing (MKT)   | Active    |       ✓ Yes      |
| Operations (OPS)  | Active    |       ✓ Yes      |

***

### 3. Retrieve All Tags from Pleo for the Tag Group

**API Endpoint**: GET [`/v0/tag-groups/{groupId}/tags`](/reference/tags-api/tags/returns-tags-for-given-tag-group)

**Example parameters:** groupId: `768fb809-b282-4411-875a-406f8e4c5bdb`, includeArchived: `true`

Fetch both active and archived Tags for the current Tag Group. Including archived Tags allows unarchiving rather than creating duplicates.

**Example Pseudo:**

```pseudo theme={null}
tags = fetchTagsFromPleo(tagGroup.id, includeArchived: true)
```

#### Example Request

<Tabs>
  <Tab title="OAuth 2.0">
    ```bash theme={null}
    curl -X GET "https://external.staging.pleo.io/v0/tag-groups/768fb809-b282-4411-875a-406f8e4c5bdb/tags?include_archived=true" \
      -H "Authorization: Bearer <access_token>"
    ```
  </Tab>

  <Tab title="API Key">
    ```bash theme={null}
    curl --request GET \
    -u "pls_1ab2cd3e4f5g6h7a89b012c34de56f78_gabc90:" \
    -H "Accept: application/json;charset=UTF-8" \
    "https://external.staging.pleo.io/v0/tag-groups/768fb809-b282-4411-875a-406f8e4c5bdb/tags?include_archived=true" \
    | jq
    ```
  </Tab>
</Tabs>

#### Example Response

```json theme={null}
{
  "data": [
    {
      "id": "92771fb4-cdd7-4679-b594-f21a005c731a",
      "groupId": "768fb809-b282-4411-875a-406f8e4c5bdb",
      "name": "Engineering · ENG",
      "code": "ENG",
      "archived": false,
      "createdAt": "2026-05-22T14:12:43.358326Z",
      "updatedAt": "2026-05-22T14:12:43.358326Z"
    },
    {
      "id": "8fef04fe-0fe5-44ef-b863-a6fa93fdcfc4",
      "groupId": "768fb809-b282-4411-875a-406f8e4c5bdb",
      "name": "Marketing · MKT",
      "code": "MKT",
      "archived": true,
      "createdAt": "2026-05-22T14:13:00.697506Z",
      "updatedAt": "2026-05-22T14:19:53.667246Z"
    },
    {
      "id": "7b079251-c225-46e6-9f0b-6f2e1b1cdec5",
      "groupId": "768fb809-b282-4411-875a-406f8e4c5bdb",
      "name": "Sales · Sales",
      "code": "Sales",
      "archived": false,
      "createdAt": "2026-05-22T14:13:25.178728Z",
      "updatedAt": "2026-05-22T14:13:25.178728Z"
    }
  ],
  "pagination": {
    "hasPreviousPage": false,
    "hasNextPage": false,
    "currentRequestPagination": {
      "sortingKeys": [],
      "sortingOrder": [],
      "parameters": {
        "include_archived": [
          "true"
        ],
        "groupId": [
          "768fb809-b282-4411-875a-406f8e4c5bdb"
        ]
      }
    },
    "startCursor": "~=AAAAAADKCBSFWFK3T3YA=SJ3R7NGN25DHTNMU6INAAXDTDI",
    "endCursor": "~=AAAAAADKCBSIKCVHFRAA=PMDZEUOCEVDONHYLN4XBWHG6YU",
    "total": 3
  }
}
```

#### Example Result

| Tag               | Pleo Status |
| ----------------- | ----------- |
| Engineering (ENG) | Active      |
| Marketing (MKT)   | Archived    |
| Sales (Sales)     | Active      |

#### What it looks like in Pleo Web App

<div style={{ textAlign: "center" }}>
  <img src="https://mintcdn.com/pleo-61d4d38b/wtOkkKeJcHLAWNr4/images/current/accounting-integrations/imports/tags/ui-tags-active-eng-sales.png?fit=max&auto=format&n=wtOkkKeJcHLAWNr4&q=85&s=04c135df1a8ee13f48ad013684d71843" alt="Active Tags in Pleo for Department Tag Group" width="100%" style={{ display: "block", margin: "0 auto" }} data-path="images/current/accounting-integrations/imports/tags/ui-tags-active-eng-sales.png" />
</div>

<br />

<div style={{ textAlign: "center" }}>
  <img src="https://mintcdn.com/pleo-61d4d38b/wtOkkKeJcHLAWNr4/images/current/accounting-integrations/imports/tags/ui-tags-archive-mark.png?fit=max&auto=format&n=wtOkkKeJcHLAWNr4&q=85&s=9baef0105df935508f3a3d9e8d345285" alt="Archived Tags in Pleo for Department Tag Group" width="100%" style={{ display: "block", margin: "0 auto" }} data-path="images/current/accounting-integrations/imports/tags/ui-tags-archive-mark.png" />
</div>

***

### 4. Resolve Duplicate Tags

Before matching, detect and resolve any Tags in Pleo that share the same code.

If multiple Tags share the same code:

* Retain the Tag whose name matches the current AS Dimension Value name (case-insensitive)
* If no name match, retain one Tag chosen at random (using the most recently created Tag as a tiebreaker is a reasonable approach)
* Archive all other duplicates

**Example Pseudo:**

```pseudo theme={null}
tagsByCode = groupTagsByCode(tags)

for code, duplicates in tagsByCode where duplicates.count > 1:
    dimensionValue = findDimensionValue(dimensionValues, code)
    tagToKeep = findBestMatch(duplicates, dimensionValue.name)
    tagsToArchive = duplicates excluding tagToKeep

    for tag in tagsToArchive:
        archiveTag(tag)
```

#### Example Result

No duplicate Tags detected for the Department Tag Group. No action required.

***

### 5. Match Dimension Values to Tags by Code

For each **active** Dimension Value from the AS, attempt to find a matching Tag in Pleo using **code** (case-insensitive).

**Example Pseudo:**

```pseudo theme={null}
tagsByCode = index tags by code.toLowerCase()

activeDimensionValues = filter dimensionValues where status == "active"

for dimensionValue in activeDimensionValues:
    matchedTag = tagsByCode[dimensionValue.code.toLowerCase()]

    if matchedTag is null:
        createTag(tagGroup, dimensionValue)
    else if matchedTag.archived == true:
        unarchiveTag(matchedTag, dimensionValue)
    else:
        updateTagIfNameChanged(matchedTag, dimensionValue)
```

#### Example Result

| Dimension Value (AS) | Tag (Pleo)        | Pleo Status    | Action              |
| -------------------- | ----------------- | -------------- | ------------------- |
| Engineering (ENG)    | Engineering (ENG) | Active         | No action           |
| Marketing (MKT)      | Marketing (MKT)   | Archived       | → Step 7: Unarchive |
| Operations (OPS)     | —                 | Does not exist | → Step 6: Create    |
| —                    | Sales (Sales)     | Active         | → Step 8: Archive   |

***

### 6. Create Tags for New Dimension Values

**API Endpoint**: POST [`/v0/tag-groups/{groupId}/tags`](/reference/tags-api/tags/creates-a-new-tag-sub-resource-under-the-given-tag-group)

**Example parameters:** groupId: `768fb809-b282-4411-875a-406f8e4c5bdb`

If an AS Dimension Value is active but no matching Pleo Tag exists, create a new Tag within the Tag Group.

**Example Pseudo:**

```pseudo theme={null}
if matchedTag is null:
    newTag.name     = dimensionValue.name
    newTag.code     = dimensionValue.code
    newTag.archived = false
    POST newTag to Pleo
```

#### Example Request

<Tabs>
  <Tab title="OAuth 2.0">
    ```bash theme={null}
    curl -X POST "https://external.staging.pleo.io/v0/tag-groups/768fb809-b282-4411-875a-406f8e4c5bdb/tags" \
      -H "Authorization: Bearer <access_token>" \
      -H "Content-Type: application/json" \
      -d '{
            "name": "Operations",
            "code": "OPS",
            "archived": false
          }'
    ```
  </Tab>

  <Tab title="API Key">
    ```bash theme={null}
    curl --request POST \
    -u "pls_1ab2cd3e4f5g6h7a89b012c34de56f78_gabc90:" \
    -H "Accept: application/json;charset=UTF-8" \
    -H "Content-Type: application/json" \
    "https://external.staging.pleo.io/v0/tag-groups/768fb809-b282-4411-875a-406f8e4c5bdb/tags" \
    -d '{
          "name": "Operations",
          "code": "OPS",
          "archived": false
        }' \
    | jq
    ```
  </Tab>
</Tabs>

#### Example Response

```json theme={null}
{
  "data": {
    "id": "c55b216a-ffd1-426e-8eb2-fcf8b7376a81",
    "groupId": "768fb809-b282-4411-875a-406f8e4c5bdb",
    "name": "Operations",
    "code": "OPS",
    "archived": false,
    "createdAt": "2026-05-22T14:27:56.239032674Z",
    "updatedAt": "2026-05-22T14:27:56.239032979Z"
  }
}
```

#### What it looks like in Pleo Web App

<div style={{ textAlign: "center" }}>
  <img src="https://mintcdn.com/pleo-61d4d38b/wtOkkKeJcHLAWNr4/images/current/accounting-integrations/imports/tags/ui-tags-active-eng-ops-sales.png?fit=max&auto=format&n=wtOkkKeJcHLAWNr4&q=85&s=cdfb335ad0f077f596e031a91ed4d81c" alt="Active Tags in Pleo for Department Tag Group" width="100%" style={{ display: "block", margin: "0 auto" }} data-path="images/current/accounting-integrations/imports/tags/ui-tags-active-eng-ops-sales.png" />
</div>

***

### 7. Unarchive or Update Existing Tags

**API Endpoint**: PUT [`/v0/tags/{tagId}`](/reference/tags-api/tags/updates-tag-by-id)

**Example parameters:** tagId: `8fef04fe-0fe5-44ef-b863-a6fa93fdcfc4`

If a matching Tag is found:

* **AS Dimension Value is active, Pleo Tag is archived** → Unarchive the Tag by setting `archived: false` and update the name if changed
* **AS Dimension Value is active, Pleo Tag name differs** → Update the Tag name to match the AS
* **AS Dimension Value is active, Pleo Tag name matches** → No action required

**Example Pseudo:**

```pseudo theme={null}
if matchedTag.archived == true:
    matchedTag.archived = false
    matchedTag.name     = dimensionValue.name
    PUT matchedTag to Pleo

else if matchedTag.name != dimensionValue.name:
    matchedTag.name = dimensionValue.name
    PUT matchedTag to Pleo
```

#### Example Request

<Tabs>
  <Tab title="OAuth 2.0">
    ```bash theme={null}
    curl -X PUT "https://external.staging.pleo.io/v0/tags/8fef04fe-0fe5-44ef-b863-a6fa93fdcfc4" \
      -H "Authorization: Bearer <access_token>" \
      -H "Content-Type: application/json" \
      -d '{
            "name": "Marketing",
            "code": "MKT",
            "archived": false
          }'
    ```
  </Tab>

  <Tab title="API Key">
    ```bash theme={null}
    curl --request PUT \
    -u "pls_1ab2cd3e4f5g6h7a89b012c34de56f78_gabc90:" \
    -H "Accept: application/json;charset=UTF-8" \
    -H "Content-Type: application/json" \
    "https://external.staging.pleo.io/v0/tags/8fef04fe-0fe5-44ef-b863-a6fa93fdcfc4" \
    -d '{
          "name": "Marketing",
          "code": "MKT",
          "archived": false
        }' \
    | jq
    ```
  </Tab>
</Tabs>

#### Example Response

```json theme={null}
{
  "data": {
    "id": "8fef04fe-0fe5-44ef-b863-a6fa93fdcfc4",
    "groupId": "768fb809-b282-4411-875a-406f8e4c5bdb",
    "name": "Marketing",
    "code": "MKT",
    "archived": false,
    "createdAt": "2026-05-22T14:13:00.697506Z",
    "updatedAt": "2026-05-22T14:19:53.667246Z"
  }
}
```

#### What it looks like in Pleo Web App

<div style={{ textAlign: "center" }}>
  <img src="https://mintcdn.com/pleo-61d4d38b/wtOkkKeJcHLAWNr4/images/current/accounting-integrations/imports/tags/ui-tags-active-eng-mark-ops-sales.png?fit=max&auto=format&n=wtOkkKeJcHLAWNr4&q=85&s=82900ceb8ad5a3dc84488cfdc4484943" alt="Active Tags in Pleo for Department Tag Group" width="100%" style={{ display: "block", margin: "0 auto" }} data-path="images/current/accounting-integrations/imports/tags/ui-tags-active-eng-mark-ops-sales.png" />
</div>

<br />

<div style={{ textAlign: "center" }}>
  <img src="https://mintcdn.com/pleo-61d4d38b/wtOkkKeJcHLAWNr4/images/current/accounting-integrations/imports/tags/ui-tags-archive-empty.png?fit=max&auto=format&n=wtOkkKeJcHLAWNr4&q=85&s=58587f266d07b0ea68e3782f20dee007" alt="Archived Tags in Pleo for Department Tag Group - Empty" width="100%" style={{ display: "block", margin: "0 auto" }} data-path="images/current/accounting-integrations/imports/tags/ui-tags-archive-empty.png" />
</div>

***

### 8. Archive Tags with No Matching Active Dimension Value

**API Endpoint**: PUT [`/v0/tags/{tagId}`](/reference/tags-api/tags/updates-tag-by-id)

For any active Tag that does not match an active Dimension Value (because the Dimension Value is absent, deleted, blocked, expired, or deactivated in the AS), archive it.

Do not delete Tags. Archiving is non-destructive and reversible.

**Example Pseudo:**

```pseudo theme={null}
activeDimensionCodes = activeDimensionValues.map(dv => dv.code.toLowerCase())

for tag in tags where archived == false:
    if tag.code.toLowerCase() not in activeDimensionCodes:
        tag.archived = true
        PUT tag to Pleo
```

#### Example Request

<Tabs>
  <Tab title="OAuth 2.0">
    ```bash theme={null}
    curl -X PUT "https://external.staging.pleo.io/v0/tags/7b079251-c225-46e6-9f0b-6f2e1b1cdec5" \
      -H "Authorization: Bearer <access_token>" \
      -H "Content-Type: application/json" \
      -d '{
            "name": "Sales",
            "code": "Sales",
            "archived": true
          }'
    ```
  </Tab>

  <Tab title="API Key">
    ```bash theme={null}
    curl --request PUT \
    -u "pls_1ab2cd3e4f5g6h7a89b012c34de56f78_gabc90:" \
    -H "Accept: application/json;charset=UTF-8" \
    -H "Content-Type: application/json" \
    "https://external.staging.pleo.io/v0/tags/7b079251-c225-46e6-9f0b-6f2e1b1cdec5" \
    -d '{
          "name": "Sales",
          "code": "Sales",
          "archived": true
        }' \
    | jq
    ```
  </Tab>
</Tabs>

<RememberCallout title="Remember">
  Archive a Tag whenever its corresponding Dimension Value is absent, deleted, blocked, expired, or deactivated in the AS, not only when it is explicitly marked as archived.
</RememberCallout>

#### Example Response

```json theme={null}
{
  "data": {
    "id": "7b079251-c225-46e6-9f0b-6f2e1b1cdec5",
    "groupId": "768fb809-b282-4411-875a-406f8e4c5bdb",
    "name": "Sales",
    "code": "Sales",
    "archived": true,
    "createdAt": "2026-05-22T14:13:25.178728Z",
    "updatedAt": "2026-05-22T14:22:19.413192Z"
  }
}
```

#### What it looks like in Pleo Web App

<div style={{ textAlign: "center" }}>
  <img src="https://mintcdn.com/pleo-61d4d38b/wtOkkKeJcHLAWNr4/images/current/accounting-integrations/imports/tags/ui-tags-active-eng-ops-sales.png?fit=max&auto=format&n=wtOkkKeJcHLAWNr4&q=85&s=cdfb335ad0f077f596e031a91ed4d81c" alt="Active Tags in Pleo for Department Tag Group" width="100%" style={{ display: "block", margin: "0 auto" }} data-path="images/current/accounting-integrations/imports/tags/ui-tags-active-eng-ops-sales.png" />
</div>

<br />

<div style={{ textAlign: "center" }}>
  <img src="https://mintcdn.com/pleo-61d4d38b/wtOkkKeJcHLAWNr4/images/current/accounting-integrations/imports/tags/ui-tags-archive-sales.png?fit=max&auto=format&n=wtOkkKeJcHLAWNr4&q=85&s=3a9f208e26606729cf23acdcc74f2dd2" alt="Archived Tags in Pleo for Department Tag Group" width="100%" style={{ display: "block", margin: "0 auto" }} data-path="images/current/accounting-integrations/imports/tags/ui-tags-archive-sales.png" />
</div>

***

## Result

The table below recaps what happened to each Tag across all steps for the Department Tag Group.

| Tag         | Step 2 (AS Dimension Value) | Step 3 (Pleo State) | Step 5 (Match)     | Action              |
| ----------- | --------------------------- | ------------------- | ------------------ | ------------------- |
| Engineering | Active (ENG)                | Active              | Matched (active)   | No action           |
| Marketing   | Active (MKT)                | Archived            | Matched (archived) | Unarchived (Step 7) |
| Operations  | Active (OPS)                | Does not exist      | No match           | Created (Step 6)    |
| Sales       | —                           | Active              | No match           | Archived (Step 8)   |

Pleo now reflects the active Dimension Values from the AS for the Department Tag Group.

| Tag         | Final State in Pleo | AS Dimension Value | Aligned with AS? |
| ----------- | ------------------- | ------------------ | :--------------: |
| Engineering | Active              | Active             |       ✓ Yes      |
| Marketing   | Active              | Active             |       ✓ Yes      |
| Operations  | Active              | Active             |       ✓ Yes      |
| Sales       | Archived            | —                  |       ✓ Yes      |

This same process runs for every active Tag Group (**Project**, **Finance**, and **Cost Centre**) until all Tags across all Tag Groups are aligned with the AS.

***

## What Comes Next?

<WhatComesNext href="/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-periodicity">
  Sync Periodicity and Scheduling
</WhatComesNext>

***

<div className="text-xs uppercase" style={{ fontVariant: 'small-caps' }}>
  this how-to is part of:
</div>

<div className="mt-4 flex flex-wrap gap-2">
  <a
    href="/docs/current/guides/accounting-integrations/imports/tags-sync-workflow-guide"
    className="inline-flex items-center rounded-full border border-gray-300 dark:border-gray-600
px-3 py-1 text-xs font-medium
bg-white dark:bg-[#1f262b] text-black dark:text-white
hover:bg-gray-100 dark:hover:bg-[#2b2f33]
transition-colors"
  >
    Tags Sync Workflow Guide
  </a>
</div>

***

## Related Reading

* [Sync Tags with Dimension Values](/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-sync-tags)
* [Data Mapping](/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-data-mapping)
* [Sync Periodicity and Scheduling](/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-periodicity)
* [Platform Capabilities — Tags Sync](/docs/current/platform/accounting-integrations/imports/tags/tags-sync-overview)

***