Get a segment

GET

/api/v3/contacts/segments/{segmentId}

curl --request GET \
  --url 'https://api.tryletterhead.com/api/v3/contacts/segments/1?api=true' \
  --header 'Authorization: Bearer <token>'

• Production

Retrieves a single company-level contact segment by its ID.

This is a company-level (v3) read. Authenticate with a company API key as a Bearer token.

Response

The segment is returned under items (see List segments for the segment shape). An unknown ID (or one owned by another company) returns 404.

Authorizations

• bearerAuth

Parameters

Path Parameters

segmentId

required

integer

The segment’s identifier. This is the numeric id returned by List segments — not a UUID.

Query Parameters

api

required

boolean

Required. Set to true.

Responses

200

200 OK

Media type application/json

object

items

object

id

integer

name

string

description

string

criteria

object

matchMode

string

conditions

Array<object>

object

type

string

customFieldKey

string

operator

string

value

string

suppressionSegmentIds

Array<object>

object

channelSlugs

Array<string>

createdAt

string

updatedAt

string

message

string

total

integer

Example

{
  "items": {
    "id": 5,
    "name": "Readers over 30",
    "description": "Contacts whose age custom field is over 30",
    "criteria": {
      "matchMode": "all",
      "conditions": [
        {
          "type": "customField",
          "customFieldKey": "age",
          "operator": ">",
          "value": "30"
        }
      ],
      "suppressionSegmentIds": []
    },
    "channelSlugs": [
      "the-daily",
      "weekend-reads",
      "product-updates"
    ],
    "createdAt": "2026-05-20 17:48:15",
    "updatedAt": "2026-05-20 17:48:15"
  },
  "message": "Segment retrieved.",
  "total": 1
}