Resonate Real-Time API FAQ

Covers IP and HEM (Hashed Email) identifier support. 

In this article

Authentication and Access

• What authentication method does the API use?
• How do I update or rotate my API key?
• How many attributes can I get delivered via API?

Identifier Types (IP and HEM)

• What identifier types does the API support?
• How do I submit a HEM vs. an IP address?
• What are the formatting requirements for HEM inputs?
• Can I submit a raw email address?

Request and Response Format

• What are the request and response formats?
• What does a typical attributes response look like?
• How do null values work in the response?

Error Codes and Handling

• What error codes should we expect and how do we handle them?

Data, Caching, and Regions

• How often is the data updated?
• Can we cache API responses?
• What regions does the API support?
• Is there a test environment or sandbox?

Privacy and Data Handling

• How does the API handle hashed email data?
• Are attribute results shared across customers?

Integration and Onboarding

• Which hash type should I use — MD5, SHA1, or SHA256?
• Are there any limitations on what can be submitted per request?
• Who should I contact if I have questions during integration?

Authentication and Access

What authentication method does the API use?

The API uses an API key passed through the request header:

X-API-KEY: <your-api-key>

Your API key controls which identifier types (e.g., IP, HEM) and data outputs (attributes, predictive models) are available to your account. If you are unsure what is enabled for your key, contact your Customer Success Manager.

How do I update or rotate my API key?

Contact your Customer Success Manager. A new key can be generated if your existing key has been compromised or your internal protocols require rotation. Key rotation is supported up to once per year.

How many attributes can I get delivered via API?

Customers can select 25 attributes at the attribute name level, which includes all attribute values (answers) to the attribute name (question). Limitations on attributes are enforced for API performance.

Identifier Types (IP and HEM)

What identifier types does the API support?

Only one identifier may be submitted per request.

How do I submit a HEM vs. an IP address?

The API uses different request methods depending on the identifier type:

• IP lookups use a GET request. If no identifier is provided, the API automatically uses the IP address of the incoming request.
• HEM lookups use a POST request with the identifier in the JSON request body.

GET — IP (default):

GET /v1/personalization

POST — HEM MD5:

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

POST — HEM SHA1:

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

POST — HEM SHA256:

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

What are the formatting requirements for HEM inputs?

Each HEM type has a specific required format. Submitting a value that does not meet the validation criteria will return a 400 error.

• HEM_MD5: exactly 32 lowercase hexadecimal characters
• HEM_SHA1: exactly 40 lowercase hexadecimal characters
• HEM_SHA256: exactly 64 lowercase hexadecimal characters

To avoid match rate issues, ensure your hashes are produced from a normalized email: trimmed of whitespace and lowercased before hashing. Inconsistent normalization is one of the most common causes of low match rates.

Can I submit a raw email address?

No. The API does not accept raw email addresses. You must hash the email before submitting. Any of the three supported hash types (MD5, SHA1, or SHA256) are accepted.

When producing a hash, normalize the email first by trimming whitespace and converting to lowercase before applying the hash function. This ensures your hash matches what is in our system.

Request and Response Format

What are the request and response formats?

All requests use HTTPS and return JSON responses. IP lookups use GET; HEM lookups use POST with a JSON body containing the identifier type and value.

What does a typical attributes response look like?

The response includes the identifier type used for the lookup, a timestamp of when the data was last updated, and a map of attribute IDs to values.

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

Attribute values:

• 1 — attribute applies to this individual
• 0 — attribute does not apply
• null — data present but redacted

How do null values work in the response?

A null value for an attribute indicates that data has been redacted for that identifier. It does not mean the attribute is absent from our data set.

Error Codes and Handling

What error codes should we expect and how do we handle them?

Always verify that the response body is not undefined before attempting to parse it. If you encounter persistent errors, contact your Customer Success Manager.

Data, Caching, and Regions

How often is the data updated?

Attribute data is refreshed on a bi-monthly basis.

Can we cache API responses?

Yes, and it is recommended. The API includes server-side caching to optimize performance. Clients should also implement their own response caching with a TTL of 1 day to reduce latency and minimize unnecessary API calls.

What regions does the API support?

The API supports requests made from within the United States only. Requests originating from outside the US will be rejected and will return a 204 response.

Is there a test environment or sandbox?

A dedicated sandbox is not currently available. If you need support validating your integration, reach out to your Customer Success Manager — we're happy to work with you during onboarding.

Privacy and Data Handling

How does the API handle hashed email data?

The API accepts only pre-hashed email values — raw email addresses are never submitted to or processed by the API. Hashing should be performed on your side before making the API call. To maximize match rates, ensure emails are normalized (trimmed and lowercased) before hashing.

Are attribute results shared across customers?

Attribute data is derived from Resonate's shared data set and licensed by contract. It is non-account-specific and available to all customers with appropriate entitlements.

Integration and Onboarding

Which hash type should I use — MD5, SHA1, or SHA256?

All three are supported, so you can use whichever your system already produces. There is no need to convert between hash types before submitting.

Regardless of which type you use, always normalize the email before hashing: trim leading and trailing whitespace, convert the email to lowercase, then apply your hash function. Skipping normalization is the most common cause of hash mismatches and reduced match rates.

Are there any limitations on what can be submitted per request?

Yes. Only one identifier may be submitted per request. Submitting multiple identifiers in a single call is not supported. Batch processing is also not available in the current version of the API.

Who should I contact if I have questions during integration?

Your Customer Success Manager is your primary point of contact for integration support, API key configuration, and questions about your account entitlements. For technical issues encountered during a live integration, your CSM can also connect you with our technical team.