Scorecards

Toolkit Scorecards represent B-BBEE scorecards generated within BEEtoolkit, covering all pillars such as Ownership, Management Control, Skills Development, Enterprise/Supplier Development, and SED. These APIs allow you to programmatically create, retrieve, update, and delete scorecards.

Each scorecard has a unique ID used for all subsequent interactions.

Endpoints

Method	Path	Purpose
`GET`	`/api/public/v1/scorecards`	Retrieve all scorecards
`GET`	`/api/public/v1/scorecards/{scorecard_id}`	Retrieve a specific scorecard
`POST`	`/api/public/v1/scorecards`	Create a new scorecard
`PUT`	`/api/public/v1/scorecards/{scorecard_id}`	Update an existing scorecard
`PUT`	`/api/public/v1/scorecards/{scorecard_id}/recalculate`	Recalculate scorecard totals after data changes
`DELETE`	`/api/public/v1/scorecards/{scorecard_id}`	Delete a 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 otherwise specified, all fields are optional.

Field	Type	Required	Description
`description`	string	yes	Free-text description for internal use.
`start_date`	string	yes	Start date for the scorecard period (`YYYY-MM-DD`).
`end_date`	string	yes	End date for the scorecard period (`YYYY-MM-DD`).
`charter_id`	string	yes	B-BBEE charter used for calculations. See Accepted Charter IDs.
`province`	string	yes	Province used for reporting and funding allocation.

System Fields (Response Only)

Field	Type	Description
`id`	string	Unique scorecard identifier.
`created_at`	datetime	Creation timestamp.
`updated_at`	datetime	Last update timestamp.

Notes

Dates must be in ISO 8601 format (YYYY-MM-DD).
charter_id must match one of the Accepted Charter IDs.
Updates are partial — only send the fields you want to modify.
The API returns structured JSON representing the full scorecard record.

List scorecards

Retrieve all scorecards.

GET /api/public/v1/scorecards

Code examples

cURL
JavaScript (axios)

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

const url = "https://www.beetoolkit.co.za/api/public/v1/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

[
  {
    "id": "scorecard_mG712bEVavpq3ukr0Z5R89qY",
    "description": "YTD Scorecard Nov 2024",
    "start_date": "2024-01-01",
    "end_date": "2024-11-30",
    "charter_id": "bravo_generic",
    "province": "National",
    "created_at": "2024-11-15T08:00:00.000Z",
    "updated_at": "2024-11-15T08:00:00.000Z"
  }
]

Create a scorecard

Create a new scorecard.

POST /api/public/v1/scorecards

Request body

Send a JSON object with a scorecard key:

{
  "scorecard": {
    "description": "YTD Scorecard Nov 2024",
    "start_date": "2024-01-01",
    "end_date": "2024-11-30",
    "charter_id": "bravo_generic",
    "province": "National"
  }
}

Code examples

cURL
JavaScript (axios)

curl -X POST "https://www.beetoolkit.co.za/api/public/v1/scorecards" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your account key>" \
  -H "Authorization: HMAC <your signature>" \
  -d '{
    "scorecard": {
      "description": "YTD Scorecard Nov 2024",
      "start_date": "2024-01-01",
      "end_date": "2024-11-30",
      "charter_id": "bravo_generic",
      "province": "National"
    }
  }'

const url = "https://www.beetoolkit.co.za/api/public/v1/scorecards";
const payload = {
  scorecard: {
    description: "YTD Scorecard Nov 2024",
    start_date: "2024-01-01",
    end_date: "2024-11-30",
    charter_id: "bravo_generic",
    province: "National",
  },
};

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

Returns the created scorecard record.

Update a scorecard

Update an existing scorecard. Only send the fields you want to modify.

PUT /api/public/v1/scorecards/{scorecard_id}

Path parameters

Name	Type	Required	Description
`scorecard_id`	string	yes	The scorecard identifier.

Request body

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

{
  "scorecard": {
    "description": "Updated Scorecard Description"
  }
}

Code examples

cURL
JavaScript (axios)

