Data Activation API documentation

This article covers the Data Activation REST API (version 1), including authentication, error handling, rate limiting, and the available API endpoints for data feeds, profiles, and journey orchestration.

Get started with the API

Data Activation uses HTTP Basic authentication over HTTPS. Unencrypted HTTP requests are rejected.

To authenticate, use your API identifier as the username and your access token as the password.

We recommend using a dedicated Data Activation account with full API permissions, linked to a generic email address and protected by a strong password.

When connecting to the REST API, use an HTTP persistent connection (also known as HTTP keep-alive or HTTP connection reuse). Use a single TCP connection to send and receive multiple HTTP requests and responses, instead of opening a new connection for every request.

If you need to insert special characters through the API, use UTF-8 encoding by including Content-type: application/json;charset=utf-8 in the header.

Note:
Data Activation also supports token-based (JWT) authentication, which you can configure through your user settings. This authentication method isn't modeled in the current OpenAPI spec. For details on generating and using API keys and access tokens, contact your assigned integration specialist or our support team at support@relay42.com.

Error handling

The following HTTP error codes may be returned by the API at runtime:

HTTP 400 — Bad Request: The process can continue, but store the HTTP request and URL endpoint because the generated request didn't match our specifications. The follow-up action is on your side. The record is ignored.
HTTP 401 — Unauthorized: Halt the process. The user isn't found for this site ID. Verify that you have the correct site ID or grant access to the user.
HTTP 403 — Forbidden: Halt the process. This code can have 3 causes:
1. The user doesn't have proper access to the functionality.
2. The account has been locked out due to inactivity.
3. The wrong credentials are used. This tends to lock API access for 15 minutes if tried multiple times (for example, programmatically).
HTTP 404 — Not Found: The process can continue. The system was unable to find and process the record. Store the HTTP request and URL endpoint. This shouldn't happen for POST requests but can occur for both GET and DELETE requests.
HTTP 429 — Rate Limit: Slow down the overall import process. A request with 429 isn't processed and should be retried. See the rate limiting section below.
HTTP 50x and other connection errors: The REST API can't handle the volume of HTTP requests. Pause the process incrementally (1 minute, 2 minutes, 4 minutes — up to 30 minutes). After each incremental step, resend the HTTP request. In most cases, the REST API returns an HTTP 200 or 201 OK response within 2 minutes. If the problem persists for more than 30 minutes, halt the process and notify our support team at support@relay42.com.

Note:
Individual endpoints declare a subset of these status codes (typically 200/201/204 for success and 401/403/404 for errors). The codes 400, 429, and 50x may also occur at runtime even though they aren't explicitly declared in the OpenAPI spec.

Rate limiting

The rate limit is the total number of requests (not only API calls) that Data Activation processes. The rate limit value depends on your contract. Contact your consultant or reach out to our support team at support@relay42.com to learn your exact rate limit.

To properly handle the rate limit, provision your script with exponential back-off. The script should react by slowing itself down until 429 responses stop being returned, and can try to speed up in a similar way.

Examples:

A GET request always counts as 1 call toward the rate limit.
A POST with 2 facts counts as 3 requests: 1 API call + 2 fact updates.

Data feeds

Data feeds are used to generate dynamic content. The /datafeeds namespace contains all operations you can execute on a data feed. Each feed is identified by a feedPrefix that must match the value entered in the user interface.

Get multiple data feed entries

Retrieve multiple data feed entries by key.

Endpoint: GET /v1/site-{siteNumber}/datafeeds/{feedPrefix}/entries

Path parameters:

feedPrefix (required): The prefix identifying the data feed.

Query parameters:

key (required, array of strings): Comma-separated list of entry keys to retrieve.

Responses:

200: An object mapping each key to its properties (key-value pairs of strings).
401: Unauthorized.
403: Forbidden.
404: Not found.

Get a single data feed entry

Retrieve a single data feed entry by key.

Endpoint: GET /v1/site-{siteNumber}/datafeeds/{feedPrefix}/entries/{itemKey}

