Users APIs

User APIs enable you to fetch or create Wix Answers users.

All API methods that create or modify a user trigger a call to the Customer Created of 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.

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.

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.

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.

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.

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)
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 (yyyy-MM-dd)
  * toDate (yyyy-MM-dd)
  * from (long)
  * to (long)
  * values (list)
  * text (string)
  * searchType (integer):
    * Exact (1)
    * Contains (2)
    * No contains (3)
  * bool (Boolean)
Structure; see User object
fromCreationDate
Filter by users created on or after this date
yyyy-MM-dd
toCreationDate
Filter by users created on or before this date
yyyy-MM-dd
fromLastUpdateDate
Filter by users last updated on or after this date
yyyy-MM-dd
toLastUpdateDate
Filter by users last updated on or before this date
yyyy-MM-dd
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/search/dashboard

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 level
  • 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/search/dashboard

{
    "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.

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

invalidPhoneNumbers
List of invalid phone numbers of as strings, including country codes
List of strings

companyId
The company to associate with this user

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.

  • Authorization: Requires admin  authorization level
  • 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

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 a User

PUT https://<tenant_subdomain>.wixanswers.com/api/v1/users/{user GUID}

Payload Params
Description
Type
firstName 
First name
String
lastName
Last name
String
phoneNumbers
Phone numbers
companyId
The company to associate with this user
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
13
PUT https://<tenant_subdomain>.wixanswers.com/api/v1/users/bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa

{
  "firstName": "User",
  "lastName": "Name",
  "email": "user@user.com",
  "phoneNumbers": [
    {
      "countryCode": "972",
      "number": "0541234567"
    }
  ]
}

Update an SSO User

POST https://<tenant_subdomain>.wixanswers.com/api/v1/users/{user GUID}/sso

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

companyId
The company to associate with this user

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).
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.
PUT https://<tenant_subdomain>.wixanswers.com/api/v1/users/{user GUID}/fields

Update custom field values for a user record. For information about configuring the available custom fields for a user, see Custom Fields API.

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:
* <generated field name>: The field name generated by Wix Answers
* <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": {
      "digitField":5,
      "stringField":"new value"
    }
}

Update Your User Information

PUT https://<tenant_subdomain>.wixanswers.com/api/v1/users/me

Payload Params
Description
Type
firstName 
First name
String
lastName
Last name
String
phoneNumbers
Phone numbers
companyId
The company to associate with this user
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 Company to One or More Users

POST https://<tenant_subdomain>.wixanswers.com/api/v1/users/company

Associate a list of users to a company.

  • Authorization: Requires agent  authorization level
  • Content type: application/json; charset=utf-8.
  • Accept: application/json.
  • Response: None
Payload Params
Description
Type
Required
companyId
The company ID

If not set, the company is removed from the list of users.

userIds
A list of user IDs
List of GUIDs (between 1 and 50)
At least one user ID is required
Payload Example:
1
2
3
4
5
6
POST https://<tenant_subdomain>.wixanswers.com/api/v1/users/company

{ 
    "companyId": "d367738e-368e-41fe-9289-1a5cbbc3c239",
    "userIds": ["e932c0a3-6e9b-43cf-b3a9-90f6ee6a5b07","d7f4c80c-7560-4dc2-8bca-37c589727e5c"]
}

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 level
  • 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
Unix time string
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 level
  • 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.

  • Authorization: Requires agent  authorization level
  • 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.

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.

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

PUT https://<tenant_subdomain>.wixanswers.com/api/v1/users/{user GUID}/note/{note GUID}

  • Authorization: Requires agent  authorization level
  • 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 https://<tenant_subdomain>.wixanswers.com/api/v1/users/{user GUID}/note/{note GUID}

Delete a user note.

  • Authorization: Requires agent  authorization level
  • 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