OpenAPI Specification
openapi: 3.0.1
info:
title: Thinkific Admin Bundles Users API
description: Thinkific's public API can be used to integrate your application with your Thinkific site.
termsOfService: https://www.thinkific.com/legal/
contact:
email: developers@thinkific.com
version: v1
servers:
- url: https://api.thinkific.com/api/public/v1
security:
- OAuthAccessToken: []
- ApiKey: []
ApiKeySubdomain: []
tags:
- name: Users
description: Users operations
paths:
/users:
get:
tags:
- Users
summary: List Users
description: Retrieve a list of users
operationId: getUsers
parameters:
- name: page
in: query
description: The page within the collection to fetch
schema:
type: number
default: 1.0
- name: limit
in: query
description: The number of items to be returned
schema:
type: number
default: 25.0
- name: query[email]
in: query
description: Search Users by email.
schema:
type: string
- name: query[role]
in: query
description: Search Users by role.
schema:
type: string
- name: query[external_source]
in: query
description: Search Users by external source.
schema:
type: string
- name: query[custom_profile_field_label]
in: query
description: Search by custom profile field label (must be combined with custom_profile_field_value)
schema:
type: string
- name: query[custom_profile_field_value]
in: query
description: Search by custom profile field value (must be combined with custom_profile_field_label)
schema:
type: string
- name: query[group_id]
in: query
description: Search by group id.
schema:
type: number
responses:
200:
description: Users response
content:
application/json:
schema:
$ref: '#/components/schemas/GetUsersResponse'
403:
$ref: '#/components/responses/ErrorForbiddenAppsNotAvailableResponse'
post:
tags:
- Users
summary: Create user
description: Create a new user
operationId: createUser
requestBody:
description: Create user request body
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
required: true
responses:
201:
description: User Created
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
403:
$ref: '#/components/responses/ErrorForbiddenAppsNotAvailableResponse'
422:
description: UnprocessableEntity
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityError'
example:
errors:
first_name:
- can't be blank
x-codegen-request-body-name: body
/users/{id}:
get:
tags:
- Users
summary: List Users by ID
description: Retrieves a User identified by the provided id
operationId: getUserByID
parameters:
- name: id
in: path
description: Accepts a Thinkific generated ID (in the form of an integer), or an External ID (as a string) when accompanied by the "provider" parameter.
required: true
schema:
type: string
- name: provider
in: query
description: Provider from which the user's External Id is associated (Required if using External Id as id parameter)
required: false
schema:
type: string
enum:
- SSO
- OPENID_CONNECT
description: Provider that creates the user and with which the External Id is associated.
example: SSO
responses:
200:
description: User Response
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
403:
$ref: '#/components/responses/ErrorForbiddenAppsNotAvailableResponse'
404:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
put:
tags:
- Users
summary: Update user by ID
description: Updates the user specified by the provided id
operationId: updateUserByID
parameters:
- name: id
in: path
description: Accepts a Thinkific generated ID (in the form of an integer), or an External ID (as a string) when accompanied by the "provider" parameter.
required: true
schema:
type: string
- name: provider
in: query
description: Provider from which the user's External Id is associated (Required if using External Id as id parameter)
required: false
schema:
type: string
enum:
- SSO
- OPENID_CONNECT
description: Provider that creates the user and with which the External Id is associated.
example: SSO
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserRequest'
required: true
responses:
204:
description: User Updated
403:
$ref: '#/components/responses/ErrorForbiddenAppsNotAvailableResponse'
404:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
422:
description: UnprocessableEntity
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityError'
example:
errors:
first_name:
- can't be blank
x-codegen-request-body-name: body
delete:
tags:
- Users
summary: Delete user by ID
description: Deletes a User identified by the provided id
operationId: deleteUserByID
parameters:
- name: id
in: path
description: Accepts a Thinkific generated ID (in the form of an integer), or an External ID (as a string) when accompanied by the "provider" parameter.
required: true
schema:
type: string
- name: provider
in: query
description: Provider from which the user's External Id is associated (Required if using External Id as id parameter)
required: false
schema:
type: string
enum:
- SSO
- OPENID_CONNECT
description: Provider that creates the user and with which the External Id is associated.
example: SSO
responses:
204:
description: User Deleted
404:
description: NotFound
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
/users/{id}/authentications/{provider}:
get:
tags:
- Users
summary: Get User Auth data by ID and Provider
description: Retrieves a User authentication data identified by the id and provider
operationId: getUserAuthByIDAndProvider
parameters:
- name: id
in: path
description: Accepts a Thinkific generated ID (in the form of an integer)
required: true
schema:
type: string
- name: provider
in: path
description: Provider from which the user's External Id is associated
required: true
schema:
type: string
enum:
- SSO
- OPENID_CONNECT
description: Provider that creates the user and with which the External Id is associated.
example: SSO
responses:
200:
description: User Response
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationResponse'
403:
$ref: '#/components/responses/ErrorForbiddenAppsNotAvailableResponse'
404:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorNotFound'
components:
schemas:
AuthenticationResponse:
type: object
properties:
provider:
type: string
enum:
- SSO
- OPENID_CONNECT
description: Authentication provider associated with the user.
example: OPENID_CONNECT
external_id:
type: string
description: User External Id given by the provider.
example: abc123
UpdateUserRequest:
type: object
properties:
first_name:
type: string
description: 'User''s first name '
example: Bob
last_name:
type: string
description: User's last name
example: Smith
email:
type: string
description: User's email. This can only be updated by private integrations.
format: email
example: bob@example.com
password:
minLength: 6
type: string
description: The password of the User.
example: password
roles:
type: array
description: User's roles
example:
- affiliate
items:
type: string
enum:
- affiliate
- course_admin
- group_analyst
- site_admin
avatar_url:
type: string
description: The fully-qualified avatar url of the User.
example: https://example.com/avatar/123
bio:
type: string
description: User's bio
example: The user's bio
company:
type: string
description: User's Company Name
example: The user's company
headline:
type: string
description: User's headline
example: The user's job title
external_source:
type: string
description: User's external source
example: The external source that the user was created from
affiliate_code:
type: string
description: User's affiliate code
example: abc123
affiliate_commission:
type: number
description: Required only if the User is an affiliate. This should be greater than 0 and less than or equal to 100 if the type is percentage or lower than 9999.99 if is a fixed type.
example: 20.0
affiliate_commission_type:
type: string
description: The affiliate payout type, it can be either % (percentage, default) or $ (fixed amount). Required only if the User is an affiliate.
example: '%'
affiliate_payout_email:
type: string
description: The email of the User. Required only if the user is an affiliate. Used to pay the User out.
example: bob@example.com
custom_profile_fields:
type: array
description: Custom profile fields for the User.
items:
$ref: '#/components/schemas/CustomProfileFieldRequest'
ValidationError:
type: object
properties:
field_name:
type: string
description: validation error
Meta:
type: object
properties:
pagination:
$ref: '#/components/schemas/Pagination'
UserResponse:
type: object
properties:
id:
type: number
description: User's ID
example: 1.0
created_at:
type: string
description: User's created date
format: date-time
example: '2018-07-12T23:19:00.154Z'
first_name:
type: string
description: The first name of the User.
example: Bob
last_name:
type: string
description: The last name of the User.
example: Smith
full_name:
type: string
description: The email of the User.
example: Bob Smith
company:
type: string
description: The company of the User.
example: The user's company
email:
type: string
description: User's email
format: email
example: bob@example.com
roles:
type: array
description: 'Any specific roles that the User should be placed in. Possible roles are: affiliate, course_admin, group_analyst, site_admin.'
example:
- affiliate
items:
type: string
enum:
- affiliate
- course_admin
- group_analyst
- site_admin
avatar_url:
type: string
description: The fully-qualified avatar url of the User.
example: https://example.com/avatar/123
bio:
type: string
description: The bio of the User.
example: User's bio
headline:
type: string
description: The headline/title of the User.
example: User's headline
affiliate_code:
type: string
description: The affiliate code of the User. ** Required only if the User is an affiliate. **
example: abc123
external_source:
type: string
description: User's external source
affiliate_commission:
type: number
description: The affiliate commission % of the User. ** Required only if the User is an affiliate. This should be greater than 0 and less than or equal to 100. **
example: 20.0
affiliate_commission_type:
type: string
description: The affiliate payout type, it can be either % (percentage, default) or $ (fixed amount). ** Required only if the User is an affiliate. **
example: '%'
affiliate_payout_email:
type: string
description: The email of the User. ** Required only if the user is an affiliate. Used to pay the User out. **
example: bob@example.com
administered_course_ids:
type: array
description: User's administered course ids
items:
type: number
example:
- 10
- 20
- 30
custom_profile_fields:
type: array
description: Custom profile fields for the User.
items:
$ref: '#/components/schemas/CustomProfileField'
CustomProfileFieldRequest:
required:
- custom_profile_field_definition_id
type: object
properties:
value:
type: string
description: Custom profile field value
example: 887 909 9999
custom_profile_field_definition_id:
type: number
description: Custom profile field definition id
example: 1.0
ErrorForbiddenAppsNotAvailable:
type: object
properties:
error:
type: string
description: access forbidden
example:
error: Access to Apps is not available on your plan. Upgrade to gain access
GetUsersResponse:
required:
- items
- meta
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/UserResponse'
meta:
$ref: '#/components/schemas/Meta'
CreateUserRequest:
required:
- email
- first_name
- last_name
type: object
properties:
first_name:
type: string
description: 'User''s first name '
example: Bob
last_name:
type: string
description: User's last name
example: Smith
email:
type: string
description: User's email
format: email
example: bob@example.com
password:
minLength: 6
type: string
description: The password of the User. If not included, the Express Sign In Link becomes activated for the User.
example: password
roles:
type: array
description: User's roles
example:
- affiliate
items:
type: string
enum:
- affiliate
- course_admin
- group_analyst
- site_admin
bio:
type: string
description: User's bio
example: The user's bio
company:
type: string
description: User's Company Name
example: The user's company
headline:
type: string
description: User's headline
example: The user's job title
affiliate_code:
type: string
description: User's affiliate code
example: abc123
affiliate_commission:
type: number
description: Required only if the User is an affiliate. This should be greater than 0 and less than or equal to 100 if the type is percentage or lower than 9999.99 if is a fixed type.
example: 20.0
affiliate_commission_type:
type: string
description: The affiliate payout type, it can be either % (percentage, default) or $ (fixed amount). Required only if the User is an affiliate.
example: '%'
affiliate_payout_email:
type: string
description: The email of the User. Required only if the user is an affiliate. Used to pay the User out.
example: bob@example.com
custom_profile_fields:
type: array
description: Custom profile fields for the User.
items:
$ref: '#/components/schemas/CustomProfileFieldRequest'
skip_custom_fields_validation:
type: boolean
description: Option to skip required custom profile fields validation.
default: false
send_welcome_email:
type: boolean
description: Option to send the Site Welcome email to the User.
default: false
external_id:
type: string
description: Optional identifier of the user in an external system. Typically used in conjunction with Thinkific's single sign-on. For further information on this, please read [this](https://help.thinkific.com/support/solutions/articles/221622-sso-automatically-sign-in-from-your-own-website)
provider:
type: string
description: When using Thinkific single sign-on and providing an external_id, specify the provider type to distinguish which single sign-on type the user should be associated with.
enum:
- SSO
- OPENID_CONNECT
default: SSO
ErrorNotFound:
type: object
properties:
error:
type: string
description: item not found error
example:
error: Record not found.
CustomProfileField:
type: object
properties:
id:
type: number
description: Custom profile field ID
example: 1.0
value:
type: string
description: Custom profile field value
example: 887 909 9999
label:
type: string
description: Custom profile field label
example: Phone
custom_profile_field_definition_id:
type: number
description: Custom profile field definition ID
example: 1.0
UnprocessableEntityError:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ValidationError'
Pagination:
type: object
properties:
current_page:
type: number
description: Current page number
example: 1.0
next_page:
type: number
description: Next page number
example: 2.0
prev_page:
type: number
description: Previous page number
total_pages:
type: number
description: Number of total pages
example: 10.0
total_items:
type: number
description: Number of total items
example: 250.0
entries_info:
type: string
description: Entries info
example: 1-10 of 10
description: Pagination metadata
responses:
ErrorForbiddenAppsNotAvailableResponse:
description: Access Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorForbiddenAppsNotAvailable'
securitySchemes:
OAuthAccessToken:
type: http
scheme: bearer
ApiKey:
type: apiKey
in: header
name: X-Auth-API-Key
description: Used together with ApiKeySubdomain
ApiKeySubdomain:
type: apiKey
in: header
name: X-Auth-Subdomain
description: Used together with ApiKey
externalDocs:
description: Find out more about Thinkifc's API
url: http://developers.thinkific.com/api/api-documentation/