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 Notes

  • Throughout this doc, you will see references to Token <insert token here>. If you are a Tahoe site admin, please contact support@appsembler.com to request a unique auth token for your site. 
  • User information is considered private, protected information, so it falls under our Privacy Policy and Terms of Use. By using the user APIs, you agree to adhere to the terms of the GDPR (General Data Protection Regulation).

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

Related Articles