API

Documentation

Version 2.0 - 2026

REAL DATA. REAL TIME. YOUR WAY.

The smart way to access your OOH audience data. No spreadsheets. No waiting. Just plug in and go.

The Data Jam API puts your live impressions, movement data, dwell time, and visitor analytics right where you need it. Pull it into your dashboards, feed it to your BI tools, automate your reporting - whatever works for you. Your JamBoxes are already doing the hard work. Now make that data work harder.

What's New: Interactive API sandbox - test live API calls right in your browser. Fresh documentation. Clean examples. Plus - Data Jam PULSE predictive analytics is on the way.

Contents

1. Quick Start 2. Try It Live 3. Authentication 4. API Endpoints 5. Data Types 6. Request Format 7. Response Format 8. Rate Limits & Constraints 9. Postman Setup Guide 10. Code Examples 11. FAQ 12. Support

1. Quick Start

Let's get you jamming. Five minutes, three API calls, and you're pulling live audience data across all your projects. Here's how:

Base URL

https://datajamportal.com/CustomerAPI/

Step 1: Discover Your Projects

First, find out what projects and devices you have access to:

curl -X GET "https://datajamportal.com/CustomerAPI/GetUserProjects/" \
  -H "Authorization: Basic $(echo -n 'your_email@domain.com:your_password' | base64)" \
  -H "Content-Type: application/json"

Step 2: Pull Data

Use a project name and device number from the response above:

curl -X GET "https://datajamportal.com/CustomerAPI/GetData/" \
  -u "your_email@domain.com:your_password" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "Your Project",
    "device_number": "JB000XXX",
    "start_date": "2026-01-01",
    "end_date": "2026-01-30",
    "type_data": "Impression",
    "filter": "All"
  }'
The Workflow: GetUserProjects → GetDeviceInfo → GetData. Discover your projects, get device details, pull your data. No hardcoding needed.

Try It Live

Test the API right here. Enter your credentials and parameters, hit send, and see real responses.

Response

// Response will appear here...
Start here: GetUserProjects returns every project assigned to your account, with all device IDs nested inside. No parameters needed beyond your credentials.

Response

// Response will appear here...
Note: Use your own Data Jam Portal credentials. Only projects assigned to your account will work.

Response

// Response will appear here...
Tip: Leave Device Number blank to get full metadata for every device in the project. Or specify one device for a single result.

2. Authentication

Same login you use for the Data Jam Portal. Simple as that. We use HTTP Basic Authentication - secure, standard, no fuss.

Credentials

Parameter Description
username Your Data Jam Portal email address
password Your Data Jam Portal password

Header Format

Authorization: Basic base64(username:password)
Important: Users can only access projects they have been assigned to. Attempting to access an unauthorized project will return: {"msg": "User not allowed for Project."}

3. API Endpoints

Four endpoints to cover everything you need. Discover your projects, find your devices, pull your data, and push your own. Clean and simple.

GET

/CustomerAPI/GetUserProjects/

List all projects assigned to your account, complete with every device in each project. Your starting point for dynamic discovery.

GET

/CustomerAPI/GetDeviceInfo/

Retrieve device configuration, location, status, and metadata. Pass a project name to get all devices, or specify a single device.

GET

/CustomerAPI/GetData/

Retrieve impressions, movement data, dwell time, or visitor analytics for a specific device and date range.

POST

/CustomerAPI/AddData/

Submit custom user data to associate with a device (for external data integration).

Dynamic Discovery: Don't hardcode project or device IDs. Use GetUserProjects to discover your projects and devices, then GetDeviceInfo for full metadata including lat/long, timezone, and status.

4. Data Types

Pick your flavour. Whether you need impressions for media buyers or dwell time for engagement analysis, we've got you covered. Just set the type_data parameter:

Type Description Filter Options
Impression Total impressions/views detected by the JamBox sensor All, Default
Visitors Unique visitor counts All, Default
DwellTime Time spent in detection zone (engagement metrics) All, Default
UserData Custom user-submitted data All

Filter Options

5. Request Format

Here's exactly what to send. Copy it, tweak it, make it yours.

GetUserProjects Request

No request body needed. Just authenticate and go.

GET /CustomerAPI/GetUserProjects/
Authorization: Basic base64(username:password)

