Skip to main content
This page describes how integrations must detect new DRAFT vendors created in Pleo, ready to be created in the Accounting System. This is the first step in the Vendor Creation workflow.

​
Implementation

See the corresponding how-to article for API usage and step-by-step instructions:

​
Conceptual Model

Detection identifies DRAFT vendors that need to be created in the Accounting System. It must:
  • Detect vendors newly created in Pleo with state: DRAFT
  • Avoid modifying vendor state in Pleo
  • Avoid re-processing a vendor that has already been created in the AS

​
Detection Mechanisms

Integrations may use one of the following:

​
Webhooks (preferred)

  • Subscribe to v1.vendor.created
  • Trigger creation processing as soon as the event is received
  • Pleo triggers this event the moment a bookkeeper adds a vendor with no matching AS record, so this is the fastest path to a usable vendor
  • Even when using webhooks as the primary mechanism, pair them with a low-frequency backstop poll (for example, hourly, using the polling mechanism below): webhook delivery is not guaranteed under all failure conditions, and a stranded DRAFT vendor with no repair path can otherwise go undetected indefinitely

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

  • Periodically call POST /v1/vendors:search filtering for vendors in DRAFT state
  • Use a controlled interval of every 5 minutes

​
Single-Item Processing

Unlike Export Jobs, there is no batching concept for Vendor Creation. Each DRAFT vendor is:
  • Detected and processed as its own independent unit of work
  • Not blocked by, or blocking, any other DRAFT vendor being processed at the same time, with one narrow exception: the per-company concurrency lock shared with Vendor Sync (see Create and Activate: Failure Handling) is scoped to the whole company, so two DRAFT vendors for the same company can briefly wait on each other for that lock; vendors in different companies are never affected by each other’s locks

​
Avoiding Duplicate Processing

Filtering on state: DRAFT is not sufficient by itself to prevent the same vendor from being processed twice:
  • Webhook redelivery: the webhook provider may redeliver the same v1.vendor.created event. Persist the event’s eventId and skip any event already processed.
  • Overlapping polls, or webhook and polling running together: a poll cycle can re-detect a DRAFT vendor that is already being created or activated from a previous poll or from the webhook path, because the vendor genuinely still has state: DRAFT until activation completes. Before beginning creation, 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.
See How to Detect Draft Vendors for the implementation.

​
Key Rules

  • Detection must not change a vendor’s state in Pleo; only creation and activation do
  • Prefer webhooks over polling: they notify the integration immediately, rather than after up to 5 minutes of delay
  • If polling, filter strictly on state: DRAFT so already-active vendors are not reprocessed
  • Treat each detected DRAFT vendor as an independent item to create and activate

​
Processing Order

​
Upstream Dependencies

  • A bookkeeper adding a new vendor in Pleo’s Web App
  • Integration authentication configured
  • Webhook subscription or scheduled polling implemented

​
Downstream Dependencies

  • Vendor creation in the Accounting System
  • Vendor activation in Pleo

​
What Comes Next?