Path parameters:

feedPrefix (required): The prefix identifying the data feed.
itemKey (required): The key of the entry to retrieve.

Responses:

200: The entry's properties as key-value pairs.
401: Unauthorized.
403: Forbidden.
404: Not found.

Insert a single data feed entry

Insert or update a single data feed entry.

Endpoint: POST /v1/site-{siteNumber}/datafeeds/{feedPrefix}/entries/{itemKey}

Path parameters:

feedPrefix (required): The prefix identifying the data feed.
itemKey (required): The key of the entry to insert.

Query parameters:

ttl (optional, integer): The time to live (TTL) in seconds. Valid range: 60–630,720,000.

Request body (application/json):

A DataFeedValuesContainer object with a values property containing key-value pairs:

{
  "values": {
    "property1": "string",
    "property2": "string"
  }
}

Responses:

201: Created — new record is created.
401: Unauthorized — proper credentials weren't provided.
403: Forbidden — you don't have access to this API method.
404: Not found.

Delete a single data feed entry

Delete a single data feed entry by key.

Endpoint: DELETE /v1/site-{siteNumber}/datafeeds/{feedPrefix}/entries/{itemKey}

Path parameters:

feedPrefix (required): The prefix identifying the data feed.
itemKey (required): The key of the entry to delete.

Responses:

204: No content — the entry was deleted.
401: Unauthorized.
403: Forbidden.
404: Not found.

Profiles

When you need to update a profile using several requests, make the requests synchronous to avoid profile duplicates. For example, when inserting offline facts and mappings from your CRM, first POST facts based on your CRM ID, get the profileId from the response, and use this profile ID (partner type 42) for the POST mappings request.

If multiple events occur for the same customer, you can submit a single request that includes all corresponding events within the interactions array.

Date properties: The suggested date format is YYYY-MM-DD HH:mm, this is the default date-time format in Data Activation, but you can modify it if necessary. If you use a custom format, the end user must update the date-time format in all audiences and journey steps.

The forceInsert option: The forceInsert parameter (boolean) forces the system to present the profile to the audience engine. The default value is false, meaning the profile is only presented to the audience engine for a given fact name when there's a change in properties or TTL compared to the previous fact insertion. If you have frequent profile updates and infrequent duplicate calls, you can set forceInsert to true. Note that forceInsert also resets the TTL for already-existing facts, which is important for facts with retention periods managed outside of Data Activation.

When accessing a profile, each endpoint requires both a partnerType and a partnerId. The partner type for Data Activation IDs is 42. For other partners, use the partner number as configured in the ID-matching process.

Get raw facts for a profile

Retrieve all raw facts for a profile.

Endpoint: GET /v1/site-{siteNumber}/profiles/{partnerType}/facts

Path parameters:

partnerType (required): The partner type identifier.

Query parameters:

partnerId (required): The partner ID value.

Responses:

200: The profile's facts.
401: Unauthorized.
403: Forbidden.
404: Not found — profile doesn't exist.

Add raw facts to a new or existing profile

Add a set of raw facts to a profile, creating the profile if it doesn't exist (virtual profile). This operation triggers a re-evaluation of the profile.

Endpoint: POST /v1/site-{siteNumber}/profiles/{partnerType}/facts

Path parameters:

partnerType (required): The partner type identifier.

Query parameters:

partnerId (required): The partner ID value.
forceInsert (optional, boolean, default: false): When false, duplicate facts aren't updated in the backend, reducing server load. When true, the fact is updated regardless of whether it already exists.
renewMappingTtl (optional, boolean): When true, renews the TTL for existing mappings on the profile.

Request body (application/json):

An array of FactAddRequest objects, each containing:

factName (required, string): The name used for the fact (external fact in the interface).
factTtl (required, integer): The TTL of the fact in seconds. Valid range: 60–504,576,000.
properties (optional, object): A key-value map of properties for the fact. Maximum of 64 properties.

Example request:

[
  {
    "factName": "string",
    "factTtl": 60,
    "properties": {}
  }
]

