Learners

List, create, update and archive the learners in your team.

Scopeslearners:readlearners:write

Data requests act inside the key’s centre as the person who created the key: each needs the scope and that person’s current EduMark permission. See auth and pagination.

List learners

GET/v1/learners

Learners in your team, newest first. Requires learners:read, and the key's creator must be able to see people in EduMark. Email and phone are included when they can manage people.

Scope learners:read

Parameters

List learners: parameters
Field	Details
`limit`	integerItems per page, 1 to 100.1 to 100Default `25`
`cursor`	string, optionalThe `next_cursor` from the previous page.Up to 512 characters
`updated_since`	string, optionalOnly learners created or changed since this ISO-8601 time.
`status`	enum, optionalOne of `active`, `archived`
`cohort_id`	string, optionalUp to 200 characters
`email`	string, optionalExact email address (needs people management).Up to 254 characters
`external_id`	string, optionalYour organisation's identifier.Up to 160 characters

Headers

List learners: headers
Field	Details
`EduMark-Version`	enumAPI version. Defaults to the latest.One of `2026-10-21`

Responses

Status	Meaning
200	Successful Response
400	Request rejected. Inspect error.code and request_id; failed work is not billed.
401	Request rejected. Inspect error.code and request_id; failed work is not billed.
403	Request rejected. Inspect error.code and request_id; failed work is not billed.
404	Request rejected. Inspect error.code and request_id; failed work is not billed.
409	Request rejected. Inspect error.code and request_id; failed work is not billed.
410	Request rejected. Inspect error.code and request_id; failed work is not billed.
413	Request rejected. Inspect error.code and request_id; failed work is not billed.
415	Request rejected. Inspect error.code and request_id; failed work is not billed.
422	Validation Error
429	Request rejected. Inspect error.code and request_id; failed work is not billed.
503	Request rejected. Inspect error.code and request_id; failed work is not billed.

Create a learner

POST/v1/learners

Creates the learner's record. An invitation to sign in is sent only when send_invitation is true (an email is then required). Without an email, give an external_id or unique_learner_number. Send a unique Idempotency-Key.

Scope learners:write

Headers

Create a learner: headers
Field	Details
`Idempotency-Key`	stringRequiredA unique key per new learner.
`EduMark-Version`	enumAPI version. Defaults to the latest.One of `2026-10-21`

Request body

Create a learner: request body
Field	Details
`first_name`	stringRequiredUp to 80 characters
`last_name`	stringUp to 80 charactersDefault `""`
`email`	string (email), optionalNeeded to invite the learner. Without one the learner is a record only.
`phone`	string, optionalUp to 50 characters
`preferred_name`	string, optionalUp to 160 characters
`external_id`	string, optionalYour identifier, e.g. a student number.Up to 160 characters
`unique_learner_number`	string, optionalUp to 160 characters
`cohort_ids`	array of stringUp to 100 items
`send_invitation`	booleanEmail the learner an invitation to sign in now. Needs email.Default `false`

Responses

Status	Meaning
201	Successful Response
400	Request rejected. Inspect error.code and request_id; failed work is not billed.
401	Request rejected. Inspect error.code and request_id; failed work is not billed.
403	Request rejected. Inspect error.code and request_id; failed work is not billed.
404	Request rejected. Inspect error.code and request_id; failed work is not billed.
409	Request rejected. Inspect error.code and request_id; failed work is not billed.
410	Request rejected. Inspect error.code and request_id; failed work is not billed.
413	Request rejected. Inspect error.code and request_id; failed work is not billed.
415	Request rejected. Inspect error.code and request_id; failed work is not billed.
422	Validation Error
429	Request rejected. Inspect error.code and request_id; failed work is not billed.
503	Request rejected. Inspect error.code and request_id; failed work is not billed.

Request

curl -X POST 'https://api.edumark.ai/v1/learners' \
  -H "Authorization: Bearer $EDUMARK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "amara.okafor@example.org",
  "external_id": "NC-1001",
  "first_name": "Amara",
  "last_name": "Okafor",
  "send_invitation": false
}'

Response 201JSON

{
  "cohort_ids": [
    "cohort_2026_biology"
  ],
  "created_at": "2026-09-01T09:00:00Z",
  "email": "amara.okafor@example.org",
  "external_id": "NC-1001",
  "first_name": "Amara",
  "has_account": true,
  "id": "user_4f1c0e9a2b7d4c3e8f6a1b2c3d4e5f60",
  "invitation_status": "invited",
  "last_name": "Okafor",
  "name": "Amara Okafor",
  "status": "active",
  "updated_at": "2026-09-01T09:00:00Z"
}

Get a learner

GET/v1/learners/{learner_id}

Scope learners:read

Parameters

Get a learner: parameters
Field	Details
`learner_id`	stringRequired

Headers

Get a learner: headers
Field	Details
`EduMark-Version`	enumAPI version. Defaults to the latest.One of `2026-10-21`

Responses

Status	Meaning
200	Successful Response
400	Request rejected. Inspect error.code and request_id; failed work is not billed.
401	Request rejected. Inspect error.code and request_id; failed work is not billed.
403	Request rejected. Inspect error.code and request_id; failed work is not billed.
404	Request rejected. Inspect error.code and request_id; failed work is not billed.
409	Request rejected. Inspect error.code and request_id; failed work is not billed.
410	Request rejected. Inspect error.code and request_id; failed work is not billed.
413	Request rejected. Inspect error.code and request_id; failed work is not billed.
415	Request rejected. Inspect error.code and request_id; failed work is not billed.
422	Validation Error
429	Request rejected. Inspect error.code and request_id; failed work is not billed.
503	Request rejected. Inspect error.code and request_id; failed work is not billed.

