API Requests & Responses
The APIs are defined on a custom BASE_DOMAIN. All paths mentioned across all API Endpoint categories will be available on this domain. Eg: If BASE_DOMAIN is demo.api.jivox.com, then create accounts are available on POST https://demo.api.jivox.com/v2/accounts.
Jivox programmable personal API is built on Open API specification and is a REST based API request set, with GET, PUT, POST, DELETE methods supported over an HTTPS connection. The description of these methods are listed below:
| Method Type | Description |
|---|---|
| GET | To fetch data from the system |
| PUT | To update existing data in the system |
| POST | To insert new data into the system |
| DELETE | To delete existing data in the system |
The request and responses are made available in JSON formats. In order to make the API request, we get the requests authenticated through from the API backend. This is done by using an API key that’s added as part of the API request header before the request is sent.
API Key as Header
The API key has be added under the header jvx_apikey
The security on the API key behaves as a password authentication, and the API key the user receives is like a password. For every API request made, the API key has to be attached to the request as a header. This API key helps to find out the accounts the user has access to and the ads and campaigns used.
The header name to use is jvx_apikey
For example:
curl --location --request GET 'https://BASE_DOMAIN/v2/accounts' \ --header 'jvx_apikey: APIKEY_HERE'Some of the GET methods support the following optional parameters that can be input as part of the API request URL:
| Parameter Name | Description |
|---|---|
| limit | Max number of items to return as part of the API response body. Default value is 100. |
| offset | Starting offset of pagination of data. Default value is 0. |
| fields | List of fields, comma separated, that the API requester wants to be returned. By default, all the values are returned. |
| filters | The value for the filters parameter will be a comma separated string. Each part has to be of the format Field(Operator)Value (the parenthesis are optional but help in parsing the input). Field will be the same as the fields query parameter. Valid operators are =,<>,<,>,<=,>=,like,in. < and > are only supported for int field types. By default, all filters are combined with AND operator. So, API only returns data that matches all the filters. Adding |
A sample request and response to showcase the usage of filters is added below:
Sample Request
xxxxxxxxxxGETdemo.stub.api.jivox.com/v2/accounts/1234/campaigns?next=dQt51J&filters=defaultURL=https://www.jivox.com,lastUpdate=2017-11-10 06:41:51-- This is the URL for filter usage.-- The part after `filters=` has to be url encodedAlternatively, filters can also be used like this:
xxxxxxxxxxdemo.stub.api.jivox.com/v2/accounts/1234/campaigns?next=dQt51J&filters=defaultURL=https://www.jivox.com&filters=lastUpdate=2017-11-10 06:41:51-- For this also, the part after `filters=` has to be url encoded.Sample Response
xxxxxxxxxx{ "campaigns": [ { "lastUpdate": "2017-11-10 06:41:51", "defaultURL": "https://www.jivox.com", "campaignName": "Klx Demo", "creationDate": "2017-10-20 14:29:57", "campaignId": "113087" }, . . . ], "previous": "", "next": ""}Parameter Types
The API request parameters are of the following types:
| Parameter | Description |
|---|---|
| Header Parameters | Parameters that are included in the API request header. Example: An API key that’s used for authorization of the API request) |
| Path Parameters | Parameters that appear within the path of the request endpoint but before the query string, before the ‘?’ symbol on the path. |
| Query Parameters | Parameters that appear in the query string of the endpoint, after the ‘?’ symbol on the path. |
| Request Body Parameters | Parameters that are submit as part of the API request body (usually for POST and PUT requests). |
Data Types
The API request parameters are of the following data types:
| Data Type | Description |
|---|---|
| string | A sequence of letters and/or numbers. |
| integer | A whole number |
| array | A set of values of similar type (eg :an integer array will be a set of integer values) |
HTTP Status Codes
The following HTTP Status Codes are returned by the system under various scenarios:
| HTTP Status Code | Description |
|---|---|
| 200 | Request was processed successfully. |
| 400 | Request schema is incorrect. |
| 401 | Unauthorized request. Credentials or session is invalid |
| 403 | Forbidden. Access permissions are not there for the client calling the method |
| 404 | API method not found. |
| 429 | Too many API method requests made |
| 500 | Internal Error |
| 503 | Service Unavailable |