Users

Download OpenAPI specification:Download

Manage user profiles

Create users

Create multiple users

SecurityOAuth2: ClientAccessToken
Request
Request Body schema: application/json
required
Array
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

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
post/v1/users/bulk
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
{
  • "result": {
    }
}

Get users count

Get the number of saved users

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.

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

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

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).

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

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

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

SecurityOAuth2: ClientAccessToken
Request
path Parameters
external_user_id
required
string

The external user ID to search for

Responses
200
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

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

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.

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.

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

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

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

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).

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).

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).

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
get/v1/users/me/device-keys
Request samples
Response samples
application/json
{
  • "result": {
    }
}