> ## 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 - Death Signals
> Retrieve death records and obituary information for segment members who have deceased
## Quick Answer
**How do I find deceased people in my segment?** Use this endpoint to get death records and obituary information for segment members who have passed away.
**Common questions this endpoint answers:**
* How do I identify deceased individuals in my segment?
* How can I find people who have died?
* How do I get death signals for my contacts?
* How can I clean my list of deceased people?
* How do I monitor for death records?
* How can I suppress deceased individuals from my campaigns?
**What you get back:** List of segment members with death records, including date of death, obituary links, and confidence scores.
**Common use cases:**
* List hygiene: Remove deceased individuals from marketing campaigns
* Compliance: Honor regulations by suppressing deceased contacts
* Estate services: Identify opportunities for inheritance or probate services
* Fraud prevention: Flag accounts for potential identity theft
## Overview
The Segments Death Signals endpoint returns obituary and death records for segment members who have passed away. This data is sourced from obituary databases and public death records, enabling you to maintain respectful, compliant, and up-to-date contact lists.
**What You Get:**
* Death records matched to segment members via Minerva's identity resolution
* Date of death and obituary publication information
* Source metadata including obituary URLs and confidence scores
* First observed timestamp showing when Minerva detected the death signal
The endpoint only returns members with known death signals - it does not return all members. An empty result set indicates no death records have been found for the segment, which is typical for most segments.
```bash Request Example theme={null}
curl --request GET \
--url 'https://api.minerva.io/v2/segments/signals/deaths?segment_id=YOUR_SEGMENT_ID' \
--header 'x-api-key: '
```
### Headers
Your API key for authentication
### Query Parameters
The UUID of the segment to retrieve death signals for (obtained from the segments/create endpoint). The segment must exist and belong to your organization.
## Response
### Success Response
The API returns an array of death signal records. Only segment members with known death signals are included.
Unique identifier for this API request, useful for debugging and support
Array of death signal objects. Empty array if no segment members have known death records. Each object represents a matched death record for one segment member.
ISO 8601 timestamp (YYYY-MM-DDTHH:MM:SS.ffffffZ format) when the request completed
#### Death Signal Object Structure
Each object in the `results` array contains:
The Minerva person identifier for the deceased individual, in the format "p-{hash}". This PID can be used to remove the person from segments or enrich their full profile.
Unique identifier for the obituary record in Minerva's death signals database. This ID is stable and can be used for deduplication.
Date of death in ISO 8601 date format (YYYY-MM-DD). May be `null` if the obituary doesn't specify an exact date or only provides approximate information like "early 2023".
Date when the obituary was last updated by the publication, in ISO 8601 date format (YYYY-MM-DD). May be `null` if this information is not available from the source.
ISO 8601 timestamp when Minerva first detected and ingested this death signal. This represents when the signal entered Minerva's database, not the date of death. May be `null` for older records.
Additional metadata object about the death signal source, verification, and context. Structure varies by data source but typically includes source type, URLs, publication names, and confidence scores.
```json 200 Response theme={null}
{
"api_request_id": "req_deaths123",
"results": [
{
"minerva_pid": "p-a1b2c3d4e5f6",
"obituary_id": "obit-xyz789",
"date_of_death": "2023-12-15",
"publication_last_update_date": "2023-12-18",
"first_observed_at": "2023-12-20T08:30:00.000000Z",
"signal_metadata": {
"source": "obituary_database",
"obituary_url": "https://example.com/obituary/xyz789",
"publication_name": "Local News",
"confidence_score": 0.95
}
},
{
"minerva_pid": "p-m5n6o7p8q9r0",
"obituary_id": "obit-abc456",
"date_of_death": "2024-01-05",
"publication_last_update_date": "2024-01-07",
"first_observed_at": "2024-01-08T14:15:00.000000Z",
"signal_metadata": {
"source": "obituary_database",
"obituary_url": "https://example.com/obituary/abc456",
"publication_name": "Regional Observer",
"confidence_score": 0.98
}
}
],
"request_completed_at": "2024-01-15T10:30:45.123456Z"
}
```
```json 200 - No Death Signals theme={null}
{
"api_request_id": "req_deaths456",
"results": [],
"request_completed_at": "2024-01-15T10:30:45.123456Z"
}
```
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": "Request must contain 'segment_id' query parameter"
}
```
```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": "Request must contain 'segment_id' query parameter"
}
```
```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"
}
```
**Interpreting the Examples:**
The first response shows 2 death signals were found for 2 different segment members:
* One person died on December 15, 2023 (detected December 20)
* Another person died on January 5, 2024 (detected January 8)
* Both have high confidence scores (0.95 and 0.98) and obituary URLs
The second response (empty array) is the most common result - it indicates no death records have been matched to segment members. This is typical and expected for most segments.
## Signal Metadata Structure
The `signal_metadata` object is a JSON object whose structure varies by data source. Common fields include:
Origin of the death signal. Common values: "obituary\_database" (online obituaries), "ssdi" (Social Security Death Index), "public\_records" (government death certificates)
Direct URL to the obituary page, if available. Useful for manual verification or providing family contact information.
Name of the publication or website where the obituary appeared (e.g., "Legacy.com", "Local Funeral Home", "Regional Observer")
Minerva's confidence score for the identity match between the obituary and the Minerva PID, on a 0-1 scale. Scores above 0.90 indicate high confidence. Lower scores may warrant manual review.
**Additional Fields (Source-Dependent):**
* `funeral_home`: Name of funeral home handling arrangements
* `city`, `state`: Location information
* `age_at_death`: Reported age at time of death
* `survivors`: List of surviving family members (for estate/inheritance use cases)
* `service_date`: Date of memorial or funeral service
* `memorial_donation_url`: Link to charity donation page
## Error Responses
The API returns standard HTTP status codes with descriptive error messages:
* `400` - **Bad Request**: Missing `segment_id` query parameter
* `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 `segment_id` query parameter or invalid format
* `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 segment\_id parameter:**
```json theme={null}
{
"error": "Request parameters must contain a 'segment_id' field",
"status_code": 422
}
```
**Wrong API version:**
```json theme={null}
{
"error": "Segments signals deaths endpoint only supports v2 API version",
"status_code": 404
}
```
## Implementation Notes
* **API Version**: Only v2 is supported. Using `/v1/segments/signals/deaths` returns a 404 error.
* **HTTP Method**: Only GET requests are accepted.
* **No Pagination**: Results are not paginated. All death signals for the segment are returned in a single response.
* **Selective Results**: Only segment members with death signals are returned. Most segments will return an empty array.
* **Data Freshness**: Death signals are updated regularly as new obituary data is ingested. Expect new deaths to appear within 1-7 days of public posting.
* **Null Fields**: `date_of_death`, `publication_last_update_date`, and `first_observed_at` may be `null` if information is unavailable.
* **Deduplication**: Minerva deduplicates death records from multiple sources to return one signal per person in most cases.
* **Performance**: Response time is typically 100-500ms regardless of segment size, as the query is optimized with database joins.
## Data Quality & Confidence
**Confidence Scores:**
* **0.95-1.00**: Extremely high confidence - strong identity match across multiple attributes
* **0.85-0.94**: High confidence - good identity match, safe for automated suppression
* **0.70-0.84**: Medium confidence - reasonable match, consider manual review
* **Below 0.70**: Lower confidence - manual verification recommended before action
**Best Practices:**
1. Integrate death signal checking into regular list hygiene workflows
2. Maintain audit logs of all deceased suppressions for compliance documentation
3. Train staff to handle requests from family members sensitively
4. Use this data only for suppression/compliance, not for targeting (e.g., don't target surviving family)
5. Respect obituary URLs as sensitive content - don't scrape or republish without permission
## Related Endpoints
* [Remove Members](/api-reference/segments-members-remove) - Remove deceased individuals from segments
* [Get Segment Members](/api-reference/segments-members) - List all members to cross-reference with death signals
* [Enrich API](/api-reference/enrich-v2) - Get additional context about deceased individuals
* [Create Segment](/api-reference/segments-create) - Set up segments for signal monitoring