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:

  1. Authorization: Basic <authKey> to authenticate yourself with Adspect;
  2. 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.

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. Below you will find lists of such values and API endpoints for obtaining them programmatically.

Operating Systems

Operating system names are case-insensitive.

GET /collections/os
  • Android 1
  • Android 2
  • Android 3
  • Android 4
  • Android 5
  • Android 6
  • Android 7
  • Android 8
  • Android 9
  • Android 10
  • Android 11
  • Android 12
  • Android 13
  • iOS
  • KaiOS
  • macOS
  • Linux
  • Other
  • Windows XP
  • Windows Vista
  • Windows 7
  • Windows 8
  • Windows 8.1
  • Windows 10
  • Windows Other

Browsers

Browser names are case-insensitive.

GET /collections/browsers
  • Apple Safari
  • Facebook app
  • Google Chrome
  • Internet Explorer
  • Microsoft Edge
  • Mozilla Firefox
  • Opera
  • Other
  • Samsung Internet
  • Snapchat app
  • UC Browser
  • WebView
  • Yandex Browser

Browser Engines

Browser engine names are case-insensitive.

GET /collections/engines
  • Blink
  • EdgeHTML
  • Gecko
  • Other
  • Presto
  • Trident
  • WebKit

Country Codes

GET /collections/countries

Language Codes

GET /collections/languages

Time Zones

GET /collections/time-zones

Stream Modes

Stream modes are case-insensitive.

GET /collections/stream-modes
  • Filter – filtering;
  • Review – on review;
  • Money – all to money page;
  • White – all to safe page.

Stream Actions

GET /collections/stream-actions
  • 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.

Funnel Groupings

Funnel grouping names are case-insensitive.

GET /collections/query-group-by
  • date – by date;
  • stream_id – by stream;
  • asn – by ASN (autonomous system number);
  • country_code – by country code;
  • os – by operating system;
  • browser – by browser;
  • engine – by browser engine;
  • sub_id – by subaccount;
  • mode – by stream mode;
  • target – by displayed page number;
  • tag – by tag.

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 referer 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:

  1. You create a saved query that specifies allowed report parameters (dates and filters);
  2. The API returns an ID of the saved query;
  3. 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>.