Create segment

Create a new audience segment.

DYNAMIC segments (the default) are defined by a condition — a boolean tree that is re-evaluated against your contacts, so membership changes on its own as contact data changes. condition is required for these.

STATIC segments hold a manually managed member list; condition is ignored. Add members with POST /segments/{id}/members.

Authorization

ApiKeyAuth

AuthorizationBearer <token>

API Key authentication. The project is automatically derived from the key.

/v1/track requires a public key (pk_*) — it is the one endpoint intended for client-side use, and a secret key is rejected there with 401.

Every other endpoint requires a secret key (sk_*) and rejects public keys with 401.

So the two key types are not interchangeable in either direction: pick the key that matches the endpoint you are calling.

In: header

Request Body

application/json

name*string

Lengthlength <= 100

description?string

Lengthlength <= 500

type?string

Defaults to DYNAMIC when omitted.

Default"DYNAMIC"

Value in"DYNAMIC" | "STATIC"

condition?

Required for DYNAMIC segments; ignored for STATIC ones.

trackMembership?boolean

Emit segment.<slug>.entry / segment.<slug>.exit events as contacts join and leave. These can be used as workflow triggers.

Defaultfalse

Response Body

`application/json`

curl -X POST "https://api.plunk.jimster.dev/segments" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Users",
    "condition": {
      "logic": "AND",
      "groups": [
        {
          "filters": [
            {
              "field": "data.plan",
              "operator": "equals",
              "value": "premium"
            }
          ]
        }
      ]
    },
    "trackMembership": true
  }'

curl -X POST "https://api.plunk.jimster.dev/segments" \  -H "Content-Type: application/json" \  -d '{    "name": "Premium Users",    "condition": {      "logic": "AND",      "groups": [        {          "filters": [            {              "field": "data.plan",              "operator": "equals",              "value": "premium"            }          ]        }      ]    },    "trackMembership": true  }'

{
  "id": "string",
  "name": "string",
  "description": "string",
  "type": "DYNAMIC",
  "condition": {
    "logic": "AND",
    "groups": [
      {
        "filters": [
          {
            "field": "string",
            "operator": "equals",
            "value": null,
            "unit": "days"
          }
        ],
        "conditions": {
          "logic": "AND",
          "groups": []
        }
      }
    ]
  },
  "trackMembership": true,
  "memberCount": 0,
  "projectId": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

{
  "error": "Condition is required and must be an object for DYNAMIC segments"
}

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid secret API key. This endpoint requires a secret key (sk_*), not a public key.",
    "statusCode": 401,
    "requestId": "8f14e45f-ceea-467a-9575-1f0f38e0b1c2"
  },
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Create segment

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

`application/json`

`application/json`

`application/json`