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 Schema

APIs for end user schema.

Allowed data types:

  • boolean: Boolean values e.g. "true", "false"
  • double: Any numeric value e.g. 10 , 20.78
  • string: Any string value e.g. "employee_role"
  • timestamp: Timestamp provided as an ISO-8601 compliant string e.g. "2001-07-04T12:08:56.235-0700"
  • encrypted_string: Any string value which is required to be stored in encrypted format for security purposes e.g. "[email protected]"

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}

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
}

Summary Reports

APIs for Summary Reports

Get report for engagement with Whatfix

Returns a set of Engagement by end-users.

path Parameters
accountId
required
string

account ID

query Parameters
endDate
string

endDate

excludeDomains
Array of strings

excludeDomains

includeDomains
Array of strings

includeDomains

startDate
string

startDate

Responses

200

OK

get /api/v1/{accountId}/reports/summary/engagements
https://whatfix.com/api/v1/{accountId}/reports/summary/engagements

Get report for most popular flows

Returns the number of times each flow is viewed over a defined time.

path Parameters
accountId
required
string

account ID

query Parameters
endDate
string

endDate

excludeDomains
Array of strings

excludeDomains

includeDomains
Array of strings

includeDomains

startDate
string

startDate

Responses

200

OK

get /api/v1/{accountId}/reports/summary/mostPopularFlows
https://whatfix.com/api/v1/{accountId}/reports/summary/mostPopularFlows

Get report for summary of usage with Whatfix

Returns the number of queries served Self Help, number of times a Popup was shown to users, number of users initiated a task from Task List, number of times a flow was played, number of times a Smart Tip was shown to users, and number of times a beacon was shown to users.

path Parameters
accountId
required
string

account ID

query Parameters
endDate
string

endDate

excludeDomains
Array of strings

excludeDomains

includeDomains
Array of strings

includeDomains

startDate
string

startDate

Responses

200

OK

get /api/v1/{accountId}/reports/summary/usage
https://whatfix.com/api/v1/{accountId}/reports/summary/usage

Self Help Reports

APIs for Self Help Reports

Get report for effectiveness of content played From Self Help

Returns the list of Self Help content, the type of content and the number of views for the selected period of time.

path Parameters
accountId
required
string

account ID

query Parameters
endDate
string

endDate

excludeDomains
Array of strings

excludeDomains

includeDomains
Array of strings

includeDomains

startDate
string

startDate

Responses

200

OK

get /api/v1/{accountId}/reports/selfHelp/effectivenessOfContent
https://whatfix.com/api/v1/{accountId}/reports/selfHelp/effectivenessOfContent

Get report for queries served by day

Returns the trend over each day as users search for content and the maximum number of queries served for that day in Self Help search.

path Parameters
accountId
required
string

account ID

query Parameters
endDate
string

endDate

excludeDomains
Array of strings

excludeDomains

includeDomains
Array of strings

includeDomains

startDate
string

startDate

Responses

200

OK

get /api/v1/{accountId}/reports/selfHelp/queriesServedByDay
https://whatfix.com/api/v1/{accountId}/reports/selfHelp/queriesServedByDay

Get report for Self Help search success

Returns the total number of queries that returned results.

path Parameters
accountId
required
string

account ID

query Parameters
endDate
string

endDate

excludeDomains
Array of strings

excludeDomains

includeDomains
Array of strings

includeDomains

startDate
string

startDate

Responses

200

OK

get /api/v1/{accountId}/reports/selfHelp/searchSuccess
https://whatfix.com/api/v1/{accountId}/reports/selfHelp/searchSuccess

Get report for unsuccessful search terms

Returns the terms that didn't get any search results.

path Parameters
accountId
required
string

account ID

query Parameters
endDate
string

endDate

excludeDomains
Array of strings

excludeDomains

includeDomains
Array of strings

includeDomains

startDate
string

startDate

Responses

200

OK

get /api/v1/{accountId}/reports/selfHelp/unsuccessfulSearchTerms