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

Authentication

Include the following headers on every request:

Authorization: HMAC <signature>
X-Api-Key: <your account key>
Accept: application/json

See Authentication.

Attributes

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

Field	Type	Required	Description
`trading_name`	string	yes	Supplier's trading name.
`vendor_code`	string	yes	Your internal supplier identifier. Must be unique.
`vat_number`	string	conditional	VAT number. Required when the account enforces compulsory VAT numbers and the supplier is not VAT exempt.
`excluded`	boolean	no	Whether the supplier is excluded from B-BBEE procurement.
`excluded_reason`	string	conditional	Reason for exclusion. Required when exclusion is enabled for the supplier.
`intragroup`	boolean	no	Whether the supplier is part of your group.
`intragroup_account_name`	string	conditional	Internal intragroup account name. Required when `intragroup` is `true`.
`date_of_first_procurement`	string	no	First recorded procurement date (`DD/MM/YYYY`).
`contract_start_date`	string	no	Contract start date (`DD/MM/YYYY`).
`contract_end_date`	string	no	Contract end date (`DD/MM/YYYY`).
`supplier_development_recipient`	boolean	no	Whether the supplier receives Supplier Development support.
`registered_name`	string	no	Registered legal name.
`registration_number`	string	no	Company registration number.
`telephone`	string	no	Supplier telephone number.
`email`	string	no	Supplier email address.
`postal_address`	string	no	Postal address.
`cost_centre`	string	no	Cost centre reference.
`priority`	string	no	Priority level (if applicable).
`custom_1`	string	no	Custom field 1.
`custom_2`	string	no	Custom field 2.
`custom_3`	string	no	Custom field 3.
`custom_4`	string	no	Custom field 4.
`property_service_provider`	boolean	no	Whether this is a property service provider.
`_disabled_participation`	boolean	no	Indicates >5% disabled ownership participation.
`living_with_disability`	boolean	no	Whether the supplier is living with a disability.
`stockbroker`	boolean	no	Whether the supplier is a stockbroker.
`fund_manager`	boolean	no	Whether the supplier is a fund manager.
`intermediary`	boolean	no	Whether the supplier is an intermediary.

System Fields (Response Only)

Field	Type	Description
`vat_exempt`	string	VAT exemption status.
`greater_than_5_percent_disabled_participation`	string	Disabled participation flag.
`created_at`	string	Creation timestamp (`DD/MM/YYYY HH:MM:SS`).
`updated_at`	string	Last update timestamp (`DD/MM/YYYY HH:MM:SS`).

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).

Retrieve a supplier

Retrieve a single supplier by vendor code.

GET /api/v1/suppliers/{vendor_code}

Path parameters

Name	Type	Required	Description
`vendor_code`	string	yes	The supplier's vendor code.

Code examples

cURL
JavaScript (axios)

curl -X GET "https://www.suppliermanagement.co.za/api/v1/suppliers/af001" \
  -H "Accept: application/json" \
  -H "X-Api-Key: <your account key>" \
  -H "Authorization: HMAC <your signature>"

const url = "https://www.suppliermanagement.co.za/api/v1/suppliers/af001";
const path = new URL(url).pathname;
const signature = await generateSignature(path, "", apiSecret, 5);

const response = await axios.get(url, {
  headers: {
    Accept: "application/json",
    Authorization: `HMAC ${signature}`,
    "X-Api-Key": apiKey,
  },
});

console.log(response.data);

Response

{
  "trading_name": "African Reinforcing Construction",
  "vendor_code": "af001",
  "vat_number": "4312345678",
  "vat_exempt": "false",
  "excluded": "false",
  "excluded_reason": "",
  "intragroup": "false",
  "intragroup_account_name": "",
  "date_of_first_procurement": "",
  "contract_start_date": "",
  "contract_end_date": "",
  "supplier_development_recipient": "false",
  "registered_name": "",
  "registration_number": "",
  "telephone": "",
  "email": "",
  "postal_address": "",
  "cost_centre": "",
  "priority": "",
  "custom_1": "",
  "custom_2": "",
  "custom_3": "",
  "custom_4": "",
  "property_service_provider": "false",
  "greater_than_5_percent_disabled_participation": "false",
  "living_with_disability": "false",
  "stockbroker": "false",
  "fund_manager": "false",
  "intermediary": "false",
  "created_at": "18/05/2022 11:14:34",
  "updated_at": "18/05/2022 11:23:17"
}

Create a supplier

Create a new supplier.

POST /api/v1/suppliers

Request body

Send a JSON object with a supplier key:

