> ## 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 - Add Members
> Add one or more people to an existing segment using their Minerva PIDs
## 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
Your API key for authentication
application/json
### Request Body
The request body must be a JSON object containing:
The UUID of the target segment (obtained from the segments/create endpoint). The segment must exist and belong to your organization.
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-{hash}". 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
```json theme={null}
{
"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.
Unique identifier for this API request, useful for debugging and support
Detailed results object containing operation statistics and invalid PIDs
ISO 8601 timestamp (YYYY-MM-DDTHH:MM:SS.ffffffZ format) when the operation completed
#### Results Object Structure
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.
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.
Count of PIDs successfully added to the segment as new members. These are PIDs that were valid and not previously in the segment.
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.
```json 200 theme={null}
{
"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):
```json theme={null}
{
"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 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 400 theme={null}
{
"api_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"error_message": "Input data must contain a 'segment_id' field"
}
```
```json 401 theme={null}
{
"api_request_id": "b2c3d4e5-f6a7-1234-bcde-f12345678901",
"error_message": "Unauthorized"
}
```
```json 404 theme={null}
{
"api_request_id": "c3d4e5f6-a7b8-2345-cdef-123456789012",
"error_message": "Segment abc123 does not exist"
}
```
```json 422 theme={null}
{
"api_request_id": "e5f6a7b8-c9d0-4567-ef01-345678901234",
"error_message": "Input data must contain a 'segment_id' 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 descriptive error messages:
* `400` - **Bad Request**: Request body is not valid JSON or missing required fields
* `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
* `422` - **Unprocessable Entity**: Missing required fields (`segment_id` or `minerva_pids`), or `minerva_pids` is not an array
* `429` - **Too Many Requests**: Rate limit exceeded
* `500` - **Internal Server Error**: Unexpected server error occurred
### Error Examples
**Segment not found:**
```json theme={null}
{
"error": "Segment 550e8400-e29b-41d4-a716-446655440000 does not exist",
"status_code": 404
}
```
**Missing minerva\_pids field:**
```json theme={null}
{
"error": "Input data must contain a 'minerva_pids' field with a list of IDs",
"status_code": 422
}
```
**Invalid data type for minerva\_pids:**
```json theme={null}
{
"error": "Field 'minerva_pids' must be a list",
"status_code": 422
}
```
**Missing segment\_id field:**
```json theme={null}
{
"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
## Related Endpoints
* [Create Segment](/api-reference/segments-create) - Create the segment before adding members
* [Get Segment Members](/api-reference/segments-members) - Retrieve current members
* [Remove Members](/api-reference/segments-members-remove) - Remove specific members
* [Resolve API](/api-reference/resolve-v2) - Get Minerva PIDs for people to add