Procurement Scorecards

Procurement Scorecards collate information about what was spent on which suppliers over a defined period. They are the core objects used to calculate your B‑BBEE procurement results for a given financial period or year‑to‑date window.

Each Procurement Scorecard has a unique identifier, which you will use when retrieving, updating, deleting, publishing, or unpublishing a scorecard.

Endpoints

Method	Path	Purpose
GET	`/api/v1/procurement_scorecards/heartbeat`	Confirm API availability and authentication
GET	`/api/v1/procurement_scorecards`	Retrieve all procurement scorecards
GET	`/api/v1/procurement_scorecards/{procurement_scorecard_id}`	Retrieve a specific procurement scorecard, along with the points you've scored
POST	`/api/v1/procurement_scorecards`	Create a new procurement scorecard
PUT	`/api/v1/procurement_scorecards/{procurement_scorecard_id}`	Update an existing procurement scorecard
DELETE	`/api/v1/procurement_scorecards/{procurement_scorecard_id}`	Delete a procurement scorecard
PUT	`/api/v1/procurement_scorecard/{procurement_scorecard_id}/publish`	Publish a procurement scorecard (mark it as the canonical scorecard for its period)
PUT	`/api/v1/procurement_scorecard/{procurement_scorecard_id}/unpublish`	Unpublish a procurement scorecard

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

Procurement Scorecard Attributes

Unless stated otherwise, all fields are optional.

Attribute	Example	Description
period	`"ytd"`	The measurement period. Must be one of: `"month"`, `"ytd"`, `"year"`.
start_date	`"01/04/2025"`	Start date of the spend period (`DD/MM/YYYY`).
end_date	`"31/03/2026"`	End date of the spend period (`DD/MM/YYYY`).
charter	`"Amended Codes of Good Practice"`	The B‑BBEE charter used for this scorecard. Must match one of the Charter Options listed below.
financial_year	`"2025"`	Financial year label used for reporting (e.g. `"2025"`).
description	`"YTD Scorecard"`	Free‑text description of the scorecard.
weight_black_and_black_female_owned_spending	`true`	Whether to apply weighting for black‑owned and black female‑owned spend.
include_later_supplier_scorecards	`true`	Whether to include supplier certificates issued outside the spend period when calculating recognition.
sum_tmps_from_line_items	`true`	When `true`, TMPS is calculated automatically from the underlying procurement line items.
total_measured_procurement_spend	`1000`	Manually specified Total Measured Procurement Spend (TMPS). Typically only used if you are not auto‑summing from line items.

Notes

Dates must be formatted as DD/MM/YYYY.
period must be one of: "month", "ytd", "year".
charter must exactly match one of the values listed in Charter Options below.
Boolean fields must be sent as JSON booleans (true / false), not strings.
You will typically supply at least period, start_date, end_date, charter, and financial_year when creating a scorecard.

Example: Creating a Procurement Scorecard

const url = "https://www.suppliermanagement.co.za/api/v1/procurement_scorecards";
const payload = {
  procurement_scorecard: {
    period: "ytd",
    start_date: "01/04/2025",
    end_date: "31/03/2026",
    charter: "Amended Codes of Good Practice",
    financial_year: "2025",
    description: "YTD Scorecard",
    weight_black_and_black_female_owned_spending: true,
    include_later_supplier_scorecards: true,
    sum_tmps_from_line_items: true,
    total_measured_procurement_spend: 0
  }
};

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

Example: Retrieving a Procurement Scorecard

Example request:

const url = "https://www.suppliermanagement.co.za/api/v1/procurement_scorecards/321";

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

Example response:

