Suppliers API

Suppliers API

Push Suppliers

POST /api/v1/integration/suppliers

Bulk upsert suppliers. Matches existing records by externalId — creates new records or updates existing ones.

Required scope: integration:suppliers:write

Request Body

{
  "suppliers": [
    {
      "externalId": "string (required)",
      "name": "string (required)",
      "code": "string",
      "country": "string (ISO 3166-1 alpha-2)",
      "address": "string",
      "contactPerson": "string",
      "email": "string",
      "phone": "string",
      "certifications": ["string"],
      "isEuOrigin": "boolean"
    }
  ]
}

Limits

• Maximum 500 suppliers per request

Response

{
  "success": true,
  "created": 2,
  "updated": 1,
  "errors": [
    { "externalId": "VENDOR-005", "error": "Supplier name is required" }
  ],
  "records": [
    { "externalId": "VENDOR-001", "internalId": "clx...", "status": "CREATED" },
    { "externalId": "VENDOR-002", "internalId": "clx...", "status": "UPDATED" },
    { "externalId": "VENDOR-005", "internalId": "", "status": "ERROR" }
  ]
}

Field Reference

Field	Type	Required	Description
externalId	string	✅	Unique ID in your system
name	string	✅	Supplier/vendor name
code	string		Vendor number or code
country	string		ISO country code (e.g., “BR”, “DE”)
address	string		Full address
contactPerson	string		Primary contact name
email	string		Contact email
phone	string		Contact phone
certifications	string[]		List of certifications
isEuOrigin	boolean		Whether supplier is EU-based

---

List Synced Suppliers

GET /api/v1/integration/suppliers

List suppliers that were synced from external systems with their sync status.

Required scope: integration:suppliers:read

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	50	Items per page (max 100)
since	string		ISO date — only show records synced after this date

Response

{
  "entities": [
    {
      "externalId": "VENDOR-001",
      "internalId": "clx...",
      "name": "Amazon Timber Co.",
      "syncStatus": "SYNCED",
      "lastSyncedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 50
}