Skip to main content

User Endpoints

User Endpoints and Parameters

To find out more about the objects relations, go to the Object Relations section.

For more information about users, visit the User and Group Management help page.

Create a New User

To create a new user record, use the POST {baseURL}/v3/users endpoint.

Note

Only Curators can use this API endpoint.

This endpoint can’t be used for Windows Authentication configured Server instances.

Parameters

  • userContract (body): To create a new user, the userContract parameter is required. Specify the following parameters:

    • firstName (string): Required. Enter a user’s first name.

    • lastName (string): Required. Enter a user’s last name.

    • email (string): Required. Enter a user’s email address.

    • role (string): Optional. You can select from these options: NoAccess, Viewer, Member, Artisan, Curator, and Evaluated (the default role evaluated at runtime). For more information about roles and permissions, visit the User Roles and Permissions page. When no role is selected, the default is the Evaluated role.

    • defaultWorkerTag (string): Optional. Specify the worker tag defined in the workers to help assign jobs to certain worker nodes. When not specified, the default is "". For more information, visit the Worker help page.

    • canScheduleJobs (boolean): Optional. Specify whether the user can schedule jobs. When not specified, the default is false. For more information, visit the Jobs help page.

    • canPrioritizeJobs (boolean): Optional. Specify whether a user can prioritize jobs. When not specified, the default is false. For more information, visit the Jobs help page.

    • canAssignJobs (boolean): Optional. Specify whether a user can assign jobs. When not specified, the default is false. For more information, visit the Jobs help page.

    • canCreateCollections (boolean): Optional. Specify whether a user can create new collections. When not specified, the default is false. For more information, visit the Collections help page.

    • isApiEnabled (boolean): Optional. Specify whether the API is enabled for a user. When not specified, the default is false.

    • defaultCredentialId (string): Optional. This parameter refers to the unique ID of a workflow, assigned to the user as default. When not specified, the default is "".

    • isActive (boolean): Optional. Select whether a user is active or deactivated. When not specified, the default is true.

    • timeZone (string): Optional. Enter the time zone, for example, Europe/Kiev. When not specified, the default is "".

Request Example: cURL

curl --location --request POST 'http://localhost/webapi/v3/users' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer BearerTokenGoesHere' \ --data-urlencode 'firstName=John' \ --data-urlencode 'lastName=Doe' \ --data-urlencode 'email=John.Doe@emailexample.com'

Deactivate a User

To deactivate a user in the system, use the POST {baseURL}/v3/users/{userId}/deactivate endpoint.

Note

Only Curators can use this API endpoint.

As a response, you get an array of user group IDs that the deactivated user is removed from.

Parameters

  • userId (string): Required. Enter a user ID to deactivate this user.

Request Example: cURL

curl --location --request POST 'http://localhost/webapi/v3/users/61d57bea3c15317e1a48205b/deactivate' \ --header 'Authorization: Bearer BearerTokenGoesHere'

Send a Password Reset Email to a User

To send a password reset email to an existing user, use the POST {baseURL}/v3/users/{userId}/passwordReset endpoint.

Note

Only Curators can use this API endpoint.

This endpoint can't be used for Windows Authentication and SAML Authentication configured Server instances.

Parameters

  • userId (string): Required. Enter a user ID to send a reset email to the user.

Request Example: cURL

curl --location --request POST 'http://localhost/webapi/v3/users/61d57bea3c15317e1a48205b/passwordReset' \ --header 'Authorization: Bearer BearerTokenGoesHere'

Retrieve all User Records

To retrieve all accessible user records, use the GET {baseURL}/v3/users endpoint. Use various parameters as a filter.

Note

Only Curators can use this API endpoint.

If the searchContract.Verbose is set to false, then a reduced view object will be returned.

Parameters

  • view (string): Optional. Can be left without a value. You can choose from the following values: ‘Default’ and ‘Full’. If this parameter is set to 'Default’, then a reduced view object will be returned. When not specified, the ‘Default’ value is used.

  • active (boolean): Optional. Select whether a user is active or deactivated.

  • email (string): Optional. Enter user’s email address.

  • role (string): Optional. Select the user role to narrow the search. Select from these options: NoAccess, Viewer, Member, Artisan, Curator, and Evaluated. The default (Evaluated) role is evaluated at runtime. For more information about roles and permissions, visit the User Roles and Permissions page.

  • firstName (string): Optional. Enter user’s first name.

  • lastName (string): Optional. Enter user’s last name.

  • createdAfter (date-time): Optional. Enter the date and time after which the user was created. Enter the date and time in ISO8601 format.

  • createdBefore (date-time): Optional. Enter the date and time before which the user was created. Enter the date and time in ISO8601 format.

Request Example: cURL

curl --location --request GET 'http://localhost/webapi/v3/users?view=Full&active=true&lastName=Doe' \ --header 'Authorization: Bearer BearerTokenGoesHere'

Retrieve Details about a Specific User

To retrieve details about an existing user, use the GET {baseURL}/v3/users/{userId} endpoint.

Note

