Knowledge Article

Overview

The illumin API empowers developers to request data on any of their illumin campaigns or a combination of campaigns. This document provides information about illumin's API endpoints.

To access the platform API, you need the platform API credentials provided by your illumin Account Manager. You also need an authentication token to generate and place in the header of your integration. See the Authentication section of this document for details.

The examples shown are in curl:

Version information: Version: 1.1
Terms of service: Terms and conditions

To learn more about our Rest API service, email the API team. The service comes with some fine print. Be sure to read our Terms of Service. Of course, everything is copyrighted. License illumin©2025. All rights reserved.

Revisions and approvals

Step 1 - Authentication

New token
Token renewal

Step 2 - Pulling Data

Date range
Columns
Filters
Report data
Example report POST request and response

Revisions and approvals

Version	Date	Author	Description
1.0	Oct 27, 2022		Created initial SS illumin API guide.
1.2	Feb 13, 2024	Guy A Levanon	Modified token expiry time, reformatted and adjusted text to add clarification.
1.3	July 1, 2024	R Whyte	Moved the REST API guide online. Updated reference docs.
1.3a	June 18, 2025	Ash Muralikanthan	Added in grouBy documentation

Step 1 Authentication

All API requests must be authenticated using the X-Acuity-Authentication-Token HTTP request header.

New token

To get the authentication token, send a POST request to /public-api/v1/session with the following JSON object in the body.

    {
        "password": "string",
        "username": "string"
    }

Example login request.

curl --location 'https://api.illumin.com/aa/public-api/v1/session' \
-H 'Content-Type: application/json' \
-d '  {
        "password": "Acuity-provided-password",
        "username": "Acuity-provided-username"
    }'

The token from the response below should be passed as the value of the X-Acuity-Authentication-Token header for all subsequent API requests. The token expires after 48 hours. Scroll down to learn about renewing the token.

Example authentication response.

{
"status": 200,
"requestId": "MTcyLjI5LjEuNDc6MTYONDc3NzAxODcyMDoxNjQ0NjEyMDYyNDkx", 
"systemTimestamp": "2022-02-13T18:30:18.868+00:00",
"timeTaken": 148,
"location": "api-public-55855c4ff5-t787r [172.29.1.47]",
"errors": [],
"warnings": [],
"data": {
     "token": "YOUR TOKEN"
},
"statusCodeValue": 200
}

Token renewal

To renew a token, make a GET request to /public-api/v1/session with the old token as the X-Acuity-Authentication-Token request header.

Renew token GET request.

curl https://api.illumin.com/aa/public-api/v1/session \ 
-H 'X-Acuity-Authentication-Token: YOUR_TOKEN'

If the token can be renewed, you'll receive the response below. It's similar to the response from a new authentication request. The renewed token should be passed as the X-Acuity-Authentication-Token header for all subsequent API requests. If the token cannot be renewed, try a new authentication request to get a fresh token.

{
"status": 200,
"requestId": "MTcyLjI5LjEuNDc6MTYONDc4NzQ1NjU10ToxNjQ0NjEyMDYyNDk0",
"systemTimestamp": "2022-02-13T19:24:16.563+00:00",
"time Taken": 4,
"location": "api-public-55855c4ff5-t787r [172.29.1.47]",
"errors": [],
"warnings": [],
"data": {
     "token": "YOUR_NEW_TOKEN"
},
"statusCodeValue": 200
}

Token expiry and password reset

Access tokens are linked to your account password and stop working when your password expires. Passwords expire every two months. If you can’t log in to the API or fetch data, go here and check whether your password has expired, then reset it if needed.

Step 2 - Pulling data

With the token obtained in the previous step, you're now ready to pull data from illumin using the API endpoints listed in this step. illumin report generation requires three input parameters:

Date range.
List of columns to be included. Each column is either a Dimension column or a Metric column.
Filters that allow you to refine the report data.

Date range

The date range of the resulting report. Metrics value will be pulled only for these dates. The period is limited to 365 days (i.e. the duration of the date range in a single API call cannot exceed 365 days).

Columns

Metric columns provide the report data (e.g. impressions or clicks). Dimension columns show how the report aggregates metrics (e.g. city or ad type). For example, below is a sample report with three columns: City and ad type are the dimensions. Impressions is the metric.

City (Dimension)	Ad Type (Dimension)	Impressions (Metric)
New York	Display	1,000,000
New York	Video	200,000
Boston	Display	800,000
Boston	Video	150,000

The list of available columns is specific to each user. To obtain a list of columns available to the authentication token you are using (see Step 1 above), perform the following API call to /public-api/v1/revenue-report/columns.

GET all columns.

curl
https://api.illumin.com/aa/public-api/v1/revenue-report/columns \
-H 'X-Acuity-Authentication-Token: YOUR_TOKEN'

You can expect to see the following response:

{
"status": 200,
"requestId": "MTcyLjI5LjEuNDc6MTYONDC4OTIZMTUOMDoxNjQONjEyMDYyNDk1", 
"systemTimestamp": "2022-02-13T21:53:51.611+00:00",
"timeTaken": 71,
"location": "api-public-55855c4ff5-t787r [172.29.1.47]",
"errors": [],
"warnings": [],
"data": [{
}, {
     "id": 2,
     "name": "vconv",
     "displayName": "Vconv",
     "type": "METRIC"
}, 
     "id": 7,
     "name": "journeyId",
     "displayName": "Journey ID",
     "type": "DIMENSION"
}
...
...
{
     "id": 16,
     "name": "video CompanionViews", 
     "displayName": "Video Companion Views", 
     "type": "METRIC"
},
{
     "id": 17,
     "name": "video CompanionClicks",
     "displayName": "Video Companion Clicks", 
     "type": "METRIC"
}],
"statusCodeValue": 200
}

