Assignments API

Assign up to 100 learners to one package per request. The API creates a learner account if the email address is new.

Before calling this API, turn on Assign Users for the client in API Access, then request a token with scope=assignments.write. Clients are read-only by default. See Authentication for the token request.

Assign learners

POST /api/v1/assignments

Required scope: assignments.write.

curl --request POST \
  --url "https://courses.e-learningcourses.com/api/v1/assignments" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"packageId":"46647b28-2785-4435-9fa9-715e8c461902","groupId":"d812aa9e-160b-4a19-b7ef-8be3112f4e6a","users":[{"firstName":"Alex","lastName":"Example","email":"alex@example.com","doNotEmail":false}]}'

Request body

Field	Type	Required	Description
packageId	UUID	Yes	Package to assign. Find it with the Packages API.
groupId	UUID or null	No	For an organization client, the group to assign under. Omit for an organization-level assignment. A group client always uses its own group; if supplied, this ID must match that group.
users	array	Yes	Between 1 and 100 learners.
users[].firstName	string	Yes	Learner's first name.
users[].lastName	string	Yes	Learner's last name.
users[].email	string	Yes	Learner's email address; existing accounts are matched by email.
users[].doNotEmail	boolean	No	Defaults to false. Set to true to suppress assignment and invitation emails for that learner.

The package must belong to the client's organization. A group must be linked to that package. Assignments require an eligible subscription and respect the group's learner limit, when applicable.

Response

The API processes learners independently. A valid batch returns 200 OK even if some learners fail:

{
  "packageId": "46647b28-2785-4435-9fa9-715e8c461902",
  "groupId": "d812aa9e-160b-4a19-b7ef-8be3112f4e6a",
  "succeeded": 1,
  "failed": 1,
  "results": [
    { "index": 0, "email": "alex@example.com", "success": true, "userId": "learner-id" },
    { "index": 1, "email": "invalid-address", "success": false, "error": "A valid email address is required." }
  ]
}

index is the learner's position in the request, starting at zero. Successful entries include userId; failures include error. Retry only failed entries. Repeating a successful assignment may start a new training attempt.

Existing assignments in another group

Assigning an existing learner can move that package assignment from another group. Only enable assignment access for integrations you trust to make that change.

Errors and limits

An invalid batch returns 400. A missing or expired token returns 401; a token without assignment access or an ineligible subscription returns 403. An unavailable or out-of-scope package or group returns 404. The limit is 2 assignment requests per minute per client; excess requests return 429. See Authentication for retry guidance.

OpenAPI

https://courses.e-learningcourses.com/api/v1/openapi.json