Whatfix API Reference Beta (1.0.0)

Download OpenAPI specification:Download

This reference helps you implement the RESTful Whatfix API v1. This API uses a JSON format for output and is capable of handling CORS (Cross-Origin Resource Sharing) requests. The API is stateless – all requests are validated against an API token. The API token can be obtained manually from the Whatfix app.

Authentication

While some endpoints do not require authentication, most will require you to be authenticated. To get authenticated you will need to create an user API token from the Whatfix dashboard and pass as header x-whatfix-integration-key. To know more, see Generating the API Integration Key. Pass the email address of the user as the x-whatfix-user header.

    curl -X GET 'https://whatfix.com/api/v1/c5eerfd0-db6f-11e9-a037-d43b0489acab/content'
       -H 'x-whatfix-integration-key: 9255925e-3e26-4e31-ba77-b680dbf3ba4e'
       -H 'x-whatfix-user: [email protected]'
       -H 'Content-Type: application/json'

This is how POST requests look like:

    curl -X POST 'https://whatfix.com/api/v1/c5eerfd0-db6f-11e9-a037-d43b0489acab/content'
       -H 'Content-Type: application/json'
       -H 'x-whatfix-integration-key: 9255925e-3e26-4e31-ba77-b680dbf3ba4e'
       -H 'x-whatfix-user: [email protected]'
       -d '[{ "title": "Wikipedia Home Page", "url": "https://www.wikipedia.org/", "type": "link" }]'

Status Codes

The following status codes are possible in Whatfix API Responses. In general

  • Codes in the 2xx range indicate success
  • Codes in the 4xx range indicate request error
  • Codes in the 5xx range indicate server-side error

200 - OK: Returned for GET and PUT when the request is processed on the server and a payload is returned.

201 - Created: Returned for POST and PUT requests when a new object is created

204 - No Content: Returned for DELETE requests when resource is deleted.

207 - Multistatus: Returned for POST/PUT/DELETE requests on partial success. Detailed information of success and failure objects are provided in the response.

400 - Bad Request: Returned for any request if the API format is incorrect or if any query parameters do not comply with the requested resource.

401 - Unauthorized: Returned for any request if the Whatfix integration key is not valid.

403 - Forbidden: Returned for any request if the Whatfix integration key does not have permission for the requested resource. For example, requesting data for an account that cannot be accessed using the integration key.

404 – Not Found: Returned for GET and DELETE requests when no content is found for the requested resource ID.

429 - Too Many Requests: Returned if the permitted rate limit for the account is exceeded.

500, 502, 503, 504 - Server Errors: Returned for any requests if there are server-side errors. Request may succeed on retry.

Pagination

Pagination is performed by the use of 2 filters: cursor and limit

  • cursor is a pointer to a specific row of data.

  • limit specifies the maximum data to return in the result. The maximum value for the limit is 10,000.

Content

APIs for content

Get all content (paginated)

path Parameters
accountId
required
string

account ID

query Parameters
cursor
string

cursor

limit
integer <int32>
Default: 10

limit

Responses

200

OK

get /api/v1/{accountId}/content
https://whatfix.com/api/v1/{accountId}/content

Update content

path Parameters
accountId
required
string

account ID

Request Body schema: application/json

array of content

Array
description
string

Description of the content. It will not be present for content where description is not allowed such as videos.

id
string

ID of the content. Only needed for the update calls.

source
string

Source of the link content. It can be ''default'' or ''knowledgebase''.

tags
Array of strings

Tags IDs associated with the content.

title
string

Title of the content.

type
string

Type of the content. Example ''flow'' or ''link''.

url
string

Responses

200

OK

put /api/v1/{accountId}/content
https://whatfix.com/api/v1/{accountId}/content

Request samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Create a static content namely links, videos and text by ID

path Parameters
accountId
required
string

account ID

Request Body schema: application/json

array of content

Array
description
string

Description of the content. It will not be present for content where description is not allowed such as videos.

id
string

ID of the content. Only needed for the update calls.

source
string

Source of the link content. It can be ''default'' or ''knowledgebase''.

tags
Array of strings

Tags IDs associated with the content.

title
string

Title of the content.

type
string

Type of the content. Example ''flow'' or ''link''.

url
string

Responses

201

Created

post /api/v1/{accountId}/content
https://whatfix.com/api/v1/{accountId}/content

Request samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Delete content by IDs

