SapaganDocs sapagan.com

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.

Accepted keys Server key

Parameters

NameInTypeNotes
qquerystring
namequerystring
afterquerystring (uuid)
limitqueryinteger
curl -X GET "$SAPAGAN_URL/v1/people" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required
curl -X GET "$SAPAGAN_URL/v1/people/user-42" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "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).

Accepted keys Server key

curl -X GET "$SAPAGAN_URL/v1/workspace/overview" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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>"
}