How to Create, Update, and Archive Accounts

This how-to covers the write operations for Chart of Accounts Sync: creating new Accounts, updating or unarchiving existing Accounts, and archiving Accounts that are no longer active in the Accounting System. Run this after How to Sync Accounts, which covers fetching and matching accounts from both systems.

Prerequisites

Before you begin:

You have completed How to Sync Accounts and determined what action is needed for each account
Your integration is authenticated using one of the supported authentication methods
Your integration can call Pleo’s Chart of Accounts API endpoints

Scenario

This how-to continues from the How to Sync Accounts scenario. After matching, the following actions are required:

AS Account	Pleo Account	Action
1000 - Office Supplies	1000 - Office Supplies	No action
2000 - Travel	2000 - Travel	Unarchive
3000 - Software	—	Create
4000 - Marketing	4000 - Advertising	Update
—	5000 - Entertainment	Archive

The diagram below shows where these operations fit in the full reconciliation loop.

Steps

1. Create Accounts for New AS Entries

API Endpoint: POST /v1/chart-of-accounts If an AS account has no matching Pleo Account, create a new Account. Example Pseudo:

if matchedAccount is null:
    newAccount.externalId = account.externalId
    newAccount.code       = account.code
    newAccount.name       = account.name
    newAccount.archived   = false
    POST newAccount to Pleo

Example Request

OAuth 2.0
API Key

curl -X POST "https://external.staging.pleo.io/v1/chart-of-accounts" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
        "externalId": "ext-3000",
        "code": "3000",
        "name": "Software",
        "archived": false
      }'

curl --request POST \
  -u "pls_1ab2cd3e4f5g6h7a89b012c34de56f78_gabc90:" \
  -H "Accept: application/json;charset=UTF-8" \
  -H "Content-Type: application/json" \
  "https://external.staging.pleo.io/v1/chart-of-accounts" \
  -d '{
        "companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
        "externalId": "ext-3000",
        "code": "3000",
        "name": "Software",
        "archived": false
      }' \
| jq

Example Response

{
  "data": {
    "id": "e5f6g7h8-i901-234i-5678-efg90i12defg",
    "companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
    "externalId": "ext-3000",
    "code": "3000",
    "name": "Software",
    "archived": false
  }
}

What it looks like in Pleo Web App

2. Unarchive or Update Existing Accounts

API Endpoint: PUT /v1/chart-of-accounts/{accountId} If a matching Account is found:

AS account is active, Pleo Account is archived: Unarchive by setting archived: false and update name and code if they differ.
AS account is active, Pleo Account name or code differs: Update the Account to match the AS.
AS account is active, Pleo Account name and code match: No action required.

Example Pseudo:

if matchedAccount.archived == true:
    matchedAccount.archived = false
    matchedAccount.name     = account.name
    matchedAccount.code     = account.code
    PUT matchedAccount to Pleo

else if matchedAccount.name != account.name or matchedAccount.code != account.code:
    matchedAccount.name = account.name
    matchedAccount.code = account.code
    PUT matchedAccount to Pleo

Unarchive

Example Request

The “2000 - Travel” Account is unarchived in this example.

OAuth 2.0
API Key

curl -X PUT "https://external.staging.pleo.io/v1/chart-of-accounts/d8371c2d-3f62-47df-a8d6-6a3ba6387e00" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "externalId": "ext-2000",
        "code": "2000",
        "name": "Travel",
        "archived": false
      }'

curl --request PUT \
  -u "pls_1ab2cd3e4f5g6h7a89b012c34de56f78_gabc90:" \
  -H "Accept: application/json;charset=UTF-8" \
  -H "Content-Type: application/json" \
  "https://external.staging.pleo.io/v1/chart-of-accounts/d8371c2d-3f62-47df-a8d6-6a3ba6387e00" \
  -d '{
        "externalId": "ext-2000",
        "code": "2000",
        "name": "Travel",
        "archived": false
      }' \
| jq

Example Response

{
  "data": {
    "id": "d8371c2d-3f62-47df-a8d6-6a3ba6387e00",
    "companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
    "externalId": "ext-2000",
    "code": "2000",
    "name": "Travel",
    "archived": false
  }
}

What it looks like in Pleo Web App

Update

Example Request

The “4000 - Advertising” Account is renamed to “4000 - Marketing” to match the AS in this example.

OAuth 2.0
API Key

curl -X PUT "https://external.staging.pleo.io/v1/chart-of-accounts/a470bfbe-8046-4b43-a4d9-4f5796acdd93" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "externalId": "ext-4000",
        "code": "4000",
        "name": "Marketing",
        "archived": false
      }'

