Wix Answers Help Center
Users APIs
User APIs enable you to fetch or create Wix Answers users.
Although agents are also users, and some of their information is managed using this API, agents have additional privileges and associated parameters. These are managed using the Agents API.
A user may or may not be associated with one or more companies (to manage companies, see the Company API).
All API methods that create or modify a user trigger a call to the Customer Created or Updated webhook.
All API methods that create or modify a user trigger a call to the Customer Created or Updated webhook.
Get User Information
Get Your User Information
GET https://<tenant_subdomain>.wixanswers.com/api/v1/users/me
Get the user information of the user associated with the logged in JWT token.
Get the user information of the user associated with the logged in JWT token.
- Authorization: Requires user authorization token for specific user
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: User Object (restricted level)
Request Example:
1
GET https://<account_subdomain>.wixanswers.com/api/v1/users/me
Get a User's Information by User ID
GET https://<tenant_subdomain>.wixanswers.com/api/v1/users/{user GUID}
Get a user's information, given the user's GUID.
Get a user's information, given the user's GUID.
- Authorization: Requires agent authorization token and permission FETCH_CONTACTS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: User Object (extended level)
Request Example:
1
GET https://<account_subdomain>.wixanswers.com/api/v1/users/bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa
Get a User's Information by Email Address
GET https://<tenant_subdomain>.wixanswers.com/api/v1/users?email={email address}
Get a user's information, given the user's email address. Note that the email address uniquely identifies a user.
Get a user's information, given the user's email address. Note that the email address uniquely identifies a user.
- Authorization: Requires agent authorization token and permission FETCH_CONTACTS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: User Object (extended level)
Request Param | Description | Type | Required |
---|---|---|---|
email | The user's email address | String | ✓ |
Request Example:
1
GET https://<account_subdomain>.wixanswers.com/api/v1/users?email=user@user.com
Get an SSO User's Information by External ID
GET https://<tenant_subdomain>.wixanswers.com/api/v1/users/sso?externalId={externalId}
Get an SSO user's information given the user's external ID.
Get an SSO user's information given the user's external ID.
- Authorization: Requires agent authorization token and permission FETCH_CONTACTS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: User Object
Request Param | Description | Type | Required |
---|---|---|---|
externalId | External ID of the user in auth system | String | ✓ |
Request Example:
1
GET https://<account_subdomain>.wixanswers.com/api/v1/users/sso?externalId=12345
Search for Users (Agent)
POST https://<tenant_subdomain>.wixanswers.com/api/v1/users/search/admin
Get users matching the search criteria. Includes users who are deleted, pending, and pending deletion.
Get users matching the search criteria. Includes users who are deleted, pending, and pending deletion.
- Authorization: Requires agent authorization token and permission FETCH_CONTACTS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: Structure including list of User Objects (extended level)
Payload Params | Description | Type |
---|---|---|
text | Text string to search for at the start of the following fields: firstName, lastName, email, id, externalId, phoneNumbers. | String |
emailStatus | Filter by Email Status | Integer |
userTypes | Filter by list of User Types | List of integers |
banned | Filter by whether the user is banned | Boolean |
permissionLevels | Filter by list of User Permission Levels If not specified, admins, agents, and regular users are all returned. | List of integers |
isAgent | Filter by whether the user is an agent This is the same as filtering by permissions levels 20 and 80. | Boolean |
userIds | Filter by user IDs | List of GUIDs |
emails | Filter by email addresses | List of strings |
userSortType | Sort the results as follows: * Creation date, ascending (10) * Creation date, descending (20) * Last update date, ascending (30) * Last update date, descending (40) * First name, ascending (50) * First name, descending (60) * Email address, ascending (70) * Email address, descending (80) * Company customer permission, ascending (90) * Company customer permission, descending (100) | Integer The default is 40. |
phoneNumber | Return only the record(s) matching this phone number | |
companyIds | Filter by companies | List of GUIDs |
customFieldFilters | Filter using a map of user custom field values; a structure of one or more fields and values, each one as follows: * <API field name> (string): The API name of the field (auto-generated; see Finding a Custom Field Name) * <Custom Field values / range> (format depends on the field): * fromDate (Date string) * toDate (Date string) * from (long) * to (long) * values (list) * text (string) * searchType (integer): * Contains (2) * No contains (3) * bool (Boolean) | Structure; see User object |
fromCreationDate | Filter by users created on or after this date | |
toCreationDate | Filter by users created on or before this date | |
fromLastUpdateDate | Filter by users last updated on or after this date | |
toLastUpdateDate | Filter by users last updated on or before this date | |
timeZone | Enter when searching by one of the above date fields. | Long time zone name string, for example America/Denver |
page | Page of results The default is 1. | Integer |
pageSize | Number of results on each page The default is 10. | Integer, between 1 and 250 |
Note that custom field values are case-sensitive.
Payload Example:
1 2 3 4 5 6
POST https://<tenant_subdomain>.wixanswers.com/api/v1/users/search/admin { "text": "John", "isAgent": true }
Response Example:
1 2 3 4 5 6 7 8 9
{ "items": [ List of @User objects ], "itemsCount": 108, "page": 2, "numPages": 22, "previousPage": 1, "nextPage": 3, "pageSize": 5 }
Get User Ticket Counts
POST https://<tenant_subdomain>.wixanswers.com/api/v1/users/dashboard/search
Get users matching the search criteria, including the number of tickets associated with them. This method does not return agents or admins.
Get users matching the search criteria, including the number of tickets associated with them. This method does not return agents or admins.
- Authorization: Requires agent authorization token and permission FETCH_CONTACTS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: Return structure, see below
The payload is the same as described in Search for Users (Agent).
Each user is returned as part of a search result structure, as follows:
Response Params | Description | Format |
---|---|---|
items | List of user counts, as follows: * user (User Object(extended level)): The user * numberOfTickets (integer): The number of tickets associated with the user | Structure |
itemsCount | The number of returned items | Integer |
page | The page of results | Integer |
numPages | The total number of pages of results | Integer |
pageSize | The number of results on this page | Integer |
Payload Example:
1 2 3 4 5 6
POST https://<tenant_subdomain>.wixanswers.com/api/v1/users/dashboard/search { "text": "John", "isAgent": true }
Response Example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
{ "items": [ { "user": { @User object }, "numberOfTickets": 3, }, { "user": { @User object }, "numberOfTickets": 25 }, ... ], "itemsCount": 108, "page": 2, "numPages": 22, "pageSize": 5 }
Manage Users
Add User
POST https://<account_subdomain>.wixanswers.com/api/v1/users
Add an unauthenticated user. See also Add Users in Bulk. See also Requesting a Specific User's Authorization Token from a Widget.
Add an unauthenticated user. See also Add Users in Bulk. See also Requesting a Specific User's Authorization Token from a Widget.
- Authorization: Requires agent authorization token and permission MANAGE_CONTACTS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: User Object
Payload Params | Description | Type | Required |
---|---|---|---|
firstName | First name | String | ✓ |
lastName | Last name | String | |
email | Email The email address must be unique for your tenant; if it is not, Wix Answers returns an error. When not provided, Wix Answers generates a fake email address. | String | |
emailVerified | Whether the email is verified Default is false. | Boolean | |
phoneNumbers | Phone numbers | List of Phone Number objects | |
invalidPhoneNumbers | List of invalid phone numbers of as strings, including country codes | List of strings | |
companiesPermissions | Map of associated companies and their permissions, as follows: * <company GUID> The default for each company is to inherit the permission from the company. | Structure | |
profileImage | URL of user's avatar | String | |
customFields | Map of user custom field values, each field entry a structure of: * <API field name> (string): The API name of the field (auto-generated; see Finding a Custom Field Name) * <Custom Field value> (format depends on the field) | Structure |
Payload Example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
POST https://<account_subdomain>.wixanswers.com/api/v1/users { "firstName": "User", "lastName": "Name", "email": "User@aaa.com", "emailVerified": false, "phoneNumbers": [ { "countryCode": "972", "number": "0541234567" } ], "customFields": { "field-1": "value", "field-22": true } }
Add Users in Bulk
POST https://<account_subdomain>.wixanswers.com/api/v1/users/bulk
Add up to 100 users at once. If any of the users fail, the API will still succeed for the remaining users. See also Add User.
Add up to 100 users at once. If any of the users fail, the API will still succeed for the remaining users. See also Add User.
- Authorization: Requires agent authorization token and permission MANAGE_CONTACTS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: List of successfully added User Objects
Importing a Large Number of Records
To import a large number of users, such as your initial user database, contact Wix Answers for assistance.
Payload Params | Description | Type | Required |
---|---|---|---|
users | The user information, a list of between 1 and 100 "Add User" structures. | Structure See Add User. | ✓ |
override | When true, the import process updates any fields in matched users. When false, no changes are made to matched users. | Boolean The default is false. | |
addNonExisting | When true, unmatched users are created. When false, no users are created. If both override and addNonExisting are false, the endpoint throws an exception. | Boolean The default is true. |
Payload Example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
POST https://<account_subdomain>.wixanswers.com/api/v1/users/bulk { "users": [ { "firstName": "User", "lastName": "Name", "email": "User@aaa.com", "emailVerified": false, "phoneNumbers": [ { "countryCode": "972", "number": "0541234567" } ], "customFields": { "field-1": "value", "field-22": true } }, // End first user { "firstName": "Another User", ... } // End second user ] }
Update (or Add) Unauthenticated User
POST https://<tenant_subdomain>.wixanswers.com/api/v1/users/addOrUpdate
Update or add an unauthenticated user. The payload is the same as the one in Add User. See Important Information about Updating Structures Using the API.
Update or add an unauthenticated user. The payload is the same as the one in Add User. See Important Information about Updating Structures Using the API.
- Authorization: Requires agent authorization token and permission MANAGE_CONTACTS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: User Object
Update a User
PUT https://<tenant_subdomain>.wixanswers.com/api/v1/users/{user GUID}
Update an authenticated user. See Important Information about Updating Structures Using the API.
Update an authenticated user. See Important Information about Updating Structures Using the API.
- Authorization: Requires agent authorization token and permission MANAGE_CONTACTS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: User Object
Payload Params | Description | Type |
---|---|---|
firstName | First name | String |
lastName | Last name | String |
phoneNumbers | Phone numbers | List of Phone Number objects |
profileImage | URL of user's avatar | String |
signature | Email signature Relevant only for agents. | String |
email | Email The email address must be unique for your tenant; if it is not, Wix Answers returns an error. | String |
Payload Example:
1 2 3 4 5 6 7 8 9 10 11 12
PUT https://<tenant_subdomain>.wixanswers.com/api/v1/users/bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa { "firstName": "User", "lastName": "Name", "phoneNumbers": [ { "countryCode": "972", "number": "0541234567" } ] }
Update an SSO User
POST https://<tenant_subdomain>.wixanswers.com/api/v1/users/{user GUID}/sso
Update an SSO user. See Important Information about Updating Structures Using the API.
Update an SSO user. See Important Information about Updating Structures Using the API.
- Authorization: Requires agent authorization token and permission MANAGE_CONTACTS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: User Object
Enable SSO Login
You must enable SSO logins to perform this action. See Setting Up Single Sign-On (SSO) for Your Users.
Payload Params | Description | Type | Required |
---|---|---|---|
externalId | External ID in the auth system | String | ✓ |
firstName | First name | String | |
lastName | Last name | String | |
phoneNumbers | Phone numbers | List of Phone Number objects | |
profileImage | URL of user's avatar | String | |
signature | Email signature Relevant only for agents. | String | |
email | Email The email address must be unique for your tenant if you want Wix Answers to create a user record (see resolvedConflict). Once the user has a non-temporary email address (see Add User), the email address cannot be changed. | String | |
resolvedConflict | Whether to replace any previous user record with the same email address. When true, a new user record is created. The old record's email address is changed to <email>#<timestamp> (the email address, followed by a hash character, followed by the Unix time string), and the old user is now considered unauthenticated. Note that this process does not work on an agent user record. When false, and there exists a record with the same email address, the API fails. By default, this is false. | Boolean |
Payload Example:
1 2 3 4 5 6 7 8 9 10 11 12 13
POST https://<tenant_subdomain>.wixanswers.com/api/v1/users/bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa/sso { "externalId": "TL23", "firstName": "User", "lastName": "Name", "phoneNumbers": [ { "countryCode": "972", "number": "0541234567" } ] }
Update a User's Custom Fields
Agent Custom Fields
An agent may have additional custom fields associated with the agent record. For more information, see Update an Agent's Custom Fields.
Update custom field values for a user record. For information about configuring the available custom fields for a user, see Custom Fields API.
- Authorization: Requires agent authorization token and permission MANAGE_CONTACTS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: User Object (extended level)
Merge
Unlike most update scenarios in Wix Answers (see Important Information about Updating Structures Using the API), when updating user custom fields you can specify whether all existing custom field values are first removed, or whether the new values sent with this API call are added to the existing values.
Payload Params | Description | Format | Required |
---|---|---|---|
customFields | A map of new field values, each mapping containing: * <custom field GUID>: The field id * <new value>: The new value in the relevant format | Structure | ✓ |
merge | Whether to add the new values but leave any existing values that are not being replaced (true), or to first remove all existing custom field values and then add the new values (false). | Boolean |
Payload Example:
1 2 3 4 5 6 7 8 9
PUT https://<tenant_subdomain>.wixanswers.com/api/v1/users/77bc8694-5ccf-436c-ab2b-543563a5f425/fields { "merge": false, "customFields": { "bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa":5, "e932c0a3-6e9b-43cf-b3a9-0ae790f6ee6a":"new value" } }
Update Your User Information
PUT https://<tenant_subdomain>.wixanswers.com/api/v1/users/me
Update your user information. See Important Information about Updating Structures Using the API.
- Authorization: Requires user authorization token for specific user
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: User Object (restricted level)
Payload Params | Description | Type |
---|---|---|
firstName | First name | String |
lastName | Last name | String |
phoneNumbers | Phone numbers | List of Phone Number objects |
profileImage | URL of user's avatar | String |
signature | Email signature Relevant only for an agent. | String |
Payload Example:
1 2 3 4 5 6 7 8 9 10 11 12
PUT https://<tenant_subdomain>.wixanswers.com/api/v1/users/me { "firstName": "User", "lastName": "Name", "phoneNumbers": [ { "countryCode": "972", "number": "0541234567" } ] }
Add One or More Companies to a User
PUT https://<tenant_subdomain>.wixanswers.com/api/v1/users/{user GUID}/companies
Set the companies, and company permissions, of this user. Note: The list that you send overrides any existing company list for this user.
- Authorization: Requires agent authorization token and permission MANAGE_CONTACTS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: User Object (restricted level)
Payload Params | Description | Type | Required |
---|---|---|---|
companiesPermissions | Map of associated companies and their permissions, as follows: * <company GUID> The default for each company is to inherit the permission from the company. | Map |
Payload Example:
1 2 3 4 5 6 7 8 9
PUT https://<tenant_subdomain>.wixanswers.com/api/v1/users/77bc8694-5ccf-436c-ab2b-543563a5f425/companies { "companiesPermissions": { "1f550b89-a12a-4169-82fd-82e4ca51f264": 2, "1f550b89-a12a-4169-82fd-82e4ca51f265": 1, "1f550b89-a12a-4169-82fd-82e4ca51f266": 0, } }
Add Companies to One or More Users
PUT https://<tenant_subdomain>.wixanswers.com/api/v1/users/companies
Set the companies, and company permissions, of one or more users. Note: The list that you send overrides any existing company list for these users.
- Authorization: Requires agent authorization token and permission MANAGE_CONTACTS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: List of User Objects (restricted level)
Payload Params | Description | Type | Required |
---|---|---|---|
userIds | List of users to which to add or change companies | List of user GUIDs | At least one user is required |
companiesPermissions | Map of associated companies and their permissions, as follows: * <company GUID> The default for each company is to inherit the permission from the company. | Map |
Payload Example:
1 2 3 4 5 6 7 8 9 10 11
PUT https://<tenant_subdomain>.wixanswers.com/api/v1/users/companies { "userIds": ["77bc8694-5ccf-436c-ab2b-543563a5f425", "bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa"], "companiesPermissions": { "1f550b89-a12a-4169-82fd-82e4ca51f264": 2, "1f550b89-a12a-4169-82fd-82e4ca51f265": 1, "1f550b89-a12a-4169-82fd-82e4ca51f266": 0, } }
Manage User Bans
For more information, see Banning a User.
Get a User's Ban Information
GET https://<tenant_subdomain>.wixanswers.com/api/v1/users/{user GUID}/ban
Get the reason that a user is banned (if any).
- Authorization: Requires agent authorization token and permission FETCH_CONTACTS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: null if the user if not banned; otherwise a return structure, see below
If the user is banned, the return structure is as follows.
Response Params | Description | Format |
---|---|---|
userId | The user that is banned | |
agentId | The agent that created the ban | |
reason | The reason for the ban | String |
creationDate | Time this record was created |
Request Example:
1
GET https://<account_subdomain>.wixanswers.com/api/v1/users/d7f4c80c-7560-4dc2-8bca-37c589727e5c/ban
Response Example:
1 2 3 4 5 6
{ "userId": "d7f4c80c-7560-4dc2-8bca-37c589727e5c", "agentId": "e932c0a3-6e9b-43cf-b3a9-90f6ee6a5b07", "reason": "Spam", "creationDate": 1568181779000 }
Ban a User
POST https://<tenant_subdomain>.wixanswers.com/api/v1/users/{user GUID}/ban
Add a user ban.
- Authorization: Requires agent authorization token and permission MANAGE_CONTACTS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: Same return structure as in Get User Ban Information
Payload Params | Description | Type |
---|---|---|
reason | The reason for the ban | String |
Payload Example:
1 2 3 4 5
POST https://<tenant_subdomain>.wixanswers.com/api/v1/users/bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa/ban { "reason": "Spam" }
Remove a User Ban
DELETE https://<tenant_subdomain>.wixanswers.com/api/v1/users/{user GUID}/ban
Remove a user ban (unban the user).
- Authorization: Requires agent authorization token and permission MANAGE_CONTACTS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: None
Request Example:
1
DELETE https://<account_subdomain>.wixanswers.com/api/v1/users/e932c0a3-6e9b-43cf-b3a9-90f6ee6a5b07/ban
Manage User Notes
Get a User's Notes
GET https://<tenant_subdomain>.wixanswers.com/api/v1/users/{user GUID}/notes
Get a user's notes.
- Authorization: Requires agent authorization token and permission FETCH_CONTACTS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: List of Note objects
Request Example:
1
GET https://<account_subdomain>.wixanswers.com/api/v1/users/e932c0a3-6e9b-43cf-b3a9-90f6ee6a5b07/notes
Add a User Note
POST https://<tenant_subdomain>.wixanswers.com/api/v1/users/{user GUID}/notes
Add a user note.
- Authorization: Requires agent authorization token and permission BASIC_TICKET_ACTIONS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: Note object (restricted level)
Payload Params | Description | Type | Required |
---|---|---|---|
content | The note HTML content. | String | ✓ |
Payload Example:
1 2 3 4 5
POST https://<tenant_subdomain>.wixanswers.com/api/v1/users/bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa/notes { "content": "<b>This is a test note</b>" }
Update a User Note
Update a user note. See Important Information about Updating Structures Using the API.
- Authorization: Requires agent authorization token
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: None
The payload is the same as adding a user note; see Add a User Note.
Delete a User Note
Delete a user note.
- Authorization: Requires agent authorization token
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: None
Request Example:
1
DELETE https://<account_subdomain>.wixanswers.com/api/v1/users/e932c0a3-6e9b-43cf-b3a9-90f6ee6a5b07/notes/e932c0a3-6e9b-43cf-b3a9-0ae790f6ee6a
Was this article helpful?