API reference

Segments API

Reference for creating, listing, updating and deleting segments, and for the contacts inside them, including the legacy audiences paths.

The segments API manages the segments of the project that owns your API key. Every endpoint needs a full_access key. For the concepts, see Segments.

Every path also exists with /audiences in place of /segments, and returns the same data with object set to audience. New code should use /segments.

Create a segment

POST/segments

Field	Type	Required	Description
`name`	string	Yes	1 to 100 characters.

Shell

curl -X POST https://api.sooner.dev/segments \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Newsletter subscribers" }'

JSON

{ "object": "segment", "id": "jd5f2h8k4m7p1r6t9v3x0z2c", "name": "Newsletter subscribers" }

List segments

GET/segments

Returns the project's segments, newest first. Accepts limit and after. See Pagination.

Shell

curl https://api.sooner.dev/segments \
  -H "Authorization: Bearer $SOONER_API_KEY"

JSON

{
  "object": "list",
  "data": [
    {
      "object": "segment",
      "id": "jd5f2h8k4m7p1r6t9v3x0z2c",
      "name": "Newsletter subscribers",
      "created_at": "2026-11-14T10:00:00.000Z"
    }
  ],
  "has_more": false
}

Retrieve a segment

GET/segments/{id}

Returns one segment in the shape above. Notable errors: not_found.

Update a segment

PATCH/segments/{id}

Field	Type	Required	Description
`name`	string	Yes	1 to 100 characters.

Shell

curl -X PATCH https://api.sooner.dev/segments/jd5f2h8k4m7p1r6t9v3x0z2c \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Subscribers" }'

JSON

{ "object": "segment", "id": "jd5f2h8k4m7p1r6t9v3x0z2c" }

Delete a segment

DELETE/segments/{id}

Deletes the segment and its memberships. The contacts remain. Deletion finishes in the background.

JSON

{ "object": "segment", "id": "jd5f2h8k4m7p1r6t9v3x0z2c", "deleted": true }

Contacts in a segment

These endpoints work on contacts through a segment. They accept the same fields and return the same shapes as the contacts API.

Endpoint	What it does
`GET /segments/{id}/contacts`	Lists the segment's contacts, newest member first. Accepts `limit` and `after`.
`POST /segments/{id}/contacts`	Creates a contact and adds it to this segment. A `segments` field in the body is ignored.
`GET /segments/{id}/contacts/{identifier}`	Retrieves a contact by ID or email.
`PATCH /segments/{id}/contacts/{identifier}`	Updates a contact.
`DELETE /segments/{id}/contacts/{identifier}`	Deletes the contact.

Shell

curl -X POST https://api.sooner.dev/segments/jd5f2h8k4m7p1r6t9v3x0z2c/contacts \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "grace@example.com", "first_name": "Grace" }'

JSON

{ "object": "contact", "id": "jx9c2m5v8n1b4q7w0e3r6t1y" }

The segment ID in the path is not checked when you retrieve, update or delete a contact. The contact is found by identifier alone.