Responses:

201: Created — new record is created.
401: Unauthorized — proper credentials weren't provided.
403: Forbidden — you don't have access to this API method.
404: Not found.

Update raw facts on an existing profile

Update a set of raw facts on an existing profile. Unlike POST, this operation returns a 404 if the profile doesn't exist (no auto-creation). This operation triggers a re-evaluation of the profile.

Endpoint: PUT /v1/site-{siteNumber}/profiles/{partnerType}/facts

Path parameters:

partnerType (required): The partner type identifier.

Query parameters:

partnerId (required): The partner ID value.
forceInsert (optional, boolean, default: false): Same behaviour as POST.
renewMappingTtl (optional, boolean): When true, renews the TTL for existing mappings on the profile.

Request body: Same as POST (array of FactAddRequest objects with required factName and factTtl).

Responses:

201: Created — facts updated.
401: Unauthorized.
403: Forbidden.
404: Not found — the profile doesn't exist.

Delete raw facts from a profile

Delete a set of raw facts from a profile. This operation triggers a re-evaluation of the profile.

Endpoint: DELETE /v1/site-{siteNumber}/profiles/{partnerType}/facts

Path parameters:

partnerType (required): The partner type identifier.

Query parameters:

partnerId (required): The partner ID value.
fact (required): The fact(s) to delete.

Example request:

curl -X DELETE --header 'Accept: */*' \

  'https://api.relay42.com/v1/<SiteID>/profiles/42/facts?partnerId=4ccee44e-5cea-457e-a94d-fc7ed086ae6f&fact=%5B%22FactName%22%5D'

Responses:

204: No content — the facts were deleted.
401: Unauthorized.
403: Forbidden.
404: Not found — the record doesn't exist.

Add interactions to a new or existing profile

Add a set of interactions to a profile, creating the profile if it doesn't exist. This operation follows normal interaction processing.

Endpoint: POST /v1/site-{siteNumber}/profiles/{partnerType}/interactions

Path parameters:

partnerType (required): The partner type identifier.

Query parameters:

partnerId (required): The partner ID value.

Request body (application/json):

An object containing an interactions array. Each interaction is defined by the interactionType property. The available interaction types and their properties are:

bannerView: identifier, subIdentifier, referral
conversion: transactionId, value, products (list), variables (map)
engagement: type, content, variables (map)
experimentMatch: experimentGroupNumber, experimentNumber
pageView: url, source
sessionStart: url, source
userPreferences: optOutRemarketing, optOutAdapting
sync: partnerNumber, partnerCookie, mergeType
thirdPartySync: partnerNumber, partnerCookie
externalFact: type, ttl, forceInsert, variables (map), operationType (one of INSERT, REMOVE)

Example request:

{
  "interactions": [
    {
      "interactionType": "engagement",
      "type": "productView",
      "variables": {
        "productId": "1234",
        "category": "sports"
      }
    }
  ]
}

Responses:

201: Created — new record is created.
401: Unauthorized — proper credentials weren't provided.
403: Forbidden — you don't have access to this API method.
404: Not found.

Update interactions on an existing profile

Update a set of interactions on an existing profile. Unlike POST, this operation returns a 404 if the profile doesn't exist (no auto-creation).

Endpoint: PUT /v1/site-{siteNumber}/profiles/{partnerType}/interactions

Path parameters:

partnerType (required): The partner type identifier.

Query parameters:

partnerId (required): The partner ID value.

Request body: Same as POST (object with interactions array).

Responses:

201: Created — interactions updated.
401: Unauthorized.
403: Forbidden.
404: Not found — the profile doesn't exist.

Get mappings for a profile

Retrieve all ID mappings for a user profile.

Endpoint: GET /v1/site-{siteNumber}/profiles/{partnerType}/mappings

Path parameters:

partnerType (required): The partner type identifier.

Query parameters:

partnerId (required): The partner ID value.

Example request:

curl -X GET --header 'Accept: application/json' \

  'https://api.relay42.com/v1/<SiteID>/profiles/<partnerType>/mappings?partnerId=<partnerId>'

