Actors

List Actors

GET https://{organisation}.clearlrs.com/api/actors

Retrieves a list of all actors in the system.

Insert/Update Agent

PUT https://{organisation}.clearlrs.com/api/actors/agents

Updates any agent with a matching account or unique identifier in the system, otherwise inserts a new agent. The request body must be a valid xAPI actor.

Headers

Name
Type
Description

clear-account-source

string

An arbitrary string to log against this update operation for audit purposes.

Request Body

Name
Type
Description

object

An xAPI actor as per https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#actor

{
  "name": "First Last",
  "account": {
    "homePage": "http://example.com"
    "name": "accountid"
  }
}

Search Actors

POST https://{organisation}.clearlrs.com/api/actors/search

Advanced search for all actors in the system. The results of this search will include both Agents and Groups unless the criteria object specifies otherwise.

Query Parameters

Name
Type
Description

limit

number

Restricts the number of results returned

skip

number

Skips over this number of items in the search results

Request Body

Name
Type
Description

criteria

object

A Search Criteria object as described below

{
    "actors": [
        {
            "objectType": "Agent",
            "mbox": "mailto:user1@example.com"
        },
        {
            "objectType": "Agent",
            "mbox": "mailto:user2@example.com"
        }
    ]
}

Search Criteria

The actor search endpoint allows for defining a complex search criteria. The most basic request body might look like the following:

{
    criteria: {
        "=": [
            { type: "name" },
            "Stephen Smith"
        ]
    }
}

A more complex example can include nested conditions:

{
    criteria: {
        and: [
            { "=": [
                { type: "attribute", key: "Country" },
                "AU"
            ] },
            { or: [
                { "=": [
                    { type: "attribute", key: "Department" },
                    "Marketing"
                ] },
                { "!=": [
                    { type: "attribute", key: "Job Title" },
                    "*Manager"
                ] }
            ] }
        ]
    }
}

List Attributes

GET https://{organisation}.clearlrs.com/api/actors/attributes

Lists any recorded attributes for Actors in the system along with a JSON Schema of what types each attribute is, if relevant.

{
    "attributes": [
        "Country",
        "Department",
        "Job Title",
        "Start Date"
    ],
    "schema": {
        "properties": {
            "Start Date": {
                "type": "date-time"
            }
        }
    }
}

Get Completion Records

GET https://{organisation}.clearlrs.com/api/actors/completions

Pulls all completion records for the current actor, filterable by status as well as activity. When an activityId and expand=hierarchy is set, then each result will include a recursive children field containing the results for each child in the hierarchy.

Query Parameters

Name
Type
Description

agent

string

Serialised JSON object of the Inverse Functional Identifier for the actor (i.e. {"mbox": "mailto:test@example.com"})

actorId

string

Serialised Inverse Functional Identifier in ID format (i.e. "mbox|mailto:test@example.com")

activityId

string

The ID of the activity to filter records for

expand

string

Set to hierarchy to optionally pull completion records for any child activities in the activity hierarchy.

Headers

Name
Type
Description

Accept-Version

string

2.0.0

{
    "activity": {
        "id": "http://example.com/1"
    },
    "progress": 0,
    "status": "incomplete",
    "timestampCompleted": null
},
{
    "activity": {
        "id": "http://example.com/2"
    },
    "progress": 1,
    "status": "completed",
    "timestampCompleted": "2021-07-01T01:00:00.000Z"
}

Last updated