# Actors

## List Actors

<mark style="color:blue;">`GET`</mark> `https://{organisation}.clearlrs.com/api/actors`

Retrieves a list of all actors in the system.

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Insert/Update Agent

<mark style="color:orange;">`PUT`</mark> `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>** |

{% tabs %}
{% tab title="200 The updated actor object after insertion or merge with existing." %}

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

{% endtab %}
{% endtabs %}

## Search Actors

<mark style="color:green;">`POST`</mark> `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 |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

#### Search Criteria

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

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

A more complex example can include nested conditions:

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

## List Attributes

<mark style="color:blue;">`GET`</mark> `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.

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

## Get Completion Records

<mark style="color:blue;">`GET`</mark> `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       |

{% tabs %}
{% tab title="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"
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.clearxp.com/clear-api-reference/actors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.