The WIX Answers REST API enables you to use code to interact with the Wix Answers back-end. You can use the API to create webhooks that interact with the Wix Answers front and back-ends, or create a new front-end app that works with the Wix Answers back-end. You can also use the API to get information about your customers and their Wix Answers history.

The API documentation assumes that you are familiar with Wix Answers features and have read the knowledge base articles about these features.

The API documentation includes articles with the following subcategories in the Developers category:

API Overview: This document
API Reference: All public Wix Answers APIs. Start with the API Reference Overview.
Data Reference: Common objects and enumerations returned by APIs, as well as required permissions and roles
Procedures: Frequently asked workflow questions, such as how to find information you might need or how to combine APIs or webhooks to perform common procedures
SDK: How and where to create code that works with the APIs and back-end. Start with the Wix Answers SDK Overview.
Webhooks: How to create webhooks that may be called from the APIs

Note: Keep a Debug Log

We highly recommend that you create a minimum 3-day log of responses from Wix Answers. This will ease your debugging process in the case of any issues.

You can test API calls using cURL or any similar software.

Wix API methods accept HTTPS requests in JSON content-type with UTF-8 character set (application/json; charset=utf-8). Parameters are case-sensitive: for example, ID is not accepted when id is expected.

Successful responses are returned by HTTPS in JSON format (application/json) with status headers that include codes in the 200-300 range. For example:

Status: 200

{
    "id": "bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa",
    "name": "Article Title",
    ...
    "creationDate": 1568180889000
}

API Endpoint

All URLs referenced in the API documentation have the following endpoint: https://<tenant_subdomain>.wixanswers.com

Authorization

Some API endpoints do not require authorization. Most endpoints require a JWT authorization token generated from an API key. The token is valid for one hour and must be sent on every request using an Authorization header:

Authorization: Bearer <token>

Token Types

A user-specific authorization token has the authorization for that user or agent. This token has an intersection of the permissions of the user and the API key, and contains the user's ID. A general authorization token (not specific to a user) has all permissions of the API key and contains the user ID for "System User".

Some endpoints require a user-specific authorization token. For these endpoints, a general authorization token does not work. For example, adding a ticket as a specific user requires a user-specific token; see Add a Ticket as Authenticated User. In addition, for some endpoints that require a user-specific authorization token, the user must have a verified email address.

For all other endpoints, you can use a general token, if the API key has the required permission, or a user-specific token, if the API key + user ID has the required permission. If you use the general token, Wix Answers records the activity as done by "System User".

In some cases, such as reading articles on a public website, no authorization token is required.

The required authorization is noted for each endpoint in this documentation.

API Keys, Roles, and Permissions

Wix Answers uses API keys, roles, and permissions to determine whether you are allowed to access an endpoint.

You can configure multiple API keys in Wix Answers, and you can enable or restrict sets of permissions for each API key.

For more information about creating API keys and selecting sets of permissions, see Obtaining an API Key to Your Wix Answers Account.
For the list of which permissions are enabled or disabled with each selection, see Roles and Permissions.

In addition to restricting permissions by API keys, you can assign roles to agents. Agents are users that are assigned any role: these are your team members who have access to the Wix Answers app. Roles are collections of permissions. Wix Answers comes with three out-of-the-box roles: Viewer, Agent, and Admin. Viewers have access to read-only Wix Answers endpoints and to the Wix Answers app. Agents can do anything Viewers can do, but they also can manage users, tickets, articles, calls, and other non-administrative areas of the app. An Admin(istrator) can do anything an Agent can do, and can also manage other agents and perform other administrative tasks. An admin can define other roles in the Wix Answers App.

Since a non-agent user does not have a role, a user-specific token generated for this kind of user has no permissions, not even the ones in the API key. A user-specific token generated for an agent has an intersection of the permissions of the agent's role and the API key. For example, if an agent has a role that includes FETCH_ARTICLES but does not include MANAGE_ARTICLES, then a token generated for this agent does not include MANAGE_ARTICLES, even if the API key does. This token cannot access any endpoints that require MANAGE_ARTICLES.

For some endpoints, no token is required. For some endpoints, any valid token is required and the endpoint does not require any specific permission. For some endpoints, a user-specific authorization token is required but the endpoint does not require any specific permission. And for some endpoints, any valid token is required but the API key and the user associated with the token (when sending a user-specific authorization token) must all have a specific permission.

