Suppliers

Suppliers represent the organisations to which you allocate spend within Procurement Scorecards. All interactions with the Supplier API use your own vendor codes as the primary identifier. You will use these codes when creating, updating, retrieving, and deleting suppliers, as well as when loading procurement data.

---

Endpoints

Method	Path	Purpose
GET	/api/v1/suppliers/heartbeat	Confirm API availability and authentication
GET	/api/v1/suppliers/{vendor_code}	Retrieve a supplier by vendor code
POST	/api/v1/suppliers	Create a new supplier
PUT	/api/v1/suppliers/{vendor_code}	Update an existing supplier
DELETE	/api/v1/suppliers/{vendor_code}	Delete a supplier

All requests must be authenticated using your API key and HMAC signature. See the Authentication section for details.

---

Supplier Attributes

Below is the full list of supported supplier fields. Unless stated otherwise, all fields are optional.

Attribute	Example	Description
trading_name	"Test Supplier 1"	Supplier’s trading name
vendor_code	"TS001"	Your internal supplier identifier (required)
vat_number	"40091231233"	VAT number
excluded	false	Whether the supplier is excluded from B‑BBEE procurement
excluded_reason	""	Reason for exclusion (if any)
intragroup	false	Whether the supplier is part of your group
intragroup_account_name	""	Internal intragroup account name
date_of_first_procurement	"25/01/2025"	First recorded procurement date
contract_start_date	"25/01/2025"	Contract start date
contract_end_date	"25/01/2028"	Contract end date
supplier_development_recipient	false	Whether the supplier receives Supplier Development support
registered_name	""	Registered legal name
registration_number	""	Company registration number
telephone	""	Supplier telephone number
email	""	Supplier email address
postal_address	""	Postal address
cost_centre	""	Cost centre reference
priority	""	Priority level (if applicable)
custom_1	""	Custom field 1
custom_2	""	Custom field 2
custom_3	""	Custom field 3
custom_4	""	Custom field 4
property_service_provider	false	Whether this is a property service provider
_disabled_participation	false	Indicates >5% disabled ownership participation
living_with_disability	false	Whether the supplier is living with a disability
stockbroker	false	Whether the supplier is a stockbroker
fund_manager	false	Whether the supplier is a fund manager
intermediary	false	Whether the supplier is an intermediary

---

Notes

• Dates must be formatted as DD/MM/YYYY.
• vendor_code must be unique and is required for creation, updates, and lookups.
• Boolean fields must be sent as JSON booleans (true / false).

Example: Creating a Supplier

const url = "https://www.suppliermanagement.co.za/api/v1/suppliers";
const payload = {
  supplier: {
    trading_name: "New Supplier Ltd",
    vendor_code: "NS002",
  }
}

await axios.post(url, payload, {
  headers: {
    Accept: "application/json",
    Authorization: "HMAC <your signature>",
    'X-Api-Key': "<your account key>",
  }
});