What You’ll Have Built
After implementing this workflow:- Active vendors from the AS are reflected as Vendors in Pleo.
- Vendors are automatically kept up to date on a scheduled basis.
- Bookkeepers can tag current, accurate vendors to expenses and invoices in Pleo.
- The integration aligns with Pleo’s Vendor Sync guarantees and matching model.
Who This Guide Is For
This guide is intended for:- Integration developers
- Solution architects
- Accounting platform integrators
Before You Start
You should be familiar with:- Pleo’s supported authentication methods.
- The Vendor Sync platform capabilities page.
Vendor Sync Workflow Overview
Vendors in the AS are the definitive list of parties expenses and invoices can be attributed to. Each vendor has anexternalId (the stable identifier used for matching), a code, a name, a country, a defaultCurrency, and optional registrationNumber and taxRegistrationNumber values.
Vendor Sync copies this structure into Pleo. The Accounting System is the source of truth; the integration’s role is to keep Pleo’s Vendors aligned with the current state of the AS so bookkeepers always have accurate, up-to-date vendors when tagging expenses and invoices.
The how-to articles in this section use a consistent example to illustrate each step. The table below shows the starting state in both systems before the sync runs.
The steps progress as follows:
Steps
1. Fetch and Match Vendors
Purpose
This step runs at the start of every Vendor Sync cycle. The integration retrieves active vendors from the AS and all Vendors from Pleo (active and archived), then matches them using theexternalId field to determine what action is needed for each vendor.
Input
- Active vendors from the AS
- Active and archived Vendors from Pleo. Archived Vendors are included so they can be unarchived rather than duplicated if a vendor becomes active in the AS again.
Workflow Process
The integration retrieves AS vendors, then retrieves all Pleo Vendors. It matches every AS vendor against Pleo Vendors byexternalId and determines the required action for each.
Output
- Each AS vendor matched to a Pleo Vendor (or identified as new)
- Each Pleo Vendor identified as requiring creation, unarchiving, updating, or no action
- Active Pleo Vendors with no AS match flagged for archiving
Why It Matters
The matching step is the foundation of the reconciliation. Accurate matching byexternalId ensures vendors are updated rather than duplicated, and that vendors removed from the AS are archived rather than left stale in Pleo.
Integration Design
If you’re an integration developer or architect, read the Sync Vendors integration design doc before implementing this step. It covers the matching rules, performance considerations, and how the sync handles each reconciliation outcome.Step-by-Step Instructions
When you’re ready to start implementing, follow the step-by-step instructions in the accompanying how-to article.2. Create Vendors
Purpose
For each active AS vendor with no matching Pleo Vendor, the integration creates a new Vendor in Pleo.Input
- Active AS vendors identified in Step 1 as having no matching Pleo Vendor
Workflow Process
Output
- A new Vendor created in Pleo, in
ACTIVEstate
Why It Matters
Without this step, a vendor that’s genuinely active in the AS would never appear in Pleo, and bookkeepers could not tag expenses or invoices to it.Integration Design
If you’re an integration developer or architect, read the Sync Vendors integration design doc before implementing this step. It covers the API operation, request and response structure, and the data mapping requirements.Step-by-Step Instructions
3. Unarchive Vendors
Purpose
For each Pleo Vendor identified in Step 1 asARCHIVED while its matching AS vendor is active, the integration unarchives it.
Input
- Pleo Vendors identified in Step 1 as
ARCHIVEDwith an active matching AS vendor
Workflow Process
Output
- The Pleo Vendor’s
statetransitions back toACTIVE
Why It Matters
An AS vendor that becomes active again after being archived should reuse its existing Pleo Vendor record, not a duplicate. Unarchiving preserves that vendor’s history.Integration Design
If you’re an integration developer or architect, read the Sync Vendors integration design doc before implementing this step. It covers the API operation, request and response structure, and the data mapping requirements.Step-by-Step Instructions
4. Update Vendors
Purpose
For each matched Vendor whose details differ from the AS, the integration updates the Pleo Vendor to match.Input
- Matched Pleo Vendors identified in Step 1 as having details that differ from the AS
Workflow Process
Output
- The Pleo Vendor’s details (name, country, currency, registration and tax numbers) updated to match the AS
Why It Matters
Without this step, Pleo’s vendor details drift out of date, and bookkeepers could tag expenses or invoices to a vendor whose details no longer reflect the AS.Integration Design
If you’re an integration developer or architect, read the Sync Vendors integration design doc before implementing this step. It covers the API operation, request and response structure, and the data mapping requirements.Step-by-Step Instructions
5. Archive Vendors
Purpose
For each active Pleo Vendor identified in Step 1 as having no matching active AS vendor, across at least two consecutive sync runs, the integration archives it.Input
- Active Pleo Vendors with no matching active AS vendor, unmatched across at least two consecutive sync runs. See the Sync Vendors integration design doc for the full two-consecutive-run safeguard.
Workflow Process
Output
- The Pleo Vendor’s
statetransitions toARCHIVED - The vendor is no longer offered for bookkeepers to tag on expenses and invoices, though it remains available to unarchive if it becomes active in the AS again
Why It Matters
A vendor no longer active in the AS should not stay tag-able in Pleo. Archiving, rather than deleting, keeps historical data intact while preventing new expenses or invoices from being tagged to it.Integration Design
If you’re an integration developer or architect, read the Sync Vendors integration design doc before implementing this step. It covers the API operation, request and response structure, and the data mapping requirements.Step-by-Step Instructions
Observability and Recovery
Build in enough visibility to detect and recover from failures without manual database inspection:- Sync-run ID: generate a unique ID for each sync run and include it in every log line for that run, so all create/update/unarchive/archive actions taken during one execution can be traced together.
- Per-action counters: log how many Vendors were created, updated, unarchived, and archived in each run. A sudden spike (for example, archiving far more vendors than usual) can indicate a partial AS fetch or a misconfigured connection, and is easier to catch with counters than by inspecting individual log lines.
- Audit trail: for each write action, log the vendor’s
id,externalId, the action taken, and the fields that changed, so any Vendor’s history can be reconstructed later.
What Comes Next?
Once Vendor Sync is live, bookkeepers can tag the synced vendors to expenses and invoices in Pleo before export. To complete Level 4, also implement the complementary direction:- Vendor Creation Workflow Guide: create vendors in the AS when a bookkeeper adds a new one directly in Pleo.