Training Program Participants

Participants belong to exactly one training program, and each training program can have many participants. This API allows you to create, retrieve, and delete participants for a specific training program.

---

Endpoints

Method	Path	Purpose
GET	/api/public/v1/scorecards/{scorecard_id}/training_programs/{training_program_id}/participants	Retrieve participants for a training program
POST	/api/public/v1/scorecards/{scorecard_id}/training_programs/{training_program_id}/participants	Create participants in bulk
DELETE	/api/public/v1/scorecards/{scorecard_id}/training_programs/{training_program_id}/participants/{id}	Delete a single participant

Authentication

Include the following headers on every request:

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

See Authentication.

---

Attributes

Field	Type	Required	Description
full_name	string	yes	Participant full name.
gender	string	yes	Accepted values: Male, Female.
disabled	boolean	yes	Indicates a disability.
foreign	boolean	yes	Indicates a foreign national.
race	string	yes	Accepted values: African, Coloured, Indian, White.
id_number	string	conditional	Participant ID number. Required when the scorecard enforces compulsory ID numbers.
office_based	boolean	no	Indicates office-based training.
age	integer	no	Participant age.
province	string	no	Participant province.
business_unit	string	no	Business unit.
employee_code	string	no	Employee code.
employed	boolean	no	Indicates employment status.
completed	boolean	no	Indicates course completion.
absorbed	boolean	no	Indicates absorption status.
course_cost	number	no	Course cost.
travel_cost	number	no	Travel cost.
catering_cost	number	no	Catering cost.
stationery_cost	number	no	Stationery cost.
training_facility_cost	number	no	Training facility cost.
salary_cost	number	no	Salary cost.
other_costs	number	no	Other costs.
start_date	string | null	no	Start date (YYYY-MM-DD).
end_date	string | null	no	End date (YYYY-MM-DD).
accommodation_cost	number	no	Accommodation cost.
custom_data	string	no	Custom data payload.
man_hours	number	no	Man hours.
driver	boolean	no	Indicates driver training.
starting_employment_status	string	no	Employment status at start of training. Must be: Permanent, Fixed-Term, or Unemployed.
yes_employee	boolean	no	Indicates YES employee status.
absorption_date	string | null	no	Absorption date (YYYY-MM-DD).
legal_attorney_status	string | null	conditional	Legal attorney status. Required for Legal Attorneys charter scorecards.
admission_as_legal_practitioner	boolean	no	Indicates admission as legal practitioner.

System Fields (Response Only)

Field	Type	Description
id	integer	Internal identifier for the participant.
created_at	datetime	Record creation timestamp.
updated_at	datetime	Record update timestamp.

---

Notes

• Dates must be in ISO 8601 format (YYYY-MM-DD).
• Cost fields are returned as strings in responses (e.g. "5000.0") but can be sent as numbers in requests.
• After creating or deleting participants, recalculate the scorecard to refresh totals.

---

List participants

Returns a paginated list of participants for a single training program.

GET /api/public/v1/scorecards/{scorecard_id}/training_programs/{training_program_id}/participants

Path parameters

Name	Type	Required	Description
scorecard_id	string	yes	The scorecard identifier.
training_program_id	integer	yes	Training program ID.

Query parameters

Name	Type	Required	Description
page	integer	no	Page number (min 1, max 100000). Default is 1.
per_page	integer	no	Page size (min 1, max 1000). Default is 50.

Code examples

cURL

curl -X GET "https://www.beetoolkit.co.za/api/public/v1/scorecards/{scorecard_id}/training_programs/{training_program_id}/participants?page=1&per_page=50" \
  -H "Accept: application/json" \
  -H "X-Api-Key: <your account key>" \
  -H "Authorization: HMAC <your signature>"

JavaScript (axios)

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

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

Returns a JSON object with data and meta keys.

