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.

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.

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.

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.

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.

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	Phone Number object
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	Date string
toCreationDate	Filter by users created on or before this date	Date string
fromLastUpdateDate	Filter by users last updated on or after this date	Date string
toLastUpdateDate	Filter by users last updated on or before this date	Date string
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.

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> * Company customer permission 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.

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.

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.

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.

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.

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.

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> * Company customer permission 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> * Company customer permission 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	GUID
agentId	The agent that created the ban	GUID
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 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

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

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

Was this article helpful?

Yes

Working with Tickets

Banning a User

Block spammers and abusive users from using your support channels by banning them. When you ban a user they can no longer send or receive tickets via your support channels. You can unban them later if needed. T

1 min read

Wix Answers Help Center

Users APIs

Get User Information

Get Your User Information

Get a User's Information by User ID

Get a User's Information by Email Address

Get an SSO User's Information by External ID

Search for Users (Agent)

Get User Ticket Counts

Manage Users

Add User

Add Users in Bulk

Update (or Add) Unauthenticated User

Update a User

Update an SSO User

Update a User's Custom Fields

Update Your User Information

Add One or More Companies to a User

Add Companies to One or More Users

Manage User Bans

Get a User's Ban Information

Ban a User

Remove a User Ban

Manage User Notes

Get a User's Notes

Add a User Note

Update a User Note

Delete a User Note

Related Articles

Working with Tickets

Banning a User

Block spammers and abusive users from using your support channels by banning them. When you ban a user they can no longer send or receive tickets via your support channels. You can unban them later if needed. T