Suppliers

How suppliers and their compliance certifications are modeled in the ConformaESG API.

A supplier represents any external counterparty that provides you with materials, components, chemicals or services.

What a supplier record captures

A supplier contains:

  • Identity — name, vatNumber, category (and customCategory for free-form categorization).
  • Location — address, city, zipCode, province, country (ISO alpha-2) and optional latitude / longitude for geospatial analyses.
  • Contact details — contactName, contactEmail, contactPhone.
  • Compliance flags — reachCompliant, svhcCompliant.
  • Activity — activityType (e.g. Dyeing, Weaving, Finishing) for textile supply chains.
  • Metadata — arbitrary JSON to attach your ERP code or custom tags.

See the full supplier schema in the API reference.

Certifications

Each supplier can have any number of certifications attached to it. A certification captures:

  • The certificationType (e.g. GOTS, GRS, OEKO_TEX, REACH, ISO_14001).
  • Document identifiers — certificateNumber, certificateExpiry, and the internal documentId of the uploaded PDF.
  • Verification state — isDigitallySigned, signatureVerified, verificationStatus, verificationDetails, verifiedAt.

Deleting a supplier cascades to its certifications.

Typical lifecycle

  1. Create the supplier via POST /api/v1/suppliers and store the returned id against your ERP record.
  2. Attach certifications via POST /api/v1/supplier-certifications?supplierId=… — one call per certificate.
  3. Track expiry — periodically list certifications and alert on entries whose certificateExpiry is near.
  4. Update the supplier's compliance flags or contact info with PATCH /api/v1/suppliers/{id}.
  5. Archive by deleting the supplier; this also removes every certification attached to it.
Tip

Use the metadata field on the supplier to keep a bidirectional link with your ERP: { "metadata": { "erpCode": "SUP-042" } }. You can then reconcile without extra lookups on your side.

Related reading