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.

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 Your Current Geographic Location

GET https://<tenant_subdomain>.wixanswers.com/api/v1/users/me/geo/country

Get the current geographic location of the user associated with the logged in JWT token. The geographic location is derived using the IP address. Note that the user must be an agent to access this endpoint.
  • Authorization: Requires agent authorization token for specific user
  • Content type: application/json; charset=utf-8.
  • Accept: application/json.
  • Response: Two-letter country code string
Request Example:
1
GET https://<account_subdomain>.wixanswers.com/api/v1/users/me/geo/country

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 (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.
  • 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.
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.
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

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

Update an SSO user. See Important Information about Updating Structures Using the API.
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 token and permission MANAGE_CONTACTS
  • Content type: application/json; charset=utf-8.
  • Accept: application/json.
  • Response: None
Add Company to Ticket and User
You can also add a company to a user while adding a company to a ticket owned by the user. See Update Company of a Ticket and Ticket User (Owner).
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"]
}

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: None
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,
  }
}

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

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