Vendors via API

The Vendors API lets you create and manage external suppliers or service providers that your organization pays. Vendors are a foundational resource for Accounts Payable workflows, referenced by purchase orders and bills.

Before you begin

• Obtain your access token API by authenticating to Airwallex using your unique Client ID and API key. You can create scoped API keys in Settings > Developer > API keys in the Airwallex web app. Spend resources require Organization-level permissions.
• Retrieve your legal entity IDs: Vendor creation requires legal_entity_ids to associate the vendor with specific legal entities in your organization. Call the Retrieve account details API endpoint to get your account's legal_entity_id. See Retrieve legal entity IDs for details.
• Set up custom accounting data if you plan to use accounting field selections.

Retrieve legal entity IDs

Creating a vendor requires one or more legal entity IDs to specify which legal entities in your organization the vendor is associated with.

1. Call the Retrieve account details API endpoint:

   Shell

   1curl -G \
   2  'https://api-demo.airwallex.com/api/v1/account' \
   3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

2. Extract the legal_entity_id from the response:

   JSON

   1{
   2  "id": "acct_abc123",
   3  "legal_entity_id": "le_xyz789",
   4  "account_name": "Acme Corp"
   5}

3. Save the legal_entity_id value to use in the legal_entity_ids field when creating a vendor.

For multi-entity organizations, you can associate a vendor with multiple legal entities by providing multiple IDs in the array.

Create a vendor

After retrieving legal entity IDs, create the vendor by calling the Create vendor API endpoint.

1. Send the create request with the required fields:

   Shell

   1curl -X POST \
   2  'https://api-demo.airwallex.com/api/v1/spend/vendors/create' \
   3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
   4  -H 'Content-Type: application/json' \
   5  -d '{
   6    "request_id": "unique-request-id-001",
   7    "external_id": "VENDOR-ERP-001",
   8    "name": "Global Supplies Ltd",
   9    "legal_entity_ids": [
   10      "le_xyz789"
   11    ],
   12    "status": "ACTIVE",
   13    "sync_status": "SYNCED"
   14  }'

   Optional fields include owner_email, business_registration_number, business_name, country_code, address, and contacts.

2. The response returns the created vendor with its unique ID:

   JSON

   1{
   2  "id": "985461d5-016f-4e1f-a387-5f1380b42d92",
   3  "external_id": "VENDOR-ERP-001",
   4  "name": "Global Supplies Ltd",
   5  "legal_entity_ids": ["le_xyz789"],
   6  "status": "ACTIVE",
   7  "sync_status": "SYNCED",
   8  "created_at": "2026-02-01T10:00:00Z"
   9}

List vendors

To retrieve a list of vendors, call the List vendors API endpoint. You can filter by legal entity, by status (ACTIVE, DRAFT...) or by sync_status (NOT_SYNCED, SYNCED...).

1. Send the request with optional filters:

   Shell

   1curl -G \
   2  'https://api-demo.airwallex.com/api/v1/spend/vendors' \
   3  --data-urlencode 'legal_entity_id=le_xyz789' \
   4  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

2. The response returns a list of matching vendors:

   JSON

   1{
   2  "items": [
   3    {
   4      "address": {...},
   5      "approvers": [],
   6      "business_name": "Example Vendor Business Name",
   7      "business_registration_number": "123456789",
   8      "contacts": [],
   9      "created_at": "",
   10      "id": "uuid",
   11      "legal_entity_ids": ["le_xyz789"],
   12      "name": "Global Supplies Ltd",
   13      "status": "ACTIVE",
   14      "sync_status": "SYNCED",
   15      "updated_at": "",
   16      "owner_email": ""
   17    }
   18  ],
   19  "page_after": "eyJwYWdlX2JlZm9yZSI6IjIwMjUtMDctMDFUMDA6MDA6MDBaIn0=",
   20  "page_before": "eyJwYWdlX2JlZm9yZSI6IjIwMjUtMDctMDFUMDA6MDA6MDBaIn0="
   21}

Key query parameters include:

Get vendor details

To retrieve the full details of a specific vendor, call the Get vendor API endpoint.

1. Use the id from the list response:

   Shell

   1curl -G \
   2  'https://api-demo.airwallex.com/api/v1/spend/vendors/{{VENDOR_ID}}' \
   3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

Update vendor sync status

To update the sync status of an existing vendor, call the Sync vendor status API endpoint.

1. Send the sync request with the updated status:

   Shell

   1curl -X POST \
   2  'https://api-demo.airwallex.com/api/v1/spend/vendors/{{ID}}/sync' \
   3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
   4  -H 'Content-Type: application/json' \
   5  -d '{
   6    "sync_status": "SYNCED"
   7  }'

2. The response returns the updated vendor.

Next steps

Now that you can manage vendors via the API, explore these related guides:

• Purchase orders via API
• Bills via API
• Error codes