Users

Download OpenAPI specification:Download

Manage user profiles

Get users count

Get the number of saved users.

Required permissions: users:list, apps:list, [appId]:list.

SecurityOAuth2: ClientAccessToken
Request
query Parameters
search
string

Search expression based on the SCIM protocol. For syntax and searchable fields, see Search query syntax

Responses
200
400
get/v1/users/count
Request samples 
Response samples 
application/json
{
  • "result": {
    }
}
Create user
Add a user to Transmit. A user_id is returned as part of the User in the response that can then be used to perform other operations, such as get, update and delete. An email or a phone_number are required. 

Required permissions: apps:create, [appId]:create, users:create.


SecurityOAuth2: ClientAccessToken 
Request 
Request Body schema: application/json
required
email
string
Primary email address of the user


 
phone_number
string
Primary phone number of the user, specified in E.164 format


 
username
string
Username used to identify the user


 
secondary_emails
Array of strings
Secondary email addresses to add to user's current emails


 
secondary_phone_numbers
Array of strings
Secondary phone numbers to add to user's phone numbers, each specified in E.164 format


 
birthday
string <date-time> 
User's birthday


 
object
User's address


 
object
Object describing user's full name


 
external_account_id
string
User identifier in an app, set by the app


 
custom_app_data
object
Custom data object for app-related user info


 
picture
string
The picture of user, specified as a URL


 
language
string
The language of the user, as provided by the browser using the Accept-Language header field


 
custom_data
object
Custom data object for tenant user info


 
external_user_id
string
A unique identifier in a tenant


 
object
The password of the user, who is identified by either a username or primary email.


 
object
If this user is a dependent, this defines the permissions that the primary user will have to act on behalf of the dependent user.


 
Responses 
201
400
409
post/v1/users
Request samples 
application/json
{
  • "email": "string",
  • "phone_number": "string",
  • "username": "string",
  • "secondary_emails": [
    ],
  • "secondary_phone_numbers": [
    ],
  • "birthday": "2019-08-24T14:15:22Z",
  • "address": {
    },
  • "name": {
    },
  • "external_account_id": "string",
  • "custom_app_data": { },
  • "picture": "string",
  • "language": "string",
  • "custom_data": { },
  • "external_user_id": "string",
  • "credentials": {
    },
  • "delegated_access": {
    }
}
Response samples 
application/json
{
  • "result": {
    }
}
Get users
Search across your application’s users at Transmit. This endpoint also allows you to return all of your application’s users by sending no filters at all. 

Required permissions: users:read, users:list, apps:read, [appId]:read, apps:list, [appId]:list.


SecurityOAuth2: ClientAccessToken 
Request 
query Parameters
search
string
Search expression based on the SCIM protocol. For syntax and searchable fields, see Search query syntax


 
page_offset
number
Number of users you wish to skip before selecting users


 
page_limit
number  <= 10000 
Number of users to return in page


 
search_prefix
string
Value to search for in the primary email and phone_number fields, where the search value must match the prefix of the field value. For example, "search_prefix=john" will return users whose email starts with "john" and "search_prefix=%2B1212" returns users whose phone number starts with "+1212".


 
 Example:  search_prefix=joe
sort_field
string
 Default:  "created_at"
The name of the field you wish to sort by


 Enum: "email" "created_at" "phone_number" "last_auth"  
sort_order
string
 Default:  "asc"
The order of the sort


 Enum: "asc" "desc"  
Responses 
200
400
get/v1/users
Request samples 
Response samples 
application/json
{
  • "total_count": 0,
  • "page_info": {
    },
  • "result": [
    ]
}
Get user by ID
Search for a user by user ID. 

Required permissions: apps:read, [appId]:read, users:read.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
user_id
required
string
The user ID to search for


 
Responses 
200
400
404
get/v1/users/{user_id}
Request samples 
Response samples 
application/json
{
  • "result": {
    }
}
Update user
Update a user's attributes or their custom data. Changes will be merged into the user's profile, so you can specify only the fields you want to update. 

 Note: 
     
  •  Attributes (like name and address) cannot be partially updated, as the new value of an object or array will just replace the current one.
    •  
  • custom_data can be partially updated since it will be merged with the existing data (as a shallow merge).
. 

Required permissions: apps:edit, [appId]:edit, users:edit.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
user_id
required
string
The ID of the user that should be updated


 
header Parameters
user-agent
string
 