Responses:

200: The profile's ID mappings.
401: Unauthorized.
403: Forbidden.
404: Not found.

Add ID mappings to a profile

Add a list of ID mappings to a profile for the specified partner ID.

Endpoint: POST /v1/site-{siteNumber}/profiles/{partnerType}/mappings

The API also supports PUT for this operation. Both methods have the same payload and behaviour.

Path parameters:

partnerType (required): The partner type identifier.

Query parameters:

partnerId (required): The partner ID value.
mergeType (optional, string, default: NO_MERGE): Options are NO_MERGE (profiles won't get merged), SITE (profiles will get merged), or MERGE_NO_OVERRIDE (profiles will be safe-merged).

Request body (application/json):

An array of mapping objects, each containing:

partnerId (required, string): The value of the partner cookie.
partnerType (required, integer): The identifier used for the partner (for example, 42 is the internal cookie).

Example request:

[
  {
    "partnerId": "string",
    "partnerType": 0
  }
]

Responses:

201: Created — mappings added. Returns a ProfileMappingResponse.
401: Unauthorized.
403: Forbidden.
404: Not found.

Delete mappings from a profile

Remove a list of ID mappings from a profile.

Endpoint: DELETE /v1/site-{siteNumber}/profiles/{partnerType}/mappings

Path parameters:

partnerType (required): The partner type identifier.

Query parameters:

partnerId (required): The partner ID value.

Request body (application/json):

An array of mapping objects to delete, each containing:

partnerId (required, string): The value of the partner cookie.
partnerType (required, integer): The identifier used for the partner.

Responses:

204: No content — the mappings were deleted.
401: Unauthorized.
403: Forbidden.
404: Not found.

Get ID mappings for a specific partner

Retrieve a list of IDs mapped to a profile for a specific partner.

Endpoint: GET /v1/site-{siteNumber}/profiles/{partnerType}/mappings/{mappingPartnerType}

Path parameters:

partnerType (required): The partner type identifier.
mappingPartnerType (required): The partner type to retrieve mappings for.

Query parameters:

partnerId (required): The partner ID value.

Example request:

curl -X GET --header 'Accept: application/json' \

  'https://api.relay42.com/v1/<SiteID>/profiles/<partnerType>/mappings/<mappingPartnerType>?partnerId=<partnerId>'

Responses:

200: The mappings for the specified partner.
401: Unauthorized.
403: Forbidden.
404: Not found.

Delete a profile

Delete all data for a profile.

Endpoint: DELETE /v1/site-{siteNumber}/profiles/{partnerType}/profile

Path parameters:

partnerType (required): The partner type identifier.

Query parameters:

partnerId (required): The partner ID value.

Example request:

curl -X DELETE --header 'Accept: application/json' \

  'https://api.relay42.com/v1/<SiteID>/profiles/<partnerType>/profile?partnerId=<partnerId>'

Responses:

204: No content — the profile was deleted.
401: Unauthorized.
403: Forbidden.
404: Not found.

Get the profile ID for a user

Retrieve the profile ID for a user.

Endpoint: GET /v1/site-{siteNumber}/profiles/{partnerType}/profileId

Path parameters:

partnerType (required): The partner type identifier.

Query parameters:

partnerId (required): The partner ID value.

Example request:

curl -X GET --header 'Accept: application/json' \

  'https://api.relay42.com/v1/<SiteID>/profiles/<partnerType>/profileId?partnerId=<partnerId>'

Responses:

200: The profile ID.
401: Unauthorized.
403: Forbidden.
404: Not found.

Get segments for a profile

Retrieve the segments a user belongs to.

Endpoint: GET /v1/site-{siteNumber}/profiles/{partnerType}/segments

Path parameters:

partnerType (required): The partner type identifier.

Query parameters:

partnerId (required): The partner ID value.

Example request:

curl -X GET --header 'Accept: application/json' \

  'https://api.relay42.com/v1/<SiteID>/profiles/<partnerType>/segments?partnerId=<partnerId>'

Responses:

200: The segments the profile belongs to.
401: Unauthorized.
403: Forbidden.
404: Not found.

Get a specific segment for a profile

Retrieve data for a specific segment by segment name.

Endpoint: GET /v1/site-{siteNumber}/profiles/{partnerType}/segments/{segmentName}

Path parameters:

partnerType (required): The partner type identifier.
segmentName (required): The name of the segment.

Query parameters:

partnerId (required): The partner ID value.

Example request:

curl -X GET --header 'Accept: */*' \

  'https://api.relay42.com/v1/<SiteID>/profiles/<partnerType>/segments/<segmentName>?partnerId=<partnerId>'

Responses:

200: The segment data for the profile.
401: Unauthorized.
403: Forbidden.
404: Not found.

Journey orchestration

The journey orchestration namespace allows you to retrieve information about a profile's position within journeys, access journey variables, and activate connectors.

Get the current journey step for a profile

Retrieve the current journey step for a given partner type and partner number within a specific journey.

Endpoint: GET /v1/site-{siteNumber}/journeyorchestration/{journeyId}/{partnerType}

Path parameters:

journeyId (required): The journey ID for which to retrieve the journey step.
partnerType (required): The partner type identifier.

Query parameters:

partnerId (required): The partner ID value.

Example request:

curl -X GET --header 'Accept: */*' \

  'https://api.relay42.com/v1/<SiteID>/journeyorchestration/<journeyId>/<partnerType>?partnerId=<partnerId>'

Responses:

200: The current journey step.
401: Unauthorized.
403: Forbidden.
404: Not found.

Get the current journey step with variables

Retrieve the current journey step and its associated variables for a given partner type and partner number within a specific journey.

Endpoint: GET /v1/site-{siteNumber}/journeyorchestration/{journeyId}/{partnerType}/stepvariables

Path parameters:

journeyId (required): The journey ID.
partnerType (required): The partner type identifier.

Query parameters:

partnerId (required): The partner ID value.

Responses:

200: A StepJourneyVariables object containing the step ID and variables.
401: Unauthorized.
403: Forbidden.
404: Not found.

Get all journeys and steps for a profile

Retrieve all journeys and steps for a given partner type and partner number.

Endpoint: GET /v1/site-{siteNumber}/journeyorchestration/{partnerType}

Path parameters:

partnerType (required): The partner type identifier.

Query parameters:

partnerId (required): The partner ID value.

Example request:

curl -X GET --header 'Accept: application/json' \

  'https://api.relay42.com/v1/<SiteID>/journeyorchestration/<partnerType>?partnerId=<partnerId>'

Responses:

200: All journeys and steps for the profile.
401: Unauthorized.
403: Forbidden.
404: Not found.

Get journey variables

Retrieve journey variables for a profile. If journeyId is omitted, variables for all journeys are returned.

Endpoint: GET /v1/site-{siteNumber}/journeyorchestration/variables

Query parameters:

partnerId (required): The partner ID value.
partnerType (required): The partner type identifier.
journeyId (optional): A specific journey ID. If omitted, returns variables for all journeys.

Responses:

200: An array of JourneyVariables objects, each containing a journey ID and its variables.
401: Unauthorized.
403: Forbidden.
404: Not found.

Activate a connector

Activate a connector for a specific profile. You can optionally restrict the activation scope to specific journeys and steps.

Endpoint: POST /v1/site-{siteNumber}/journeyorchestration/{partnerType}/mappings/activate

Path parameters:

partnerType (required): The partner type identifier.

Query parameters:

partnerId (required): The partner ID value.

Request body (application/json):

A ConnectorActivationRequest object containing:

connectorId (required, UUID): The ID of the connector to activate.
journeyFilters (optional, array): A list of filters to restrict the activation scope. Each filter contains:
- journeyId: The journey ID.
- stepId: The step ID within the journey.

Responses:

202: Accepted — the connector activation request has been accepted.
401: Unauthorized.
403: Forbidden.
404: Not found.