To summarize, the following lists the cases in which you can access a particular endpoint:

The endpoint does not require you to send a token

The endpoint requires you to send a token
The endpoint does not require a token with a specific permission
You send a valid token

The endpoint requires you to send a user-specific token
You send a valid user-specific token

The endpoint requires you to send a token
The endpoint requires a specific permission
You send a valid token
The permission related to the endpoint, if any, is
- Included in the API key's list of permissions, AND
- Included in the role assigned to the user associated with the token, if any

In a few cases, the endpoint requires you to send a user-specific token AND the endpoint requires a specific permission. In this case, the user for the token must be an agent with a role that includes the required permission and the API key must include the required permission.

Help Center Authorization Override

You can configure your help center to require users to register before they can access any contents. In this case, all API calls require an authorization token, even if no authorization is indicated in the documentation.

Tokens with no User Specified

If you request a token without specifying the user that the token is for, the token is a general token with admin privileges, but will not work for endpoints that require a token associated with a specific user.

Authenticated Users

To be an authenticated user means that Wix Answers has authenticated the user's email and the user has a unique ID (GUID).

A user is unauthenticated when the user is created: by an agent using an outbound email, after the user submits a ticket from an unauthenticated widget, because of a migration process, or by an agent using the Update (or Add) Unauthenticated User API endpoint. A user becomes authenticated if the user submits a ticket by email, is created using single sign-on (SSO), is created using the Add User API endpoint, or is authenticated with the widget.

Chat Unauthenticated User Header

When starting a chat for an authenticated user, first request an authorization token using the user's GUID. For information about this token and about chat API endpoints, see Chats API.

Requesting an Authorization Token (Without Specifying a User)

Requesting an Authorization Token Must be Made as a Server-Side Request

You send the tenant secret in order to obtain an authorization token. This secret is extremely sensitive and must be kept private. Therefore, requests to obtain an authorization token must be made from your servers as server-side requests, NOT from a client.

The authorization token is also sensitive, since it enables its holder to act on behalf of the user that it represents. It is important to ensure that the token is kept secure (from everyone except the client/user who will use it). Therefore, Wix Answers recommends that all client requests be made to your servers, which in turn send the token as server-side requests to the Wix Answers API.

To obtain an API token without specifying a user:

In the Wix Answers app, navigate to Settings > Tools > Webhooks & API Keys (https://<tenant_subdomain>.wixanswers.com/app/settings/tools/webhooks-and-api/webhooks) and copy Key ID (Public) and Secret (Private).
Make a request to the token generator endpoint, with the parameters key and secret (both are required).

POST https://<tenant_subdomain>.wixanswers.com/api/v1/accounts/token

Content type: application/json; charset=utf-8
Accept: application/json

Payload Structure:

POST https://<tenant_subdomain>.wixanswers.com/api/v1/accounts/token

{
   "keyId":"<key_id>",
   "secret":"<secret>"
}

Request Example Using cURL:

curl -XPOST 'https://<tenant_subdomain>.wixanswers.com/api/v1/accounts/token' -d '{
 "keyId":"<key_id>",
 "secret":"<secret>"
}' 
-H 'Content-Type: application/json; charset=utf-8'
-H 'Accept: application/json'

Response Example:

{
    "token":"eyJlbmMiOiJBMTI0NNIiwiYWxnIjoiZGlyIn0..9-fRNeE8J3SspYg9.3eaSroE6kEIpLfdgmhg0fvOxMUs1YAHZC6dHacAkZOOjD1EA-1pApV863H1fxqCVoGbq2163PnE--83rFqU4RxbH33tTbfw0kE-baf1YEnbVt5MOWoQ_F59FzY.BiTX-Ao-OcaDeRuEDIuaeA"
}

Requesting a Specific User's Authorization Token

POST https://<tenant_subdomain>.wixanswers.com/api/v1/accounts/token

If you have the required permission (users with the agent or admin roles have this permission), you can get a token for a specific user. This kind of token is required where noted in the documentation. You must have the user's GUID.

Content type: application/json; charset=utf-8
Accept: application/json

Payload Structure:

POST https://<tenant_subdomain>.wixanswers.com/api/v1/accounts/token

{
   "keyId":"<key_id>",
   "secret":"<secret>",
   "userId":"<GUID>"
}

