Version: Latest (0.11)0.100.9.40.9.30.9.10.9.00.8.0

Activation API (Early Access)

The Activation API is part of our Early Access Program, where we work with users and customers to test new features and get feedback before making them generally available. These features are fully functional but can change as we improve them. We recommend connecting with our team before running them in production.

Contact us if you would like access to this feature.

With RudderStack’s Activation API, you can fetch enriched user traits stored in your Redis instance and use them for near real-time personalization for your target audience.

Overview

A brief summary of how the Activation API works:

1. Sync all your customer 360 data from your Profiles project to your Redis store.
2. The Activation API sits on top of this Redis instance and provides endpoints for retrieving and using the enriched user data for personalization.

How to use the Activation API

1. Use your Profiles project to create a 360-degree view of the features stored in your data warehouse.
2. In your Profiles project settings, scroll down to Activation API and turn on the Enable sync to Redis toggle.

Before you enable the Activation API toggle, make sure that:

• You have at least one successful Profiles run.
• Your pb_project.yaml > entites defines a serve_traits property.

Also, note that the first time you toggle on this API, RudderStack requests for your Redis credentials of the Profiles Redis store.

3. Generate a personal access token with Admin role in your RudderStack dashboard. You will need this token for authenticating the Activation API.

Personal access token with an Admin role is only available to the Org Admin users. Refer User management guide for more information.

4. Note the Redis destination ID. See FAQ for more information on obtaining this ID.
5. Use the Activation API endpoint to access your Redis instance and get user data.

See Use case for more information on how you can use this data.

Authorization

This API uses Bearer Authentication for authenticating all requests.

Set the personal access token as the bearer token for authentication.

Base URL

https://profiles.rudderstack.com/v1/

Get user profiles

Request body

{
  "entity": <entity_type>,  // User, project, account, etc.
  "destinationId": <redis_destination_id> , // Redis destination ID
  "id": {
    "type": <id_type>,
    "value": <id_value>
  }
}

Example request

POST /v1/activation HTTP/1.1
Host: profiles.rudderstack.com
Content-Type: application/json
Authorization: Bearer <personal_access_token>
Content-Length: 90

{
 "entity": <entity_type>,
 "destinationId": <redis_destination_id>, // Redis destination ID
 "id": {
   "type": <id_type>,
   "value": <id_value>
 }
}

curl --location 'https://profiles.rudderstack.com/v1/activation' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <personal_access_token>' \
--data '{
 "entity": <entity_type>,
 "destinationId": <redis_destination_id>, // Redis destination ID
 "id": {
   "type": <id_type>,
   "value": <id_value>
 }
}'

const axios = require('axios');
let data = JSON.stringify({
  "destinationId": <redis_destination_id>,
  "entity": <entity_type>,
  "id": {
    "type": <id_type>,
    "value": <id_value>
  }
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://profiles.rudderstack.com/v1/activation',
  headers: {
    'Content-Type': 'application/json',
    'authorization': 'Bearer <personal_access_token>'
  },
  data: data
};

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

Responses

• If the personal access token is absent or trying to access a destination to which it does not have access:

statusCode: 401
Response: {
  "error": "Unauthorized request. Please check your access token"
}

• If the destination is not Redis or the destination ID is absent/blank:

statusCode: 404
Response: {
  "error": "Invalid Destination. Please verify you are passing the right destination ID"
}

• If ID is present:

statusCode: 200
Response:
{
  "entity": <entity_type>,
  "id": {
    "type": <id_type>,
    "value": <id_value>
  },
  "data": {
    <traits_from_Redis>
  }
}

• If ID is not present in Redis:

statusCode: 200
Response:
{
  "entity": <entity_type>,
  "id": {
    "type": <id_type>,
    "value": <id_value>
  },
  "data": {}
}

Use case

You can use the Activation API for real-time personalization. Once you fetch the user traits from your Redis instance via the API, you can pull them into your client application to alter the application behavior in real-time based on user interactions.

You can respond immediately with triggered, user-focused messaging based on actions like page views or app clicks and provide a better customer experience.

Redis configuration

This section describes the settings required to set up a Reverse ETL connection from your warehouse (containing the project’s output table) to the Redis destination in RudderStack.

• Address: Enter the public endpoint of your Redis database. If you are using Redis Cloud, you can find this endpoint by going to your Redis database and navigating to Configuration tab > General.

You can also use Amazon ElastiCache for Redis to set up your Redis database. See the ElastiCache documentation to get started.

• Password: Enter the database password. You can find the password in the Security section of the Configuration tab:

• Database: Enter the database name.
• Cluster Mode: Disable this setting if you haven’t set up Redis in a cluster.

Data mapping

RudderStack creates multiple Reverse ETL sources automatically based on your Profiles project. You will see separate sources for different id_served connected to the same Redis destination.

The following pb_project.yaml snippet shows the sources to be created. RudderStack syncs the customer 360 features to different tables in Redis indexed by id_served.

entities:
  - name: user
    serve_traits:
      - id_served: user_id
      - id_served: anonymous_id
      - id_served: email
      - id_served: cart_token
      - id_served: rudder_id

FAQ

How do I generate a personal access token to use the Activation API?

1. Log in to your RudderStack dashboard.
2. Go to Settings > Your Profile > Account tab and scroll down to Personal access tokens. Then, click Generate new token:

3. Enter the Token name. Set Role to Admin and click Generate.

4. Use the personal access token to authenticate to the Activation API.

Save the generated token securely as it will not be visible again once you close this window.

Where can I find the Redis destination ID?

1. Set up a Redis destination in RudderStack.
2. Go to the Settings tab of your destination to see the Destination ID:

How can I make Profiles work with the Activation API?

To use the Activation API with your Profiles project, you need a successful run of your Profiles project that is not past the retention period.

To enable the Activation API for your Profiles project, turn on the Enable sync to Redis setting. A Profile run will then sync automatically.

Why am I getting an error trying to enable API in my instance for a custom project hosted on GitHub?

For GitHub projects, you need to explicitly add the IDs of the custom project that need to be served.

In your pb_project.yaml file, you can specify them as shown:

entities:
  - name: user
    serve_traits:
      - id_served: user_id
      - id_served: anonymous_id
      - id_served: email
      - id_served: cart_token
      - id_served: user_main_id

If I force a full resync, stop it, and then start a new sync, does RudderStack always perform a full sync the next time?

It depends on the state of the task when it was canceled.

• If the sync is cancelled while RudderStack is preparing a snapshot, then next run depends on the state of the previous successful run and any mapping changes.
• If it is cancelled after the sync data is prepared, the next run is incremental.

Generally if a sync is cancelled manually, it is recommended to trigger a full sync if the previous cancelled task was a full sync. If the previously cancelled sync was incremental, triggering an incremental sync is recommended.

Does RudderStack perform a full sync if I add a new column?

RudderStack does not change the sync mode if you make any column additions. It triggers a full sync only if you change/update the data mappings, for example, if the newly added column is sent to the destination via the Visual Data Mapper.

For Profiles activation syncs, RudderStack updates the mappings and automatically sends all columns from the customer 360 view by triggering a full sync.

Suppose I’m running a full sync and the Profiles job is running in parallel and finishes eventually. What happens to the scheduled sync? Does it get queued?

RudderStack first creates a temporary snapshot copy of any sync when it starts. So its syncing the created copy. Even if a Profiles job is running in parallel, the sync - if started - is not impacted by it.

Questions? Contact us by email or on Slack