---
title: "Create new segment"
method: POST
path: "/v2/segments"
tags: ["Segments"]
---

# Create new segment

`POST /v2/segments`

## Request

- Base URL: `https://api.attentivemobile.com`
- URL: `https://api.attentivemobile.com/v2/segments`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://ui-devel.attentivemobile.com/integrations/oauth-install?client_id={clientId}&redirect_uri={redirectUri}&scope={scope}`
    - Token URL: `https://api.attentivemobile.com/v1/authorization-codes/tokens` scopes: `segments:write`

Creates a new empty segment with the specified name and optional description.

Scopes Required: [segments:Write]

Default Rate Limit: 100 requests per second

## Request body

- CreateSegmentRequest
  - `name` string, required: The name of the segment. Cannot be empty or whitespace only. Leading and trailing whitespace will be trimmed.
  - `description` string: Optional description of the segment. If not provided, defaults to "Manual Segment Upload Public API V2". When provided, cannot be empty or whitespace only and must be at least 2 characters. Leading and trailing whitespace will be trimmed.
  - `externalId` string: Auto generated if not supplied. Optional externalId set on the segment. Cannot be empty or whitespace only. Leading and trailing whitespace will be trimmed.

## Response `201`

Segment created successfully

- CreateSegmentResponse
  - `externalId` string: The external segment ID (client-facing identifier)
  - `name` string: The name of the segment
  - `description` string: The description of the segment

## Other responses

- `400`: Bad request - invalid parameters
- `401`: Unauthorized - invalid or missing token
- `403`: Access denied - insufficient permissions
- `429`: Too many requests - rate limit exceeded
- `500`: Internal server error

## Changes

- **2026-11-03** `2f49ffff7d65`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/attentive/apis/attentive-api-v2/changes/v2/segments/post.md)

---

[API](https://skmtc.dev/attentive/apis/attentive-api-v2.md) - [All operations](https://skmtc.dev/attentive/apis/attentive-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/attentive/apis/attentive-api-v2/revisions/2f49ffff7d65?raw)