Request Example Using cURL:

curl -XPOST 'https://<tenant_subdomain>.wixanswers.com/api/v1/accounts/token' -d '{
 "keyId":"<key_id>",
 "secret":"<secret>",
 "userId":"77bc8694-5ccf-436c-ab2b-543563a5f425"
}' 
-H 'Content-Type: application/json; charset=utf-8'
-H 'Accept: application/json'

Response Example:

{ 
    "token":"eyJlbmMiOiJBMTI0NNIiwiYWxnIjoiZGlyIn0..9-fRNeE8J3SspYg9.3eaSroE6kEIpLfdgmhg0fvOxMUs1YAHZC6dHacAkZOOjD1EA-1pApV863H1fxqCVoGbq2163PnE--83rFqU4RxbH33tTbfw0kE-baf1YEnbVt5MOWoQ_F59FzY.BiTX-Ao-OcaDeRuEDIuaeA"
}

Requesting a Specific SSO User Authorization Token

POST https://<tenant_subdomain>.wixanswers.com/api/v1/accounts/token/sso

For tenants that use single sign-on (SSO), then if you have the required permission (users with the agent or admin roles have this permission), you can get a token for a specific SSO user using their SSO ID. You must have the user's external ID, and you must also send the user's email address.

If the user is registered as authenticated in Wix Answers, and the user's email address has changed in the external system since the user was registered, Wix Answers tries to update the user's email address, but not if the user is an agent. If the user is not registered as authenticated in Wix Answers, Wix Answers registers the user as authenticated before returning the token.

Content type: application/json; charset=utf-8
Accept: application/json

Payload Structure:

POST https://<tenant_subdomain>.wixanswers.com/api/v1/accounts/token/sso

{
   "keyId":"<key_id>",
   "secret":"<secret>",
   "params": {
     "id":"<external_SSO_ID>",
// Send the following parameters (optional, unless noted) if you are adding the
// user to Wix Answers. They are added to the user's record in Wix Answers.
     "email":"<email address>",     // String. Mandatory, see above note.
     "firstName":"<first name>",    // String. If not provided, the
                // username of the email address
                // is used.
     "lastName":"<last name>",     // String
     "profileImage":"<URL of profile image>", // String
     "emailVerified":"<true|false">    // Boolean
   }
}

Request Example Using cURL:

curl -XPOST 'POST https://<tenant_subdomain>.wixanswers.com/api/v1/accounts/token/sso' -d '{
 "keyId":"<key_id>",
 "secret":"<secret>",
 "params": {
   "id":"user77",
   "email":"user77@yourdomain.com"
 }
}' 
-H 'Content-Type: application/json; charset=utf-8'
-H 'Accept: application/json'

Response Example:

{ 
    "token":"eyJlbmMiOiJBMTI0NNIiwiYWxnIjoiZGlyIn0..9-fRNeE8J3SspYg9.3eaSroE6kEIpLfdgmhg0fvOxMUs1YAHZC6dHacAkZOOjD1EA-1pApV863H1fxqCVoGbq2163PnE--83rFqU4RxbH33tTbfw0kE-baf1YEnbVt5MOWoQ_F59FzY.BiTX-Ao-OcaDeRuEDIuaeA"
}

POST https://<tenant_subdomain>.wixanswers.com/api/v1/widgets/{widget GUID}/auth

If you have the required permission (users with the agent or admin roles have this permission), you can get a token for a specific user from a widget using the user's email address. If the user is not registered as authenticated in Wix Answers, Wix Answers registers the user as authenticated before returning the token.

This is a shorter process than adding the user, receiving the user's GUID, and then requesting a token using the GUID.

Content type: application/json; charset=utf-8
Accept: application/json

Payload Structure:

POST https://<tenant_subdomain>.wixanswers.com/api/v1/widgets/{widget GUID}/auth

{
   "email":"<email_address>",
   "keyId":"<key_id>",
   "secret":"<secret>",
   "externalId":"<external_SSO_ID>",// String. If provided, and the tenant
                                    // uses SSO, then this value is used
                                    // to identify the user, instead of
                                    // the email address.
    
// If Wix Answers registers this user as an authenticated user,
// it will add the following optional parameters to the user record.
// If the tenant uses SSO, it will also add the email address (above).
// If the user is already registered, these parameters are ignored.
    
   "emailVerified":"<true|false">,  // Boolean
   "firstName":"<first_name>",      // If not provided, the username
                                    // of the email address is used.
   "lastName":"<last_name>"
}

