This how-to covers creating a new Pleo Vendor for an active AS vendor that has no matching Pleo record.
Run this after [How to Fetch and Match Vendors](/docs/current/how-tos/accounting-integrations/imports/vendors/how-to-fetch-and-match-vendors), which covers fetching and matching vendors from both systems.
## Prerequisites
Before you begin:
* You have completed [How to Fetch and Match Vendors](/docs/current/how-tos/accounting-integrations/imports/vendors/how-to-fetch-and-match-vendors) and have an AS vendor with no matching Pleo Vendor
* Your integration is authenticated using one of the [supported authentication methods](/docs/current/integration-design/auth/integration-design-auth-overview#authentication-policy-overview)
* Your integration can call Pleo's Vendors API endpoints
## Scenario
This how-to continues from the [How to Fetch and Match Vendors](/docs/current/how-tos/accounting-integrations/imports/vendors/how-to-fetch-and-match-vendors) scenario: "Bright Office Ltd" (EXT-003) is active in the AS with no matching Pleo Vendor.
## Steps
Run this call inside your per-company concurrency lock. It's the same lock used by [Vendor Creation](/docs/current/how-tos/accounting-integrations/vendors/how-to-create-vendor-in-as).
Don't run it for a company while a Vendor Creation create-and-activate attempt is in flight for that same company. Doing so risks creating a duplicate for the Vendor it already has in flight.
See [Concurrency with Vendor Creation](/docs/current/integration-design/accounting-integrations/imports/vendors/integration-design-vendor-sync#concurrency-with-vendor-creation) for the full race this prevents.
The same applies to [Unarchiving](/docs/current/how-tos/accounting-integrations/imports/vendors/how-to-unarchive-vendors), [Updating](/docs/current/how-tos/accounting-integrations/imports/vendors/how-to-update-vendors), and [Archiving](/docs/current/how-tos/accounting-integrations/imports/vendors/how-to-archive-vendors) Vendors too.
### 1. Create Vendors for New AS Entries
**API Endpoint**: POST [`/v1/vendors`](/reference/external-vendors/create-a-new-vendor)
If an AS vendor has no matching Pleo Vendor, create a new Vendor. Providing `externalId` on creation sets the Vendor's `state` to `ACTIVE` automatically.
If the AS record has a blank, malformed, or non-ISO `country` (see [Data Mapping](/docs/current/integration-design/accounting-integrations/imports/vendors/integration-design-vendor-sync-data-mapping)), omit that field from the create payload rather than sending the invalid value. Log the invalid value for investigation.
`defaultCurrency` is required by the Vendors API, so it can't be omitted from the create payload. If the AS value is blank, malformed, or non-ISO, either skip creating that vendor and log it for investigation, or send a fallback currency your integration preconfigures for the company and continue. There is no existing Pleo Vendor to fall back to on create, and this API doesn't expose the company's default currency to the integration, so don't guess a value.
Don't fail the entire sync run over one vendor's bad data.
**Example Pseudo:**
```pseudo theme={null}
if matchedVendor is null:
if vendor.defaultCurrency is valid ISO 4217:
currency = vendor.defaultCurrency
else:
logDataQualityIssue(vendor, field = "defaultCurrency")
currency = preconfiguredFallbackCurrency
# or: skip creating this vendor, log it, and continue with the next one
newVendor.companyId = companyId
newVendor.externalId = vendor.externalId
newVendor.code = vendor.code
newVendor.name = vendor.name
if vendor.country is valid ISO 3166-1 alpha-2:
newVendor.country = vendor.country
else:
logDataQualityIssue(vendor, field = "country")
newVendor.defaultCurrency = currency
newVendor.registrationNumber = vendor.registrationNumber
newVendor.taxRegistrationNumber = vendor.taxRegistrationNumber
POST newVendor to Pleo
```
#### Example Request
```bash theme={null}
curl -X POST "https://external.staging.pleo.io/v1/vendors" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json;charset=UTF-8" \
-d '{
"companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
"externalId": "EXT-003",
"code": "1003",
"name": "Bright Office Ltd",
"country": "GB",
"defaultCurrency": "GBP",
"registrationNumber": "08451234",
"taxRegistrationNumber": "GB123456789"
}'
```
```bash theme={null}
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" \
-d '{
"companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
"externalId": "EXT-003",
"code": "1003",
"name": "Bright Office Ltd",
"country": "GB",
"defaultCurrency": "GBP",
"registrationNumber": "08451234",
"taxRegistrationNumber": "GB123456789"
}' \
| jq
```
#### Example Response
```json theme={null}
{
"data": {
"id": "e5f6a7b8-c901-234c-5678-efa90c12dabc",
"companyId": "12abc3d4-e567-890e-1234-abc56e78fabc",
"externalId": "EXT-003",
"code": "1003",
"name": "Bright Office Ltd",
"country": "GB",
"defaultCurrency": "GBP",
"registrationNumber": "08451234",
"taxRegistrationNumber": "GB123456789",
"state": "ACTIVE",
"accountingSystem": "custom_api_integration",
"createdAt": "2026-07-08T10:11:25.715331584Z",
"updatedAt": "2026-07-08T10:11:25.715331584Z"
}
}
```
Because `externalId` was provided, this Vendor is created directly in `ACTIVE` state. Omitting `externalId` instead produces a `DRAFT` Vendor, which is the [Vendor Creation](/docs/current/how-tos/accounting-integrations/vendors/how-to-create-vendors-in-pleo) flow, not Vendor Sync.
`externalId` is unique per company in Pleo. If this call returns `409 CONFLICT_EXCEPTION`, a Vendor with this `externalId` already exists, active or archived, even though [How to Fetch and Match Vendors](/docs/current/how-tos/accounting-integrations/imports/vendors/how-to-fetch-and-match-vendors) didn't find it. See [Handling Edge Cases](#handling-edge-cases) below for what to do.
#### What it looks like in Pleo Web App
1. Select **Accounting** from the main left-hand navigation.
2. Select **Export** from the sub-menu.
3. Click on a row to open the details panel for that expense.
4. Select the **Vendor** drop-down menu to view active Vendors.
"Bright Office Ltd" is now searchable and selectable in the Vendor field on an expense, confirming the Vendor was created as `ACTIVE`.
***
## Handling Edge Cases
The following apply to every write in this suite, Create, Unarchive, Update, and Archive alike, not just this page. The other how-tos link back here rather than repeating them.
* **Create collides with an existing `externalId`:** `externalId` is unique per company, so this call returns `409 CONFLICT_EXCEPTION` if a Vendor with that `externalId` already exists, active or archived. This should not happen for a vendor that went through matching correctly, since that step already checks both states, so treat it as a sign the prior fetch-and-match step missed something (for example, a race condition with a concurrent sync run). Look up the existing Vendor by that `externalId` and unarchive or update it instead of retrying Create, and log the anomaly for investigation.
* **Partial write failure:** If one write (create, update, unarchive, or archive) fails partway through the batch, do not abort the entire run. Continue processing the remaining vendors, and log or report the specific vendor(s) that failed so they can be retried on the next sync cycle.
* **Unknown write outcome:** If a create, update, unarchive, or archive request times out or the response is lost after the request was sent, its outcome is unknown, not necessarily a failure. Do not blindly re-send the same write on this run, since it may have already applied. Instead, re-fetch that specific Vendor's current Pleo state before deciding: if it already matches the intended target state, treat the write as a no-op success and move on; if it does not, retry the write on the next sync cycle rather than immediately, so a slow-but-successful original request has time to be reflected before you re-check.
***
## Result
| Vendor | AS Status | Pleo State Before | Action | Final Pleo State |
| --------------------------- | --------- | ----------------- | ------- | ---------------- |
| Bright Office Ltd (EXT-003) | Active | Does not exist | Created | Active |
***
## What Comes Next?
How to Unarchive Vendors
***
