Segments

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

Primary Use Cases:

List Hygiene: Remove deceased individuals from marketing and outreach campaigns
Compliance: Honor CAN-SPAM, GDPR, and other regulations by suppressing deceased contacts
Respectful Communication: Prevent sending communications that could reach grieving families
Estate Services: Identify opportunities for inheritance, estate planning, or probate services
Fraud Prevention: Flag accounts for potential identity theft or account takeover

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.

curl --request GET \
  --url 'https://api.minerva.io/v2/segments/signals/deaths?segment_id=YOUR_SEGMENT_ID' \
  --header 'x-api-key: <api-key>'

Headers

x-api-key

string

required

Your API key for authentication

Query Parameters

segment_id

string

required

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.

api_request_id

string

Unique identifier for this API request, useful for debugging and support

results

array

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.

request_completed_at

string

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:

minerva_pid

string

The Minerva person identifier for the deceased individual, in the format “p-”. This PID can be used to remove the person from segments or enrich their full profile.

obituary_id

string

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

string | null

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”.

publication_last_update_date

string | null

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.

first_observed_at

string | null

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.

signal_metadata

object

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.

{
  "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"
}

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:

source

string

Origin of the death signal. Common values: “obituary_database” (online obituaries), “ssdi” (Social Security Death Index), “public_records” (government death certificates)

obituary_url

string

Direct URL to the obituary page, if available. Useful for manual verification or providing family contact information.

publication_name

string

Name of the publication or website where the obituary appeared (e.g., “Legacy.com”, “Local Funeral Home”, “Regional Observer”)

confidence_score

number

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:

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 POST, PUT, DELETE, or other methods (only GET supported)
422 - Unprocessable Entity: Missing segment_id query parameter or invalid format
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 segment_id parameter:

{
  "error": "Request parameters must contain a 'segment_id' field",
  "status_code": 422
}

Wrong API version:

{
  "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:

Integrate death signal checking into regular list hygiene workflows
Maintain audit logs of all deceased suppressions for compliance documentation
Train staff to handle requests from family members sensitively
Use this data only for suppression/compliance, not for targeting (e.g., don’t target surviving family)
Respect obituary URLs as sensitive content - don’t scrape or republish without permission

Remove Members - Remove deceased individuals from segments
Get Segment Members - List all members to cross-reference with death signals
Enrich API - Get additional context about deceased individuals
Create Segment - Set up segments for signal monitoring

Getting Started

Core Endpoints

Validation Workflows

Segments - Death Signals

Quick Answer

Overview

Headers

Query Parameters

Response

Success Response

Death Signal Object Structure

Signal Metadata Structure

Error Responses

Error Examples

Implementation Notes

Data Quality & Confidence

Getting Started

Core Endpoints

Validation Workflows

Segments

​Quick Answer

​Overview

​Headers

​Query Parameters

​Response

​Success Response

​Death Signal Object Structure

​Signal Metadata Structure

​Error Responses

​Error Examples

​Implementation Notes

​Data Quality & Confidence

​Related Endpoints

Quick Answer

Overview

Headers

Query Parameters

Response

Success Response

Death Signal Object Structure

Signal Metadata Structure

Error Responses

Error Examples

Implementation Notes

Data Quality & Confidence

Related Endpoints