SapaganDocs sapagan.com

Concepts

Profiles and identifiers

How Sapagan knows who a person is, and how devices and consent attach to them.

A profile is one person in a workspace. It has an external id: the id your own system uses for that person, up to 200 characters. Everything else hangs off it.

PartWhat it holds
AttributesA free JSON object: name, plan, city, anything you want to use in a template or a segment.
Email and phoneContact fields. People are found by them.
IdentifiersOther ways to recognise the person: id, email, phone, anonymous_id and cio_id. A profile can have up to 20.
DevicesPush tokens, each with a platform (android, ios or web). A person can have several.
RelationshipsMarketplaces only: the stores a person follows or bought from.
ConsentWhat the person agreed to. See Consent topics.

Writing a profile#

Send a profile item to POST /v1/batch, or call PUT /v1/customers/{id}. A write creates the person if they do not exist and updates the attributes you send.

{
  "type": "profile",
  "id": "user-42",
  "email": "budi@example.com",
  "attributes": { "name": "Budi Santoso", "city": "Jakarta" },
  "identifiers": [{ "kind": "anonymous_id", "value": "a1b2c3" }]
}

An anonymous_id identifier links what a visitor did before logging in to the profile they become.

A write never revives a deleted person. The id prefix erased: is reserved and refused.

Reading a person#

GET /v1/customers/{id} returns one profile. GET /v1/people searches by external id, email, phone or name. Email and phone are masked for a store credential and for console roles below operator.

Deleting a person#

DELETE /v1/customers/{id} stops all messages to the person at once and removes their personal data from working tables. Erasure completes within 30 days. A small record of consent history and deliveries moves to an encrypted legal archive, kept for a retention period (five years by default). GET /v1/customers/{id}/export returns everything held about a person.

Devices#

A device belongs to one person at a time. If the same token is registered for another person, it moves, and the move is recorded. When the push provider says a token is no longer valid, Sapagan marks the device invalid and skips it.