path Parameters
accountId
required
string

account ID

contentIDArray
required
string
Example: 123%2C456%2C789

Comma-separated list of IDs of content

Responses

204

Deleted

207

Multi-Status

delete /api/v1/{accountId}/content/{contentIDArray}
https://whatfix.com/api/v1/{accountId}/content/{contentIDArray}

Get content by ID

path Parameters
accountId
required
string

account ID

id
required
string

ID of content

Responses

200

OK

get /api/v1/{accountId}/content/{id}
https://whatfix.com/api/v1/{accountId}/content/{id}

End User

End Users resource API returns the list of end users of the account.

An end user is anyone who engages with Whatfix content on the parent application. The user is identified via one of the following methods:

  • A unique id passed by the application

  • A unique id detected by Whatfix on known applications such as Salesforce

  • A unique cookie set on the user’s browser

The method of user identification must be set in the account. The same ID must be used while specifying the user Id in the API requests. If the detection method is not set, it defaults to the unique cookie method.

Get all end users (paginated)

path Parameters
accountId
required
string

accountId

query Parameters
cursor
string

cursor

limit
integer <int32>
Default: 10

limit

Responses

200

OK

get /api/v1/{accountId}/endUsers
https://whatfix.com/api/v1/{accountId}/endUsers

Update or add end users’ details

path Parameters
accountId
required
string

account ID

Request Body schema: application/json

array of end user

Array
creationTime
integer <int64>

Timestamp of creation of the record.

custom
object

Custom fields defined in the user schema.

id
string

ID of the user.

lastUpdateTime
integer <int64>

Timestamp of last updation of the record.

Responses

200

OK

put /api/v1/{accountId}/endUsers
https://whatfix.com/api/v1/{accountId}/endUsers

Request samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Deletes one or more end users

path Parameters
accountId
required
string

account ID

ids
required
string
Example: 123%2C456%2C789

comma-separated list of IDs

Responses

204

Deleted

207

Multi-Status

delete /api/v1/{accountId}/endUsers/{ids}
https://whatfix.com/api/v1/{accountId}/endUsers/{ids}

Get end user by ID

path Parameters
accountId
required
string

account ID

id
required
string

id

Responses

200

OK

get /api/v1/{accountId}/endUsers/{id}
https://whatfix.com/api/v1/{accountId}/endUsers/{id}

Update or add an end user

path Parameters
accountId
required
string

accountId

id
required
string

id

Request Body schema: application/json

customObjects

Responses

200

OK

put /api/v1/{accountId}/endUsers/{id}
https://whatfix.com/api/v1/{accountId}/endUsers/{id}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{ }

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "statusCode": 0
}

End User Schema

APIs for end user schema

Get end user schema

Returns schema of the end users resource for the account. The schema contains both Whatfix-provided default fields as well custom fields defined by the Account user.

path Parameters
accountId
required
string

account ID

fieldName
required
string

fieldName

Responses

200

OK

get /api/v1/{accountId}/endUserSchema
https://whatfix.com/api/v1/{accountId}/endUserSchema

Update/Add end user schema

Updates or adds one or more custom fields in the end user schema. Field names are unique and are used to identify the fields that are required to be updated. A maximum of 50 custom fields can be added to the user schema for each account.

path Parameters
accountId
required
string

account ID

Request Body schema: application/json

array of end user schema

Array
description
string

Explanation of the field’s purpose.

name
string

Name of the field.

type
string

Data type of the field.

Responses

200

OK

put /api/v1/{accountId}/endUserSchema
https://whatfix.com/api/v1/{accountId}/endUserSchema

Request samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get end user schema by field name

Get an end user schema by field name.

path Parameters
accountId
required
string

account ID

fieldName
required
string

fieldName

Responses

200

OK

get /api/v1/{accountId}/endUserSchema/{fieldName}
https://whatfix.com/api/v1/{accountId}/endUserSchema/{fieldName}

Delete custom fields

Deletes one or more custom fields from the end user schema in the account. Whatfix-provided default fields cannot be deleted.

path Parameters
accountId
required
string

account ID

fieldsToDelete
required
string

comma-separated list of fieldNames

Responses

204

Deleted

207

Multi-Status

delete /api/v1/{accountId}/endUserSchema/{fieldsToDelete}
https://whatfix.com/api/v1/{accountId}/endUserSchema/{fieldsToDelete}