Users

Creates a new user account, optionally upserting by email and granting access to licenses, courses, bundles, and learning paths in a single request

Creates a new user account, optionally upserting by email and granting access to licenses, courses, bundles, and learning paths in a single request.

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

Example request

curl -X POST "https://example.thoughtindustries.com/incoming/v2/users" \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "string",
  "upsert": true,
  "externalCustomerId": "string",
  "studentLicenseSkus": []
}'

Parameters

Name	Type	Required	Location	Description
`email`	`string`	No	body	Email address for the new user account.
`upsert`	`boolean`	No	body	When `true`, updates the existing user if one with the given email already exists instead of returning an error.
`externalCustomerId`	`string`	No	body	Identifier for the user in an external system.
`studentLicenseSkus`	`string[]`	No	body	SKUs of licenses to assign to the user with the student role.
`managerLicenseSkus`	`string[]`	No	body	SKUs of licenses to assign to the user with the manager role.
`studentLicenseIds`	`uuid[]`	No	body	UUIDs of licenses to assign to the user with the student role.
`managerLicenseIds`	`uuid[]`	No	body	UUIDs of licenses to assign to the user with the manager role.
`role`	`string`	No	body	Platform-level role to assign to the user (e.g., `admin`, `learner`).
`clientSku`	`string`	No	body	SKU of the client (tenant) to associate with the user.
`clientSlug`	`string`	No	body	URL slug of the client (tenant) to associate with the user.
`clientId`	`uuid`	No	body	UUID of the client (tenant) to associate with the user.
`replaceLicenseAccess`	`boolean`	No	body	When `true`, replaces the user's existing license assignments with those provided in this request.
`courseIds`	`uuid[]`	No	body	UUIDs of courses to grant the user access to.
`courseSlugs`	`string[]`	No	body	URL slugs of courses to grant the user access to.
`courseSkus`	`string[]`	No	body	SKUs of courses to grant the user access to.
`bundleSlugs`	`string[]`	No	body	URL slugs of bundles to grant the user access to.
`learningPathSlugs`	`string[]`	No	body	URL slugs of learning paths to grant the user access to.
`learningPathSkus`	`string[]`	No	body	SKUs of learning paths to grant the user access to.
`learningPathIds`	`uuid[]`	No	body	UUIDs of learning paths to grant the user access to.
`firstName`	`string`	No	body	User's first name.
`lastName`	`string`	No	body	User's last name.
`address1`	`string`	No	body	Primary street address line for the user.
`address2`	`string`	No	body	Secondary street address line (e.g., apartment or suite number) for the user.
`city`	`string`	No	body	City component of the user's address.
`state`	`string`	No	body	State or province component of the user's address.
`zipCode`	`string`	No	body	Postal code component of the user's address.
`country`	`string`	No	body	Country component of the user's address.
`telephone`	`string`	No	body	User's phone number.
`ref1`	`string`	No	body	Custom reference field 1 for storing arbitrary external data.
`ref2`	`string`	No	body	Custom reference field 2 for storing arbitrary external data.
`ref3`	`string`	No	body	Custom reference field 3 for storing arbitrary external data.
`ref4`	`string`	No	body	Custom reference field 4 for storing arbitrary external data.
`ref5`	`string`	No	body	Custom reference field 5 for storing arbitrary external data.
`ref6`	`string`	No	body	Custom reference field 6 for storing arbitrary external data.
`ref7`	`string`	No	body	Custom reference field 7 for storing arbitrary external data.
`ref8`	`string`	No	body	Custom reference field 8 for storing arbitrary external data.
`ref9`	`string`	No	body	Custom reference field 9 for storing arbitrary external data.
`ref10`	`string`	No	body	Custom reference field 10 for storing arbitrary external data.
`language`	`string`	No	body	Preferred language for the user interface, as a BCP 47 language tag (e.g., `en`, `fr`).
`tieredSubscription`	`boolean`	No	body	When `true`, enrolls the user under a tiered subscription plan.
`replaceCourseAccess`	`boolean`	No	body	When `true`, replaces the user's existing course access with the courses provided in this request.
`replaceLearningPathAccess`	`boolean`	No	body	When `true`, replaces the user's existing learning path access with the learning paths provided in this request.
`replaceBundleAccess`	`boolean`	No	body	When `true`, replaces the user's existing bundle access with the bundles provided in this request.
`customFields`	`object`	No	body	Key-value pairs for any custom profile fields defined on the client.
`sfContactId`	`uuid`	No	body	Salesforce Contact ID to associate with this user.
`sfAccountId`	`uuid`	No	body	Salesforce Account ID to associate with this user.
`sendInvite`	`boolean`	No	body	When `true`, sends an invitation email to the user after account creation.
`inviteMessage`	`string`	No	body	Custom message body included in the invitation email when `sendInvite` is `true`.
`balance`	`number`	No	body	Initial credit balance to assign to the user, in the client's configured credit units.
`enforceAccessDays`	`boolean`	No	body	When `true`, enforces the access-day limit defined on the assigned license or content.
`preferredCurrency`	`string`	No	body	ISO 4217 currency code representing the user's preferred display currency (e.g., `USD`, `EUR`).

Example response

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