API reference
People
Search people and read the workspace's totals.
Search people and read the workspace's totals.
GET /v1/people#
List people, or search by external id, email, phone or name
Newest first. q with @ searches emails, with digits only phones, otherwise external ids: by prefix (emails, ids) or last digits (phones) from the operator role up, by the whole value only below it. name (Composer UX): part of a name, two characters at least, matched anywhere for every role (names are not masked); trigram-indexed, at most 3 s. total is given for an unfiltered first page. Contacts are masked below the operator role. Audited.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
q | query | string | |
name | query | string | |
after | query | string (uuid) | |
limit | query | integer |
curl -X GET "$SAPAGAN_URL/v1/people" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/people`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"people": [
{
"id": "user-42",
"externalId": "user-42",
"name": "order_placed",
"email": "budi@example.com",
"phone": "+6281234567890",
"city": "<city>",
"hasPushDevice": true,
"unsubscribed": true,
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>"
}
],
"total": 1,
"next": "<next>",
"masked": true
}GET /v1/people/{id}#
One person by external id: attributes, devices, events, consent, relationships, campaigns
Device tokens show their last 6 characters. Events show their names and property names, not values. campaigns is null until the dispatcher's deliveries exist (P1-08). Contacts are masked below the operator role. Audited.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/people/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/people/user-42`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"person": {
"id": "user-42",
"externalId": "user-42",
"name": "order_placed",
"email": "budi@example.com",
"phone": "+6281234567890",
"city": "<city>",
"hasPushDevice": true,
"unsubscribed": true,
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>"
},
"masked": true,
"attributes": {},
"devices": [
{
"id": "user-42",
"platform": "<platform>",
"appId": "com.example.app",
"token": "<device token>",
"lastSeenAt": "<lastSeenAt>",
"invalidatedAt": "<invalidatedAt>",
"invalidReason": "<invalidReason>"
}
],
"events": [
{
"name": "order_placed",
"occurredAt": "<occurredAt>",
"scopeId": "<scopeId>",
"source": "<source>",
"propertyKeys": [
"<propertyKeys>"
]
}
],
"consent": {
"unsubscribedAt": "<unsubscribedAt>",
"topics": [
{
"topicId": "<topicId>",
"scopeId": "<scopeId>",
"key": "<key>",
"name": "order_placed",
"mode": "<mode>",
"granted": true,
"source": "<source>",
"updatedAt": "<updatedAt>"
}
]
},
"relationships": [
{
"scopeId": "<scopeId>",
"scopeName": "<scopeName>",
"relation": "<relation>",
"firstAt": "<firstAt>",
"lastAt": "<lastAt>",
"orderCount": 1,
"endedAt": "<endedAt>"
}
],
"campaigns": [
{
"broadcastId": "<broadcastId>",
"name": "order_placed",
"channel": "<channel>",
"status": "<status>",
"suppressedReason": "<suppressedReason>",
"at": "<at>"
}
]
}GET /v1/workspace/overview#
The workspace at a glance: people, push devices, events, stores, its type (the console's Home)
Aggregates only. pushDevices counts people with a live device, in all and by platform. stores is 0 for a workspace without stores. kind and audienceName: the workspace's type and what it calls its people. activity (own-brand workspaces only, null for a marketplace): over the last days days, messages sent and opened, conversions, and the people who have not unsubscribed (optIns).
curl -X GET "$SAPAGAN_URL/v1/workspace/overview" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/workspace/overview`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"people": {
"total": 1,
"newThisWeek": 1
},
"pushDevices": {
"total": 1,
"byPlatform": {}
},
"events": {
"last24h": 1,
"last7d": 1
},
"stores": 1,
"kind": "marketplace",
"audienceName": {
"en": {
"one": "<one>",
"other": "<other>"
},
"id": {
"one": "<one>",
"other": "<other>"
}
},
"activity": {
"days": 1,
"optIns": 1,
"sends": 1,
"opens": 1,
"conversions": 1
},
"at": "<at>"
}