How to Create Vendors

​

Prerequisites

• You have completed 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
• Your integration can call Pleo’s Vendors API endpoints

​

Scenario

​

Steps

​

1. Create Vendors for New AS Entries

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

curl -X POST "https://external.staging.pleo.io/v1/vendors" \
  -H "Authorization: Bearer <access_token>" \
  -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"
      }'

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

{
  "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"
  }
}

​

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.

​

Handling Edge Cases

• 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

​

What Comes Next?

​

Related Reading

• How to Fetch and Match Vendors
• How to Unarchive Vendors
• Sync Vendors Integration Design
• Vendor Sync Data Mapping
• Platform Capabilities: Vendor Sync