How to Select Dimensions for Tags Sync

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 and the Integration Design for Dimension Selection
Your integration is authenticated using one of the supported authentication methods
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:

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:

{
  "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 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:

tagGroups = fetchTagGroupsFromPleo(includeArchived: false)

Example Request

OAuth 2.0
API Key

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>"

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

Example Response

{
  "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": {}
    }
  ]
}

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:

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.

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:

storeSelectedDimensions(selectedDimensions)

Example Stored Selection

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

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:

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?

this how-to is part of:

Tags Sync Workflow Guide

​Prerequisites

​Scenario

​Steps

​1. Retrieve Active Dimensions from the Accounting System

​Example Response

​2. Retrieve Existing Tag Groups from Pleo

​Example Request

​Example Response

​3. Apply Auto-Selection on First Connection

​Example Auto-Selection Result

​4. Store the Dimension Selection

​Example Stored Selection

​5. Handle Inactive Dimensions

​Example Result

​Result

​What Comes Next?

​Related Reading

Prerequisites

Scenario

Steps

1. Retrieve Active Dimensions from the Accounting System

Example Response

2. Retrieve Existing Tag Groups from Pleo

Example Request

Example Response

3. Apply Auto-Selection on First Connection

Example Auto-Selection Result

4. Store the Dimension Selection

Example Stored Selection

5. Handle Inactive Dimensions

Example Result

Result

What Comes Next?

Related Reading