Actors

List Actors

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

Retrieves a list of all actors in the system.

200

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

200 The updated actor object after insertion or merge with existing.

{
  "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

200

{
    "actors": [
        {
            "objectType": "Agent",
            "mbox": "mailto:[email protected]"
        },
        {
            "objectType": "Agent",
            "mbox": "mailto:[email protected]"
        }
    ]
}

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.

200

{
    "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:[email protected]"})
actorId	string	Serialised Inverse Functional Identifier in ID format (i.e. "mbox|mailto:[email protected]")
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

200 Completion records for the actor specified.

{
    "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"
}