REST API

Adspect provides a REST API for automating various tasks:

Creating, editing, and deleting streams;
Downloading integration PHP files;
Managing guest access to reporting.

The API supports JSON and XML data encoding. Examples below use JSON encoding for simplicity.

Authentication

Adspect REST API employs HTTP Basic authentication scheme in which API key is supplied as username and password is left blank. You may find your API key in profile.

Each API request must contain two mandatory headers:

Authorization: Basic <authKey> to authenticate yourself with Adspect;
Content-Type for selecting content data encoding:
- Content-Type: application/json for JSON data encoding;
- Content-Type: application/xml for XML data encoding.

The <authKey> field in the Authorization header is formed by base64-encoding a string composed of the API key and a colon appended to it.

Example code in PHP:

<?php
$apiKey = 'SEbMw152aoe2ArffS7yjEJzJ_MFnd33e';
$authKey = base64_encode($apiKey . ':');

For convenience, there’s a readily encoded value of <authKey> available in your profile in the Authorization Header field.

Some HTTP clients offer native support for HTTP Basic authentication scheme which will set the Authorization header for you (e.g. Python Requests provides the requests.auth.HTTPBasicAuth class.) In this case pass your API key for username and leave password blank. Example for php-curl:

<?php
$curl = curl_init();
curl_setopt($curl, CURLOPT_USERPWD, $apiKey . ':');

Endpoints

The base URL for all API endpoints is https://api.adspect.net/v1/. Endpoint descriptions below specify paths relative to this base URL. HTTP method (verb) comes first, followed by the relative endpoint path, e.g. the description GET /streams means making a GET request to the https://api.adspect.net/v1/streams URL.

Collections

Certain object properties may take values only from concrete finite sets–collections. The table below lists collection endpoints:

Endpoint	Description
`GET /collections/presets`	Presets for various traffic sources when creating streams.
`GET /collections/os`	Operating systems for targeting and reporting.
`GET /collections/browsers`	Browsers for targeting and reporting.
`GET /collections/engines`	Browser engines for targeting and reporting.
`GET /collections/countries`	Country codes for targeting and reporting.
`GET /collections/languages`	Language codes for targeting and reporting.
`GET /collections/time-zones`	Time zones for targeting and reporting.
`GET /collections/stream-modes`	Stream modes.
`GET /collections/stream-actions`	Actions for money and safe pages (see below.)
`GET /collections/query-group-by`	Reporting funnel groupings.

Stream Actions

The following table details available stream page actions and their meanings:

Action	Description
`local`	Local file (“zero redirect”).
`proxy`	Reverse proxy.
`fetch`	Insert HTML code.
`iframe`	Display in iframe.
`301`	HTTP 301 redirect.
`302`	HTTP 302 redirect.
`303`	HTTP 303 redirect.
`noop`	No action.
`refresh`	HTTP Refresh redirect.
`meta`	HTML meta refresh redirect.
`return`	Custom HTTP response code.
`php`	Execute PHP code.
`js`	Execute JavaScript code.
`xar`	`X-Accel-Redirect` header.
`xsf`	`X-Sendfile` header.

Managing Streams

A stream is represented as an object with the following properties:

