> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pleo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

export const NoteCallout = ({title, children}) => <div className="callout-box callout-note">
    <div className="callout-row">
      <span className="callout-icon">
        <svg width="22" height="22" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="currentColor"><path d="M208,104a79.86,79.86,0,0,1-30.59,62.92A24.29,24.29,0,0,0,168,186v6a8,8,0,0,1-8,8H96a8,8,0,0,1-8-8v-6a24.11,24.11,0,0,0-9.3-19A79.87,79.87,0,0,1,48,104.45C47.76,61.09,82.72,25,126.07,24A80,80,0,0,1,208,104Z" opacity="0.2" /><path d="M176,232a8,8,0,0,1-8,8H88a8,8,0,0,1,0-16h80A8,8,0,0,1,176,232Zm40-128a87.55,87.55,0,0,1-33.64,69.21A16.24,16.24,0,0,0,176,186v6a16,16,0,0,1-16,16H96a16,16,0,0,1-16-16v-6a16,16,0,0,0-6.23-12.66A87.59,87.59,0,0,1,40,104.49C39.74,56.83,78.26,17.14,125.88,16A88,88,0,0,1,216,104Zm-16,0a72,72,0,0,0-73.74-72c-39,.92-70.47,33.39-70.26,72.39a71.65,71.65,0,0,0,27.64,56.3A32,32,0,0,1,96,186v6h64v-6a32.15,32.15,0,0,1,12.47-25.35A71.65,71.65,0,0,0,200,104Zm-16.11-9.34a57.6,57.6,0,0,0-46.56-46.55,8,8,0,0,0-2.66,15.78c16.57,2.79,30.63,16.85,33.44,33.45A8,8,0,0,0,176,104a9,9,0,0,0,1.35-.11A8,8,0,0,0,183.89,94.66Z" /></svg>
      </span>
      <div>
        {title && <div className="callout-title">
            {title}
          </div>}
        <div className="callout-body">
          {children}
        </div>
      </div>
    </div>
  </div>;

<NoteCallout title="Note">
  This API is in the early access stage and is available to select pilot partners.
</NoteCallout>

This API enables you to synchronise the list of vendor records, applicable for your business, between the external ERP/accounting system and Pleo. This is crucial as this enables you to tag specific vendors to accounting entries, helping you in assessing the amount of expenses incurred per vendor.

## What is a Vendor?

A vendor is an individual or business entity that sells goods or services to customers.

## Vendor Synchronisation between Pleo and ERP/Accounting System

This is how vendor records are synchronised between Pleo and the ERP/accounting system:

* For importing vendors from the ERP/accounting system to Pleo — the integration sends a request for each individual record to the `POST Create a New Vendor` endpoint.
* Whenever, a new vendor is created in the accounting application, the integration sends a request to the `POST Create a New Vendor` endpoint — this creates the corresponding record in Pleo.

<NoteCallout title="Note">The vendor is created in `Active` state and is identified by its unique code assigned by the ERP/accounting application. There is another scenario, where you can create a vendor in Pleo, without the record existing in the ERP/accounting system. For more information, see [Vendor Creation in Pleo](#vendor-creation-in-pleo).</NoteCallout>

* If and when any updates are made to a vendor account in the accounting application, the integration sends a request to the `PUT Update a Vendor` endpoint. This ensures that the vendor records in both the accounting system and Pleo are always in sync.
* When any vendor is inactivated or deleted in the ERP/accounting system — the integrations sends a request to `POST Archive a Vendor` endpoint; the status is changed to `archive` state in Pleo.
  <NoteCallout title="Note">You cannot remove a vendor in Pleo, unless the record is inactivated or deleted in the ERP/accounting system.</NoteCallout>
* Similarly, when any vendor is unarchived and set to the `active` status in the ERP/accounting system — a request is sent to the `POST Marks a Vendor as active` endpoint. This activates the vendor record in Pleo.

<NoteCallout title="Note">For optimised results, we recommend the integration to send a request to the `POST Fetches Vendors by Search Criteria` endpoint to compare the records existing between the ERP/accounting system and Pleo; for fetching the search results, the integration must send the specific vendor `codes`. Based on the response received, the integration might create, update, archive, or activate vendors in Pleo.</NoteCallout>

### Vendor Creation in Pleo

You can also create a new vendor in Pleo without the record existing in the ERP/accounting system — send a manual request to the `POST Create a New Vendor` endpoint. The vendor is created in `Draft` state as the corresponding record is not yet present in the client; also, the `code` identifier is missing in this stage as it is assigned to each record by the ERP/accounting system. A webhook event `v1.vendor.created` is generated and a notification is sent to the integration. Once the record is created in the ERP system, the integration sends a request to the `POST Marks a Vendor as Active` endpoint — this changes the `Draft` state to `Active` and also assigns a unique `code` to the record.

<NoteCallout title="Note">The synchronisation mechanism is run frequently to avoid stale data.</NoteCallout>

## Vendor API Functions

The Vendor API allows you to perform various operations related to vendors, such as creating, retrieving, updating, archiving, and activating vendors. Each vendor is identified by a unique `code` that is assigned by the external application. Pleo also assigns an `id` to each record for internal identification.

When an accounting entry is linked to a vendor, it helps to bookkeep the accounting entry to the correct vendor in the external accounting system.

## Webhook Notification

When any vendor is created in Pleo (the record is not yet existing in the ERP/accounting system), a webhook event `v1.vendor.created` is triggered. If the integration has subscribed to this event, a notification is sent to the configured endpoint.

For more information on how to configure webhook subscriptions, see [Configuring Webhooks During Integration](/reference/overview-webhooks#configuring-webhooks-during-integration).

### Sample Webhook Notification

```json theme={null}
"Event Headers":
{
    "webhook-id":"msg_p5jXN8AQM9LWM0D4loKWxJek",
    "webhook-timestamp":1614265330,
    "webhook-signature":"v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE="
}
"Event Body":
{
    "data": {
        "id": "c27ed4d6-3d3d-458e-8f3f-735fdf32a3bc",
        "companyId": "00000000-0000-0000-0000-000000000000",
        "name": "Pleo Technologies GmbH",
        "country": "DE",
        "registrationNumber": "",
        "taxRegistrationNumber": "DE36538686",
        "code": null,
        "state": "DRAFT",
        "defaultCurrency": "EUR",
        "createdBy": "22aff90a-a53d-4f0c-851f-dd4cc85ac947",
        "createdAt": "2025-02-21T10:05:43.530450712Z",
        "updatedAt": "2025-02-21T10:05:43.530450712Z",
        "deletedAt": null,
    },
    "eventType": "v1.vendor.created",
    "eventId": "13d8550d-dd22-46e9-ae18-c171846ba373"
}
```

## Rate Limits

The APIs have a rate limit of 600 requests per minute.