Request Body schema: application/json
required
email
string
Primary email address of the user


 
phone_number
string
Primary phone number of the user, specified in E.164 format


 
secondary_emails
Array of strings
Secondary email addresses to add to user's current emails


 
secondary_phone_numbers
Array of strings
Secondary phone numbers to add to user's phone numbers, each specified in E.164 format


 
birthday
string <date-time> 
User's birthday


 
object
User's address


 
object
Object describing user's full name


 
status
string
Status of user


 Enum: "Active" "Disabled" "Pending"  
external_account_id
string
User identifier in an app, set by the app


 
custom_app_data
object
Custom data object for app-related user info


 
picture
string
The picture of user, specified as a URL


 
language
string
The language of the user, as provided by the browser using the Accept-Language header field


 
custom_data
object
Custom data object for tenant user info


 
external_user_id
string
A unique identifier in a tenant


 
username
string
Username used to identify the user for password login (unless a primary email will be used instead)


 
Responses 
200
400
404
put/v1/users/{user_id}
Request samples 
application/json
{
  • "email": "string",
  • "phone_number": "string",
  • "secondary_emails": [
    ],
  • "secondary_phone_numbers": [
    ],
  • "birthday": "2019-08-24T14:15:22Z",
  • "address": {
    },
  • "name": {
    },
  • "status": "Active",
  • "external_account_id": "string",
  • "custom_app_data": { },
  • "picture": "string",
  • "language": "string",
  • "custom_data": { },
  • "external_user_id": "string",
  • "username": "string"
}
Response samples 
application/json
{
  • "result": {
    }
}
Get user's groups
Retrieve a list of groups associated with a user. 

Required permissions: apps:read, [appId]:read, groups:read.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
user_id
required
string
ID of the user to retrieve groups for


 
Responses 
200
400
404
get/v1/users/{user_id}/groups
Request samples 
Response samples 
application/json
{
  • "result": [
    ]
}
Get user by email
Search for a user by primary email. 

Required permissions: apps:read, [appId]:read, users:read.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
email
required
string
The user's primary email to search for


 
Responses 
200
400
404
get/v1/users/email/{email}
Request samples 
Response samples 
application/json
{
  • "result": {
    }
}
Get user by external user ID
Search for a user by their external_user_id, which represents the user identifier in external provider. 

Required permissions: apps:read, [appId]:read, users:read.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
external_user_id
required
string
The external user ID to search for


 
Responses 
200
400
404
get/v1/users/external-user-id/{external_user_id}
Request samples 
Response samples 
application/json
{
  • "result": {
    }
}
Get user by username
Search for a user by username. 

Required permissions: apps:read, [appId]:read, users:read.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
username
required
string
The user's username to search for


 
Responses 
200
400
404
get/v1/users/username/{username}
Request samples 
Response samples 
application/json
{
  • "result": {
    }
}
Remove user from app
Remove a user from the requesting application. 

Required permissions: apps:edit, [appId]:edit, users:edit.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
user_id
required
string
The ID of the user to remove from application


 
Responses 
204
User removed


400
404
delete/v1/users/{user_id}/apps
Request samples 
Response samples 
application/json
{
  • "message": "Bad request",
  • "error_code": 400
}
Create credentials
Creates new password credentials for a user that doesn't already have a password. The password is temporary, and must be reset upon the user's first login. 

Required permissions: apps:create, [appId]:create, authenticators:create.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
user_id
required
string
The ID of the user


 
Request Body schema: application/json
required
password
required
string
The user's new password


 
force_replace
boolean
 Default:  true
When true the password is temporary and the user will be required to replace it upon successful login


 
username
string
The user's new username. This will be the identifier the user will use to authenticate. If username is not provided and the user has verified their email, that email address will be used as the username.


 
enforce_complexity
boolean
 Default:  true
If true, the password must meet the password complexity requirements. If false, the password can be any string.


 
Responses 
201
404
409
post/v1/users/{user_id}/password
Request samples 
application/json
{
  • "password": "string",
  • "force_replace": true,
  • "username": "string",
  • "enforce_complexity": true
}
Response samples 
application/json
{
  • "result": {
    }
}
Update password
Updates the user's existing credentials with a new temporary password, which must be reset the next time they login. 

Required permissions: apps:edit, [appId]:edit, authenticators:edit.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
user_id
required
string
The ID of the user


 
Request Body schema: application/json
required
password
string
The user's new password


 
force_replace
boolean
 Default:  true
