Resonate Enrichment API

Overview

The Resonate Attribute API enables clients to request real-time data about their site visitors and leads using an IPv4 address or a hashed email (HEM). In response, the API returns behavioral, demographic, and psychographic attributes, represented by client-specific survey value keys.

This guide explains authentication, request/response structure, usage expectations, and support procedures.

1. Authentication

Clients must authenticate requests with a unique API key.

Required header:

X-API-KEY: YOUR_CLIENT_KEY

• API keys are client-specific and revocable
• During onboarding, clients will need to provide a list of allowed source domains:
  • URI only (no http, https, etc.) in a comma-separated format
  • Wildcards (*) are accepted for domains, but providing the root domain as well is recommended
  • Example: *.example.com, example.com
• Resonate validates both the API key and the origin domain of the request
• API keys do not expire

2. Endpoint and request format

Base URL:

https://api.reson8.com/v1/personalization

The API supports two HTTP methods. Use GET for IP-based lookups (backwards compatibility) and POST for all identifier types including HEMs.

GET request (IP — backwards compatible)

When no ID is provided, the API uses the requesting IP address.

GET /v1/personalization

POST request (all identifier types)

Submit the identifier in the request body as JSON.

POST /v1/personalization
{
  "id": {
    "type": "<idType>",
    "value": "<identifier value>"
  }
}

Required body fields:

3. Supported identifier types

Important notes:

• Only one identifier may be submitted per request
• Submitted identifiers are validated for proper formatting — malformed or unsupported values return a 400 error
• Non-US requests are not supported and will return a 204 with no content
• Batch submission is not supported

HEM formatting guidance:

• Clients commonly produce incorrect HEMs by not lowercasing emails before hashing, including whitespace, or mixing hash types. To ensure correct match rates, normalize emails before hashing: lowercase(trim(email))
• Clients must hash emails client-side and submit the hash — raw email ingestion is not supported

4. Example requests

IP (GET — default)

GET /v1/personalization

IP (POST)

POST /v1/personalization
{
  "id": {
    "type": "IP",
    "value": "203.0.113.42"
  }
}

HEM MD5 (POST)

POST /v1/personalization
{
  "id": {
    "type": "HEM_MD5",
    "value": "c3a80cfdca3a7fa93b48d7582c300621"
  }
}

HEM SHA1 (POST)

POST /v1/personalization
{
  "id": {
    "type": "HEM_SHA1",
    "value": "c3a80cfdca3a7fa93b48d7582c300621d8b596f5"
  }
}

HEM SHA256 (POST)

POST /v1/personalization
{
  "id": {
    "type": "HEM_SHA256",
    "value": "67edc94d1cac42c584c7076f067e6cbd577d33863426ce251160b356ace79fe5"
  }
}

curl

# IP (GET)
curl --location 'https://api.reson8.com/v1/personalization' \
  --header 'X-API-KEY: ********'

# HEM (POST)
curl --location --request POST 'https://api.reson8.com/v1/personalization' \
  --header 'X-API-KEY: ********' \
  --header 'Content-Type: application/json' \
  --data '{"id": {"type": "HEM_MD5", "value": "c3a80cfdca3a7fa93b48d7582c300621"}}'

JavaScript — Fetch

const myHeaders = new Headers();
myHeaders.append("Origin", "https://example.com");
myHeaders.append("X-API-KEY", "***********");
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");

// For HEM POST:
const body = JSON.stringify({ id: { type: 'HEM_MD5', value: '<md5_hash>' } });

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body,
  redirect: "follow"
};

fetch("https://api.reson8.com/v1/personalization", requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.error(error));

JavaScript — axios

const axios = require('axios');

const config = {
  method: 'post',
  url: 'https://api.reson8.com/v1/personalization',
  headers: {
    'Origin': 'https://example.com',
    'X-API-KEY': '*********',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  data: { id: { type: 'HEM_MD5', value: '<md5_hash>' } }
};

axios.request(config)
  .then(response => console.log(JSON.stringify(response.data)))
  .catch(error => console.log(error));

Python — Requests

import requests, json

url = "https://api.reson8.com/v1/personalization"

headers = {
    'Origin': 'https://example.com',
    'X-API-KEY': '************',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
}

payload = json.dumps({'id': {'type': 'HEM_MD5', 'value': '<md5_hash>'}})

response = requests.request('POST', url, headers=headers, data=payload)
print(response.text)

5. Response format

Successful responses return a JSON object with the following structure:

{
  "type": "HEM_MD5",
  "lastUpdated": "2025-05-06T14:53:08Z",
  "attributes": {
    "123456": 1,
    "234567": 0,
    "345678": null
  }
}

• Each survey value key corresponds to a licensed attribute
• Each client receives a key definitions file mapping survey value keys to human-readable names and descriptions
• For IP lookups, responses are only returned for residential IPs

6. Error handling

The API returns JSON-formatted error responses with a message field.

{
  "message": "Unauthorized – Invalid API key"
}

Note: Check that the response body is not undefined before parsing.

There is currently no retry guidance. Clients should implement standard resilience patterns as appropriate.

7. Caching

• Resonate handles internal caching for optimal performance
• It is recommended that clients cache responses as well, with a TTL of 1 day

8. Data freshness

Attribute data is refreshed every 2 months in line with the new wave.

9. Security and compliance

• Responses are scoped to the client's licensed attributes
• Clients must not store or share API keys publicly
• Required domain allowlisting adds an extra layer of protection
• Foreign IPs and IPv6 are not supported to enforce regional compliance
• Raw email is never accepted, stored, logged, or returned — clients must hash emails before submission
• HEM values must not be logged or used in cache keys in their raw form; only the resolved MD5 hash is used internally

10. Support

Email: customersupport@resonate.com

For onboarding or attribute mapping help, include your client ID (provided by Resonate).

Appendix: Attribute key definitions

Each client will receive a definitions file mapping their survey value keys to friendly names and descriptions.