Skip to main content
POST
/
v2
/
segments
/
members
/
add
Segments - Add Members
curl --request POST \
  --url https://api.minerva.io/v2/segments/members/add \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "segment_id": "<string>",
  "minerva_pids": [
    {}
  ]
}'
{
  "api_request_id": "req_add789",
  "results": {
    "invalid_minerva_pids": ["p-invalid123"],
    "n_redundant_additions": 1,
    "n_added": 2,
    "new_current_size": 1523
  },
  "request_completed_at": "2024-01-15T10:30:45.123456Z"
}

​
Quick Answer

How do I add members to a segment? Use this endpoint to add people to a custom segment. After creating a segment, you can populate it with people by providing their Minerva PIDs (person identifiers).Common questions this endpoint answers:
  • How do I add a bunch of members to a custom segment?
  • How do I populate a segment with people?
  • How do I add contacts to a segment I can reference later?
  • How do I build a list of people in a segment?
  • How do I add users to a group or cohort?
Simple workflow:
  1. Create a segment using /v2/segments/create
  2. Get Minerva PIDs from /v2/resolve or /v2/enrich endpoints
  3. Use this endpoint to add those PIDs to your segment
  4. Reference the segment later for analysis, monitoring, or exports

​
Overview

The Segments Add Members endpoint populates a segment with people identified by their Minerva PIDs. This is the primary method for building segment membership after creating a segment. How It Works:
  1. Provide a segment_id (from the create endpoint) and an array of minerva_pids (from resolve/enrich calls)
  2. The API validates each PID against the Minerva database
  3. New members are added; existing members are tracked but not duplicated
  4. The segment’s current_size is automatically updated
  5. Membership timestamps (first_added_at, last_added_at) are maintained for each person
The endpoint handles partial successes gracefully - invalid PIDs are reported but don’t cause the entire operation to fail. Members can be re-added after removal; the system preserves their original first_added_at timestamp for historical tracking.

​
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 containing:
​
segment_id
string
required
The UUID of the target segment (obtained from the segments/create endpoint). The segment must exist and belong to your organization.
​
minerva_pids
array
required
Array of Minerva person identifiers (strings) to add to the segment. PIDs are obtained from the resolve or enrich endpoints and follow the format “p-”. There is no strict upper limit on array size, but keep requests reasonable for performance (batches of 1,000-10,000 are typical).

​
Request Example

{
  "segment_id": "550e8400-e29b-41d4-a716-446655440000",
  "minerva_pids": [
    "p-a1b2c3d4e5f6",
    "p-x9y8z7w6v5u4",
    "p-m5n6o7p8q9r0"
  ]
}

​
Response

​
Success Response

The API returns a detailed breakdown of the operation, reporting successes, duplicates, and invalid PIDs.
​
api_request_id
string
Unique identifier for this API request, useful for debugging and support
​
results
object
Detailed results object containing operation statistics and invalid PIDs
​
request_completed_at
string
ISO 8601 timestamp (YYYY-MM-DDTHH:MM:SS.ffffffZ format) when the operation completed

​
Results Object Structure

​
invalid_minerva_pids
array
Array of Minerva PID strings that were not found in the Minerva database. These PIDs were rejected and not added to the segment. This typically indicates PIDs that don’t exist, were incorrectly formatted, or came from a different data source.
​
n_redundant_additions
integer
Count of PIDs that were already members of this segment. These PIDs were not added again (segments maintain unique membership), but their last_added_at timestamp was updated to reflect the re-addition attempt.
​
n_added
integer
Count of PIDs successfully added to the segment as new members. These are PIDs that were valid and not previously in the segment.
​
new_current_size
integer
The total number of unique members in the segment after this operation completes. This reflects the segment’s size including all historical members, not just those added in this request.
{
  "api_request_id": "req_add789",
  "results": {
    "invalid_minerva_pids": ["p-invalid123"],
    "n_redundant_additions": 1,
    "n_added": 2,
    "new_current_size": 1523
  },
  "request_completed_at": "2024-01-15T10:30:45.123456Z"
}
Interpreting the Example Response:
  • 3 PIDs submitted in the request
  • 1 PID invalid (p-invalid123 not found in database)
  • 1 PID redundant (already in the segment, last_added_at updated)
  • 2 PIDs added (new members successfully added)
  • 1,523 total members now in the segment (including these 2 new additions)
Perfect Success Response (all PIDs added, none invalid or redundant): 
{
  "api_request_id": "req_add790",
  "results": {
    "invalid_minerva_pids": [],
    "n_redundant_additions": 0,
    "n_added": 5,
    "new_current_size": 1528
  },
  "request_completed_at": "2024-01-15T10:31:12.456789Z"
}

​
Error Responses

The API returns standard HTTP status codes with descriptive error messages:
  • 401 - Unauthorized: Invalid or missing API key in x-api-key header
  • 404 - Not Found: Segment with the provided segment_id does not exist in your organization OR attempting to use v1 API version (only v2 supported)
  • 405 - Method Not Allowed: Using GET, PUT, DELETE, or other methods (only POST supported)
  • 422 - Unprocessable Entity: Request body is not valid JSON, missing required fields (segment_id or minerva_pids), or minerva_pids is not an array
  • 500 - Internal Server Error: Unexpected server error occurred

​
Error Examples

Segment not found: 
{
  "error": "Segment 550e8400-e29b-41d4-a716-446655440000 does not exist",
  "status_code": 404
}
Missing minerva_pids field: 
{
  "error": "Input data must contain a 'minerva_pids' field with a list of IDs",
  "status_code": 422
}
Invalid data type for minerva_pids: 
{
  "error": "Field 'minerva_pids' must be a list",
  "status_code": 422
}
Missing segment_id field: 
{
  "error": "Input data must contain a 'segment_id' field",
  "status_code": 422
}

​
Implementation Notes

  • API Version: Only v2 is supported. Using /v1/segments/members/add returns a 404 error.
  • HTTP Method: Only POST requests are accepted.
  • Partial Success: Invalid PIDs are reported in invalid_minerva_pids but don’t cause the entire operation to fail. Valid PIDs are still added.
  • Idempotency: Adding a PID already in the segment is safe and not an error. It increments n_redundant_additions and updates last_added_at, but doesn’t create a duplicate entry.
  • Atomicity: The operation is atomic for valid PIDs - either all are added successfully, or none are (in case of database errors).
  • Batch Size: There’s no hard limit on array size, but for optimal performance keep batches between 1,000-10,000 PIDs.
  • Validation: Each PID is validated against the Minerva database (person_core_v1 table). PIDs not found in the database are returned as invalid.
  • Timestamps: The system maintains both first_added_at (initial addition) and last_added_at (most recent addition) for each member.

​
Performance Considerations

  • Throughput: The endpoint can handle large batches efficiently due to bulk SQL operations
  • Response Time: Expect ~100-500ms for batches of 1,000 PIDs, scaling roughly linearly
  • Rate Limiting: Standard API rate limits apply (contact support for details)
  • Concurrent Requests: Multiple concurrent add operations to the same segment are safe; the database handles concurrency