Tahoe User API
API Endpoint to retrieve user identifier data on Tahoe from a third-party system.
Use these to use an external system to retrieve user identifier information. We will be building out a more robust set of User API endpoints in the future, but we built this first set to enable a remote client to manage user enrollments, supporting the Enrollment API.
Important Note
GET List
Endpoint: /tahoe/api/v1/users/ Request Method: GET
The endpoint returns a paginated list of all users.
For our initial release, enrolled learners can be retrieved via the Enrollment API using the course id as the query parameter ( /tahoe/api/v1/enrollments/?course_id=<course-id>). This returns a collection of enrollments where each enrollment contains the learner identity. For more details, see the enrollment API GET List action.
Table 1 - Query parameters
| Name | Type | Description |
| email_exact | string | Email of the user to find. This will only look for exact matches in a case insensitive manner. Either one user will be returned in the list or none. This is often useful do check whether a learner have registered with this exact email. |
Response
The top level response contains pagination data, which can be used to page through the list responses.
Table 2 - Top Level Response Keys
| Name | Description |
| count | Number of total records retrieved |
| next | Link to the next page of results. Null if no next page |
| previous | Link to the previous page of results. Null if no previous page |
| results | List of enrollment data. See the next table |
Table 3 - Results element values
| Name | Description |
| id | Unique user id (long) |
| username | User’s username as the user entered during registration |
| fullname | User’s full name as the user entered during registration |
| User’s email address |
Example cURL command
curl -X GET \ https://<your-site-name>.tahoe.appsembler.com/tahoe/api/v1/users/ \ -H 'Accept: */*' \ -H 'Authorization: Token <insert token here> \ -H 'Cache-Control: no-cache'
Example response
{
"count": 15,
"next": null,
"previous": null,
"results": [
{
"id": 1766,
"username": "bsmith",
"fullname": "Bucephalus Smith",
"email": "bsmith@example.com"
},
{
"id": 3913,
"username": "Delia Adams",
"fullname": "dadams",
"email": "delia.adams@example.com"
},
...
]
}
Example cURL command with email_exact
curl -X GET \ https://<your-site-name>.tahoe.appsembler.com/tahoe/api/v1/users/?email_exact=jack@turner.org.uk \ -H 'Accept: */*' \ -H 'Authorization: Token <insert token here> \ -H 'Cache-Control: no-cache'
Example response for known email
When using email_exact with an existing email a list containing one user will be returned:
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 7870,
"username": "jackturner",
"fullname": "Jack Turner",
"email": "jack@turner.org.uk"
}
]
}
Example response for non-existent email_exact
If no email was found with email_exact an empty list will be returned with a HTTP status code of 200:
{
"count": 0,
"next": null,
"previous": null,
"results": []
}
GET Detail
Endpoint: /tahoe/api/v1/users/<user id>/ Request Method: GET
This returns the detail data for a single user. The fields are the same as in Table 3 above.
Example cURL command
curl -X GET \ https://<your-site-name>.tahoe.appsembler.com/tahoe/api/v1/users/1766/ \ -H 'Accept: */*' \ -H 'Authorization: Token <insert token here> \ -H 'Cache-Control: no-cache'
Example response
{
"id": 1766,
"username": "bsmith",
"fullname": "Bucephalus Smith",
"email": "bsmith@example.com"
}