{
  "supplier": {
    "trading_name": "New Supplier",
    "vendor_code": "NS001"
  }
}

Code examples

cURL
JavaScript (axios)

curl -X POST "https://www.suppliermanagement.co.za/api/v1/suppliers" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your account key>" \
  -H "Authorization: HMAC <your signature>" \
  -d '{
    "supplier": {
      "trading_name": "New Supplier",
      "vendor_code": "NS001"
    }
  }'

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

const path = new URL(url).pathname;
const signature = await generateSignature(path, payload, apiSecret, 5);

const response = await axios.post(url, payload, {
  headers: {
    Accept: "application/json",
    Authorization: `HMAC ${signature}`,
    "X-Api-Key": apiKey,
  },
});

console.log(response.data);

Response

{
  "trading_name": "New Supplier",
  "vendor_code": "NS001",
  "vat_number": "",
  "vat_exempt": "false",
  "excluded": "false",
  "excluded_reason": "",
  "intragroup": "false",
  "intragroup_account_name": "",
  "date_of_first_procurement": "",
  "contract_start_date": "",
  "contract_end_date": "",
  "supplier_development_recipient": "false",
  "registered_name": "",
  "registration_number": "",
  "telephone": "",
  "email": "",
  "postal_address": "",
  "cost_centre": "",
  "priority": "",
  "custom_1": "",
  "custom_2": "",
  "custom_3": "",
  "custom_4": "",
  "property_service_provider": "false",
  "greater_than_5_percent_disabled_participation": "false",
  "living_with_disability": "false",
  "stockbroker": "false",
  "fund_manager": "false",
  "intermediary": "false",
  "created_at": "16/02/2026 08:08:12",
  "updated_at": "16/02/2026 08:08:12"
}

Update a supplier

Update an existing supplier by vendor code.

PUT /api/v1/suppliers/{vendor_code}

Path parameters

Name	Type	Required	Description
`vendor_code`	string	yes	The supplier's vendor code.

Request body

Send a JSON object with a supplier key containing only the fields to update:

{
  "supplier": {
    "trading_name": "Updated Supplier Name"
  }
}

Code examples

cURL
JavaScript (axios)

curl -X PUT "https://www.suppliermanagement.co.za/api/v1/suppliers/NS001" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your account key>" \
  -H "Authorization: HMAC <your signature>" \
  -d '{
    "supplier": {
      "trading_name": "Updated Supplier Name"
    }
  }'

const url = "https://www.suppliermanagement.co.za/api/v1/suppliers/NS001";
const payload = {
  supplier: {
    trading_name: "Updated Supplier Name",
  },
};

const path = new URL(url).pathname;
const signature = await generateSignature(path, payload, apiSecret, 5);

const response = await axios.put(url, payload, {
  headers: {
    Accept: "application/json",
    Authorization: `HMAC ${signature}`,
    "X-Api-Key": apiKey,
  },
});

console.log(response.data);

Response

Returns the updated supplier record.

Delete a supplier

Delete a supplier by vendor code.

DELETE /api/v1/suppliers/{vendor_code}

Path parameters

Name	Type	Required	Description
`vendor_code`	string	yes	The supplier's vendor code.

Code examples

cURL
JavaScript (axios)

curl -X DELETE "https://www.suppliermanagement.co.za/api/v1/suppliers/NS001" \
  -H "Accept: application/json" \
  -H "X-Api-Key: <your account key>" \
  -H "Authorization: HMAC <your signature>"

const url = "https://www.suppliermanagement.co.za/api/v1/suppliers/NS001";
const path = new URL(url).pathname;
const signature = await generateSignature(path, "", apiSecret, 5);

const response = await axios.delete(url, {
  headers: {
    Accept: "application/json",
    Authorization: `HMAC ${signature}`,
    "X-Api-Key": apiKey,
  },
});

console.log(response.status);

Response

Returns 204 No Content on success.

Endpoints​

Attributes​

System Fields (Response Only)​

Notes​

Retrieve a supplier​

Path parameters​

Code examples​

Response​

Create a supplier​

Request body​

Code examples​

Response​

Update a supplier​

Path parameters​

Request body​

Code examples​

Response​

Delete a supplier​

Path parameters​

Code examples​

Response​

Endpoints

Attributes

System Fields (Response Only)

Notes

Retrieve a supplier

Path parameters

Code examples

Response

Create a supplier

Request body

Code examples

Response

Update a supplier

Path parameters

Request body

Code examples

Response

Delete a supplier

Path parameters

Code examples

Response