Suppliers API

Full reference for Supplier REST endpoints — create, read, update, bulk upsert, with rich filtering and sorting.

Endpoints

MethodPathDescription
GET/api/suppliersList suppliers (paginated + filtered)
GET/api/suppliers/{id}Get a single supplier
POST/api/suppliersCreate a new supplier
PATCH/api/suppliers/{id}Partially update a supplier
POST/api/suppliers/bulkBulk create/update suppliers

GET /api/suppliers

Note

Updated in v1.0.1 — Default page size changed from 20 to 50. Maximum allowed size is 250. New query parameters: complianceStatus, search, sortBy, sortOrder.

Query Parameters

ParameterTypeDefaultDescription
pageinteger0Zero-based page index
sizeinteger50 (was 20)Items per page (max 250)
countrystring—ISO alpha-2 country filter
categorystring—Category filter
complianceStatusstring—Compliance status filter (New v1.0.1)
searchstring—Free-text search on name/category (New v1.0.1)
sortBystringcreated_dateSort field (New v1.0.1)
sortOrderstringdescasc or desc (New v1.0.1)
Shell
# List all with default settings (page 0, 50 results, sorted by created_date desc)
curl "http://localhost:8080/api/suppliers" \
  -H "X-API-Key: your-api-key"


# Filter + sort
curl "http://localhost:8080/api/suppliers?country=IT&category=TEXTILES&sortBy=name&sortOrder=asc&size=100" \
  -H "X-API-Key: your-api-key"


# Full-text search
curl "http://localhost:8080/api/suppliers?search=acme&size=20" \
  -H "X-API-Key: your-api-key"
JavaScript
const resp = await fetch(
  '/api/suppliers?country=IT&sortBy=name&sortOrder=asc',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const { items, total, page, page_size } = await resp.json();

Response 200 OK

JSON
{
  "items": [
    {
      "id": 1,
      "name": "Acme Textiles Ltd",
      "country": "IT",
      "category": "TEXTILES",
      "reach_compliant": true,
      "svhc_compliant": false,
      "created_at": "2025-09-01T10:00:00"
    }
  ],
  "total": 23,
  "page": 0,
  "page_size": 50
}

POST /api/suppliers

Request Body

FieldTypeRequiredDescription
namestring✅Supplier legal name
countrystring❌ISO 3166-1 alpha-2
categorystring❌Business category
reach_compliantboolean❌Default: false
svhc_compliantboolean❌Default: false
Shell
curl -X POST http://localhost:8080/api/suppliers \
  -H "Content-Type: application/json" \
  -H "X-User-Id: 1" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "name": "Acme Textiles Ltd",
    "country": "IT",
    "category": "TEXTILES",
    "reach_compliant": true
  }'
JavaScript
const resp = await fetch('/api/suppliers', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-User-Id': '1', 'X-API-Key': 'your-api-key' },
  body: JSON.stringify({ name: 'Acme Textiles Ltd', country: 'IT', category: 'TEXTILES', reach_compliant: true })
});

POST /api/suppliers/bulk

Upserts by name. Returns aggregated counts.

JSON
{
  "items": [
    { "name": "Acme Textiles", "country": "IT", "category": "TEXTILES" },
    { "name": "Delta Chemicals", "country": "DE", "category": "CHEMICALS" }
  ]
}

Response:

JSON
{ "created": 1, "updated": 1, "failed": 0, "errors": [] }