curl --request PUT \
  -u "pls_1ab2cd3e4f5g6h7a89b012c34de56f78_gabc90:" \
  -H "Accept: application/json;charset=UTF-8" \
  -H "Content-Type: application/json" \
  "https://external.staging.pleo.io/v1/chart-of-accounts/a470bfbe-8046-4b43-a4d9-4f5796acdd93" \
  -d '{
        "externalId": "ext-4000",
        "code": "4000",
        "name": "Marketing",
        "archived": false
      }' \
| jq

Example Response

{
  "data": {
    "id": "a470bfbe-8046-4b43-a4d9-4f5796acdd93",
    "companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
    "externalId": "ext-4000",
    "code": "4000",
    "name": "Marketing",
    "archived": false
  }
}

What it looks like in Pleo Web App

Before update:

Active Accounts showing 4000 - Advertising

After Update:

Active Accounts showing 4000 - Marketing

3. Archive Accounts with No Matching AS Entry

API Endpoint: PUT /v1/chart-of-accounts/{accountId} If a Pleo Account is active but its corresponding AS account is no longer active (or does not exist), archive the Account. Do not delete Accounts. Archiving is non-destructive and reversible. Example Pseudo:

activeASExternalIds = activeASAccounts.map(a => a.externalId)

for account in pleoAccounts where archived == false:
    if account.externalId not in activeASExternalIds:
        account.archived = true
        PUT account to Pleo

Example Request

OAuth 2.0
API Key

curl -X PUT "https://external.staging.pleo.io/v1/chart-of-accounts/7ea2006f-180e-4c52-a2bb-562d3a62fd48" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "externalId": "5000",
        "code": "5000",
        "name": "Entertainment",
        "archived": true
      }'

curl --request PUT \
  -u "pls_1ab2cd3e4f5g6h7a89b012c34de56f78_gabc90:" \
  -H "Accept: application/json;charset=UTF-8" \
  -H "Content-Type: application/json" \
  "https://external.staging.pleo.io/v1/chart-of-accounts/7ea2006f-180e-4c52-a2bb-562d3a62fd48" \
  -d '{
        "externalId": "5000",
        "code": "5000",
        "name": "Entertainment",
        "archived": true
      }' \
| jq

Example Response

{
  "data": {
    "id": "7ea2006f-180e-4c52-a2bb-562d3a62fd48",
    "companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
    "externalId": "5000",
    "code": "5000",
    "name": "Entertainment",
    "archived": true
  }
}

What it looks like in Pleo Web App

Archive Accounts showing that Entertainment is not longer part of the list

Archive Accounts showing that Entertainment was archived

Result

The table below recaps what happened to each Account across all steps.

Account	AS Status	Pleo State Before	Action	Final Pleo State
1000 - Office Supplies	Active	Active, matches	No action	Active
2000 - Travel	Active	Archived	Unarchived	Active
3000 - Software	Active	Does not exist	Created	Active
4000 - Marketing	Active	Active, name differed	Updated	Active
5000 - Entertainment	Not in AS	Active	Archived	Archived

Pleo now reflects the current Chart of Accounts from the AS.

Account	Final State in Pleo	In AS?	Aligned?
1000 - Office Supplies	Active	Yes	✓ Yes
2000 - Travel	Active	Yes	✓ Yes
3000 - Software	Active	Yes	✓ Yes
4000 - Marketing	Active	Yes	✓ Yes
5000 - Entertainment	Archived	No	✓ Yes

What Comes Next?

this how-to is part of:

Chart of Accounts Sync Workflow Guide

​Prerequisites

​Scenario

​Steps

​1. Create Accounts for New AS Entries

​Example Request

​Example Response

​What it looks like in Pleo Web App

​2. Unarchive or Update Existing Accounts

​Unarchive

​Example Request

​Example Response

​What it looks like in Pleo Web App

​Update

​Example Request

​Example Response

​What it looks like in Pleo Web App

​3. Archive Accounts with No Matching AS Entry

​Example Request

​Example Response

​What it looks like in Pleo Web App

​Result

​What Comes Next?

​Related Reading

Prerequisites

Scenario

Steps

1. Create Accounts for New AS Entries

Example Request

Example Response

What it looks like in Pleo Web App

2. Unarchive or Update Existing Accounts

Unarchive

Example Request

Example Response

What it looks like in Pleo Web App

Update

Example Request

Example Response

What it looks like in Pleo Web App

3. Archive Accounts with No Matching AS Entry

Example Request

Example Response

What it looks like in Pleo Web App

Result

What Comes Next?

Related Reading