stream_id – stream ID, string, read-only;
account_id – account ID, string, read-only;
name – stream name, string;
tags – stream tags, array of strings;
mode – stream mode, string, either Filter, Review, Money, or White;
notes – any notes you may want to write down, string;
filter_level – filtering level, integer:
- 0 – essentially off;
- 1 – low;
- 2 – medium;
- 3 – high;
- 4 – paranoid;
enable_fp – JavaScript fingerprints enabled flag, boolean or integer;
allow_apps – mobile apps allowed flag, boolean or integer;
money_pages – array of one or more (up to 254) money page objects, each having the following format:
- page – URL / file path / code (depending on action), string;
- action – action to perform for the visitor, string;
- arg_passthru – whether to perform URL parameters passthru, boolean;
- weight – relative weight for A/B traffic distribution, integer;
- enabled – whether this money page is enabled, boolean;
rotator – money page rotator, string, either Split or Timer;
safe_pages – array of exactly one safe page object of the following format:
- page – URL / file path / code (depending on action), string;
- action – action to perform for the visitor, string;
- arg_passthru – whether to perform URL parameters passthru, boolean;
skipClicks – number of first clicks to send to the safe page (delayed start), integer;
cost_parameter – parameter name for click cost accounting, string;
sid_parameter – sub ID parameter name, string;
cid_parameter – click ID parameter name, string;
countries – array of allowed country strings in ISO 3166-1 alpha-2 format;
os – array of allowed operating system strings;
browsers – array of allowed browser strings;
engines – array of allowed browser engine strings;
languages – array of allowed browser language codes;
timezones – array of allowed time zones as integer hour offsets from UTC;
tz_match_ip – match browser time zone to IP time zone flag, boolean or integer;
url_rules – array of zero or more (up to 64) URL rule objects, each having the following format:
- param – URL parameter name, string;
- op – rule operator, one of:
  - EXISTS – parameter exists;
  - NEXISTS – parameter does not exist;
  - REGEX – value matches regular expression;
  - IREGEX – value matches regular expression (case-sensitive);
  - NREGEX – value does not match regular expression;
  - NIREGEX – value does not match regular expression (case-insensitive);
  - EQ – value equals argument;
  - NEQ – value does not equal argument;
  - GT – value is greater than argument;
  - GE – value is greater than or equal to argument;
  - LT – value is less than argument;
  - LE – value is less than or equal to argument;
  - ASSIGN – assign new value to parameter;
  - RENAME – rename parameter;
  - DELETE – delete parameter;
- arg – rule argument, string;
- enabled – rule enabled flag, boolean;
referer_regex (obsolete, will be removed) – regular expression for the referrer filter, string;
ip_on_review – blacklist IP addresses in “Review” mode flag, boolean or integer.

Example:

{
  "stream_id": "1eacc6d0-875f-6f5c-bff8-00162501c2b4",
  "account_id": "1eaa2ce5-d4dd-63ec-b8a4-00162501c2b4",
  "name": "Example Stream",
  "tags": ["Tag1", "Tag2"],
  "mode": "Filter",
  "notes": "This is an example comment.",
  "money_pages": [
    {
      "page": "https://example.com/offer1?clid={clickid}",
      "action": "302",
      "arg_passthru": true,
      "weight": 10,
      "enabled": true
    },
    {
      "page": "https://example.com/offer2?clid={clickid}",
      "action": "302",
      "arg_passthru": true,
      "weight": 20,
      "enabled": true
    }
  ],
  "rotator": "Split",
  "safe_pages": [
    {
      "page": "safe.html",
      "action": "local",
      "arg_passthru": true
    }
  ],
  "ml_precision": 95,
  "cost_parameter": "cost",
  "sid_parameter": "zoneid",
  "cid_parameter": "clickid",
  "enable_fp": true,
  "paranoid": false,
  "allow_apps": true,
  "countries": ["AE", "HK"],
  "os": ["iOS", "macOS"],
  "browsers": ["Google Chrome"],
  "engines": ["Blink"],
  "languages": ["en", "fr", "es"],
  "timezones": [-5, -6, -7],
  "tz_match_ip": true,
  "url_rules": [
    {
      "param": "secretkey",
      "op": "EQ",
      "arg": "4gHzQvF2IoqeQ",
      "enabled": true
    }
  ],
  "ip_on_review": false
}

List Streams

GET /streams

This endpoint returns a list of streams configured in the account. The list is paginated and ordered by stream name in ascending lexicographic order.

Supported URL parameters:

page=1 – sets the number of page to display, defaults to 1;
per-page=20 – sets the number of streams per page, from 1 to 100, defaults to 20;
name=substr – lists only streams whose name contains substr (case-insensitive.)

Stream List Metadata

HEAD /streams

This endpoint returns several headers with useful pagination information:

X-Pagination-Total-Count: 1000 – total number of streams;
X-Pagination-Page-Count: 50 – total number of pages.

Supported URL parameters:

per-page=20 – sets the number of streams per page, from 1 to 100, defaults to 20.

Get Stream

GET /streams/<id>

This endpoint returns the stream specified by <id>.

Create Stream

POST /streams

This endpoint creates and returns a new stream. Send a stream object in request body. All of the stream object properties have default values, so you need to specify only those properties that you want to assign concrete values to, e.g. {"name":"My Stream"}.

Update Stream

PATCH /streams/<id>

This endpoint updates the stream specified by <id>. Send a stream object in request body. You need to specify only those properties that you want to change; the rest of them will be left unchanged.