Request Example Using cURL:

curl -XPOST 'POST https://<tenant_subdomain>.wixanswers.com/api/v1/widgets/77bc8694-5ccf-436c-ab2b-543563a5f425/auth' -d '{
 "keyId":"<key_id>",
 "secret":"<secret>",
 "email":"user@yourdomain.com"
}' 
-H 'Content-Type: application/json; charset=utf-8'
-H 'Accept: application/json'

Response Example:

{ 
    "token":"eyJlbmMiOiJBMTI0NNIiwiYWxnIjoiZGlyIn0..9-fRNeE8J3SspYg9.3eaSroE6kEIpLfdgmhg0fvOxMUs1YAHZC6dHacAkZOOjD1EA-1pApV863H1fxqCVoGbq2163PnE--83rFqU4RxbH33tTbfw0kE-baf1YEnbVt5MOWoQ_F59FzY.BiTX-Ao-OcaDeRuEDIuaeA"
}

Important Information about Updating Structures Using the API

Fields in a PUT request entirely replace the fields in the Wix Answers back-end. Unless noted, you cannot append information to an existing field.

To modify the existing contents of a field:

Get the structure using the relevant GET request.
Extract the relevant field.
Modify the field as required.
PUT the modified field back to Wix Answers.

Common Elements in API Payloads / Objects

The following formats or values repeatedly appear in the requests you make to, or in the structures returned by, Wix Answers.

Note About Undocumented Parameters

Most return structures include additional parameters not documented in this guide. These parameters are irrelevant and can be safely ignored.

Global IDs (GUID)

Many records, such as users, tickets, labels, and so forth, are uniquely identified by a global ID, also known as a GUID. A GUID looks something like e932c0a3-6e9b-43cf-b3a9-90f6ee6a5b07.

Unix Time Strings

Unix time strings are integers indicating the number of milliseconds since Jan 1, 1970 00:00:00. For example, 1605020237000. Unix time strings are commonly used to indicate the creation or last modified time of a record.

Date Strings

Date strings, such as those used in request payloads, are in the format yyyy-MM-dd'T'HH:mm:ss. For example, 2012-07-09T19:22:09.

Languages / Locales

Click here to see the list of supported languages.

Import ID

During the Wix Answers on-boarding process, Wix Answers can help you load your initial data by importing users, companies, articles, categories, tickets, and replies. These items are tagged during the import process with an import ID (importId).

You can use your own code (such as in a webhook) to filter these items based on their import ID.

Links to Wix Answers Entities

In some cases (where noted), you can send text containing HTML links to Wix Answers entities, using the "a href" HTML tag. Examples include:

Knowledge Base Article: kb/en/article/<article name>
Ticket: /app/helpdesk/ticket/<ticket GUID>

To find the URL for any entity, copy the URL in the address bar of your web browser while viewing that entity (removing any unnecessary parameters, as required).

API Request Rate Limit

The Wix Answers APIs have a rate limit. We reserve the right to adjust the rate limit for given endpoints so we can provide a high quality of service for all clients. If you need to make more requests than the limit, please contact us and we will try to accommodate your request.

HTTP Response Statuses

All endpoints return an HTTP response status. It is useful to check this status, especially for endpoints that do not return a payload.

API Usage Legal Notice

Your use and access to the API are expressly conditioned on your compliance with the policies, restrictions, and other provisions related to the API set forth in our Terms of Use and our Privacy Policy. If we believe that you have or attempted to violate any term, condition, or the spirit of these policies or agreements, your right to access and use the API may be temporarily or permanently revoked.

API Endpoint

Authorization

Token Types

API Keys, Roles, and Permissions

Authenticated Users

Chat Unauthenticated User Header

Requesting an Authorization Token (Without Specifying a User)

Requesting a Specific User's Authorization Token

Requesting a Specific SSO User Authorization Token

Requesting a Specific User's Authorization Token from a Widget

Important Information about Updating Structures Using the API

Common Elements in API Payloads / Objects

Global IDs (GUID)

Unix Time Strings

Date Strings

Languages / Locales

Import ID

Links to Wix Answers Entities

API Request Rate Limit

HTTP Response Statuses

API Usage Legal Notice