SapaganDocs sapagan.com

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

Accepted keys Server key

Parameters

NameInTypeNotes
includeArchivedquery"true" | "false"
afterquerystring (uuid)
limitqueryinteger
curl -X GET "$SAPAGAN_URL/v1/segments" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

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

Example response 200

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

Accepted keys Server key

Request body

FieldTypeNotes
name requiredstringmin 1, max 200
descriptionstring or nullmax 1000
definitionany
curl -X POST "$SAPAGAN_URL/v1/segments" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_placed"
  }'

Responses

201 Created, 400 Invalid request, 403 Forbidden, 409 Conflict. Errors use the error body.

Example response 201

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

Accepted keys Server key

Parameters

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

Responses

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

Example response 200

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

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
namestringmin 1, max 200
descriptionstring or nullmax 1000
definitionany
archivedboolean
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
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

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

Accepted keys Server key

Request body

FieldTypeNotes
definitionany
curl -X POST "$SAPAGAN_URL/v1/segments/count" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": null
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden, 409 Conflict, 429 Rate limited. Errors use the error body.

Example response 200

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

Accepted keys Server key

curl -X GET "$SAPAGAN_URL/v1/segments/fields" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

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

Example response 200

{
  "attributes": [
    {
      "key": "<key>",
      "type": "<type>",
      "count": 1
    }
  ],
  "events": [
    {
      "name": "order_placed",
      "count30d": 1,
      "lastSeenAt": "<lastSeenAt>"
    }
  ],
  "sources": {
    "orders": true,
    "follows": true
  },
  "limits": {
    "maxConditions": 1
  }
}