/api/users/v1/users
- 17 Oct 2024
- 6 Minutes to read
- Contributors
- Print
/api/users/v1/users
- Updated on 17 Oct 2024
- 6 Minutes to read
- Contributors
- Print
Article summary
Did you find this summary helpful?
Thank you for your feedback
Get
/api/users/v1/users
Retrieves a paginated, filtered, sorted list of users.
Query parameters
limit
integer
The number of items to return in the response.
Minimum0
Example1
offset
integer
The number of items to skip before collecting the result.
Minimum0
Example0
search
string
A matcher for a user's name/full, email/address, and badgeId fields.
filter
string
An OData field filter. Supported fields are:
idbadgeIdemail/verifiedname/fullworkspaceRoleAssignments(using a lambda function will allow for filtering on theuserRoleIdandworkspaceIdsubfields)globalRoleId
Note that filtering on roles that apply across all workspaces must be performed through the globalRoleId field. All other roles must be filtered using workspaceRoleAssignments.
archived
boolean
When set to false (the default), only active users are returned. When set to true, only deactivated users are returned.
Responses
200
A list of available users
object
items
Array of object (User)
Example{ "id": "78M2aGebq5MjhKafN", "name": { "full": "John Doe" }, "email": { "address": "john.doe@tulip.co", "verified": true }, "created": { "at": "2023-05-06T05:41:08Z", "by": { "type": "user", "id": "Acbu9bbP7jHHDSq8e" } }, "lastModified": { "at": "2024-01-18T07:11:17Z", "by": { "type": "user", "id": "ieW7gygymmFY253Ew" } } }
id
Exampleg56RCoZCtzv7borvp
name
object
The user's name.
full
string
The user's full name.
avatarUrl
string
The url which host's a user's profile picture.
language
string
ISO-639-1 Language codes supported within the Tulip platform.
Valid values[ "bg", "cs", "da", "de", "el", "en", "en-GB", "es", "et", "fi", "fr", "hu", "id", "it", "ja", "ko", "lt", "lv", "nb", "nl", "pl", "pt-PT", "pt-BR", "ro", "ru", "sk", "sl", "sv", "tr", "uk", "zh-Hans" ]
Exampleen
email
object
The user's email address and whether or not it is verified.
address
string
The user's email address.
verified
boolean
Whether a user's email address has been confirmed.
phone
object
The user's phone number and whether or not it is verified.
number
string
The user's phone number.
verified
boolean
Whether a user's phone number has been confirmed.
badgeId
string
A unique string which identifies a user for Player authentication.
invited
by
object (ActorMetadata)
Represents a user, api-token, or device.
type
string
Valid values[ "user", "client", "api-token", "app-exchange-api-token", "celosx-api-token", "automation", "instance-init" ]
id
Exampleg56RCoZCtzv7borvp
created
by
object (ActorMetadata)
Represents a user, api-token, or device.
type
string
Valid values[ "user", "client", "api-token", "app-exchange-api-token", "celosx-api-token", "automation", "instance-init" ]
id
Exampleg56RCoZCtzv7borvp
lastModified
by
object (ActorMetadata)
Represents a user, api-token, or device.
type
string
Valid values[ "user", "client", "api-token", "app-exchange-api-token", "celosx-api-token", "automation", "instance-init" ]
id
Exampleg56RCoZCtzv7borvp
archived
by
object (ActorMetadata)
Represents a user, api-token, or device.
type
string
Valid values[ "user", "client", "api-token", "app-exchange-api-token", "celosx-api-token", "automation", "instance-init" ]
id
Exampleg56RCoZCtzv7borvp
OneOf
object
workspaceRoleAssignments
Array of object (WorkspaceRoleAssignment)
object
One of a a user's member workspaces and its associated role.
workspaceId
string
ExampleDEFAULT
userRoleId
OneOf
string
string
Valid values[ "operator", "operator-with-registration", "shop-floor-operator", "apps-approver-admin", "apps-builder-admin", "apps-admin", "tables-admin", "connectors-admin", "shop-floor-admin", "viewer", "viewer-with-player", "admin", "workspace-owner", "owner" ]
object
globalRoleId
string
Valid values[ "owner" ]
count
number
The total number of items that matched the list parameters.
Example10
nextPage
string (url)
A URL at which the next page of results can be fetched.
prevPage
string (url)
A URL at which the previous page of results can be fetched.
errors
Array of object (PaginatedItemError)
A list of errors per item that is omitted from the paginated response, if any.
object
Example{ "errorCode": "generic.internal", "message": "Something went wrong.", "retryable": false, "details": { "id": "invalidRecordId" } }
errorCode
string
A machine-readable code identifying the type of error.
Pattern^[a-zA-Z0-9.]$
message
string
A human-readable description of the error intended for debugging purposes only.
The exact content of this message is not stable.
retryable
boolean
Whether the request can be automatically retried by the client.
details
object
id
string
The ID of the omitted record.
400
An error occurred. The Tulip error codes generic.customerIdRequired, generic.workspaceIdRequired, generic.invalidParams, http.invalidBodyJson, http.invalidHeaders, http.multiValueHeader, generic.filterParamUnsupportedOperation, generic.filterParamUnsupportedField, generic.limitParamNonNegativeInt, generic.limitParamBounds, generic.offsetParamNonNegativeInt, and users.invalidFilter all use the 400 HTTP status code. See the documentation of the response content schema for details on these specific Tulip errors that could result in this status code.
OneOf
object
errorCode
string
A machine-readable code identifying the type of error.
Pattern^[a-zA-Z0-9.]$
message
string
A human-readable description of the error intended for debugging purposes only.
The exact content of this message is not stable.
retryable
boolean
Whether the request can be automatically retried by the client.
object
errorCode
string
A machine-readable code identifying the type of error.
Pattern^[a-zA-Z0-9.]$
message
string
A human-readable description of the error intended for debugging purposes only.
The exact content of this message is not stable.
retryable
boolean
Whether the request can be automatically retried by the client.
object
errorCode
string
A machine-readable code identifying the type of error.
Pattern^[a-zA-Z0-9.]$
message
string
A human-readable description of the error intended for debugging purposes only.
The exact content of this message is not stable.
retryable
boolean
Whether the request can be automatically retried by the client.
object
errorCode
string
A machine-readable code identifying the type of error.
Pattern^[a-zA-Z0-9.]$
message
string
A human-readable description of the error intended for debugging purposes only.
The exact content of this message is not stable.
retryable
boolean
Whether the request can be automatically retried by the client.
object
errorCode
string
A machine-readable code identifying the type of error.
Pattern^[a-zA-Z0-9.]$
message
string
A human-readable description of the error intended for debugging purposes only.
The exact content of this message is not stable.
retryable
boolean
Whether the request can be automatically retried by the client.
object
errorCode
string
A machine-readable code identifying the type of error.
Pattern^[a-zA-Z0-9.]$
message
string
A human-readable description of the error intended for debugging purposes only.
The exact content of this message is not stable.
retryable
boolean
Whether the request can be automatically retried by the client.
details
object
headerName
string
The name of the given HTTP header which had multiple values.
object
errorCode
string
A machine-readable code identifying the type of error.
Pattern^[a-zA-Z0-9.]$
message
string
A human-readable description of the error intended for debugging purposes only.
The exact content of this message is not stable.
retryable
boolean
Whether the request can be automatically retried by the client.
object
errorCode
string
A machine-readable code identifying the type of error.
Pattern^[a-zA-Z0-9.]$
message
string
A human-readable description of the error intended for debugging purposes only.
The exact content of this message is not stable.
retryable
boolean
Whether the request can be automatically retried by the client.
object
errorCode
string
A machine-readable code identifying the type of error.
Pattern^[a-zA-Z0-9.]$
message
string
A human-readable description of the error intended for debugging purposes only.
The exact content of this message is not stable.
retryable
boolean
Whether the request can be automatically retried by the client.
object
errorCode
string
A machine-readable code identifying the type of error.
Pattern^[a-zA-Z0-9.]$
message
string
A human-readable description of the error intended for debugging purposes only.
The exact content of this message is not stable.
retryable
boolean
Whether the request can be automatically retried by the client.
details
object
upperBound
integer
The maximum allowed value for the limit parameter.
object
errorCode
string
A machine-readable code identifying the type of error.
Pattern^[a-zA-Z0-9.]$
message
string
A human-readable description of the error intended for debugging purposes only.
The exact content of this message is not stable.
retryable
boolean
Whether the request can be automatically retried by the client.
object
errorCode
string
A machine-readable code identifying the type of error.
Pattern^[a-zA-Z0-9.]$
message
string
A human-readable description of the error intended for debugging purposes only.
The exact content of this message is not stable.
retryable
boolean
Whether the request can be automatically retried by the client.
401
The request was missing required authentication information.
This error is not automatically retryable.
object
errorCode
string
A machine-readable code identifying the type of error.
Pattern^[a-zA-Z0-9.]$
message
string
A human-readable description of the error intended for debugging purposes only.
The exact content of this message is not stable.
retryable
boolean
Whether the request can be automatically retried by the client.
429
Too many requests have been made to this endpoint in a short time period.
This error is not automatically retryable.
object
errorCode
string
A machine-readable code identifying the type of error.
Pattern^[a-zA-Z0-9.]$
message
string
A human-readable description of the error intended for debugging purposes only.
The exact content of this message is not stable.
retryable
boolean
Whether the request can be automatically retried by the client.
details
object
details
string
Additional details about this endpoint's rate limits.
500
An internal server error occurred. Please contact support@tulip.co if the error persists.
This error is not automatically retryable.
object
errorCode
string
A machine-readable code identifying the type of error.
Pattern^[a-zA-Z0-9.]$
message
string
A human-readable description of the error intended for debugging purposes only.
The exact content of this message is not stable.
retryable
boolean
Whether the request can be automatically retried by the client.
Was this article helpful?
