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.
| Part | What it holds |
|---|---|
| Attributes | A free JSON object: name, plan, city, anything you want to use in a template or a segment. |
| Email and phone | Contact fields. People are found by them. |
| Identifiers | Other ways to recognise the person: id, email, phone, anonymous_id and cio_id. A profile can have up to 20. |
| Devices | Push tokens, each with a platform (android, ios or web). A person can have several. |
| Relationships | Marketplaces only: the stores a person follows or bought from. |
| Consent | What 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.