RDN Data Ingestion API

Simple, authenticated REST API for retailers to send transaction data to the Adperical Retail Data Network.

Overview

The RDN Ingestion API allows retailers to send point-of-sale transaction data securely to Adperical. This data powers audiences and closed-loop measurement for brand campaigns.

The API is designed to be simple:

Single endpoint for all transaction data
API key authentication (no OAuth complexity)
JSON request/response format
Accepts single transactions or batches
All PII is hashed on ingestion — no raw customer data is stored

Authentication

All requests must include your API key in the X-API-Key header.

HeaderX-API-Key: rdn_your_api_key_here

Your API key is provided when your retailer account is created. It can be found in the Data Config section of your RDN portal.

Security: Treat your API key like a password. Do not share it in client-side code, public repositories, or URLs.

Base URL

URLhttps://adperical.com/api/rdn

Error Handling

All errors return JSON with an error field:

JSON{
  "error": "Invalid API key"
}

Status	Meaning
200	Success
400	Bad request — check your payload
401	Missing or invalid API key
403	Account not active
500	Server error — retry or contact support

Ingest Transactions

POST /api/rdn/ingest

Send one or more transactions. Each transaction represents a single purchase event at a store.

Single Transaction

JSON Body{
  "store_id": "tawfeer-jnah",
  "timestamp": "2026-03-30T14:30:00Z",
  "total": 45.50,
  "customer_id": "phone:+961XXXXXXXX",
  "items": [
    {
      "sku": "TM-GARLIC-200",
      "category": "Sauces",
      "brand": "Toom Time",
      "qty": 2,
      "amount": 8.00
    },
    {
      "sku": "HM-CLASSIC-300",
      "category": "Dips",
      "brand": "Hummus Time",
      "qty": 1,
      "amount": 5.50
    }
  ]
}

Batch Ingest

Send multiple transactions in one request using the transactions array:

JSON Body{
  "transactions": [
    {
      "store_id": "tawfeer-jnah",
      "timestamp": "2026-03-30T14:30:00Z",
      "total": 45.50,
      "items": [...]
    },
    {
      "store_id": "tawfeer-rawche",
      "timestamp": "2026-03-30T14:35:00Z",
      "total": 22.00,
      "items": [...]
    }
  ]
}

Response

JSON Response{
  "success": true,
  "ingested": 2,
  "retailer": "Tawfeer"
}

Transaction Object

Field	Type	Required	Description
store_id	string	recommended	Unique identifier for the store location (e.g. "tawfeer-jnah")
timestamp	ISO 8601	recommended	Transaction date/time. Defaults to current time if omitted.
total	number	recommended	Total transaction amount
customer_id	string	optional	Customer identifier (phone, email, loyalty ID). Hashed on ingestion — never stored raw.
items	array	required	Array of item objects (see below)

Item Object

Field	Type	Required	Description
sku	string	optional	Product SKU or barcode
category	string	recommended	Product category (e.g. "Dairy", "Sauces", "Beverages")
brand	string	recommended	Product brand (e.g. "Toom Time", "Taanayel")
qty	integer	optional	Quantity purchased. Defaults to 1.
amount	number	recommended	Line item total amount

Privacy: The customer_id field is SHA-256 hashed immediately on ingestion. The raw value is never stored, logged, or accessible. You can send phone numbers, emails, or loyalty IDs — all are hashed identically.

CSV Upload

If API integration isn't feasible, you can upload CSV files directly through the RDN Retailer Portal.

Expected CSV format:

CSVstore_id,timestamp,sku,category,brand,qty,amount,total,customer_id
tawfeer-jnah,2026-03-30T14:30:00Z,TM-GARLIC-200,Sauces,Toom Time,2,8.00,45.50,phone:+961XXXXXXXX
tawfeer-jnah,2026-03-30T14:30:00Z,HM-CLASSIC-300,Dips,Hummus Time,1,5.50,45.50,phone:+961XXXXXXXX

Each row represents one item. Rows with the same timestamp + customer_id (or same total) are grouped as a single transaction.

Example: cURL

bashcurl -X POST https://adperical.com/api/rdn/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rdn_your_api_key_here" \
  -d '{
    "store_id": "tawfeer-jnah",
    "timestamp": "2026-03-30T14:30:00Z",
    "total": 45.50,
    "items": [
      {"category": "Sauces", "brand": "Toom Time", "qty": 2, "amount": 8.00},
      {"category": "Dips", "brand": "Hummus Time", "qty": 1, "amount": 5.50}
    ]
  }'

Example: JavaScript

javascriptconst response = await fetch('https://adperical.com/api/rdn/ingest', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'rdn_your_api_key_here',
  },
  body: JSON.stringify({
    store_id: 'tawfeer-jnah',
    timestamp: new Date().toISOString(),
    total: 45.50,
    items: [
      { category: 'Sauces', brand: 'Toom Time', qty: 2, amount: 8.00 },
      { category: 'Dips', brand: 'Hummus Time', qty: 1, amount: 5.50 },
    ],
  }),
});

const result = await response.json();
console.log(result); // { success: true, ingested: 1, retailer: "Tawfeer" }

Example: Python

pythonimport requests

response = requests.post(
    'https://adperical.com/api/rdn/ingest',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'rdn_your_api_key_here',
    },
    json={
        'store_id': 'tawfeer-jnah',
        'timestamp': '2026-03-30T14:30:00Z',
        'total': 45.50,
        'items': [
            {'category': 'Sauces', 'brand': 'Toom Time', 'qty': 2, 'amount': 8.00},
            {'category': 'Dips', 'brand': 'Hummus Time', 'qty': 1, 'amount': 5.50},
        ],
    }
)

print(response.json())  # {'success': True, 'ingested': 1, 'retailer': 'Tawfeer'}

Need help? Contact your Adperical account manager or email info@adperical.com for integration support.