Per REST API v1

Overview

The following background information applies to calling any of the v1 endpoints.

Current version

All requests to https://api.useper.com currently receive the v1 API, as documented here.

Schema

All API access is over HTTPS, and accessed from https://api.useper.com. All data is sent and received as JSON.

Blank fields are included as null instead of being omitted.

All timestamps return in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

For more information about time zones in timestamps, see the Timezones section.

Authentication

All Per API requests require authentication in the form of a token passed via the Authorization header:

curl -H "Authorization: Bearer TOKEN" https://api.useper.com

Tokens can be created or retrieved from the tokens UI of the website. Note that every token is valid for one or more “scopes”, which restrict which APIs for which it is valid. which limit the APIs to which they have access. The “activity” scope is needed for the Activity API, and the “reporting” scope is needed for the Reporting API.

Invalid credentials

Authenticating with invalid credentials, or without the needed scope, will return 401 Unauthorized:

curl -i "Authorization: Bearer INVALID-TOKEN" https://api.useper.com/activity
HTTP/1.1 401 Unauthorized

{
 "ok": false,
 "message": "invalid_auth_token"
}

Parameters

Many API methods take optional parameters. For GET requests, these parameters are specified as an HTTP query string parameter:

curl -i "https://api.useper.com/activity.set?billingId=BILLING_ID&userId=USER_ID"

In this example, the ‘BILLING_ID’ and ‘USER_ID’ values are provided for the :billingId and :userId parameters in the query string.

Responses and errors

All API responses are returned as Content-Type: application/json. At present, an HTTP status code of 200 (OK) is returned for all API access, even on failure. The response JSON includes an ok property which indicates whether the request was actually successful or not:

{
  "ok": true,
  "result": {
    // . . .
  }
}

Errors are indicated by an ok value of false, and also contain a message property that further describes the error.

{
  "ok": false,
  "message": " . . . "
}

Timezones

Some requests allow for specifying timestamps or generate timestamps with time zone information. We apply the following rules, in order of priority, to determine timezone information for API calls.

Explicitly provide an ISO 8601 timestamp with timezone information

For API calls that allow for a timestamp to be specified, we use that exact timestamp. An example of this is the Reporting API.

These timestamps look something like 2014-02-27T15:05:06+01:00. Also see this example (TODO) for how these timestamps can be specified.

UTC

If the steps above don’t result in any information, we use UTC as the default timezone.