Learner Directory

Use the learner directory to look up McCoy learner records and their public learner_id values.

When To Use This

If you need to...	Use...
Look up the McCoy learner_id for a learner	GET /api/v1/learners
See the courses a learner is assigned to	GET /api/v1/learners/{learner_id}/courses
Create or update learners and plan-based access from your system	Plan-Based Provisioning
Deactivate a learner identity	DELETE /api/v1/learners/{learner_id}
Embed Surface for a learner	GET /api/v1/learners, then create a Surface embed link
Manage individual learner access manually	Terminal Access Management, then GET /api/v1/learners

Required Permission

Ask your organization admin to create or update an API key with:

Permission	Used for
read_learners	List existing learners and find their public learner_id
provision_learners	Create/update learners, add/remove plans, and deactivate learners

For Surface embedding, the same backend integration also needs create_surface_embed_links.

List Learners

curl "https://api.mccoy.org/api/v1/learners?page=1&page_size=50" \
  -H "X-Api-Key: YOUR_API_KEY"

Response:

{
  "data": [
    {
      "learner_id": "lrn_01HX7N8V2K9Q4R6M3B5C7D9E0F",
      "email": "learner@example.com",
      "first_name": "Ava",
      "last_name": "Chen"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 1,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

The learner directory returns active learners only. Learners deactivated with DELETE /api/v1/learners/{learner_id} are omitted until a successful learner identity POST /api/v1/learners or plan add reactivates them.

Filter Learners

You can filter by exact learner_id or email:

curl "https://api.mccoy.org/api/v1/learners?email=learner@example.com" \
  -H "X-Api-Key: YOUR_API_KEY"

For many Surface integrations, email is the simplest first mapping. If your system stores McCoy learner_id, use it directly for embed links.

Field Notes

Field	Description
learner_id	Public opaque McCoy learner ID. Use this when creating Surface embed links.
email	Learner email stored in McCoy.
first_name, last_name	Learner profile names stored in McCoy.

The directory response is limited to learner identity and profile fields needed by customer integrations.

List a Learner's Assigned Courses

To see every course a learner can currently access, call:

curl "https://api.mccoy.org/api/v1/learners/lrn_01HX7N8V2K9Q4R6M3B5C7D9E0F/courses" \
  -H "X-Api-Key: YOUR_API_KEY"

Response:

{
  "data": {
    "learner_id": "lrn_01HX7N8V2K9Q4R6M3B5C7D9E0F",
    "courses": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Anatomy 101",
        "access_source": "plan",
        "plans": ["paid-2", "lab-access"]
      },
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "name": "Onboarding",
        "access_source": "manual",
        "plans": []
      }
    ]
  }
}

Courses are deduplicated and include grant metadata:

• access_source: "plan" — access from one or more active plan entitlements. plans contains every active plan key contributing access to the course.
• access_source: "manual" — access granted directly to the learner, for example via Terminal Access Management. plans is empty.

If the same course is granted both manually and by an active plan, the course appears once with access_source: "plan". A learner with no current access returns an empty courses array. The list reflects current, non-expired access. Requires the read_learners permission.

For deactivated learners, this endpoint returns 404 LEARNER_NOT_FOUND until a successful learner identity POST /api/v1/learners or plan add reactivates the learner.

Deactivate a Learner

Use DELETE /api/v1/learners/{learner_id} to deactivate a learner identity:

curl -X DELETE "https://api.mccoy.org/api/v1/learners/lrn_01HX7N8V2K9Q4R6M3B5C7D9E0F" \
  -H "X-Api-Key: YOUR_API_KEY"

Response:

{
  "data": {
    "learner_id": "lrn_01HX7N8V2K9Q4R6M3B5C7D9E0F",
    "email": "learner@example.com",
    "first_name": "Ava",
    "last_name": "Chen",
    "is_active": false
  }
}

Deactivation hides the learner from the directory and blocks new learner activity. McCoy retains records for reporting and potential reactivation. The endpoint is idempotent for an existing inactive learner.

Surface Embedding

After you find the learner's learner_id, create an embed link with POST /api/v1/surface/embed-links.

See Surface Embedding for the full iframe flow.