Skip to main content
POST
/
v2
/
segments
/
create
Segments - Create
curl --request POST \
  --url https://api.minerva.io/v2/segments/create \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "name": "<string>",
  "description": "<string>"
}'
{
  "api_request_id": "req_seg123",
  "segment_id": "550e8400-e29b-41d4-a716-446655440000",
  "request_completed_at": "2024-01-15T10:30:45.123456Z"
}

​
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

​
x-api-key
string
required
Your API key for authentication
​
Content-Type
string
required
application/json

​
Request Body

The request body must be a JSON object with the following fields:
​
name
string
required
The name of the segment. Must be unique within your organization. This is the primary identifier you’ll use to reference the segment.
​
description
string
Optional description of the segment’s purpose, selection criteria, or business context. Useful for documenting segment composition and intent.

​
Request Example

{
  "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.
​
api_request_id
string
Unique identifier for this API request, useful for debugging and request tracking
​
segment_id
string
UUID of the newly created segment. Store this ID to add members, retrieve members, and access signals for this segment.
​
request_completed_at
string
ISO 8601 timestamp (YYYY-MM-DDTHH:MM:SS.ffffffZ format) indicating when the segment was created
{
  "api_request_id": "req_seg123",
  "segment_id": "550e8400-e29b-41d4-a716-446655440000",
  "request_completed_at": "2024-01-15T10:30:45.123456Z"
}

​
Error Responses

The API returns standard HTTP status codes with detailed error messages:
  • 401 - Unauthorized: Invalid or missing API key in x-api-key header
  • 404 - Not Found: Segment name already exists (names must be unique per organization) OR attempting to use v1 API version (only v2 is supported)
  • 405 - Method Not Allowed: Using GET, PUT, DELETE, or other methods (only POST is supported)
  • 422 - Unprocessable Entity: Request body is not valid JSON, missing required name field, or invalid data types
  • 500 - Internal Server Error: Unexpected server error occurred

​
Error Examples

Duplicate segment name: 
{
  "error": "Segment name Q1 2024 Enterprise Leads already exists",
  "status_code": 404
}
Missing required field: 
{
  "error": "Input data must contain a 'name' field",
  "status_code": 422
}
Invalid API version: 
{
  "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