Persons API

A person is a set of xAPI agents that identify the same real individual — the same learner seen under an mbox, an account, an openid, … is one person. TRAX groups such agents under a shared person id. This API looks up the agents of a person (GET) and records the grouping of agents into persons (POST). Authentication, value/field types and error responses are common to all TRAX APIs.

Contents: Look up a person · Record persons

Getting access

• Enable the API. This API is gated by the DATA_API feature toggle (Settings → App). When off, the machine-token API is unavailable (the console UI is unaffected).
• Client permission. The calling client must have the data/all permission enabled (Clients → edit → Permissions) — it grants person read & write. Authentication is HTTP Basic — see Authentication.
• Base path. Copy your client's store_endpoint (…/stores/{store}) from the Clients page (the ⓘ info button) and append /persons.

The endpoint is store-scoped:

GET  /trax/api/gateway/clients/{client}/stores/{store}/persons
POST /trax/api/gateway/clients/{client}/stores/{store}/persons

Path segments:

• {client} — your API client id.
• {store} — the id of the store to read/write.

Look up a person

GET /trax/api/gateway/clients/{client}/stores/{store}/persons

Given one agent, returns all agents of the person that agent belongs to (the queried agent included).

Name	Type	Description
agent	Agent IFI	The agent whose person to resolve. Example: {"mbox":"mailto:jane@example.com"}

Behaviour:

• If the agent is known and grouped, data is the array of the person's agents.
• If the agent is unknown, data is a single-item array — just that agent (a person of one).
• If agent is omitted, data is an empty array.

Example response

{
  "data": [
    { "objectType": "Agent", "name": "Jane Doe", "mbox": "mailto:jane@example.com" },
    { "objectType": "Agent", "account": { "homePage": "https://lms.example.com", "name": "jane" } }
  ]
}

Each item is an xAPI Agent object. (To list individual agents, use the data API's Agents view.)

Record persons

POST /trax/api/gateway/clients/{client}/stores/{store}/persons

Groups agents into persons. The request body is a JSON array of persons, where each person is an array of xAPI Agent objects (agents only — a group is rejected). Each person in the body is recorded under a new person id, and its agents are (re)assigned to it — this is how agents are attached to, or moved between, persons.

Body — array of array of Agent IFI:

[
  [
    { "mbox": "mailto:jane@example.com" },
    { "account": { "homePage": "https://lms.example.com", "name": "jane" } }
  ],
  [
    { "mbox": "mailto:john@example.com" }
  ]
]

The example records two persons: Jane (two agents grouped together) and John (one agent).

On success, returns 204 with an empty body. A body that is not a JSON array of agent-arrays — or that contains a group or a malformed agent — is rejected 400.