Users

Returns a paginated list of users, optionally filtered by role

Returns a paginated list of users, optionally filtered by role.

GEThttps://example.thoughtindustries.com/incoming/v2/users

Example request

curl "https://example.thoughtindustries.com/incoming/v2/users" \
  -H 'Authorization: Bearer YOUR_API_KEY'

Parameters

Name	Type	Required	Location	Description
`role`	`string`	No	query	Filters the returned users by role key (e.g. `admin`, `learner`).
`cursor`	`string`	No	query	Opaque cursor for the next page of results. Omit to fetch the first page.

Example response

{
  "pageInfo": {
    "total": 0,
    "hasMore": true,
    "cursor": "string"
  },
  "users": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "learnerUserId": "00000000-0000-0000-0000-000000000000",
      "managerUserId": "00000000-0000-0000-0000-000000000000",
      "clientId": "00000000-0000-0000-0000-000000000000",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "disabled": true,
      "sfAccountId": "00000000-0000-0000-0000-000000000000",
      "sfContactId": "00000000-0000-0000-0000-000000000000",
      "roleKey": "string",
      "address1": "string",
      "address2": "string",
      "city": "string",
      "state": "string",
      "zipCode": "string",
      "telephone": "string",
      "country": "string",
      "stripeCustomerId": "00000000-0000-0000-0000-000000000000",
      "externalCustomerId": "string",
      "shippingName": "string",
      "asset": "string",
      "email": "string",
      "firstName": "string",
      "lastName": "string",
      "lastActiveAt": "2024-01-01T00:00:00.000Z",
      "ref1": "string",
      "ref2": "string",
      "ref3": "string",
      "ref4": "string",
      "ref5": "string",
      "ref6": "string",
      "ref7": "string",
      "ref8": "string",
      "ref9": "string",
      "ref10": "string",
      "language": "string",
      "customFields": {},
      "purchasedBundles": [
        {
          "bundleId": "00000000-0000-0000-0000-000000000000"
        }
      ],
      "allocatedLicenses": [
        {
          "licenseId": "00000000-0000-0000-0000-000000000000"
        }
      ],
      "allocatedLearningPaths": [
        {
          "learningPathId": "00000000-0000-0000-0000-000000000000",
          "status": "string"
        }
      ],
      "purchasedCourses": [
        {
          "courseId": "00000000-0000-0000-0000-000000000000",
          "status": "string"
        }
      ],
      "waitlistedCourses": [
        {
          "courseId": "00000000-0000-0000-0000-000000000000"
        }
      ],
      "balance": 0,
      "preferredCurrency": "string"
    }
  ]
}

Response fields

Field	Type	Description
`pageInfo`	`object`	Cursor-based pagination metadata for the result set.
`pageInfo.total`	`integer`	Total number of records matching the query.
`pageInfo.hasMore`	`boolean`	Whether additional pages of results are available.
`pageInfo.cursor`	`string`	Opaque cursor to pass on the next request. Present when `hasMore` is `true`.
`users`	`object[]`	Array of user objects for the current page.
`users.id`	`uuid`	Unique identifier of the user.
`users.learnerUserId`	`uuid`	Identifier of the associated learner user record, when the user has a dual role.
`users.managerUserId`	`uuid`	Identifier of the associated manager user record, when the user has a dual role.
`users.clientId`	`uuid`	Identifier of the client (tenant) the user belongs to.
`users.createdAt`	`ISO 8601 timestamp`	Timestamp when the user was created.
`users.disabled`	`boolean`	Whether the user account is disabled.
`users.sfAccountId`	`uuid`	Salesforce Account ID associated with the user.
`users.sfContactId`	`uuid`	Salesforce Contact ID associated with the user.
`users.roleKey`	`string`	Platform role key assigned to the user.
`users.address1`	`string`	Primary street address line.
`users.address2`	`string`	Secondary street address line.
`users.city`	`string`	City component of the address.
`users.state`	`string`	State or province component of the address.
`users.zipCode`	`string`	Postal code component of the address.
`users.telephone`	`string`	User's phone number.
`users.country`	`string`	Country component of the address.
`users.stripeCustomerId`	`uuid`	Stripe customer identifier for the user.
`users.externalCustomerId`	`string`	Identifier for the user in an external system.
`users.shippingName`	`string`	Name used for shipping physical goods.
`users.asset`	`string`	URL of the user's avatar asset.
`users.email`	`string`	User's email address.
`users.firstName`	`string`	User's first name.
`users.lastName`	`string`	User's last name.
`users.lastActiveAt`	`ISO 8601 timestamp`	Timestamp of the last recorded user activity.
`users.ref1`	`string`	Custom reference field 1 for storing arbitrary external data.
`users.ref2`	`string`	Custom reference field 2 for storing arbitrary external data.
`users.ref3`	`string`	Custom reference field 3 for storing arbitrary external data.
`users.ref4`	`string`	Custom reference field 4 for storing arbitrary external data.
`users.ref5`	`string`	Custom reference field 5 for storing arbitrary external data.
`users.ref6`	`string`	Custom reference field 6 for storing arbitrary external data.
`users.ref7`	`string`	Custom reference field 7 for storing arbitrary external data.
`users.ref8`	`string`	Custom reference field 8 for storing arbitrary external data.
`users.ref9`	`string`	Custom reference field 9 for storing arbitrary external data.
`users.ref10`	`string`	Custom reference field 10 for storing arbitrary external data.
`users.language`	`string`	User's preferred language (BCP 47 tag). Null for non-learner roles.
`users.customFields`	`object`	Key-value pairs for custom profile fields defined on the client.
`users.purchasedBundles`	`object[]`	Bundles the user has purchased.
`users.purchasedBundles.bundleId`	`uuid`	Identifier of the purchased bundle.
`users.allocatedLicenses`	`object[]`	Licenses allocated to the user.
`users.allocatedLicenses.licenseId`	`uuid`	Identifier of the allocated license.
`users.allocatedLearningPaths`	`object[]`	Learning paths allocated to the user.
`users.allocatedLearningPaths.learningPathId`	`uuid`	Identifier of the allocated learning path.
`users.allocatedLearningPaths.status`	`string`	Status of the learning path allocation.
`users.purchasedCourses`	`object[]`	Courses the user has purchased.
`users.purchasedCourses.courseId`	`uuid`	Identifier of the purchased course.
`users.purchasedCourses.status`	`string`	Enrollment status for the course.
`users.waitlistedCourses`	`object[]`	Courses the user is waitlisted for.
`users.waitlistedCourses.courseId`	`uuid`	Identifier of the waitlisted course.
`users.balance`	`number`	User's current credit balance.
`users.preferredCurrency`	`string`	User's preferred display currency (ISO 4217).