{
  "data": [
    {
      "id": 32047,
      "full_name": "Test",
      "gender": "Male",
      "disabled": false,
      "foreign": false,
      "race": "Indian",
      "id_number": "",
      "office_based": false,
      "age": 0,
      "province": "Gauteng",
      "business_unit": "",
      "employee_code": "",
      "employed": true,
      "completed": true,
      "absorbed": false,
      "designated_group": false,
      "course_cost": "10.0",
      "travel_cost": "20.0",
      "catering_cost": "40.0",
      "stationery_cost": "0.0",
      "training_facility_cost": "0.0",
      "salary_cost": "220.0",
      "other_costs": "0.0",
      "start_date": null,
      "end_date": null,
      "accommodation_cost": "0.0",
      "custom_data": "",
      "man_hours": "0.0",
      "driver": false,
      "starting_employment_status": "Permanent",
      "yes_employee": false,
      "absorption_date": null,
      "legal_attorney_status": null,
      "admission_as_legal_practitioner": false,
      "created_at": "2026-02-16T06:46:56.000Z",
      "updated_at": "2026-02-16T06:46:56.000Z"
    }
  ],
  "meta": {
    "prev_url": null,
    "next_url": null,
    "count": 1,
    "page": 1,
    "items": 50,
    "pages": 1
  }
}

---

Create participants (bulk)

Insert multiple participants at once via a batch payload.

POST /api/public/v1/scorecards/{scorecard_id}/training_programs/{training_program_id}/participants

Path parameters

Name	Type	Required	Description
scorecard_id	string	yes	The scorecard identifier.
training_program_id	integer	yes	Training program ID.

Request body

Send a JSON object with a participants array:

{
  "participants": [
    {
      "full_name": "John Doe",
      "race": "African",
      "gender": "Male",
      "course_cost": 5000
    }
  ]
}

Code examples

cURL

curl -X POST "https://www.beetoolkit.co.za/api/public/v1/scorecards/{scorecard_id}/training_programs/{training_program_id}/participants" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your account key>" \
  -H "Authorization: HMAC <your signature>" \
  -d '{
    "participants": [
      {
        "full_name": "John Doe",
        "race": "African",
        "gender": "Male",
        "course_cost": 5000
      }
    ]
  }'

JavaScript (axios)

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

const payload = {
  participants: [
    {
      full_name: "John Doe",
      race: "African",
      gender: "Male",
      course_cost: 5000,
    },
  ],
};

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

On success, the API returns an array containing the created participants.

[
  {
    "id": 32050,
    "full_name": "John Doe",
    "gender": "Male",
    "disabled": false,
    "foreign": false,
    "race": "African",
    "id_number": null,
    "office_based": false,
    "age": 0,
    "province": null,
    "business_unit": null,
    "employee_code": null,
    "employed": true,
    "completed": false,
    "absorbed": false,
    "course_cost": "5000.0",
    "travel_cost": "0.0",
    "catering_cost": "0.0",
    "stationery_cost": "0.0",
    "training_facility_cost": "0.0",
    "salary_cost": "0.0",
    "other_costs": "0.0",
    "start_date": null,
    "end_date": null,
    "accommodation_cost": "0.0",
    "custom_data": null,
    "man_hours": "0.0",
    "driver": false,
    "starting_employment_status": "Permanent",
    "yes_employee": false,
    "absorption_date": null,
    "legal_attorney_status": null,
    "admission_as_legal_practitioner": false,
    "created_at": "2026-02-17T07:17:42.000Z",
    "updated_at": "2026-02-17T07:17:42.000Z"
  }
]

Recalculate after loading participants

After creating participants, call the scorecard recalculate endpoint to refresh scores: Recalculate a scorecard.

Errors

Status	Description
422	One or more participant records are invalid.

{
  "error": {
    "message": "One or more participant records are invalid.",
    "invalid_records": [
      {
        "id": null,
        "full_name": "John Doe",
        "gender": "Malee",
        "race": "African",
        "errors": [
          "Gender is not included in the list"
        ]
      }
    ]
  }
}

---

Delete a participant

Deletes a single participant by ID within the specified training program.

DELETE /api/public/v1/scorecards/{scorecard_id}/training_programs/{training_program_id}/participants/{id}

Path parameters

Name	Type	Required	Description
scorecard_id	string	yes	The scorecard identifier.
training_program_id	integer	yes	Training program ID.
id	integer	yes	Participant ID.

Code examples

cURL

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

JavaScript (axios)

const scorecardId = "scorecard_mG712bEVavpq3ukr0Z5R89qY";
const trainingProgramId = 32005;
const participantId = 32047;
const url = `https://www.beetoolkit.co.za/api/public/v1/scorecards/${scorecardId}/training_programs/${trainingProgramId}/participants/${participantId}`;

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

Response

Returns 204 No Content on success.

Recalculate after deleting participants

After deleting participants, call the scorecard recalculate endpoint to refresh scores: Recalculate a scorecard.