Request

curl 'https://api.edumark.ai/v1/learners/learner_123' \
  -H "Authorization: Bearer $EDUMARK_API_KEY"

Response 200JSON

{
  "cohort_ids": [
    "cohort_2026_biology"
  ],
  "created_at": "2026-09-01T09:00:00Z",
  "email": "amara.okafor@example.org",
  "external_id": "NC-1001",
  "first_name": "Amara",
  "has_account": true,
  "id": "user_4f1c0e9a2b7d4c3e8f6a1b2c3d4e5f60",
  "invitation_status": "invited",
  "last_name": "Okafor",
  "name": "Amara Okafor",
  "status": "active",
  "updated_at": "2026-09-01T09:00:00Z"
}

Update a learner

PATCH/v1/learners/{learner_id}

Changes only the fields you send. For learners who sign in, identifiers and cohorts are managed in EduMark. Changing an email signs the learner out everywhere.

Scope learners:write

Parameters

Update a learner: parameters
Field	Details
`learner_id`	stringRequired

Headers

Update a learner: headers
Field	Details
`EduMark-Version`	enumAPI version. Defaults to the latest.One of `2026-10-21`

Request body

Update a learner: request body
Field	Details
`first_name`	string, optionalUp to 80 characters
`last_name`	string, optionalUp to 80 characters
`email`	string (email), optional
`phone`	string, optionalUp to 50 characters
`preferred_name`	string, optionalUp to 160 characters
`external_id`	string, optionalUp to 160 characters
`unique_learner_number`	string, optionalUp to 160 characters
`cohort_ids`	array of string, optionalReplaces the learner's cohorts.Up to 100 items

Responses

Status	Meaning
200	Successful Response
400	Request rejected. Inspect error.code and request_id; failed work is not billed.
401	Request rejected. Inspect error.code and request_id; failed work is not billed.
403	Request rejected. Inspect error.code and request_id; failed work is not billed.
404	Request rejected. Inspect error.code and request_id; failed work is not billed.
409	Request rejected. Inspect error.code and request_id; failed work is not billed.
410	Request rejected. Inspect error.code and request_id; failed work is not billed.
413	Request rejected. Inspect error.code and request_id; failed work is not billed.
415	Request rejected. Inspect error.code and request_id; failed work is not billed.
422	Validation Error
429	Request rejected. Inspect error.code and request_id; failed work is not billed.
503	Request rejected. Inspect error.code and request_id; failed work is not billed.

Request

curl -X PATCH 'https://api.edumark.ai/v1/learners/learner_123' \
  -H "Authorization: Bearer $EDUMARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+44 7700 900123",
  "preferred_name": "Mara"
}'

Response 200JSON

{
  "cohort_ids": [
    "cohort_2026_biology"
  ],
  "created_at": "2026-09-01T09:00:00Z",
  "email": "amara.okafor@example.org",
  "external_id": "NC-1001",
  "first_name": "Amara",
  "has_account": true,
  "id": "user_4f1c0e9a2b7d4c3e8f6a1b2c3d4e5f60",
  "invitation_status": "invited",
  "last_name": "Okafor",
  "name": "Amara Okafor",
  "status": "active",
  "updated_at": "2026-09-01T09:00:00Z"
}

Archive a learner

POST/v1/learners/{learner_id}/archive

Stops the learner signing in and keeps their record, work and history. EduMark never deletes learners through the API.

Scope learners:write

Parameters

Archive a learner: parameters
Field	Details
`learner_id`	stringRequired

Headers

Archive a learner: headers
Field	Details
`EduMark-Version`	enumAPI version. Defaults to the latest.One of `2026-10-21`

Responses

Status	Meaning
200	Successful Response
400	Request rejected. Inspect error.code and request_id; failed work is not billed.
401	Request rejected. Inspect error.code and request_id; failed work is not billed.
403	Request rejected. Inspect error.code and request_id; failed work is not billed.
404	Request rejected. Inspect error.code and request_id; failed work is not billed.
409	Request rejected. Inspect error.code and request_id; failed work is not billed.
410	Request rejected. Inspect error.code and request_id; failed work is not billed.
413	Request rejected. Inspect error.code and request_id; failed work is not billed.
415	Request rejected. Inspect error.code and request_id; failed work is not billed.
422	Validation Error
429	Request rejected. Inspect error.code and request_id; failed work is not billed.
503	Request rejected. Inspect error.code and request_id; failed work is not billed.

Request

curl -X POST 'https://api.edumark.ai/v1/learners/learner_123/archive' \
  -H "Authorization: Bearer $EDUMARK_API_KEY"

Response 200JSON

{
  "cohort_ids": [
    "cohort_2026_biology"
  ],
  "created_at": "2026-09-01T09:00:00Z",
  "email": "amara.okafor@example.org",
  "external_id": "NC-1001",
  "first_name": "Amara",
  "has_account": true,
  "id": "user_4f1c0e9a2b7d4c3e8f6a1b2c3d4e5f60",
  "invitation_status": "invited",
  "last_name": "Okafor",
  "name": "Amara Okafor",
  "status": "active",
  "updated_at": "2026-09-01T09:00:00Z"
}