API reference
Segments
Saved audiences built from conditions, with live counts.
Saved audiences built from conditions, with live counts.
GET /v1/segments#
List the workspace's segments, newest first
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
includeArchived | query | "true" | "false" | |
after | query | string (uuid) | |
limit | query | integer |
curl -X GET "$SAPAGAN_URL/v1/segments" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/segments`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"segments": [
{
"id": "user-42",
"name": "order_placed",
"description": "<description>",
"definition": null,
"version": 1,
"createdBy": "<createdBy>",
"updatedBy": "<updatedBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"archivedAt": "<archivedAt>"
}
],
"next": "<next>"
}POST /v1/segments#
Create a segment (operator)
Request body
| Field | Type | Notes |
|---|---|---|
name required | string | min 1, max 200 |
description | string or null | max 1000 |
definition | any |
curl -X POST "$SAPAGAN_URL/v1/segments" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "order_placed"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/segments`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "order_placed"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"name": "order_placed",
"description": "<description>",
"definition": null,
"version": 1,
"createdBy": "<createdBy>",
"updatedBy": "<updatedBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"archivedAt": "<archivedAt>"
}GET /v1/segments/{id}#
Read a segment and the campaigns built from it
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/segments/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/segments/user-42`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"id": "user-42",
"name": "order_placed",
"description": "<description>",
"definition": null,
"version": 1,
"createdBy": "<createdBy>",
"updatedBy": "<updatedBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"archivedAt": "<archivedAt>",
"usedIn": [
{
"id": "user-42",
"name": "order_placed",
"status": "<status>",
"createdAt": "<createdAt>"
}
]
}PATCH /v1/segments/{id}#
Change or archive a segment (operator)
A campaign keeps the definition it was built with (a snapshot, reviewed with it); edit the campaign's audience to take the segment's new definition.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
name | string | min 1, max 200 |
description | string or null | max 1000 |
definition | any | |
archived | boolean |
curl -X PATCH "$SAPAGAN_URL/v1/segments/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "order_placed",
"description": "<description>",
"definition": null,
"archived": true
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/segments/user-42`, {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "order_placed",
"description": "<description>",
"definition": null,
"archived": true
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"name": "order_placed",
"description": "<description>",
"definition": null,
"version": 1,
"createdBy": "<createdBy>",
"updatedBy": "<updatedBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"archivedAt": "<archivedAt>"
}POST /v1/segments/count#
Count a definition live (saved or not)
Everyone (live profiles), the match, those with a live push device, those reachable by marketing email (withEmail: an address, not unsubscribed, not suppressed), and the count after each top-level condition (steps: who is left for all, who is in so far for any). Consent is the dispatcher's at send time. 409 too_slow past the statement timeout.
Request body
| Field | Type | Notes |
|---|---|---|
definition | any |
curl -X POST "$SAPAGAN_URL/v1/segments/count" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"definition": null
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/segments/count`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"definition": null
}),
});
const data = await res.json();Responses
{
"total": 1,
"matched": 1,
"withPushDevice": 1,
"withEmail": 1,
"steps": [
1
],
"countedAt": "<countedAt>"
}GET /v1/segments/fields#
What the segment builder can use in this workspace
curl -X GET "$SAPAGAN_URL/v1/segments/fields" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/segments/fields`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"attributes": [
{
"key": "<key>",
"type": "<type>",
"count": 1
}
],
"events": [
{
"name": "order_placed",
"count30d": 1,
"lastSeenAt": "<lastSeenAt>"
}
],
"sources": {
"orders": true,
"follows": true
},
"limits": {
"maxConditions": 1
}
}