> ## 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 - Remove Members
> Remove one or more people from an existing segment using their Minerva PIDs
## Quick Answer
**How do I remove members from a segment?** Use this endpoint to remove specific people from a segment by providing their Minerva PIDs.
**Common questions this endpoint answers:**
* How do I remove members from a segment?
* How do I delete people from a list?
* How do I clean up my segment?
* How can I remove opt-outs from my segment?
* How do I exclude deceased individuals from my list?
* How can I remove specific contacts from a group?
**Common use cases:**
* Remove opt-outs for compliance
* Clean lists by removing deceased individuals
* Exclude converted customers from prospect segments
* Manage dynamic cohorts
## Overview
The Segments Remove Members endpoint allows you to remove specific people from a segment by their Minerva PIDs. This is useful for cleaning segments, removing opt-outs, excluding deceased individuals, or managing dynamic cohorts.
**How It Works:**
1. Provide a `segment_id` and an array of `minerva_pids` to remove
2. The API validates each PID against the Minerva database
3. Valid PIDs that are members of the segment are removed
4. The segment's `current_size` is automatically decremented
5. PIDs not in the segment or invalid PIDs are reported but don't cause errors
**Important:** Removing a member deletes their current membership record but preserves historical tracking data. If a removed member is re-added later, their original `first_added_at` timestamp is restored, maintaining historical continuity.
## 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 (from the segments/create endpoint). The segment must exist and belong to your organization.
Array of Minerva person identifiers (strings) to remove from the segment. PIDs follow the format "p-{hash}". There is no strict upper limit on array size, but keep batches reasonable for performance (typically 1,000-10,000).
### Request Example
```json theme={null}
{
"segment_id": "550e8400-e29b-41d4-a716-446655440000",
"minerva_pids": [
"p-a1b2c3d4e5f6",
"p-x9y8z7w6v5u4"
]
}
```
## Response
### Success Response
The API returns a detailed breakdown of the removal operation.
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 could not be processed. This typically indicates PIDs that don't exist, were incorrectly formatted, or came from a different data source.
Count of PIDs successfully removed from the segment. Only counts PIDs that were actually members of the segment and were valid. PIDs not in the segment (even if valid) are not counted here.
The total number of unique members remaining in the segment after this operation completes. This reflects the segment's size after the deletions.
```json 200 theme={null}
{
"api_request_id": "req_remove456",
"results": {
"invalid_minerva_pids": [],
"n_deleted": 2,
"new_current_size": 1521
},
"request_completed_at": "2024-01-15T10:30:45.123456Z"
}
```
**Interpreting the Example Response:**
* **2 PIDs submitted** in the request
* **0 PIDs invalid** (all were found in the database)
* **2 PIDs deleted** (both were members of the segment and successfully removed)
* **1,521 total members** remaining in the segment (down from 1,523)
**Partial Removal Response** (some invalid, some not in segment):
```json theme={null}
{
"api_request_id": "req_remove457",
"results": {
"invalid_minerva_pids": ["p-invalid999"],
"n_deleted": 1,
"new_current_size": 1520
},
"request_completed_at": "2024-01-15T10:32:18.789012Z"
}
```
In this case:
* **3 PIDs submitted**
* **1 PID invalid** (`p-invalid999` not in database)
* **1 PID not in segment** (valid but wasn't a member - implicitly: 3 - 1 invalid - 1 deleted = 1)
* **1 PID deleted** (was a member and removed)
* **1,520 members remaining**
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/remove` 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 removed.
* **Idempotency**: Attempting to remove a PID not in the segment is safe and not an error - it simply won't be counted in `n_deleted`.
* **Atomicity**: The operation is atomic for valid PIDs - either all are removed 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. PIDs not found in the database are returned as invalid.
* **Historical Preservation**: Removing a member deletes their current membership but preserves historical tracking. If re-added, their original `first_added_at` timestamp is restored.
## Performance Considerations
* **Throughput**: The endpoint handles large batches efficiently via bulk SQL operations
* **Response Time**: Expect \~100-500ms for batches of 1,000 PIDs, scaling roughly linearly
* **Concurrent Requests**: Multiple concurrent remove operations on the same segment are safe
## Related Endpoints
* [Add Members to Segment](/api-reference/segments-members-add) - Add members back or populate initially
* [Get Segment Members](/api-reference/segments-members) - View current members before removing
* [Death Signals](/api-reference/segments-signals-deaths) - Identify deceased members for removal
* [Create Segment](/api-reference/segments-create) - Create the segment initially