// No request body required
Pro Tip: This is your discovery endpoint. Call it first to get all your project names and device IDs, then use those to call GetDeviceInfo and GetData. No more hardcoding.

GetData Request Body

{
    "project_name": "Your Project Name",
    "device_number": "JB000XXX",
    "start_date": "YYYY-MM-DD",
    "end_date": "YYYY-MM-DD",
    "type_data": "Impression|Visitors|DwellTime|UserData",
    "filter": "All|Default"
}
Parameter Type Required Description
project_name string Yes Project name (case-sensitive)
device_number string Yes JamBox device ID (e.g., JB001234)
start_date string Yes Start date in YYYY-MM-DD format
end_date string Yes End date in YYYY-MM-DD format
type_data string Yes Data type to retrieve
filter string Yes Filter mode: "All" or "Default"
Heads Up: Project names are case-sensitive. "Mall_Campaign" and "mall_campaign" are treated as different projects. Always use the exact name as shown in your Data Jam Portal.

GetDeviceInfo Request Body

// Get all devices in a project:
{
    "project_name": "Your Project Name"
}

// Or get a specific device:
{
    "project_name": "Your Project Name",
    "device_number": "JB000XXX"
}
All Devices: Omit device_number to get full metadata (lat/long, status, timezone, hardware version) for every device in the project. Perfect for building device inventories.

AddData Request Body

Submit custom data points to associate with a device. Perfect for integrating external data sources like sales, weather, or event data.

{
    "project_name": "Your Project Name",
    "device_number": "JB000XXX",
    "timezone": "Europe/London",
    "user_data": [
        {
            "timestamp": "2026-01-15 09:00:00",
            "value": 100
        },
        {
            "timestamp": "2026-01-15 10:00:00",
            "value": 150
        },
        {
            "timestamp": "2026-01-15 11:00:00",
            "value": 200
        }
    ],
    "type_data": "UserData"
}
Parameter Type Required Description
project_name string Yes Project name (case-sensitive)
device_number string Yes JamBox device ID
timezone string Yes IANA timezone (e.g., Europe/London, America/New_York)
user_data array Yes Array of timestamp/value pairs
type_data string Yes Must be "UserData"

6. Response Format

Here's what comes back. Clean JSON, hourly breakdowns, everything you need to slice and dice your data.

Successful GetUserProjects Response

{
    "success": true,
    "projects": [
        {
            "project_name": "Mall_Entrance_Q1",
            "devices": [
                {
                    "device_number": "JB001234",
                    "device_name": "Main Entrance"
                },
                {
                    "device_number": "JB001235",
                    "device_name": "North Wing"
                }
            ]
        },
        {
            "project_name": "Retail_Summer_2026",
            "devices": [
                {
                    "device_number": "JB002001",
                    "device_name": "Window Display"
                }
            ]
        }
    ]
}

Successful GetData Response

{
    "device_info": [
        {
            "Device": "JB001338",
            "Date": "14-May",
            "Day": "Tue",
            "Field": "DwellTime",
            "dev_location_ref": "West London 4",
            "avg_temp": 47,
            "rain": 0,
            "Total": 39453.0,
            "hour00": 388.0,
            "hour01": 363.0,
            "hour02": 337.0,
            ...
            "hour23": 256.0
        }
    ]
}
Field Type Description
Device string JamBox device ID
Date string Date of the data point (e.g., "14-May")
Day string Day of the week (e.g., "Tue")
Field string Data type or zone breakdown label (e.g., "DwellTime", "Impressions", "0-1min", "5-10min")
dev_location_ref string Device location reference name
avg_temp number Average temperature for that day at the device location
rain number Rainfall amount for that day at the device location
Total number Sum of all hourly values for the day
hour00 - hour23 number Hourly breakdown values (midnight to 11pm)

Successful GetDeviceInfo Response

{
    "device_info": [
        {
            "device_number": "JB000123",
            "device_status": "Enabled",
            "create_date": "2023-12-06",
            "registration_status": "Enabled",
            "device_version": "DataJam_v5.6",
            "device_hardware": "M5AtomS3",
            "registration_date": "2025-11-10",
            "longitude": "-0.123456",
            "latitude": "51.50735",
            "dev_location_ref": "Main Entrance",
            "dev_frameid": "Frame A",
            "timezone": "Europe/London",
            "mac_address": "AA:BB:CC:DD:EE:FF",
            "min_rssi": -70
        }
    ]
}