groupBy Parameter

The groupBy parameter allows you to group your results by one or more columns. Using grouBy helps reduce the size of the dataset by returning aggregated records. If groupBy is not used, the API will return raw-level data, which can result in very large responses, especially for high-volume reports.

How to use

You can include the groupBy parameter in your API request body as an array of column names. The response will contain grouped and aggregated data based on the fields you specify.

Example request

}
"columns": [
"advertiserId", "agencyId", "creativeId", "journeyId", "views", "clicks"
],
"filters": [
{
"column": "licenseeId",
"values": [1234]
}
],
"groupBy": [
"advertiserId", "agencyId", "creativeId", "journeyId"
],
"start": "2025-06-01T00:00",
"end": "2025-06-01T23:59", 
"granularity": "DAILY"
}

Filters

Filters allow you to refine the report. For example, you can create a metric that applies to a specific campaign or a specific version of the campaign.

The list of available filters is specific to each user. To obtain the list of filters available to the authentication token you are using (see Step 1), perform the following API call to /public-api/v1/revenue-report/filters.

GET all filters.

curl
https://api.illumin.com/aa/public-api/v1/revenue-report/filters \
-H 'X-Acuity-Authentication-Token: YOUR_TOKEN'

You can expect to see the following response to GET all filters.

{
"status": 200,
"requestId": "MTcyLjI5LjEuNDc6MTYONDc5MjQ4NDA5NzoxNjQ0NjEyMDYyNDk2",
"systemTimestamp": "2022-02-13T22:48:04.109+00:00",
"timeTaken": 12,
"location": "api-public-55855c4ff5-t787r [172.29.1.47]",
"errors": [],
"warnings": [],
"data": [{
     "name": "advertiserId"
},    {
     "name": "journeyId"
},    {
     "name": "versionId"
},    {
     "name": "majorVersionId"
},    {
     "name": "licenseeId"
}],
"statusCodeValue": 200
}

Report data

To get the reporting data, make a POST request to /public-api/v1/revenue-report/data with the following JSON object in the body.

Report POST body object.

{
"columns": ["name"],
"filters": [{
     "column": "name",
     "values": []
}],
"sort": [{
     "column": "name",
     "type": "ASC/DESC"
}],
"start": "yyyy-MM-DDTHH:mm", 
"end": "yyyy-MM-DDTHH:mm",
"granularity": "OVERALL"
}

Where

"columns" is a list of the column name(s) you want in the report. Use the name field returned from calling the column endpoint
"filters" is a list of filter(s) you want to use on the report columns. Should be a list of the following filter objects:
- column is taken from the name field returned from calling a filters endpoint,
- values is a list of integers.

Filter

{
"column": "name",
"values" : [filter-values]
}

“sort“ creates a list of columns you want to sort the report by. This should be a list of the following sort object: “column” is taken from the “name” field returned from calling filters endpoint,and “type” can be “ASC” for ascending order or “DESC” for Descending order.

Sort

{
"column": "name",
"type": "ASC"/"DESC"
}

“start” & “end”: The time range of the desired report in UTC. ISO date time format “yyyy-MM-DDTHH:mm”. For example: 2024-01-13T13:00. Duration limit of 365 days.
“granularity”: How to group results by time. One of the following:
- OVERALL time will not be used as a dimension
- HOURLY break down results by hour
- DAILY break down results by day
- WEEKLY break down results by week
- MONTHLY break down results by month

Example report POST request and response

POST request to get report data.

curl -X POST
https://api.illumin.com/aa/public-api/v1/revenue-report/data\
-H 'Content-Type: application/json' \
-H 'X-Acuity-Authentication-Token:
WZR1MmIzMjBjLWMxN2ItNDc4MC1iMWRmLTE2OTYWYTUxMzJiZF0gW1B1bHNlIFFBXSBbмTY0
NDgwNjA2NTY10F0gWzEONDAwMDAwXQ' \
-d '{
"columns": ["licenseeId", "licensee", "views", "clicks"],
"filters": [{"column": "licenseeId", "values": [392]}], 
"sort": [{"column": "licenseeId", "type": "ASC"}], 
"start": "2022-01-15T10:00",
"end": "2022-02-14T10:00", 
"granularity": "OVERALL"
}'

Response containing the report.

{
"status": 200,
"requestId": "MTcyLjI5LjEuNDc6MTY ONDg0OTczNjY2NDoxNjQONjEyMDYyNTQ2", 
"systemTimestamp": "2022-02-14T14:42:18.924+00:00",
"timeTaken": 2260,
"location": "api-public-55855c4ff5-t787r [172.29.1.47]",
"errors": [],
"warnings": [],
"data": {
     "data": [{
          "stamp": "Overall",
          "licensee": "Acuity Licensee",
          "clicks": 1,
          "views": 5,
          "licenseeId":"392"
     }],
     "total": {
           "stamp": "Overall",
           "clicks": 1,
           "views": 5
}
},
"statusCodeValue": 200
}

Integrate Looker Studio

REST API Document

Overview

Contents

Revisions and approvals

Step 1 Authentication

New token

Token renewal

Token expiry and password reset

Step 2 - Pulling data

Date range

Columns

groupBy Parameter

Filters

Report data

Example report POST request and response

Related articles