{
  "period": "year",
  "start_date": "01/02/2025",
  "end_date": "31/01/2026",
  "charter": "Amended Codes of Good Practice",
  "financial_year": "2026",
  "description": "",
  "weight_black_and_black_female_owned_spending": "false",
  "include_later_supplier_scorecards": "false",
  "sum_tmps_from_line_items": "false",
  "total_measured_procurement_spend": "12500.0",
  "id": "321",
  "created_at": "06/01/2026 11:04:03",
  "updated_at": "06/01/2026 11:08:31",
  "published": "false",
  "indicator_scores": [
    {
      "name": "Empowering",
      "description": "Spend on all empowering suppliers based on BBBEE recognition levels",
      "short_description": "Spend on all empowering suppliers",
      "bonus": false,
      "target": {
        "percent": 80,
        "amount": 10000,
        "points": 5
      },
      "actual": {
        "percent": 3.2,
        "amount": 400,
        "points": 0.2
      },
      "gap": {
        "percent": 76.8,
        "amount": 9600,
        "points": 4.8
      }
    },
    {
      "name": "Qse empowering",
      "description": "Spend on QSE empowering suppliers based on BBBEE recognition levels",
      "short_description": "Spend on QSE empowering suppliers",
      "bonus": false,
      "target": {
        "percent": 15,
        "amount": 1875,
        "points": 3
      },
      "actual": {
        "percent": 3.6,
        "amount": 450,
        "points": 0.72
      },
      "gap": {
        "percent": 11.4,
        "amount": 1425,
        "points": 2.28
      }
    },
    {
      "name": "Eme spend",
      "description": "Spend on EME suppliers based on BBBEE recognition levels",
      "short_description": "Spend on EME suppliers",
      "bonus": false,
      "target": {
        "percent": 15,
        "amount": 1875,
        "points": 4
      },
      "actual": {
        "percent": 4,
        "amount": 500,
        "points": 1.07
      },
      "gap": {
        "percent": 11,
        "amount": 1375,
        "points": 2.93
      }
    },
    {
      "name": "Black owned",
      "description": "Spend on empowering suppliers with at least 51% black ownership",
      "short_description": "Spend on empowering suppliers with at least 51% black ownership",
      "bonus": false,
      "target": {
        "percent": 50,
        "amount": 6250,
        "points": 11
      },
      "actual": {
        "percent": 4.8,
        "amount": 600,
        "points": 1.06
      },
      "gap": {
        "percent": 45.2,
        "amount": 5650,
        "points": 9.94
      }
    },
    {
      "name": "Black female owned",
      "description": "Spend on empowering suppliers with at least 30% black female ownership",
      "short_description": "Spend on empowering suppliers with at least 30% black female ownership",
      "bonus": false,
      "target": {
        "percent": 12,
        "amount": 1500,
        "points": 4
      },
      "actual": {
        "percent": 5.6,
        "amount": 700,
        "points": 1.87
      },
      "gap": {
        "percent": 6.4,
        "amount": 800,
        "points": 2.13
      }
    },
    {
      "name": "Designated groups",
      "description": "Spend on designated group suppliers with at least 51% black ownership",
      "short_description": "Spend on designated group suppliers with at least 51% black ownership",
      "bonus": true,
      "target": {
        "percent": 2,
        "amount": 250,
        "points": 2
      },
      "actual": {
        "percent": 6.4,
        "amount": 800,
        "points": 2
      },
      "gap": {
        "percent": 0,
        "amount": 0,
        "points": 0
      }
    }
  ]
}

Charter Options

Below is the full list of accepted values for the charter attribute:

Amended Agricultural Sector Code
Amended Codes of Good Practice
Amended Codes of Good Practice (QSE)
Amended Construction Sector Code: Built Environment Professionals
Amended Construction Sector Code: Contractors
Amended Financial Services Sector Code: Banks
Amended Financial Services Sector Code: Long Term Insurers
Amended Financial Services Sector Code: Other
Amended Financial Services Sector Code: Short Term Insurers
Amended Financial Services Sector Code: Specialised
Amended Financial Services Sector Code: Stock Exchanges
Amended Forestry Sector Code
Amended ICT Sector Code
Amended ICT Sector Code (QSE)
Amended ICT Sector Code: Specialised
Amended Marketing, Advertising & Communication Sector Code
Amended Marketing, Advertising & Communication Sector Code (QSE)
Amended Property Sector Code: Internal Management
Amended Property Sector Code: Owners
Amended Specialised Sector Code
Amended Tourism Sector Code
Amended Transport Sector Code: Bus Commuter
Amended Transport Sector Code: Coach Services
Amended Transport Sector Code: Road Freight
Chartered Accountancy Sector Code
Codes of Good Practice
Construction Sector Code: Built Environment Professionals
Construction Sector Code: Contractors
Financial Services Sector Code
Forestry Sector Code
ICT Sector Code
Mining
Property Sector Code: Internal Management
Property Sector Code: Owners
Specialised Sector Code
Tourism Sector Code
Transport Sector Code: Forwarding & Clearing
Transport Sector Code: Forwarding & Clearing (QSE)
Transport Sector Code: Public Sector
Transport Sector Code: Road Freight
Transport Sector Code: Road Freight (QSE)

Endpoints​

Procurement Scorecard Attributes​

Notes​

Example: Creating a Procurement Scorecard​

Example: Retrieving a Procurement Scorecard​

Charter Options​