Error Responses

Response Meaning
{"msg": "Json Schema Validation Failed"} Missing or invalid request parameters
{"msg": "User not allowed for Project."} User doesn't have access to this project
{"msg": "End Date should be up to 30 days from start days"} Date range exceeds 30-day limit
{"message": "No Data Present for Device"} No data exists for specified device/date range

7. Rate Limits & Constraints

One thing to know: we keep queries focused. Here's the deal:

30-Day Window

Each request can pull up to 30 days of data. This keeps things fast and prevents massive queries from slowing everyone down. Same rule as the Portal - consistency is key.

Attempting to query more than 30 days will return:
{"msg": "End Date should be up to 30 days from start days"}

Need a Full Year?

No problem. Just batch your requests. 12 calls, 12 months - done:

# Example: Query a full year with 12 monthly calls
January:   start_date: "2026-01-01", end_date: "2026-01-31"
February:  start_date: "2026-02-01", end_date: "2026-02-28"
March:     start_date: "2026-03-01", end_date: "2026-03-31"
...
December:  start_date: "2026-12-01", end_date: "2026-12-31"

8. Postman Setup Guide

Postman is the easiest way to test the API without writing a single line of code. Here's your setup in 6 steps:

Step 1: Create a Postman Account

  1. Go to https://www.postman.com
  2. Click "Sign Up for Free" or sign in to your existing account

Step 2: Create a Workspace

  1. Click on "Workspaces" in the navigation bar
  2. Click "Create Workspace"
  3. Choose "Blank workspace" and click Next
  4. Name your workspace (e.g., "Data Jam API") and set access permissions
  5. Click "Create"

Step 3: Import Collection

  1. Click the "Import" button in the top left
  2. Drag and drop the Data Jam collection JSON file, or select it from your files
  3. The collection will appear in your sidebar under "Collections"

Step 4: Configure Authentication

  1. Click on any request in the collection
  2. Go to the "Authorization" tab
  3. Select "Basic Auth" as the Type
  4. Enter your Data Jam Portal username (email) and password

Step 5: Configure Request Body

  1. Go to the "Body" tab
  2. Select "raw" and "JSON"
  3. Enter your request parameters (project_name, device_number, dates, etc.)

Step 6: Send Request

  1. Click the blue "Send" button
  2. View the response in the lower panel

9. Code Examples

Copy. Paste. Customise. Get jamming in your language of choice:

cURL - List Your Projects

curl -X GET "https://datajamportal.com/CustomerAPI/GetUserProjects/" \
  -H "Authorization: Basic $(echo -n 'user@email.com:password' | base64)" \
  -H "Content-Type: application/json"

cURL - Get Data

curl -X GET "https://datajamportal.com/CustomerAPI/GetData/" \
  -u "user@email.com:password" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "Data Jam",
    "device_number": "JB000123",
    "start_date": "2026-01-01",
    "end_date": "2026-01-30",
    "type_data": "Impression",
    "filter": "All"
  }'

Python - Full Workflow

The real power move: discover projects, enumerate devices, pull data - all automated.

import requests
from requests.auth import HTTPBasicAuth

BASE_URL = "https://datajamportal.com/CustomerAPI"
auth = HTTPBasicAuth("user@email.com", "password")

# Step 1: Get all your projects and devices
projects = requests.get(
    f"{BASE_URL}/GetUserProjects/",
    auth=auth
).json()

for project in projects["projects"]:
    print(f"\nProject: {project['project_name']}")
    print(f"  Devices: {len(project['devices'])}")

    # Step 2: Get full device metadata for this project
    device_info = requests.get(
        f"{BASE_URL}/GetDeviceInfo/",
        json={"project_name": project["project_name"]},
        auth=auth
    ).json()

    for device in device_info["device_info"]:
        print(f"  {device['device_number']} - {device['dev_location_ref']}")
        print(f"    Status: {device['device_status']}")
        print(f"    Location: {device['latitude']}, {device['longitude']}")

        # Step 3: Get impression data for each device
        data = requests.get(
            f"{BASE_URL}/GetData/",
            json={
                "project_name": project["project_name"],
                "device_number": device["device_number"],
                "start_date": "2026-01-01",
                "end_date": "2026-01-30",
                "type_data": "Impression",
                "filter": "All"
            },
            auth=auth
        ).json()

        if "device_info" in data:
            total = sum(row["Total"] for row in data["device_info"])
            print(f"    Total Impressions: {total:,}")

