How to Detect Draft Vendors

This how-to explains how an integration detects a DRAFT Vendor created directly in Pleo, ready to be created in the Accounting System. Run this after How to Create Vendors in Pleo, which covers the bookkeeper action that produces the DRAFT Vendor. A DRAFT Vendor exists when a bookkeeper adds a new Vendor in Pleo that has no matching record in the AS yet. It has no code or externalId until the integration creates the record in the AS and activates it. Your integration must:

Detect new DRAFT Vendors, ideally the moment they are created
Avoid re-detecting a Vendor that has already been created in the AS

Prerequisites

Before you begin:

You have completed How to Create Vendors in Pleo, or a bookkeeper has otherwise added a new Vendor directly in Pleo
You’re familiar with Detect Draft Vendors
Your integration is authenticated using one of the supported authentication methods
Your integration can call Pleo’s Vendors API endpoints
Webhooks or polling are configured

Scenario

This how-to continues from the How to Create Vendors in Pleo scenario: a bookkeeper added “Greenfield Logistics” as a new Vendor in Pleo, without it existing yet in the Accounting System.

Steps

1. Detect New Draft Vendors

Two discovery strategies are supported.

Option A: Webhook Trigger (Recommended)

Subscribe to the v1.vendor.created webhook. See Configuring Webhooks During Integration for subscription setup. When the event is received, its payload already contains the Vendor’s details, so no additional fetch is required.

Example Webhook Payload

{
  "data": {
    "id": "c27ed4d6-3d3d-458e-8f3f-735fdf32a3bc",
    "companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
    "name": "Greenfield Logistics",
    "country": "GB",
    "registrationNumber": "",
    "taxRegistrationNumber": "GB987654321",
    "code": null,
    "state": "DRAFT",
    "defaultCurrency": "GBP",
    "createdBy": "22aff90a-a53d-4f0c-851f-dd4cc85ac947",
    "createdAt": "2026-07-08T10:05:43.530450712Z",
    "updatedAt": "2026-07-08T10:05:43.530450712Z",
    "deletedAt": null
  },
  "eventType": "v1.vendor.created",
  "eventId": "13d8550d-dd22-46e9-ae18-c171846ba373"
}

Proceed straight to How to Create a Vendor in the AS using the Vendor id and details from the payload.

Option B: Polling (fallback, only if webhooks cannot be supported)

API Endpoint: POST /v1/vendors:search Periodically call the search endpoint filtering on states: ["DRAFT"], on the required polling interval of every 5 minutes. Example Pseudo:

draftVendors = []
cursor = null

do:
    page = searchVendors(states=["DRAFT"], after: cursor)
    draftVendors.extend(page.data)
    cursor = page.pagination.endCursor
while page.pagination.hasNextPage

for vendor in draftVendors:
    createAndActivate(vendor)

Fetch every page before processing. Stopping after the first page can leave DRAFT Vendors undetected until the next poll 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": ["DRAFT"]
      }'

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": ["DRAFT"]
      }' \
| jq

Example Response

{
  "data": [
    {
      "id": "c27ed4d6-3d3d-458e-8f3f-735fdf32a3bc",
      "companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
      "name": "Greenfield Logistics",
      "country": "GB",
      "registrationNumber": "",
      "taxRegistrationNumber": "GB987654321",
      "state": "DRAFT",
      "defaultCurrency": "GBP",
      "createdAt": "2026-07-08T10:05:43.530450712Z",
      "updatedAt": "2026-07-08T10:05:43.530450712Z"
    }
  ],
  "pagination": {
    "hasPreviousPage": false,
    "hasNextPage": false,
    "endCursor": "ZMKHP6I3F5E43BOVXNINZOZGM4",
    "total": 1
  }
}

What it looks like in Pleo Web App

On the expense from How to Create Vendors in Pleo:

Select Accounting from the main left-hand navigation.
Select Export from the sub-menu.
Click on the same row to reopen the details panel for that expense.

“Greenfield Logistics” is selected on the Vendor field, with a note that the Vendor is still being created. This is the DRAFT state your integration needs to detect:

Vendor field on an expense showing newly created Greenfield Logistics, not yet linked to the Accounting System

Handling Edge Cases

Neither detection path guarantees a DRAFT Vendor is seen only once, and there is no batching for Vendor Creation:

Webhook redelivery: the webhook provider may redeliver the same v1.vendor.created event. Persist the eventId from the payload and skip any event you have already processed.
Overlapping polls, or webhook and polling running together: a poll cycle can re-detect a DRAFT Vendor that is already being created/activated from a previous poll or from the webhook path, because the Vendor genuinely still has state: DRAFT until activation completes. Filtering on state: DRAFT does not prevent this. Before creating or activating a Vendor, check whether that Vendor id is already marked in-flight (for example, a persisted “processing” record keyed on the Pleo Vendor id), and skip it if so.
No batching: process each detected DRAFT Vendor as its own independent item. A delay or failure creating one Vendor must not block any other.

Result

After completing this step:

A DRAFT Vendor has been detected, either via webhook or polling
The Vendor’s name, country, defaultCurrency, registrationNumber, and taxRegistrationNumber are available
The integration is ready to create the corresponding record in the AS

What Comes Next?

this how-to is part of:

Vendor Creation Workflow Guide

Get Started

Integration Design

Workflow Guides

How-to's

How to Detect Draft Vendors

Prerequisites

Scenario

Steps

1. Detect New Draft Vendors

Option A: Webhook Trigger (Recommended)

Example Webhook Payload

Option B: Polling (fallback, only if webhooks cannot be supported)

Example Request

Example Response

What it looks like in Pleo Web App

Handling Edge Cases

Result

What Comes Next?

​Prerequisites

​Scenario

​Steps

​1. Detect New Draft Vendors

​Option A: Webhook Trigger (Recommended)

​Example Webhook Payload

​Option B: Polling (fallback, only if webhooks cannot be supported)

​Example Request

​Example Response

​What it looks like in Pleo Web App

​Handling Edge Cases

​Result

​What Comes Next?

​Related Reading

Prerequisites

Scenario

Steps

1. Detect New Draft Vendors

Option A: Webhook Trigger (Recommended)

Example Webhook Payload

Option B: Polling (fallback, only if webhooks cannot be supported)

Example Request

Example Response

What it looks like in Pleo Web App

Handling Edge Cases

Result

What Comes Next?

Related Reading