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 with indicator scores
`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
`PUT`	`/api/v1/procurement_scorecard/{procurement_scorecard_id}/unpublish`	Unpublish a procurement scorecard

Authentication

Include the following headers on every request:

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

See Authentication.

Attributes

Unless stated otherwise, all fields are optional.

Field	Type	Required	Description
`period`	string	yes	The measurement period. Must be one of: `month`, `ytd`, `year`.
`start_date`	string	yes	Start date of the spend period (`DD/MM/YYYY`).
`end_date`	string	yes	End date of the spend period (`DD/MM/YYYY`).
`charter`	string	yes	The B-BBEE charter used for this scorecard. Must match one of the Charter Options.
`financial_year`	string	yes	Financial year label used for reporting (e.g. `"2025"`).
`description`	string	no	Free-text description of the scorecard.
`weight_black_and_black_female_owned_spending`	boolean	no	Whether to apply weighting for black-owned and black female-owned spend.
`include_later_supplier_scorecards`	boolean	no	Whether to include supplier certificates issued outside the spend period.
`sum_tmps_from_line_items`	boolean	no	When `true`, TMPS is calculated automatically from line items.
`total_measured_procurement_spend`	number	conditional	Manually specified TMPS. Required when `sum_tmps_from_line_items` is `false`.

System Fields (Response Only)

Field	Type	Description
`id`	string	Procurement scorecard identifier.
`published`	string	Whether the scorecard is published (`"true"` / `"false"`).
`created_at`	string	Creation timestamp (`DD/MM/YYYY HH:MM:SS`).
`updated_at`	string	Last update timestamp (`DD/MM/YYYY HH:MM:SS`).

Indicator Scores (Show endpoint only)

When retrieving a specific scorecard, the response includes an indicator_scores array with the following structure:

Field	Type	Description
`name`	string	Indicator name (e.g. `"Empowering"`, `"Black owned"`).
`description`	string	Full description of the indicator.
`short_description`	string	Short description.
`bonus`	boolean	Whether this is a bonus indicator.
`target.percent`	number	Target percentage.
`target.amount`	number	Target amount.
`target.points`	number	Target points.
`actual.percent`	number	Actual percentage achieved.
`actual.amount`	number	Actual amount achieved.
`actual.points`	number	Actual points scored.
`gap.percent`	number	Gap percentage.
`gap.amount`	number	Gap amount.
`gap.points`	number	Gap in points.

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

List procurement scorecards

Retrieve all procurement scorecards.

GET /api/v1/procurement_scorecards

Code examples

cURL
JavaScript (axios)

curl -X GET "https://www.suppliermanagement.co.za/api/v1/procurement_scorecards" \
  -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/procurement_scorecards";
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

[
  {
    "period": "year",
    "start_date": "01/12/2024",
    "end_date": "30/11/2025",
    "charter": "Amended Codes of Good Practice",
    "financial_year": "2025",
    "description": "",
    "weight_black_and_black_female_owned_spending": "false",
    "include_later_supplier_scorecards": "false",
    "sum_tmps_from_line_items": "true",
    "total_measured_procurement_spend": "123.0",
    "id": "73081",
    "created_at": "17/11/2025 07:38:52",
    "updated_at": "17/11/2025 07:38:56",
    "published": "false"
  }
]

Create a procurement scorecard

Create a new procurement scorecard.

POST /api/v1/procurement_scorecards

Request body

Send a JSON object with a procurement_scorecard key:

{
  "procurement_scorecard": {
    "period": "ytd",
    "start_date": "01/01/2025",
    "end_date": "31/12/2025",
    "charter": "Amended Codes of Good Practice",
    "financial_year": "2025",
    "description": "Test Scorecard",
    "weight_black_and_black_female_owned_spending": true,
    "include_later_supplier_scorecards": true,
    "sum_tmps_from_line_items": false,
    "total_measured_procurement_spend": 1000.0
  }
}

Code examples

cURL
JavaScript (axios)

curl -X POST "https://www.suppliermanagement.co.za/api/v1/procurement_scorecards" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your account key>" \
  -H "Authorization: HMAC <your signature>" \
  -d '{
    "procurement_scorecard": {
      "period": "ytd",
      "start_date": "01/01/2025",
      "end_date": "31/12/2025",
      "charter": "Amended Codes of Good Practice",
      "financial_year": "2025",
      "description": "Test Scorecard",
      "weight_black_and_black_female_owned_spending": true,
      "include_later_supplier_scorecards": true,
      "sum_tmps_from_line_items": false,
      "total_measured_procurement_spend": 1000.0
    }
  }'

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

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

{
  "period": "ytd",
  "start_date": "01/01/2025",
  "end_date": "31/12/2025",
  "charter": "Amended Codes of Good Practice",
  "financial_year": "2025",
  "description": "Test Scorecard",
  "weight_black_and_black_female_owned_spending": "true",
  "include_later_supplier_scorecards": "true",
  "sum_tmps_from_line_items": "false",
  "total_measured_procurement_spend": "1000.0",
  "id": "74240",
  "created_at": "16/02/2026 07:43:35",
  "updated_at": "16/02/2026 07:43:35",
  "published": "false"
}

Retrieve a procurement scorecard

Retrieve a specific procurement scorecard, including indicator scores showing your B-BBEE procurement performance.

GET /api/v1/procurement_scorecards/{procurement_scorecard_id}

Path parameters

Name	Type	Required	Description
`procurement_scorecard_id`	string	yes	The procurement scorecard identifier.

Code examples

cURL
JavaScript (axios)

curl -X GET "https://www.suppliermanagement.co.za/api/v1/procurement_scorecards/321" \
  -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/procurement_scorecards/321";
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

{
  "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": "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
      }
    }
  ]
}

Update a procurement scorecard

Update an existing procurement scorecard.

PUT /api/v1/procurement_scorecards/{procurement_scorecard_id}

Path parameters

Name	Type	Required	Description
`procurement_scorecard_id`	string	yes	The procurement scorecard identifier.

Request body

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

{
  "procurement_scorecard": {
    "description": "Updated description"
  }
}

Code examples

cURL
JavaScript (axios)

curl -X PUT "https://www.suppliermanagement.co.za/api/v1/procurement_scorecards/{procurement_scorecard_id}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your account key>" \
  -H "Authorization: HMAC <your signature>" \
  -d '{
    "procurement_scorecard": {
      "description": "Updated description"
    }
  }'

const url =
  "https://www.suppliermanagement.co.za/api/v1/procurement_scorecards/321";
const payload = {
  procurement_scorecard: {
    description: "Updated description",
  },
};

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 procurement scorecard record.

Delete a procurement scorecard

Delete a procurement scorecard by ID.

DELETE /api/v1/procurement_scorecards/{procurement_scorecard_id}

Path parameters

Name	Type	Required	Description
`procurement_scorecard_id`	string	yes	The procurement scorecard identifier.

Code examples

cURL
JavaScript (axios)

curl -X DELETE "https://www.suppliermanagement.co.za/api/v1/procurement_scorecards/{procurement_scorecard_id}" \
  -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/procurement_scorecards/321";
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.

Publish a procurement scorecard

Mark a procurement scorecard as the canonical scorecard for its period.

PUT /api/v1/procurement_scorecard/{procurement_scorecard_id}/publish

Path parameters

Name	Type	Required	Description
`procurement_scorecard_id`	string	yes	The procurement scorecard identifier.

Code examples

cURL
JavaScript (axios)

curl -X PUT "https://www.suppliermanagement.co.za/api/v1/procurement_scorecard/{procurement_scorecard_id}/publish" \
  -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/procurement_scorecard/321/publish";
const path = new URL(url).pathname;
const signature = await generateSignature(path, "", apiSecret, 5);

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

console.log(response.data);

Response

Returns the updated procurement scorecard with published set to "true".

Unpublish a procurement scorecard

Remove the published status from a procurement scorecard.

PUT /api/v1/procurement_scorecard/{procurement_scorecard_id}/unpublish

Path parameters

Name	Type	Required	Description
`procurement_scorecard_id`	string	yes	The procurement scorecard identifier.

Code examples

cURL
JavaScript (axios)

curl -X PUT "https://www.suppliermanagement.co.za/api/v1/procurement_scorecard/{procurement_scorecard_id}/unpublish" \
  -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/procurement_scorecard/321/unpublish";
const path = new URL(url).pathname;
const signature = await generateSignature(path, "", apiSecret, 5);

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

console.log(response.data);

Response

Returns the updated procurement scorecard with published set to "false".

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​

Attributes​

System Fields (Response Only)​

Indicator Scores (Show endpoint only)​

Notes​

List procurement scorecards​

Code examples​

Response​

Create a procurement scorecard​

Request body​

Code examples​

Response​

Retrieve a procurement scorecard​

Path parameters​

Code examples​

Response​

Update a procurement scorecard​

Path parameters​

Request body​

Code examples​

Response​

Delete a procurement scorecard​

Path parameters​

Code examples​

Response​

Publish a procurement scorecard​

Path parameters​

Code examples​

Response​

Unpublish a procurement scorecard​

Path parameters​

Code examples​

Response​

Charter Options​

Endpoints

Attributes

System Fields (Response Only)

Indicator Scores (Show endpoint only)

Notes

List procurement scorecards

Code examples

Response

Create a procurement scorecard

Request body

Code examples

Response

Retrieve a procurement scorecard

Path parameters

Code examples

Response

Update a procurement scorecard

Path parameters

Request body

Code examples

Response

Delete a procurement scorecard

Path parameters

Code examples

Response

Publish a procurement scorecard

Path parameters

Code examples

Response

Unpublish a procurement scorecard

Path parameters

Code examples

Response

Charter Options