Python - Simple GetData

import requests
from requests.auth import HTTPBasicAuth

url = "https://datajamportal.com/CustomerAPI/GetData/"

payload = {
    "project_name": "Data Jam",
    "device_number": "JB000123",
    "start_date": "2026-01-01",
    "end_date": "2026-01-30",
    "type_data": "Impression",
    "filter": "All"
}

response = requests.get(
    url,
    json=payload,
    auth=HTTPBasicAuth("user@email.com", "password")
)

print(response.json())

JavaScript (Node.js) - Full Workflow

const axios = require('axios');

const BASE_URL = 'https://datajamportal.com/CustomerAPI';
const credentials = Buffer.from('user@email.com:password').toString('base64');
const headers = {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
};

async function getAllData() {
    // Step 1: Get all projects
    const { data: projects } = await axios.get(
        `${BASE_URL}/GetUserProjects/`, { headers }
    );

    for (const project of projects.projects) {
        console.log(`\nProject: ${project.project_name}`);

        // Step 2: Get device details
        const { data: devices } = await axios.get(
            `${BASE_URL}/GetDeviceInfo/`, {
                headers,
                data: { project_name: project.project_name }
            }
        );

        for (const device of devices.device_info) {
            console.log(`  ${device.device_number} - ${device.dev_location_ref}`);

            // Step 3: Get impressions
            const { data } = await axios.get(
                `${BASE_URL}/GetData/`, {
                    headers,
                    data: {
                        project_name: project.project_name,
                        device_number: device.device_number,
                        start_date: '2026-01-01',
                        end_date: '2026-01-30',
                        type_data: 'Impression',
                        filter: 'All'
                    }
                }
            );

            if (data.device_info) {
                const total = data.device_info.reduce((sum, row) => sum + row.Total, 0);
                console.log(`    Total Impressions: ${total.toLocaleString()}`);
            }
        }
    }
}

getAllData().catch(console.error);

10. Frequently Asked Questions

Got questions? We've got answers:

What's a Project?

Think of it as a folder for your JamBoxes. A Project groups devices by campaign, client, or location. One project might be "Mall_Entrance_Q1" - all the JamBoxes for that activation in one place.

What's a Device?

That's your JamBox. Every JamBox has a unique ID like "JB001234" - that's the serial number you'll use in your API calls to pull data from that specific sensor.

Where do I find my Project or Device ID?

Use the GetUserProjects endpoint - it returns every project assigned to your account with all device IDs nested inside. No need to check the Portal or ask your account manager. One API call and you've got everything.

How do I get all devices in a project?

Two options: GetUserProjects gives you device IDs and names for every project at once. Or call GetDeviceInfo with just a project_name (no device_number) to get full metadata - lat/long, timezone, status, hardware version - for every device in that project.

I have 100+ devices across multiple projects. How do I automate this?

That's exactly what the discovery endpoints are for. Call GetUserProjects once to get your full project/device tree, then loop through each project and device to pull data. Check the Python and Node.js workflow examples in the Code Examples section - they show the full pattern.

What data do I get back?

The good stuff: impressions, visitor counts, dwell times, hourly breakdowns, and more. All timestamped, all ready to roll into your reports.

How fresh is the data?

Near real-time. We're talking 5 minutes from detection to API. Your JamBox captures it, we process it, you query it. That's the Data Jam way.

Can I pull more than 30 days?

Not in one call - but you can easily batch requests. Need a year? That's 12 calls. We've got code examples above that make it a breeze.

11. Support

Stuck? Hit a snag? Just want to say hi? We're here for it. The Data Jam team is ready to help you get the most out of your data:

Development Team

devteam@data-jam.com

General Support

team@data-jam.com

US Contact

Arran: (747) 243 3513

UK Contact

Alex: +44 7827 813388

Coming Soon: Data Jam PULSE - Our predictive movement engine is coming. Know where your audience will be, not just where they've been. The future of OOH intelligence is almost here.