Integrate Candu via REST API

Candu's REST API can be used to make data available for content targeting and customization. See our guide on how to use this data in segmentation.

Authentication

Candu uses Token Bearer authentication via the HTTP Authentication header. To authenticate with Candu's API, you need to access your API KEY from your workspace settings.

You can then access the API using a Authorization: Bearer token.

curl -X GET \
 https://api.candu.ai/api/contentMetadata \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer [ADD_YOUR_API_KEY_HERE]

For example if your API key is TestAPIKey:

curl -X GET \
  https://api.candu.ai/api/contentMetadata \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer TestApiKey'

/api/eventWebhook

User traits and events can be sent into candu via our inbound webhook.

Group

To send attributes for a given group. Typically, things like name, industry, domain, email, employees.

curl -X POST \
  https://api.candu.ai/api/eventWebhook \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer [YOUR_API_KEY]' \
  --data '[
    {
      "type": "group",
      "groupId": "[GROUP_ID]",
      "userId": "[USER_ID]",
      "traits": {
        "name": "Apple",
        "domain": "apple.com",
        "email": "[email protected]",
        "industry": "Technology",
        "employees": 329,
        "plan": "enterprise",
        "total billed": 830
      },
      "timestamp": "2025-04-22T15:58:02Z"
    },
    {
      "type": "group",
      "groupId": "[GROUP_ID]",
      "userId": "[USER_ID]",
      "traits": {
        "name": "Google",
        "domain": "google.com",
        "email": "[email protected]",
        "industry": "Technology",
        "employees": 158,
        "plan": "pro",
        "total billed": 516
      },
      "timestamp": "2025-04-22T15:59:02Z"
    }
  ]'

curl -X POST \
  https://api.candu.ai/api/eventWebhook \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer [YOUR_API_KEY]' \
  --data '
    {
      "type": "group",
      "groupId": "[GROUP_ID]",
      "userId": "[USER_ID]",
      "traits": {
        "name": "Apple",
        "domain": "apple.com",
        "email": "[email protected]",
        "industry": "Technology",
        "employees": 329,
        "plan": "enterprise",
        "total billed": 830
      },
      "timestamp": "2025-04-22T15:58:02Z"
    }'

Field	Required?	Description
type	yes	The type of tracking event. In this case, "Group".
groupId	yes	A unique identifier for the group we wish to create or update.
userId	no	If present, also adds the user to the given group.
traits	no	A dictionary map of group properties. Boolean, numbers, strings values are supported. For dates, we recommend using the ISO 8601 format (with the seconds and Z for timezone).'
timestamp	no	Defaults to the current time.

Identify

To send attributes for a given user. Typically, things like name, email, organization, role in company.

curl -X POST \
  https://api.candu.ai/api/eventWebhook \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer [YOUR_API_KEY]' \
  --data '[
    {
      "type": "identify",
      "userId": "[USER_ID]",
      "traits": {
        "email": "[email protected]",
        "location": "New York",
        "isAdmin": true
      },
      "timestamp": "2025-04-22T15:58:02Z"
    },
    {
      "type": "identify",
      "userId": "[USER_ID]",
      "traits": {
        "email": "[email protected]",
        "location": "London",
        "isAdmin": false
      },
      "timestamp": "2025-04-22T15:58:02Z"
    }
  ]'

curl -X POST \
  https://api.candu.ai/api/eventWebhook \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer [YOUR_API_KEY]' \
  --data '
    {
      "type": "identify",
      "userId": "[USER_ID]",
      "traits": {
        "email": "[email protected]",
        "location": "New York",
        "isAdmin": true
      },
      "timestamp": "2025-04-22T15:58:02Z"
    }
  '

Field	Required?	Description
type	yes	The type of tracking event. In this case, "identify".
userId	yes	The user ID we wish to update.
traits	yes	A dictionary map of user properties. Strings, numbers and boolean values are supported. For dates, we recommend using the ISO 8601 format (with the seconds and Z for timezone).'
timestamp	no	Defaults to the current time.

The response will be:

204 (No Content) for correct events submission and handling.
400 (Bad Request) for malformed events submission, with a list of the malformed events.
- In case of batched events, none of the correct events will be handled either.
500 (Internal Server Error) for errors in the handling of one of the events.

Track

To track a custom event for a given user. These can be used in content targeting.

curl -X POST \
  https://api.candu.ai/api/eventWebhook \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer [YOUR_API_KEY]' \
  --data '
    {
      "type": "track",
      "userId": "[USER_ID]",
      "event": "Upgraded plan",
      "properties": {
        "amountPaidInUSD": 30,
        "newPlan": "Business+"
      },
      "timestamp": "2022-01-20T11:21:02Z"
    }
  '

Field	Required?	Description
type	yes	The type of tracking event. In this case, "track"
userId	yes	The ID of the user the event belongs to
event	yes	The name of the event
properties	no	A dictionary map of event properties. Strings, numbers and boolean values are supported.
timestamp	no	Timestamp the event occurred. Defaults to the current time