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>"
}
'import requests
url = "https://api.minerva.io/v2/segments/create"
payload = {
"name": "<string>",
"description": "<string>"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "<content-type>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': '<content-type>'},
body: JSON.stringify({name: '<string>', description: '<string>'})
};
fetch('https://api.minerva.io/v2/segments/create', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.minerva.io/v2/segments/create",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: <content-type>",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.minerva.io/v2/segments/create"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "<content-type>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.minerva.io/v2/segments/create")
.header("x-api-key", "<api-key>")
.header("Content-Type", "<content-type>")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.minerva.io/v2/segments/create")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = '<content-type>'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"api_request_id": "req_seg123",
"segment_id": "550e8400-e29b-41d4-a716-446655440000",
"request_completed_at": "2024-01-15T10:30:45.123456Z"
}
{
"code": "bad_request",
"message": "Input data must contain a 'name' field",
"api_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
{
"code": "unauthorized",
"message": "Unauthorized",
"api_request_id": "b2c3d4e5-f6a7-1234-bcde-f12345678901"
}
{
"code": "unprocessable_entity",
"message": "Input data must contain a 'name' field",
"api_request_id": "e5f6a7b8-c9d0-4567-ef01-345678901234"
}
{
"code": "rate_limit_reached",
"message": "You reached your total request-rate limit, please contact help@minerva.io for help",
"api_request_id": "f6a7b8c9-d0e1-5678-f012-456789012345"
}
Segments
Segments - Create
Create a named segment to organize and track cohorts of people for analysis and signal monitoring
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>"
}
'import requests
url = "https://api.minerva.io/v2/segments/create"
payload = {
"name": "<string>",
"description": "<string>"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "<content-type>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': '<content-type>'},
body: JSON.stringify({name: '<string>', description: '<string>'})
};
fetch('https://api.minerva.io/v2/segments/create', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.minerva.io/v2/segments/create",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: <content-type>",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.minerva.io/v2/segments/create"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "<content-type>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.minerva.io/v2/segments/create")
.header("x-api-key", "<api-key>")
.header("Content-Type", "<content-type>")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.minerva.io/v2/segments/create")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = '<content-type>'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"api_request_id": "req_seg123",
"segment_id": "550e8400-e29b-41d4-a716-446655440000",
"request_completed_at": "2024-01-15T10:30:45.123456Z"
}
{
"code": "bad_request",
"message": "Input data must contain a 'name' field",
"api_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
{
"code": "unauthorized",
"message": "Unauthorized",
"api_request_id": "b2c3d4e5-f6a7-1234-bcde-f12345678901"
}
{
"code": "unprocessable_entity",
"message": "Input data must contain a 'name' field",
"api_request_id": "e5f6a7b8-c9d0-4567-ef01-345678901234"
}
{
"code": "rate_limit_reached",
"message": "You reached your total request-rate limit, please contact help@minerva.io for help",
"api_request_id": "f6a7b8c9-d0e1-5678-f012-456789012345"
}
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?
- Use this endpoint to create a segment with a name
- You’ll get back a
segment_id - Use
/v2/segments/members/addto add people to it - Reference the segment for monitoring, exports, or analysis
- 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
Request
Headers
string
required
Your API key for authentication
string
required
application/json
Request Body
The request body must be a JSON object with the following fields: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.
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.string
Unique identifier for this API request, useful for debugging and request tracking
string
UUID of the newly created segment. Store this ID to add members, retrieve members, and access signals for this segment.
string
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 the HTTP status code and the top-level code / message / api_request_id fields directly. (The deprecated nested body still carries the legacy error_message.){
"api_request_id": "req_seg123",
"segment_id": "550e8400-e29b-41d4-a716-446655440000",
"request_completed_at": "2024-01-15T10:30:45.123456Z"
}
{
"code": "bad_request",
"message": "Input data must contain a 'name' field",
"api_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
{
"code": "unauthorized",
"message": "Unauthorized",
"api_request_id": "b2c3d4e5-f6a7-1234-bcde-f12345678901"
}
{
"code": "unprocessable_entity",
"message": "Input data must contain a 'name' field",
"api_request_id": "e5f6a7b8-c9d0-4567-ef01-345678901234"
}
{
"code": "rate_limit_reached",
"message": "You reached your total request-rate limit, please contact help@minerva.io for help",
"api_request_id": "f6a7b8c9-d0e1-5678-f012-456789012345"
}
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 types401- Unauthorized: Invalid or missing API key in x-api-key header422- Unprocessable Entity: Missing requirednamefield429- Too Many Requests: Rate limit exceeded500- Internal Server Error: Unexpected server error occurred
Error Examples
Duplicate segment name:{
"code": "conflict",
"message": "Segment name Q1 2024 Enterprise Leads already exists"
}
{
"code": "unprocessable_entity",
"message": "Input data must contain a 'name' field"
}
{
"code": "bad_request",
"message": "Segments create endpoint only supports v2 API version"
}
Implementation Notes
- API Version: This endpoint only supports v2. Using
/v1/segments/createwill 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 409 conflict error.
- Initial State: Newly created segments start empty (
current_size: 0) with no members. - Storage: The
segment_idis 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:- Add members using the
/v2/segments/members/addendpoint with Minerva PIDs - Monitor signals using endpoints like
/v2/segments/signals/deathsto track lifecycle events - Retrieve members using
/v2/segments/membersto export or process the segment - Track size by checking the
current_sizefield in the segment metadata
Related Endpoints
- Add Members to Segment - Populate the segment with Minerva PIDs
- Get Segment Members - Retrieve all members with pagination
- Death Signals - Monitor death events for segment members
- Remove Members - Remove specific PIDs from the segment
Was this page helpful?