Scorecards

Scorecards are retrieved using the Beagle company ID. This returns all scorecards issued for that company.

You can optionally filter scorecards using updated_after in ISO 8601 format. To download the underlying scorecard document, use the Beagle scorecard ID. The API returns an authenticated download URL that expires after 24 hours.

---

Endpoints

Method	Path	Purpose
GET	/api/companies/{company_id}/scorecards	Retrieve all scorecard data for a company. Does not consume credits.
GET	/api/scorecards/{scorecard_id}/download	Consume one Beagle Bundle credit and return a signed download URL.

Authentication

Include the following headers on every request:

• Authorization: Basic <base64_encoded_credentials>
• Accept: application/json

See Authentication.

---

Attributes

Scorecard Fields

Field	Type	Description
id	string	Beagle scorecard identifier.
black_ownership	string	Black ownership percentage.
black_female_ownership	string	Black female ownership percentage.
certificate_number	string | null	Certificate number, if available.
company_size	string	Company size classification (e.g. QSE, Generic).
level	integer	B-BBEE level.
overall_score	string | null	Overall B-BBEE score.
valid_until	string	Certificate validity date (YYYY-MM-DD).
value_adding_supplier	string | null	Value-adding supplier status.
reviewed	boolean	Whether the scorecard has been reviewed.
revoked	boolean	Whether the scorecard has been revoked.
measured_under	string	Charter/code measured under (e.g. CoGP).
empowering	boolean	Whether the entity is empowering.
designated_group_black_ownership	string	Designated group black ownership percentage.
updated_at	datetime	Last update timestamp.
verification_agency	string	Name of the verification agency.
vat_number	string	VAT number of the scored company.

Download Response Fields

Field	Type	Description
scorecard_id	string	Beagle scorecard identifier.
download_url	string	Signed URL for downloading the scorecard document. Expires after 24 hours.
credits_remaining	integer	Number of Beagle Bundle credits remaining.
credit_consumed	string	Whether a credit was consumed ("yes" or "no").

---

Notes

• Download requests consume Beagle Bundle credits.
• Repeated requests for the same scorecard download do not consume additional credits for up to 30 days from the first request.
• Signed download_url links expire after 24 hours.
• The updated_after query parameter accepts ISO 8601 format (e.g. 2025-05-11T00:00:00Z).

---

List scorecards for a company

Retrieve all scorecards issued for a company. Does not consume credits.

GET /api/companies/{company_id}/scorecards

Path parameters

Name	Type	Required	Description
company_id	string	yes	The Beagle company identifier (from the Companies API).

Query parameters

Name	Type	Required	Description
updated_after	string	no	Filter to scorecards updated after this date (ISO 8601).

Code examples

cURL

curl -X GET "https://www.beagledatabase.co.za/api/companies/9olRro/scorecards?updated_after=2025-05-11T00:00:00Z" \
  -u "<your username>:<your password>" \
  -H "Accept: application/json"

JavaScript (axios)

const url =
  "https://www.beagledatabase.co.za/api/companies/9olRro/scorecards?updated_after=2025-05-11T00:00:00Z";

const response = await axios.get(url, {
  auth: {
    username: process.env.API_USERNAME,
    password: process.env.API_PASSWORD,
  },
});

console.log(response.data);

Response

[
  {
    "id": "YkJTmr",
    "black_ownership": "0.0",
    "black_female_ownership": "0.0",
    "certificate_number": null,
    "company_size": "QSE",
    "level": 2,
    "overall_score": null,
    "valid_until": "2026-04-01",
    "value_adding_supplier": null,
    "reviewed": true,
    "revoked": false,
    "measured_under": "CoGP",
    "empowering": false,
    "designated_group_black_ownership": "0.0",
    "updated_at": "2025-09-11T06:40:29.000Z",
    "verification_agency": "ABC Verification",
    "vat_number": "412345678"
  }
]

---

Download a scorecard

Consume one Beagle Bundle credit and receive a signed download URL for the scorecard document.

GET /api/scorecards/{scorecard_id}/download

Path parameters

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

Code examples

cURL

curl -X GET "https://www.beagledatabase.co.za/api/scorecards/L5lTaY/download" \
  -u "<your username>:<your password>" \
  -H "Accept: application/json"

JavaScript (axios)

const url =
  "https://www.beagledatabase.co.za/api/scorecards/L5lTaY/download";

const response = await axios.get(url, {
  auth: {
    username: process.env.API_USERNAME,
    password: process.env.API_PASSWORD,
  },
});

console.log(response.data);

Response

{
  "scorecard_id": "YZgTZL",
  "download_url": "www.beagledatabase.co.za/scorecards/YZgTZL?token=fbb664416297fee5313&expiry=1757670666",
  "credits_remaining": 9,
  "credit_consumed": "yes"
}