This section provides an overview of how data flows to and from the Pay as you Track API. As the API is JSON based, make sure you’re familiar with http and JSON.

Typically, a client will authenticate, make one or more calls to the API and then logoff. Logging off is not strictly necessary (but is recommended) as the ticket that is allocated during the authentication process will timeout if not used.

All calls to the Pay as you Track API should be made to:

https://portal.payasyoutrack.com/api2.ashx

The ‘2’ refers to the version number of the API. This is currently 2. Your domain name may be different if, for example, you are a white label client. If you are not sure please get in touch.

Request

Calls should be made using either a http ‘GET’ or ‘POST’ request. ‘GET’ requests are permitted mainly for testing purposes. These can sometimes fail if the query string is too long so where possible in production code, make ‘POST’ requests.

After a successful authentication attempt the Pay as you Track server responds with an authentication token (or ticket). This ticket must be sent with all subsequent API requests. The ticket can be passed via a ‘ticket’ query parameter or as an ‘XAuthorization’ HTTP Header.

Note that all API calls are logged and timed. There are limits set on call frequency to prevent over enthusiastic call rates. If you have any questions please email us and we’ll let you know what your limits are.

Query Parameters

The query parameters should as a minimum include the authentication ticket (ticket*) and an operation (op) and sub operation (subop). The remaining parameters are those required by the operation and sub operation.

Query Parameters (optional)

It can also contain the following optional parameters.

Parameter	Value	Required
ticket	{ticket}	No – if not set as query parameter, must be provided as XAuthorization Http Header
dtm	{date time format}	No – by default format is new Date(XXXXXXX). Set to ‘o’ for ISO format.
callback	{jsonp callback function}	No
reqId	{a client set unique id for the call, returned in response}	No

Response

After successful authentication data is returned from API in a format that is based on (but does not fully follow) the Google Visualization JSON format. This is described here:

https://developers.google.com/chart/interactive/docs/dev/implementing_data_source#json-response-format

Successful JSON responses (with HTTP Status Code 200) take the following form. The payload (the field ‘dataset’ here) is not shown as this will be specific to the particular API call. Status will be set to “ok”. Note that a field “dataset” is returned, not a ‘table’ field as per the Google Visualization JSON format. The “dataset” field is in fact a simple object containing a JSON array of tables in Google Visualization format. There are more detail, explanation and examples here.

{
"version":"0.6"
,"reqId":"0"
,"status":"ok"
,"sig":"-42971447"
,"dataset":{...

Failed JSON responses (with HTTP Status Code 200) follow a similar pattern. Status will be set to “error”. Status will not be set to anything other than “ok” or “error”.

{
"version":"0.6"
,"status":"error"
,"errors":[{"reason":"user_not_authenticated","message":"Access to the System denied"}]
}

In the above case the “errors” array will give the reason for error. Typically this is likely to be one of.

• user_not_authenticated
• access_denied
• unsupported_query_operation
• invalid_query
• invalid_request
• internal_error
• no_credit_left

Next: Authenticating

---