> ## 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 Select Dimensions for Tags Sync

export const SelectDimensionsDiagram = () => {
  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
    S1["1. Retrieve Active Dimensions"] --> S2["2. Retrieve Existing Tag Groups"] --> S3["3. Apply Auto-Selection"]
    S3 -->|First connection| S3a["Auto-select matching Dimensions"]
    S3 -->|Subsequent connection| S3b["Restore from config"]
    S3a --> S4["4. Store the Selection"]
    S3b --> S4
    S4 --> S5["5. Handle Inactive Dimensions"]

click S1 "#1-retrieve-active-dimensions-from-the-accounting-system"
click S2 "#2-retrieve-existing-tag-groups-from-pleo"
click S3 "#3-apply-auto-selection-on-first-connection"
click S4 "#4-store-the-dimension-selection"
click S5 "#5-handle-inactive-dimensions"

style S1 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style S2 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style S3 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style S3a white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style S3b white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style S4 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style S5 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="A" />

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

This how-to explains how an integration configures which Accounting Dimensions from the Accounting System are synchronised as Tag Groups in Pleo.

Selecting Dimensions is the first step in the Tags Sync workflow and determines the scope of every subsequent sync cycle.

Your integration must:

* Retrieve active Dimensions from the Accounting System
* Retrieve existing Tag Groups from Pleo
* Apply auto-selection logic on first connection
* Store the selection for use in recurring sync cycles

## 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 Dimension Selection](/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-dimension-selection)
* 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

## Scenario

This how-to uses a concrete example to illustrate each step.

The user is connecting their integration to Pleo for the first time. In their Accounting System, they have manually selected **Finance**, **Cost Centre**, and **Supplier** for synchronisation. The integration will also auto-select **Department** and **Project** because those codes already match active Tag Groups in Pleo.

After the initial connection, **Supplier** becomes inactive in the AS. On the next scheduled sync cycle, step 5 detects this and automatically deselects it.

The table below shows the starting state in both systems before the sync process runs.

| Dimension (AS) | AS Status | Tag Group (Pleo) | Pleo Status    |
| -------------- | --------- | ---------------- | -------------- |
| Department     | Active    | Department       | Active         |
| Project        | Active    | Project          | Active         |
| Finance        | Active    | —                | Does not exist |
| Cost Centre    | Active    | Cost Centre      | Archived       |
| Supplier       | Active    | —                | Does not exist |
| —              | —         | Region           | Active         |

***

## Steps

### 1. Retrieve Active Dimensions from the Accounting System

Fetch all active (non-archived, non-inactive) Dimensions from the Accounting System.

Each Dimension must have:

* A unique **code**
* A human-readable **name**

**Example Pseudo:**

```pseudo theme={null}
dimensions = fetchDimensionsFromAS()

activeDimensions = filter dimensions where status == "active"

if activeDimensions is empty:
    exit workflow
```

#### Example Response

The response format depends on your Accounting System. The following is a representative example:

```json theme={null}
{
  "dimensions": [
    { "code": "Department",  "name": "Department",  "status": "active" },
    { "code": "Project",     "name": "Project",     "status": "active" },
    { "code": "Finance",     "name": "Finance",     "status": "active" },
    { "code": "Cost Centre", "name": "Cost Centre", "status": "active" },
    { "code": "Supplier",    "name": "Supplier",    "status": "active" }
  ]
}
```

After filtering: `activeDimensions` = Department, Project, Finance, Cost Centre, Supplier

***

### 2. Retrieve Existing Tag Groups from Pleo

**API Endpoint**: GET [`/v0/tag-groups`](/reference/tags-api/tag-groups/returns-all-tag-groups-for-given-company)

**Example parameters:**

* companyId: `12abc3d4-e567-890e-1234-abc56e78fabc`
* includeArchived: `false`

Fetch active Tag Groups from Pleo. These are used to identify which Dimensions can be auto-selected on first connection.

**Example Pseudo:**

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

#### Example Request

<Tabs>
  <Tab title="OAuth 2.0">
    ```bash theme={null}
    curl -X GET "https://external.staging.pleo.io/v0/tag-groups?company_id=12abc3d4-e567-890e-1234-abc56e78fabc&include_archived=false" \
      -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?company_id=12abc3d4-e567-890e-1234-abc56e78fabc&include_archived=false" \
    | jq
    ```
  </Tab>
</Tabs>

#### Example Response

```json theme={null}
{
  "data": [
    {
      "id": "768fb809-b282-4411-875a-406f8e4c5bdb",
      "companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
      "name": "Department",
      "code": "Department",
      "archived": false,
      "createdAt": "2026-05-21T13:19:05.124301Z",
      "updatedAt": "2026-05-21T13:19:05.124301Z",
      "metadata": {}
    },
    {
      "id": "a9a0a2f5-a97b-41f9-aa28-dc3cde85f691",
      "companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
      "name": "Project",
      "code": "Project",
      "archived": false,
      "createdAt": "2026-05-21T13:19:43.112716Z",
      "updatedAt": "2026-05-21T13:19:43.112716Z",
      "metadata": {}
    },
    {
      "id": "f1cd0c96-32c5-4b85-8b93-8f6543bc6378",
      "companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
      "name": "Region",
      "code": "Region",
      "archived": false,
      "createdAt": "2026-05-21T14:12:44.543271Z",
      "updatedAt": "2026-05-21T14:12:44.543271Z",
      "metadata": {}
    }
  ]
}
```

<RememberCallout title="Cost Centre">
  Cost Centre also exists in Pleo but is currently archived. Archived Tag Groups are not included in this response; they do not factor into auto-selection matching, but are relevant in the next step when syncing Tag Groups.
</RememberCallout>

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

***

### 3. Apply Auto-Selection on First Connection

On first connection, automatically pre-select Dimensions whose code matches an existing active Tag Group in Pleo.

Matching is **case-insensitive**.

Up to **5 Dimensions** may be selected in total.

**Example Pseudo:**

```pseudo theme={null}
activeTagGroups = filter tagGroups where archived == false
tagGroupCodes   = activeTagGroups.map(code.toLowerCase())

autoSelected = []

for dimension in activeDimensions:
    if dimension.code.toLowerCase() in tagGroupCodes:
        autoSelected.append(dimension)

selectedDimensions = autoSelected.take(5)
```

#### Example Auto-Selection Result

Using the data from steps 1 and 2:

| AS Dimension | Before Connection | Active Pleo Tag Group?   | Auto-Selected | Now Selected |
| ------------ | ----------------- | ------------------------ | :-----------: | :----------: |
| Department   | Not selected      | ✓ Matches "Department"   |     ✓ Yes     |     ✓ Yes    |
| Project      | Not selected      | ✓ Matches "Project"      |     ✓ Yes     |     ✓ Yes    |
| Finance      | Manually selected | ✗ Does not exist in Pleo |       —       |     ✓ Yes    |
| Cost Centre  | Manually selected | ✗ Tag Group is archived  |       —       |     ✓ Yes    |
| Supplier     | Manually selected | ✗ Does not exist in Pleo |       —       |     ✓ Yes    |

Department and Project are auto-selected. Finance, Cost Centre, and Supplier were already manually selected before connecting; this step does not change their selection state.

The full selection entering step 4 is: **Department, Project, Finance, Cost Centre, Supplier**.

<RememberCallout title="Subsequent Connections">
  Auto-selection only runs on first connection. On subsequent connections, the existing selection is restored from your integration's stored configuration.
</RememberCallout>

***

### 4. Store the Dimension Selection

Persist the selected Dimensions in your integration's configuration store.

The stored selection is used as input to every Tags Sync cycle (Steps 2 and 3).

**Example Pseudo:**

```pseudo theme={null}
storeSelectedDimensions(selectedDimensions)
```

#### Example Stored Selection

| Dimension   | Source            |
| ----------- | ----------------- |
| Department  | Auto-selected     |
| Project     | Auto-selected     |
| Finance     | Manually selected |
| Cost Centre | Manually selected |
| Supplier    | Manually selected |

<RememberCallout title="Maximum Selection">
  A maximum of 5 Dimensions may be selected at any time. If the user attempts to select more than 5, reject the additional selection.
</RememberCallout>

***

### 5. Handle Inactive Dimensions

If a previously selected Dimension is no longer active in the AS, automatically deselect it during the next sync cycle.

**Example Pseudo:**

```pseudo theme={null}
for selectedDimension in storedSelectedDimensions:
    if selectedDimension not in activeDimensions:
        deselect(selectedDimension)
```

This ensures the selection remains consistent with the current state of the AS without requiring manual user intervention.

#### Example Result

Supplier was active at the time of the initial connection but has since become inactive in the AS. On this sync cycle it is detected and deselected:

| Dimension   | AS Status | Deselected |
| ----------- | --------- | ---------- |
| Department  | Active    | No         |
| Project     | Active    | No         |
| Finance     | Active    | No         |
| Cost Centre | Active    | No         |
| Supplier    | Inactive  | ✓ Yes      |

Final stored selection: **Department**, **Project**, **Finance**, **Cost Centre**

***

## Result

The table below shows what happened to each Dimension across all steps.

| Dimension   | Retrieved (Step 1) | Auto-Selected (Step 3) | Stored (Step 4) | Step 5                | Final Selection |
| ----------- | ------------------ | ---------------------- | :-------------: | --------------------- | :-------------: |
| Department  | Active             | ✓ Yes                  |      ✓ Yes      | Active (no change)    |      ✓ Yes      |
| Project     | Active             | ✓ Yes                  |      ✓ Yes      | Active (no change)    |      ✓ Yes      |
| Finance     | Active             | Manually selected      |      ✓ Yes      | Active (no change)    |      ✓ Yes      |
| Cost Centre | Active             | Manually selected      |      ✓ Yes      | Active (no change)    |      ✓ Yes      |
| Supplier    | Active             | Manually selected      |      ✓ Yes      | Inactive (deselected) |       ✗ No      |

The final selection is stored and ready for the **Tag Group Sync** cycle:

* Department
* Project
* Finance
* Cost Centre

***

## What Comes Next?

<WhatComesNext href="/docs/current/how-tos/accounting-integrations/imports/tags/how-to-sync-tag-groups-with-accounting-dimensions">
  How to Sync Tag Groups with Accounting Dimensions
</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

* [Tags Sync Overview](/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-overview)
* [Dimension Selection](/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-dimension-selection)
* [Platform Capabilities — Tags Sync](/docs/current/platform/accounting-integrations/imports/tags/tags-sync-overview)

***