How to Fetch and Match Vendors

This how-to covers the fetch and match phase of Vendor Sync: retrieving vendors from the Accounting System and Vendors from Pleo, then determining what action is needed for each. For the write operations, see How to Create Vendors, How to Unarchive Vendors, How to Update Vendors, and How to Archive Vendors. Your integration must:

Retrieve active vendors from the AS
Retrieve all Vendors (active and archived) from Pleo
Match AS vendors to Pleo Vendors by externalId to determine what action is needed

Prerequisites

Before you begin:

You’re familiar with the Vendor Sync Implementation Overview and Sync Vendors
Your integration is authenticated using one of the supported authentication methods
Your integration can call Pleo’s Vendors API endpoints
Your integration can call the target Accounting System’s own API to fetch active vendors

Scenario

This how-to uses a consistent example to illustrate each step. The table below shows the starting state in both systems before this sync runs.

Vendor (AS)	AS Status	Vendor (Pleo)	Pleo Status
Acme Supplies (EXT-001)	Active	Acme Supplies (EXT-001)	Active
Nordic Freight (EXT-002)	Active	Nordic Freight (EXT-002)	Archived
Bright Office Ltd (EXT-003)	Active	—	Does not exist
Kaffehuset AS (EXT-004)	Active	Kaffehuset AS (EXT-004)	Active
—	—	Old Print Shop (EXT-005)	Active

Steps

1. Retrieve Active Vendors from the Accounting System

Fetch all active vendors from the AS. Example Pseudo:

rawActiveASVendors = fetchActiveVendorsFromAS()

// Apply the data integrity rules from Vendor Sync's design:
// https://docs.pleo.io/docs/current/integration-design/accounting-integrations/imports/vendors/integration-design-vendor-sync
activeASVendors = []
externalIdCounts = countBy(rawActiveASVendors, v => v.externalId)

for vendor in rawActiveASVendors:
    if isEmpty(vendor.externalId):
        logError("Skipped vendor with empty/null externalId", vendor)
        continue
    if externalIdCounts[vendor.externalId] > 1:
        logError("Skipped vendor with duplicate externalId", vendor)
        continue
    activeASVendors.push(vendor)

Example Result

Vendor	externalId	Code	Country	Currency
Acme Supplies	EXT-001	1001	GB	GBP
Nordic Freight	EXT-002	1002	DK	DKK
Bright Office Ltd	EXT-003	1003	GB	GBP
Kaffehuset AS	EXT-004	1004	DK	DKK

2. Retrieve All Vendors from Pleo

API Endpoint: POST /v1/vendors:search Fetch both active and archived Vendors from Pleo. Including archived Vendors allows unarchiving rather than creating duplicates. Filter the search to the ACTIVE and ARCHIVED states explicitly using the states field. This excludes DRAFT Vendors, which belong to the Vendor Creation flow and are not handled by Vendor Sync’s matching logic. Example Pseudo:

pleoVendors = []
cursor = null

do:
    page = fetchVendorsFromPleo(states: ["ACTIVE", "ARCHIVED"], after: cursor)
    pleoVendors.extend(page.data)
    cursor = page.pagination.endCursor
while page.pagination.hasNextPage

Fetch every page before matching. Acting on a partial (first-page-only) result set can miss Vendors and cause them to be incorrectly archived or recreated. If any page fetch fails partway through, abort the sync run entirely rather than matching against an incomplete result set; retry the full fetch on the next cycle.

Example Request

OAuth 2.0
API Key

curl -X POST "https://external.staging.pleo.io/v1/vendors:search?company_id=12abc3d4-e567-890e-1234-abc56e78fabc" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -d '{"states": ["ACTIVE", "ARCHIVED"]}'

curl --request POST \
  -u "pls_1ab2cd3e4f5g6h7a89b012c34de56f78_gabc90:" \
  -H "Accept: application/json;charset=UTF-8" \
  -H "Content-Type: application/json;charset=UTF-8" \
  "https://external.staging.pleo.io/v1/vendors:search?company_id=12abc3d4-e567-890e-1234-abc56e78fabc" \
  -d '{"states": ["ACTIVE", "ARCHIVED"]}' \
| jq

Example Response

{
  "data": [
    {
      "id": "d4e5f6a7-b890-123b-4567-def89b01cabc",
      "companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
      "name": "Acme Supplies",
      "code": "1001",
      "externalId": "EXT-001",
      "country": "GB",
      "defaultCurrency": "GBP",
      "state": "ACTIVE",
      "accountingSystem": "custom_api_integration",
      "createdAt": "2026-06-01T08:46:55.778461Z",
      "updatedAt": "2026-06-01T08:47:11.345094Z"
    },
    {
      "id": "c3d4e5f6-a789-012a-3456-cde78a90babc",
      "companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
      "name": "Nordic Freight",
      "code": "1002",
      "externalId": "EXT-002",
      "country": "DK",
      "defaultCurrency": "DKK",
      "state": "ARCHIVED",
      "accountingSystem": "custom_api_integration",
      "createdAt": "2026-06-01T08:47:59.430364Z",
      "updatedAt": "2026-06-01T08:49:41.829869Z"
    },
    {
      "id": "b2c3d4e5-f678-901f-2345-bcd67f89aabc",
      "companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
      "name": "Kaffehuset AS",
      "code": "1004",
      "externalId": "EXT-004",
      "country": "SE",
      "defaultCurrency": "SEK",
      "state": "ACTIVE",
      "accountingSystem": "custom_api_integration",
      "createdAt": "2026-06-01T08:48:52.799351Z",
      "updatedAt": "2026-06-01T08:49:30.424444Z"
    },
    {
      "id": "a1b2c3d4-e567-890e-1234-abc56e78fabc",
      "companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
      "name": "Old Print Shop",
      "code": "1005",
      "externalId": "EXT-005",
      "country": "GB",
      "defaultCurrency": "GBP",
      "state": "ACTIVE",
      "accountingSystem": "custom_api_integration",
      "createdAt": "2026-06-01T08:49:26.679397Z",
      "updatedAt": "2026-06-01T08:49:26.679397Z"
    }
  ],
  "pagination": {
    "hasPreviousPage": false,
    "hasNextPage": false,
    "endCursor": "V5MEDOJJYJDJTLHZ2BMGH62EGU",
    "total": 4
  }
}

