Scores

Scores represent the B-BBEE scorecard records associated with a supplier. Each score contains the supplier's B-BBEE level, ownership details, validity period, and verification information. A supplier may have multiple scores spanning different validity periods, sourced from both the Beagle Database and locally captured records.

---

Endpoints

Method	Path	Purpose
GET	/api/v1/suppliers/{vendor_code}/scores/heartbeat	Confirm API availability and authentication
GET	/api/v1/suppliers/{vendor_code}/scores	Retrieve all scores for 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

Path Parameters

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

Response Fields

Field	Type	Description
level	string	B-BBEE level (e.g. "1" through "8").
score	string	B-BBEE score.
company_size	string	Company size classification.
valid_from	string	Scorecard validity start date (DD/MM/YYYY).
valid_until	string	Scorecard validity end date (DD/MM/YYYY).
black_ownership	string	Percentage of black ownership.
black_female_ownership	string	Percentage of black female ownership.
flow_through_black_ownership	string	Percentage of flow-through black ownership.
black_designated_group_ownership	string	Percentage of black designated group ownership.
value_adding_supplier	string	Whether the supplier is a value-adding supplier ("true" / "false").
empowering	string	Whether the supplier qualifies as empowering ("true" / "false").
measured_under	string	The charter or code the score was measured under (e.g. "1", "RCoGP").
verification_agency	string	Name of the verification agency that issued the certificate.
certificate_number	string	Verification certificate number.
id	string	Score identifier.
created_at	string	Creation timestamp (DD/MM/YYYY HH:MM:SS).
updated_at	string	Last update timestamp (DD/MM/YYYY HH:MM:SS).
source	string	Origin of the score: "beagle" (from the Beagle Database) or "local" (manually captured).
beagle_scorecard_url	string	URL to view the scorecard on Beagle. Only present when source is "beagle".
beagle_scorecard_url_expires_at	string	Expiry timestamp for the Beagle scorecard URL (ISO 8601). Only present when source is "beagle".

---

Notes

• The response is an array of score objects. A supplier may have multiple scores across different validity periods.
• Scores sourced from the Beagle Database (source: "beagle") include a time-limited beagle_scorecard_url for viewing the original scorecard.
• Locally captured scores (source: "local") do not include Beagle-specific URL fields.
• Dates are formatted as DD/MM/YYYY for date fields and DD/MM/YYYY HH:MM:SS for timestamps.

---

Retrieve scores for a supplier

Retrieve all B-BBEE scores associated with a supplier.

GET /api/v1/suppliers/{vendor_code}/scores

Path parameters

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

Code examples

cURL

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

JavaScript (axios)

const url =
  "https://www.suppliermanagement.co.za/api/v1/suppliers/T100/scores";
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

[
  {
    "level": "2",
    "score": "",
    "company_size": "2",
    "valid_from": "02/10/2023",
    "valid_until": "01/10/2024",
    "black_ownership": "0.0",
    "black_female_ownership": "0.0",
    "flow_through_black_ownership": "0.0",
    "black_designated_group_ownership": "0.0",
    "value_adding_supplier": "false",
    "empowering": "false",
    "measured_under": "1",
    "verification_agency": "ABC Verification",
    "certificate_number": "",
    "id": "",
    "created_at": "14/01/2026 08:08:19",
    "updated_at": "14/01/2026 08:08:19",
    "source": "beagle",
    "beagle_scorecard_url": "https://www.beagledatabase.co.za/scorecards/YZgTZL?token=...",
    "beagle_scorecard_url_expires_at": "2026-04-10T08:58:24Z"
  },
  {
    "level": "4",
    "score": "0",
    "company_size": "1",
    "valid_from": "10/03/2029",
    "valid_until": "09/03/2030",
    "black_ownership": "0.0",
    "black_female_ownership": "0.0",
    "flow_through_black_ownership": "0.0",
    "black_designated_group_ownership": "0.0",
    "value_adding_supplier": "false",
    "empowering": "false",
    "measured_under": "RCoGP",
    "verification_agency": "",
    "certificate_number": "",
    "id": "104",
    "created_at": "09/03/2026 08:34:52",
    "updated_at": "09/03/2026 08:34:52",
    "source": "local"
  }
]