Only Curators can use this API endpoint.

Parameters

  • userId (string): Required. Enter a user ID to retrieve details about this user.

Request Example: cURL

curl --location --request GET 'http://localhost/webapi/v3/users/61d57bea3c15317e1a48205b' \ --header 'Authorization: Bearer BearerTokenGoesHere'

Retrieve All Assets a User Owns

To get a full list of accessible assets that an existing user owns, use the GET {baseURL}/v3/users/{userId}/assets endpoint.

Note

Only Curators can use this API endpoint.

Parameters

  • userId (string): Required. Enter a user ID to retrieve the list of assets for this user.

  • assetType (string): Optional. Select the asset types you want to return. Default is set to 'All'.

Request Example: cURL

curl --location --request GET 'http://localhost/webapi/v3/users/61d564361d6d5da7ad461a32/assets?assetType=Workflows' \ --header 'Authorization: Bearer BearerTokenGoesHere'

Update an Existing User

To update details of an existing user, use the PUT {baseURL}/v3/users/{userId} endpoint.

Note

Only Curators can use this API endpoint.

The ID of the updateContract will be overwritten by the ID value in the URL.

Parameters

  • userId (string): Required. Enter a user ID to get this user updated.

  • updateContract (body): Required. To update a user, the updateContract parameter is required. Specify the following:

    • id (string): Optional. Enter a user ID to get it updated.

    • firstName (string): Required. Enter a user’s first name.

    • lastName (string): Required. Enter a user’s last name.

    • email (string): Required. Enter a user’s email address.

    • role (string): Required. You can select from these options: NoAccess, Viewer, Member, Artisan, Curator, and Evaluated. For more information about roles and permissions, visit the User Roles and Permissions page.

    • defaultWorkerTag (string): Required. Specify the worker tag defined in the workers to help assign jobs to certain worker nodes. For more information about workers, visit the Worker help page.

    • canScheduleJobs (boolean): Required. Specify whether a user can schedule jobs. For more information, visit the Jobs help page.

    • canPrioritizeJobs (boolean): Required. Specify whether a user can prioritize jobs. For more information, visit the Jobs help page.

    • canAssignJobs (boolean): Required. Specify whether a user can assign jobs. For more information, visit the Jobs help page.

    • canCreateCollections (boolean): Optional. Specify whether a user can create collections. When not specified, the value stays the same as before. For more information, visit the Collections help page.

    • isApiEnabled (boolean): Required. Specify whether the API is enabled for a user.

    • defaultCredentialId (string): Required. This parameter refers to the unique ID of a workflow, assigned to the user as default.

    • isAccountLocked (boolean): Required. Select whether to lock this user account.

    • isActive (boolean): Required. Select whether a user is active or deactivated.

    • isValidated (boolean): Required. Specify whether a user’s email address is validated.

    • timeZone (string): Required. Enter the time zone, e.g., Europe/Kiev, etc.

    • language (string): Required. Supported language values are "de-de", "en-us", "es-es", "fr-fr", "it-it", "ja-jp", "pt-br", "zh-cn".

Request Example: cURL

curl --location --request PUT 'http://localhost/webapi/v3/users/61d564361d6d5da7ad461a32' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer BearerTokenGoesHere' \ --data-urlencode 'firstName=Doe' \ --data-urlencode 'lastName=Jane' \ --data-urlencode 'email=jdoe@alteryx.com' \ --data-urlencode 'role=Artisan' \ --data-urlencode 'defaultWorkerTag=worker' \ --data-urlencode 'canScheduleJobs=true' \ --data-urlencode 'canPrioritizeJobs=true' \ --data-urlencode 'canAssignJobs=true' \ --data-urlencode 'canCreateCollections=true' \ --data-urlencode 'isApiEnabled=true' \ --data-urlencode 'defaultCredentialId=jdoe' \ --data-urlencode 'isAccountLocked=true' \ --data-urlencode 'isActive=true' \ --data-urlencode 'isValidated=true' \ --data-urlencode 'timeZone=Europe/Prague' \ --data-urlencode 'language=en-us' \ --data-urlencode 'id=61d564361d6d5da7ad461a32'

Delete a User

To delete an existing user from the system, use the DELETE {baseURL}/v3/users/{userId} endpoint.

Note

Only Curators can use this API endpoint.

If the user you want to delete has any assets (workflows, schedules, collections, insights) or user groups assigned, then this user can’t be deleted.

Parameters

  • userId (string): Required. Enter the user ID you want to delete.

Request Example: cURL

curl --location --request DELETE 'http://localhost/webapi/v3/users/61d57bea3c15317e1a48205b' \ --header 'Authorization: Bearer BearerTokenGoesHere'

Objects Relations

If you are creating a user, you can use created objects as follows:

Object created: "id" (for example, "id": "619158e57e607d0011ac3009")

You can use it as:

Postman Request Examples

GET /v3/users

Example of the GET request in Postman.

GET /v3/users/{id}/assets

Example of the GET request in Postman.

To know more about Postman requests, visit the How to Use Postman help page.