Example Result

Vendor	externalId	Status
Acme Supplies	EXT-001	Active
Nordic Freight	EXT-002	Archived
Kaffehuset AS	EXT-004	Active (country and currency differ from AS: SE/SEK vs DK/DKK)
Old Print Shop	EXT-005	Active

What it looks like in Pleo Web App

Pleo has no dedicated Vendors list page, so the Vendor field on an expense’s detail panel is used to confirm which Vendors are currently active and searchable:

Select Accounting from the main left-hand navigation.
Select Export from the sub-menu.
Click on a row to open the details panel for that expense.
Select the Vendor drop-down menu to view active Vendors.

Vendor dropdown on an expense showing active vendors

3. Match AS Vendors to Pleo Vendors by externalId

For each active AS vendor, attempt to find a matching Vendor in Pleo using externalId. Example Pseudo:

pleoExternalIdCounts = countBy(pleoVendors, v => v.externalId)
pleoVendorsByExternalId = {}
poisonedExternalIds = new Set()

for vendor in pleoVendors:
    if pleoExternalIdCounts[vendor.externalId] > 1:
        logError("Skipped Pleo Vendor with duplicate externalId", vendor)
        poisonedExternalIds.add(vendor.externalId)
        continue
    pleoVendorsByExternalId[vendor.externalId] = vendor

actions = []

for vendor in activeASVendors:
    if poisonedExternalIds.has(vendor.externalId):
        logError("Skipped AS Vendor: matching externalId has a Pleo-side duplicate", vendor)
        continue

    matchedVendor = pleoVendorsByExternalId[vendor.externalId]

    if matchedVendor is null:
        if pendingActivationExternalIds.has(vendor.externalId):
            logInfo("Skipped: externalId already claimed by an in-flight Vendor Creation attempt", vendor)
            continue
        actions.add({ action: "CREATE", asVendor: vendor })
    else if matchedVendor.state == "ARCHIVED":
        actions.add({ action: "UNARCHIVE", asVendor: vendor, pleoVendor: matchedVendor })
    else if detailsDiffer(matchedVendor, vendor):
        actions.add({ action: "UPDATE", asVendor: vendor, pleoVendor: matchedVendor })
    // else: no action needed

This step only determines the action needed for each vendor. See How to Create Vendors, How to Unarchive Vendors, How to Update Vendors, and How to Archive Vendors for how each action is executed.

Example Result

AS Vendor	Pleo Vendor	Pleo Status	Action
Acme Supplies (EXT-001)	Acme Supplies (EXT-001)	Active, matches	No action
Nordic Freight (EXT-002)	Nordic Freight (EXT-002)	Archived	Unarchive
Bright Office Ltd (EXT-003)	—	Does not exist	Create
Kaffehuset AS (EXT-004)	Kaffehuset AS (EXT-004)	Active, country and currency differ	Update
—	Old Print Shop (EXT-005)	Active	Archive

Handling Edge Cases

Empty result set: If either fetch returns no vendors (no active vendors in the AS, or no Vendors in Pleo), the matching step has nothing to pair up. This is a normal outcome, not an error; the one-sided steps still run as normal, for example Create for every AS vendor when Pleo has none, or, when the AS has none, treating every active Pleo Vendor as unmatched for this run following the normal two-consecutive-run archive safeguard, not archiving them immediately on this single run.
Already-active or already-archived conflicts: Matching a vendor that requires no change (Pleo already reflects the AS’s active state and details) is expected and should not be logged as a discrepancy.

What Comes Next?

this how-to is part of:

Vendor Sync Workflow Guide

Get Started

Integration Design

Workflow Guides

How-to's

How to Fetch and Match Vendors

Prerequisites

Scenario

Steps

1. Retrieve Active Vendors from the Accounting System

Example Result

2. Retrieve All Vendors from Pleo

Example Request

Example Response

Example Result

What it looks like in Pleo Web App

3. Match AS Vendors to Pleo Vendors by externalId

Example Result

Handling Edge Cases

What Comes Next?

​Prerequisites

​Scenario

​Steps

​1. Retrieve Active Vendors from the Accounting System

​Example Result

​2. Retrieve All Vendors from Pleo

​Example Request

​Example Response

​Example Result

​What it looks like in Pleo Web App

​3. Match AS Vendors to Pleo Vendors by externalId

​Example Result

​Handling Edge Cases

​What Comes Next?

​Related Reading

Prerequisites

Scenario

Steps

1. Retrieve Active Vendors from the Accounting System

Example Result

2. Retrieve All Vendors from Pleo

Example Request

Example Response

Example Result

What it looks like in Pleo Web App

3. Match AS Vendors to Pleo Vendors by externalId

Example Result

Handling Edge Cases

What Comes Next?

Related Reading