The CAI API exposes the core end-user and admin functionality of CAI to make it easy for you to build client applications or integrations with your own systems
1. Set up an API User Account
The API user account will need to be created in the “Convirza's Actionable Insights” (CAI) APP under Groups and Users. The username is the Email field. We recommend setting a strong Password. Both fields become the credentials for the API. This user will need to have a role of ADMIN. Only Admins will have access to use the API. The API user will have access to data from the Group the User was created in and below.
2. Generate an API authentication token
Enter the following details to get the API authentication token that should be used to access the API methods:
- Request: POST
- API method: /oauth/token
- Site Base URL: https://apicfa.convirza.com
- Client Secret: f558ba166258089b2ef322c340554c
- Username: Your API username.
- Password: Your API password
When you POST to the API method it will generate an access token as part of the response. Please use the access_token in header as part of ALL subsequent CAI API method calls.
Sample: POST Request body (JSON) and Response output (JSON) for authenticating and retrieving the access token:
3. Make an API request
Enter the following details to get a list of calls. (Refer to https://apicfa.convirza.com/apidoc for an available list of API methods):
- Request: GET
- API method: /call/list
- Site Base URL: https://apicfa.convirza.com/v2
- Headers
- Content-Type: application/JSON
- Authorization: bearer
4. Testing a Request
Use a third party client, such as Postman or Advanced REST Client to test the CAI API.
Instructions on using API methods:
How to do GET Requests:
All GET requests can include 3 additional parameters that are attached to the request in the query string. This entire value string should be URL encoded.
Example:
/v2/getmethod?limit=100&offset=50&filter=start_date%3E%3D2015-05-17%2022%3A30%3A00-0700%2Cstart_date%3C%3DNOW()
Note that the following parameters are not required, but available to most of the method endpoints.
limit=
This is used to set the limit on the number of records returned (default: 100)
offset=
The number of records to skip before starting the return set (default: 0)
filter=
Definition of rules enforced on the record set to reduce the return set
The value for filter is a set of rules, each of which is comma separated.
Each rule must contain three parts to it,
- The first part consists of the column name.
- The second part is the comparator, which can be one of the following:
= Equivalent match value to column
>= Greater than or equal to (only use on rules that have a value that is numeric or date)
<= Less than or equal to (only use on rules that have a value that is numeric or date)
!= Does not equal value to column - The third part is the value. A value that matches the column type returned is best to use. Using a value that is a string in conjunction with <= or >= can result in unpredictable results, but usually scores strings based on alphabetic position of each character.
Note that there are also a few special values that can be used for the value, which are:
- IS NULL – Tests to see if the column has a null or lack of a value set
- IS NOT NULL – Tests to insure that the column has a value set
- FALSE – Checks if the column value is false (only for boolean type)
- TRUE – Checks if the column value is true (only for boolean type)
- NOW() – Uses the current date and/or time for the value
All of the parameters are included in the query string, or in other words on the right side of the question mark, with each parameter separated with an ampersand in standard browser compliant formatting. The entire value string for the ‘filter’ parameter must be URL encoded or will not be valid and will fail.