When true the password is temporary and the user will be required to replace it upon successful login


 
Responses 
200
404
409
put/v1/users/{user_id}/password
Request samples 
application/json
{
  • "password": "string",
  • "force_replace": true
}
Response samples 
application/json
{
  • "result": {
    }
}
Get user by phone numberDeprecated
Search for a user by their primary phone number


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
phone_number
required
string
The phone number of the user to get


 
Responses 
200
400
404
get/v1/users/phone/{phone_number}
Request samples 
Response samples 
application/json
{
  • "result": {
    }
}
Get user by phone number
Search for a user by their primary phone number. 

Required permissions: apps:read, [appId]:read, users:read.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
phone_number
required
string
The phone number of the user to get


 
Responses 
200
400
404
get/v1/users/phone-number/{phone_number}
Request samples 
Response samples 
application/json
{
  • "result": {
    }
}
Remove secondary email
Removes a secondary email address from the user's profile. 

Required permissions: apps:edit, [appId]:edit, users:edit.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
email
required
string
Secondary email to remove


 
user_id
required
string
ID of the user


 
Responses 
204
Secondary email is removed


400
404
delete/v1/users/{user_id}/emails/{email}
Request samples 
Remove secondary phone number
Remove a secondary phone number from the user's profile. 

Required permissions: apps:edit, [appId]:edit, users:edit.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
phone_number
required
string
Secondary phone number to remove


 
user_id
required
string
ID of the user


 
Responses 
204
Secondary phone number is removed


400
404
delete/v1/users/{user_id}/phone-numbers/{phone_number}
Request samples 
Mark email as verified
Indicates that the user's email address was verified externally. A user's email address is automatically marked as verified when used in a Transmit authentication or verification flow. If the email address is a secondary email, the request can also be used to set it as the user's primary email (by setting change_to_primary to true). 

Required permissions: apps:edit, [appId]:edit, users:edit.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
user_id
required
string
The ID of the user that should be updated


 
email
required
string
The email of the user that should be verified


 
Request Body schema: application/json
required
change_to_primary
boolean
 
Responses 
202
User email has been verified


404
post/v1/users/{user_id}/emails/{email}/verify
Request samples 
application/json
{
  • "change_to_primary": true
}
Response samples 
application/json
{
  • "message": "string",
  • "error_code": 404
}
Mark phone as verified
Indicates that the user's phone number was verified externally. A user's phone number is automatically marked as verified when used in a Transmit authentication or verification flow. If the phone number is a secondary one, the request can also be used to set it as the user's primary phone (by setting change_to_primary to true). 

Required permissions: apps:edit, [appId]:edit, users:edit.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
phone_number
required
string
The phone number of the user that should be verified


 
user_id
required
string
The ID of the user that should be updated


 
Request Body schema: application/json
required
change_to_primary
boolean
 
Responses 
202
User phone number has been verified


404
post/v1/users/{user_id}/phone-numbers/{phone_number}/verify
Request samples 
application/json
{
  • "change_to_primary": true
}
Response samples 
application/json
{
  • "message": "string",
  • "error_code": 404
}
Delete user
Delete a user and all their data (tenant-level and app-level). Requires an admin access token (from a management app). 

Required permissions: users:delete.


SecurityHTTP: bearer 
Request 
path Parameters
user_id
required
string
ID of the user


 
Responses 
204
User deleted


404
delete/v1/manage/users/{user_id}
Request samples 
Response samples 
application/json
{
  • "message": "string",
  • "error_code": 404
}
Register password
Allows a logged-in user to register their first password. Must be authorized using a valid user access token returned upon successful authentication.


SecurityHTTP: UserAccessToken 
Request 
Request Body schema: application/json
required
password
required
string
The user's new password


 
username
string
The user's new username. This will be the identifier the user will use to authenticate. If username is not provided and the user has verified their email, that email address will be used as the username.


 
Responses 
200
403
post/v1/users/me/password-credentials
Request samples 
application/json
{
  • "password": "string",
  • "username": "string"
}
Response samples 
application/json
{
  • "result": {
    }
}
Get current user's device keys
Get device keys by user id


SecurityHTTP: UserAccessToken 
Responses 
200
404
get/v1/users/me/device-keys
Request samples 
Response samples 
application/json
{
  • "result": {
    }
}