Suppliers API

Manage supplier records — create, read, update, delete.

Endpoints

MethodPathDescription
GET/api/v1/suppliersList suppliers with pagination and optional search
GET/api/v1/suppliers/{id}Get a single supplier by id
POST/api/v1/suppliersCreate a new supplier
PATCH/api/v1/suppliers/{id}Partially update a supplier
DELETE/api/v1/suppliers/{id}Delete a supplier (cascades to certifications)

GET /api/v1/suppliers

Lists suppliers visible to the current tenant.

Query parameterTypeRequiredNotes
searchstringnoSearch suppliers
pagenumberno1-based page number
limitnumbernoItems per page
Shell
curl "{{BASE_URL}}/api/v1/suppliers?search=acme&page=1&limit=20" \
  -H "Authorization: Bearer $CONFORMA_PAT"

Response 200 OK:

JSON
{
  "data": [],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 0,
    "totalPages": 0,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

GET /api/v1/suppliers/{id}

Fetches a single supplier, including its certifications inlined in the certifications array.

Shell
curl {{BASE_URL}}/api/v1/suppliers/3f2b9a1c-4d2e-4b6e-9c1a-6f5b8e2d7c10
  • 200 OK — SupplierDto with certifications[].
  • 404 Not Found — no supplier with that id belongs to your tenant.

POST /api/v1/suppliers

Creates a new supplier.

Request body (CreateSupplierDto)

FieldTypeRequiredDescription
namestring✅Supplier legal / commercial name
categorystring✅Business category
customCategorystring—Custom label when category is a generic bucket
vatNumberstring—VAT / fiscal identifier
addressstring—Street address
citystring—City
zipCodestring—Postal code
provincestring—Province / region
countrystring—ISO 3166-1 alpha-2
latitudenumber—Geographic latitude
longitudenumber—Geographic longitude
contactNamestring—Contact person
contactEmailstring (email)—Contact email
contactPhonestring—Contact phone
reachCompliantboolean—REACH compliance flag
svhcCompliantboolean—SVHC compliance flag
activityTypestring—Activity description (e.g. Dyeing)
companyIduuid—Owning company (optional)
metadataobject—Arbitrary JSON (ERP codes, tags)
Shell
curl -X POST {{BASE_URL}}/api/v1/suppliers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Textiles Ltd",
    "category": "TEXTILES",
    "vatNumber": "IT01234567890",
    "address": "Via Roma 12",
    "city": "Milano",
    "zipCode": "20100",
    "province": "MI",
    "country": "IT",
    "latitude": 45.4642,
    "longitude": 9.1900,
    "contactName": "Mario Rossi",
    "contactEmail": "mario@acme.it",
    "reachCompliant": true,
    "activityType": "Dyeing",
    "metadata": { "erpCode": "SUP-042" }
  }'
JavaScript
const res = await fetch(`${BASE_URL}/api/v1/suppliers`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Acme Textiles Ltd',
    category: 'TEXTILES',
    country: 'IT',
    city: 'Milano',
    contactEmail: 'mario@acme.it',
    reachCompliant: true,
    metadata: { erpCode: 'SUP-042' },
  }),
});
const supplier = await res.json();

Response 201 Created — the created SupplierDto.

PATCH /api/v1/suppliers/{id}

Partially updates a supplier. Send only the fields you want to change.

Shell
curl -X PATCH {{BASE_URL}}/api/v1/suppliers/3f2b9a1c-… \
  -H "Content-Type: application/json" \
  -d '{ "reachCompliant": true, "contactPhone": "+39 02 1234567" }'
  • 200 OK — updated SupplierDto.
  • 404 Not Found — supplier does not exist in your tenant.

DELETE /api/v1/suppliers/{id}

Deletes the supplier. All certifications attached to the supplier are deleted as well.

Shell
curl -X DELETE {{BASE_URL}}/api/v1/suppliers/3f2b9a1c-…
  • 204 No Content — deleted.
  • 404 Not Found — supplier does not exist in your tenant.

Supplier schema

SupplierDto:

JSON
{
  "id": "3f2b9a1c-4d2e-4b6e-9c1a-6f5b8e2d7c10",
  "name": "Acme Textiles Ltd",
  "category": "TEXTILES",
  "customCategory": null,
  "address": "Via Roma 12",
  "city": "Milano",
  "zipCode": "20100",
  "province": "MI",
  "country": "IT",
  "latitude": 45.4642,
  "longitude": 9.19,
  "contactName": "Mario Rossi",
  "contactEmail": "mario@acme.it",
  "contactPhone": "+39 02 1234567",
  "vatNumber": "IT01234567890",
  "reachCompliant": true,
  "svhcCompliant": false,
  "companyId": null,
  "activityType": "Dyeing",
  "metadata": { "erpCode": "SUP-042" },
  "certifications": [],
  "createdAt": "2026-04-21T10:00:00.000Z",
  "updatedAt": "2026-04-21T10:00:00.000Z"
}

Fields like customCategory, address, latitude, vatNumber, contactEmail are nullable — expect null when unset.