Skip to main content
POST
/
v2
/
segments
/
members
/
remove
Segments - Remove Members
curl --request POST \
  --url https://api.minerva.io/v2/segments/members/remove \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "segment_id": "<string>",
  "minerva_pids": [
    {}
  ]
}'
{
  "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"
}

​
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

​
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 (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 remove from the segment. PIDs follow the format “p-”. There is no strict upper limit on array size, but keep batches reasonable for performance (typically 1,000-10,000).

​
Request Example

{
  "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.
​
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 could not be processed. This typically indicates PIDs that don’t exist, were incorrectly formatted, or came from a different data source.
​
n_deleted
integer
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.
​
new_current_size
integer
The total number of unique members remaining in the segment after this operation completes. This reflects the segment’s size after the deletions.
{
  "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): 
{
  "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

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/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