curl -X PUT "https://www.beetoolkit.co.za/api/public/v1/scorecards/{scorecard_id}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your account key>" \
  -H "Authorization: HMAC <your signature>" \
  -d '{
    "scorecard": {
      "description": "Updated Scorecard Description"
    }
  }'

const scorecardId = "scorecard_mG712bEVavpq3ukr0Z5R89qY";
const url = `https://www.beetoolkit.co.za/api/public/v1/scorecards/${scorecardId}`;
const payload = {
  scorecard: {
    description: "Updated Scorecard 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 scorecard record.

Delete a scorecard

Delete a scorecard by ID.

DELETE /api/public/v1/scorecards/{scorecard_id}

Path parameters

Name	Type	Required	Description
`scorecard_id`	string	yes	The scorecard identifier.

Code examples

cURL
JavaScript (axios)

curl -X DELETE "https://www.beetoolkit.co.za/api/public/v1/scorecards/{scorecard_id}" \
  -H "Accept: application/json" \
  -H "X-Api-Key: <your account key>" \
  -H "Authorization: HMAC <your signature>"

const scorecardId = "scorecard_mG712bEVavpq3ukr0Z5R89qY";
const url = `https://www.beetoolkit.co.za/api/public/v1/scorecards/${scorecardId}`;

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.

Recalculate a scorecard

After loading or updating related scorecard data (for example employees, training programs, or training participants), call the recalculate endpoint to refresh the scorecard totals.

PUT /api/public/v1/scorecards/{scorecard_id}/recalculate

Path parameters

Name	Type	Required	Description
`scorecard_id`	string	yes	The scorecard identifier.

The endpoint does not require a request body.

Processing behaviour

Recalculation runs asynchronously in the background.
For datasets larger than 20,000 records, processing can take up to 1 hour.
If a recalculation is already running for the scorecard and you submit another request, the API responds with 409 Conflict.

If you receive 409 Conflict, wait for the current recalculation to finish before retrying.

Code examples

cURL
JavaScript (axios)

curl -X PUT "https://www.beetoolkit.co.za/api/public/v1/scorecards/{scorecard_id}/recalculate" \
  -H "Accept: application/json" \
  -H "X-Api-Key: <your account key>" \
  -H "Authorization: HMAC <your signature>"

const scorecardId = "scorecard_mG712bEVavpq3ukr0Z5R89qY";
const url = `https://www.beetoolkit.co.za/api/public/v1/scorecards/${scorecardId}/recalculate`;

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

Errors

Status	Description
`409`	A recalculation is already in progress for this scorecard.

Accepted Charter IDs

The following values are accepted for charter_id:

bravo_generic
bravo_agri
bravo_forestry
bravo_transport_public_sector
bravo_construction_built_environment_professionals
bravo_construction_contractors
bravo_specialised
bravo_tourism
bravo_specialised_ict
bravo_ict
bravo_mac
bravo_transport_road_freight
bravo_transport_bus_commuter
bravo_transport_coach_services
bravo_financial_long_term
bravo_financial_short_term
bravo_financial_other
bravo_financial_specialised
bravo_financial_stock_exchanges
bravo_financial_banking
bravo_property_internal_management
bravo_property_owners
bravo_defence
bravo_legal_attorneys

Endpoints​

Attributes​

System Fields (Response Only)​

Notes​

List scorecards​

Code examples​

Response​

Create a scorecard​

Request body​

Code examples​

Response​

Update a scorecard​

Path parameters​

Request body​

Code examples​

Response​

Delete a scorecard​

Path parameters​

Code examples​

Response​

Recalculate a scorecard​

Path parameters​

Code examples​

Errors​

Accepted Charter IDs​

Endpoints

Attributes

System Fields (Response Only)

Notes

List scorecards

Code examples

Response

Create a scorecard

Request body

Code examples

Response

Update a scorecard

Path parameters

Request body

Code examples

Response

Delete a scorecard

Path parameters

Code examples

Response

Recalculate a scorecard

Path parameters

Code examples

Errors

Accepted Charter IDs