Copy Stream

COPY /streams/<id>

This endpoint copies the stream specified by <id>. Optionally you may send a stream object in request body–its properties will overwrite properties in the copy, saving you an extra PATCH call.

Delete Stream

DELETE /streams/<id>

This endpoint deletes the stream specified by <id>.

Integration PHP Files

You may obtain index.php, filter.php, and ajax.php files for any stream via the following requests:

index.php and filter.php (both are the same file) – GET https://clients.adspect.ai/getindex.php?sid=<id>
ajax.php – GET https://clients.adspect.ai/getindex.php?sid=<id>&mode=ajax

Replace <id> with an actual Adspect stream ID.

Guest Access to Reporting

Guest access to reporting lets third parties view pre-defined portions of your statistics without having to log into the system. Guess access management is centered around saved report queries:

You create a saved query that specifies allowed report parameters (dates and filters);
The API returns an ID of the saved query;
A guest may then execute this query in the Reporting section by entering the saved query ID in the corresponding field, or by navigating to a link like https://clients.adspect.ai/reporting?query_id=<id>, where <id> should be replaced with the saved query ID.

At most 100 saved queries may be created.

Saved query is represented by an object with the following properties:

query_id – saved query ID, read-only;
owner_id – saved query owner’s account ID, read-only;
date_from – minimum Unix timestamp since which the report will be pulled;
date_to – maximum Unix timestamo until which the report will be pulled;
time_zone – default time zone for displaying date and time;
group_by – default sales funnel grouping, array of strings;
account_id – filter by account IDs, array of strings, read-only;
stream_id – filter by stream IDs, array of strings;
ip_address – filter by IP addresses, array of strings;
asn – filter by ASN, array of integers or strings like AS65536 or AS1.10;
country_code – filter by countries, array of strings;
os – filter by operating systems, array of strings;
browser – filter by browsers, array of strings;
engine – filter by browser engines, array of strings;
sub_id – filter by subaccounts, array of strings;
click_id – filter by click IDs, array of strings;
mode – filter by stream modes, array of strings из списка: Filter, Review, Money, White;
target – filter by displayed paged, array of integers:
- 0 – safe page;
- 1–255 – money page with the corresponding ordinal number.

All of the fields are optional. If a particular filter is not needed, then you may either omit it or set it to null (or an empty array [] where array values are expected.)

Example:

{
  "query_id": "878efbf1-0fb9-4c69-ad36-40e714b0eeeb",
  "owner_id": "1eb5991f-a25b-68f4-b171-00162501c2b4",
  "date_from": 1577836800,
  "date_to": null,
  "time_zone": "Asia/Dubai",
  "group_by": [],
  "account_id": ["1eb5991f-a25b-68f4-b171-00162501c2b4"],
  "stream_id": ["6792f6ce-f153-439f-b223-f58749f1210f"],
  "ip_address": [],
  "asn": [],
  "country_code": ["HK", "AE"],
  "os": ["iOS", "macOS"],
  "browser": ["Apple Safari"],
  "engine": [],
  "sub_id": [],
  "click_id": [],
  "mode": ["Filter"],
  "target": []
}

Query List

GET /reports

This endpoint returns a paginated list of created saved queries in the account.

Supported URL parameters:

page=1 – sets the number of page to display, defaults to 1;
per-page=20 – sets the number of queries per page, from 1 to 100, defaults to 20;

Query List Metadata

HEAD /reports

This endpoint returns several headers with useful pagination information:

X-Pagination-Total-Count: 1000 – total number of queries;
X-Pagination-Page-Count: 50 – total number of pages.

Supported URL parameters:

per-page=20 – sets the number of queries per page, from 1 to 100, defaults to 20.

Get Query

GET /reports/<id>

This endpoint returns the query specified by <id>.

Create Query

POST /reports

This endpoint creates and returns a new query. Send a query object in request body.

Update Query

PATCH /reports/<id>

This endpoint updates the query specified by <id>. Send a query object in request body. You need to specify only those properties that you want to assign values to; the rest of the properties will remain unchanged.

Copy Query

COPY /reports/<id>

This endpoint copies the query specified by <id>. Optionally you may send a query object in request body–its properties will overwrite properties in the copy, saving you an extra PATCH call.

Delete Query

DELETE /reports/<id>

This endpoint deletes the query specified by <id>.