API reference
Consent
Consent topics of the workspace and each person's choices.
Consent topics of the workspace and each person's choices.
GET /v1/consent-topics#
List consent topics
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
scopeId | query | string (uuid) or "none" | |
after | query | string (uuid) | |
limit | query | integer |
curl -X GET "$SAPAGAN_URL/v1/consent-topics" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/consent-topics`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"topics": [
{
"id": "user-42",
"scopeId": "<scopeId>",
"key": "<key>",
"name": "order_placed",
"channel": "push",
"mode": "opt_in",
"createdAt": "<createdAt>"
}
],
"next": "<next>"
}POST /v1/consent-topics#
Create a consent topic (workspace keys only)
marketing and seller_marketing are reserved (400 topic_key_reserved): the engine creates them.
Request body
| Field | Type | Notes |
|---|---|---|
scopeId | string (uuid) or null | |
key required | string | |
name required | string | min 1, max 200 |
channel | "push" | "email" | "inbox" | "webhook" | "whatsapp" or null | |
mode required | "opt_in" | "opt_out" |
curl -X POST "$SAPAGAN_URL/v1/consent-topics" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"key": "<key>",
"name": "order_placed",
"mode": "opt_in"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/consent-topics`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"key": "<key>",
"name": "order_placed",
"mode": "opt_in"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"scopeId": "<scopeId>",
"key": "<key>",
"name": "order_placed",
"channel": "push",
"mode": "opt_in",
"createdAt": "<createdAt>"
}GET /v1/customers/{id}/consent#
Read a customer's consent
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/customers/user-42/consent" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/customers/user-42/consent`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"unsubscribedAt": "<unsubscribedAt>",
"topics": [
{
"topicId": "<topicId>",
"scopeId": "<scopeId>",
"key": "<key>",
"name": "order_placed",
"mode": "opt_in",
"granted": true,
"source": "<source>",
"grantedAt": "<grantedAt>",
"revokedAt": "<revokedAt>",
"updatedAt": "<updatedAt>"
}
]
}PUT /v1/customers/{id}/consent#
Grant or revoke a customer's consent (workspace keys only)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
source required | "settings" | "support" | "import" | "preference_center" | |
ip | any (ipv4) or any (ipv6) | |
userAgent | string | max 1000 |
topics | object[] | up to 100 items |
topics[].scopeId required | string (uuid) or null | |
topics[].key required | string | |
topics[].granted required | boolean | |
unsubscribed | boolean |
curl -X PUT "$SAPAGAN_URL/v1/customers/user-42/consent" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"source": "settings",
"unsubscribed": false
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/customers/user-42/consent`, {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"source": "settings",
"unsubscribed": false
}),
});
const data = await res.json();Responses
{
"unsubscribedAt": "<unsubscribedAt>",
"topics": [
{
"topicId": "<topicId>",
"scopeId": "<scopeId>",
"key": "<key>",
"name": "order_placed",
"mode": "opt_in",
"granted": true,
"source": "<source>",
"grantedAt": "<grantedAt>",
"revokedAt": "<revokedAt>",
"updatedAt": "<updatedAt>"
}
]
}