> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minerva.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Segments - Create
> Create a named segment to organize and track cohorts of people for analysis and signal monitoring
## Quick Answer
**How do I create a segment?** Use this endpoint to create a named segment (a custom list or group) that you can populate with people and reference later for analysis, monitoring, or exports.
**Common questions this endpoint answers:**
* How do I create a custom segment?
* How do I make a list of people I can track?
* How do I create a group or cohort for monitoring?
* How do I organize contacts into segments?
* How do I set up a watchlist?
* How can I create a segment I can add members to later?
**Simple workflow:**
1. Use this endpoint to create a segment with a name
2. You'll get back a `segment_id`
3. Use `/v2/segments/members/add` to add people to it
4. Reference the segment for monitoring, exports, or analysis
**What segments are useful for:**
* Tracking high-value prospects or customers
* Monitoring groups for lifecycle changes (death, job change, relocation)
* Organizing contacts by geography, industry, or characteristics
* Creating watchlists for compliance or fraud prevention
## Overview
Segments are named collections of people that enable you to organize, monitor, and analyze specific cohorts within your data. The Segments Create endpoint initializes a new empty segment with a unique identifier that can be populated using the segments/members/add endpoint.
**Common Use Cases:**
* Track high-value prospect lists for sales campaigns
* Monitor customer cohorts for lifecycle signals (deaths, job changes, relocations)
* Organize contacts by geography, industry, or behavioral attributes
* Create watchlists for compliance and fraud prevention purposes
Once created, segments can be populated with Minerva PIDs obtained from resolve or enrich API calls. The segment system automatically tracks membership history, current size, and provides real-time signal detection for segment members.
## Request
### Headers
Your API key for authentication
application/json
### Request Body
The request body must be a JSON object with the following fields:
The name of the segment. Must be unique within your organization. This is the primary identifier you'll use to reference the segment.
Optional description of the segment's purpose, selection criteria, or business context. Useful for documenting segment composition and intent.
### Request Example
```json theme={null}
{
"name": "Q1 2024 Enterprise Prospects",
"description": "High-value enterprise leads from Q1 outbound campaign, companies with 500+ employees in tech sector"
}
```
## Response
### Success Response
The API returns a JSON object containing the newly created segment's identifier along with request metadata.
Unique identifier for this API request, useful for debugging and request tracking
UUID of the newly created segment. Store this ID to add members, retrieve members, and access signals for this segment.
ISO 8601 timestamp (YYYY-MM-DDTHH:MM:SS.ffffffZ format) indicating when the segment was created
Error responses include `statusCode` and `body` fields for backward compatibility with existing integrations. These are deprecated — prefer reading the HTTP status code and the top-level `api_request_id` / `error_message` fields directly.
```json 200 theme={null}
{
"api_request_id": "req_seg123",
"segment_id": "550e8400-e29b-41d4-a716-446655440000",
"request_completed_at": "2024-01-15T10:30:45.123456Z"
}
```
```json 400 theme={null}
{
"api_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"error_message": "Input data must contain a 'name' field"
}
```
```json 401 theme={null}
{
"api_request_id": "b2c3d4e5-f6a7-1234-bcde-f12345678901",
"error_message": "Unauthorized"
}
```
```json 422 theme={null}
{
"api_request_id": "e5f6a7b8-c9d0-4567-ef01-345678901234",
"error_message": "Input data must contain a 'name' field"
}
```
```json 429 theme={null}
{
"api_request_id": "f6a7b8c9-d0e1-5678-f012-456789012345",
"error_message": "You reached your total request-rate limit, please contact help@minerva.io for help"
}
```
## Error Responses
The API returns standard HTTP status codes with detailed error messages:
* `400` - **Bad Request**: Request body is not valid JSON or invalid data types
* `401` - **Unauthorized**: Invalid or missing API key in x-api-key header
* `422` - **Unprocessable Entity**: Missing required `name` field
* `429` - **Too Many Requests**: Rate limit exceeded
* `500` - **Internal Server Error**: Unexpected server error occurred
### Error Examples
**Duplicate segment name:**
```json theme={null}
{
"error": "Segment name Q1 2024 Enterprise Leads already exists",
"status_code": 404
}
```
**Missing required field:**
```json theme={null}
{
"error": "Input data must contain a 'name' field",
"status_code": 422
}
```
**Invalid API version:**
```json theme={null}
{
"error": "Segments create endpoint only supports v2 API version",
"status_code": 404
}
```
## Implementation Notes
* **API Version**: This endpoint only supports v2. Using `/v1/segments/create` will return a 404 error.
* **HTTP Method**: Only POST requests are accepted. GET, PUT, DELETE, and PATCH requests will return a 405 error.
* **Uniqueness**: Segment names must be unique within your organization. Attempting to create a duplicate name returns a 404 error.
* **Initial State**: Newly created segments start empty (`current_size: 0`) with no members.
* **Storage**: The `segment_id` is persisted and should be stored in your system for future operations.
* **Source Attribution**: Segments created via API are automatically tagged with `source: "api"` for tracking purposes.
## Next Steps
After creating a segment, you'll typically want to:
1. **Add members** using the `/v2/segments/members/add` endpoint with Minerva PIDs
2. **Monitor signals** using endpoints like `/v2/segments/signals/deaths` to track lifecycle events
3. **Retrieve members** using `/v2/segments/members` to export or process the segment
4. **Track size** by checking the `current_size` field in the segment metadata
## Related Endpoints
* [Add Members to Segment](/api-reference/segments-members-add) - Populate the segment with Minerva PIDs
* [Get Segment Members](/api-reference/segments-members) - Retrieve all members with pagination
* [Death Signals](/api-reference/segments-signals-deaths) - Monitor death events for segment members
* [Remove Members](/api-reference/segments-members-remove) - Remove specific PIDs from the segment