Version:

Activation API

Expose user profiles stored in your Redis instance over an API.

6 minute read

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.

You can sync all your customer 360 data from Profiles project to your Redis store. Then, use the Activation API endpoints to retrieve and use the enriched user data for personalization.

Prerequisites

You must have a working Redis instance in place to use this API.

Use Activation API

For the warehouse used for your Profiles project, create the RudderStack schema and grant permissions to it. Refer to the detailed steps for each warehouse:
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 > entities defines a feature_views property.

Enable Redis sync for using Activation API

Enter the account credentials for your Redis instance and click Create. This will also create a Redis destination in your dashboard.

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. See the User Management guide for more information.

Note your Redis destination ID from the Settings tab. Then, use the Get user profiles API endpoint to access your Redis instance and get user 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/v2/

Get user profiles

POST

/activation

Request body

entity

Required

String

Entity type

destinationId

Required

String

Redis destination ID.

Required

Object

ID containing type and value

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

Sample request

POST /v2/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/v2/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/v2/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

You will get the following response 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"
}

You will get the following response 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"
}

You will get the following response if the destination ID is present and valid:

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

You will get the following response if the destination ID is not present in Redis:

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

Delete user profiles

DELETE

/activation

Request body

entity

Required

String

Entity type

destinationId

Required

String

Redis destination ID.

Required

Object

ID containing type and value

Sample request

POST /v2/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/v2/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/v2/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

statusCode: 200
Response: {
  "deletedKeys": 20,
  "actualKeys": 30
}

statusCode: 400
Response: {
  "message": "id should have at least one item"
}

statusCode: 200
Response: {
  "message": "Internal server error"
}

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

You must have a working Redis instance in place before setting up the connection.

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 it in the Security section of the Configuration tab:

Cluster Mode: Turn on this setting if you’re connecting to a Redis cluster.
Secure: Enable this setting to secure the TLS communication between RudderStack Redis client and your Redis server.

Data mapping

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

The following pb_project.yaml snippet shows the sources to be created:

entities:
  - name: user
    id_types:
      - main_id
      - user_id
      - email
      - salesforce_id
    feature_views:
      using_ids:
        - id: email
          name: features_by_email # Optional. Takes default view name, if not specified.
        - id: salesforce_id
          name: salesforce_id_stitched_features

FAQ

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

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

New personal access token in RudderStack dashboard

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

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.

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
    id_types:
      - main_id
      - user_id
      - email
      - salesforce_id
    feature_views:
      name: user_feature_view
      using_ids:
        - id: email
          name: features_by_email
        - id: salesforce_id
          name: salesforce_id_stitched_features

Does RudderStack perform a full sync if I add a new feature to my project?

Yes, 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.

Activation API v1

Expose user profiles stored in your Redis instance over an API.

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Questions? Contact us by email or on Slack