> ## Documentation Index
> Fetch the complete documentation index at: https://developers.candu.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Data into Candu via the 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.](https://app.candu.ai/settings/workspaces#access-keys)
You can then access the API using a `Authorization: Bearer` token.
```text theme={null}
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:`
```text theme={null}
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.
### Identify
To send attributes for a given user. Typically, things like name, email, organization, role in company.
```Text Batched Events theme={null}
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": "auser@example.com",
"location": "New York",
"isAdmin": true
},
"timestamp": "2025-04-22T15:58:02Z"
},
{
"type": "identify",
"userId": "[USER_ID]",
"traits": {
"email": "anotheruser@anotherexample.com",
"location": "London",
"isAdmin": false
},
"timestamp": "2025-04-22T15:58:02Z"
}
]'
```
```Text Single Event theme={null}
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": "auser@example.com",
"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.
### Group
To send attributes for a given group. Typically, things like name, industry, domain, email, employees.
```Text Batched Events theme={null}
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": "support@apple.com",
"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": "support@google.com",
"industry": "Technology",
"employees": 158,
"plan": "pro",
"total billed": 516
},
"timestamp": "2025-04-22T15:59:02Z"
}
]'
```
```Text Single event theme={null}
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": "support@apple.com",
"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. |
### Track
To track a custom event for a given user. These can be used in content targeting.
```text theme={null}
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 |