API Documentation

REST API v1 for submitting and managing unclaimed cremains cases in the national registry.

Overview

The UnclaimedCremains.org API allows funeral homes and partner platforms to programmatically submit, update, and manage unclaimed cremains cases in our national registry. All submitted cases go through an admin review process before being published to the public search.

Base URLhttps://unclaimedcremains.org/api/v1
FormatJSON (request and response)
EncodingUTF-8
HTTP MethodsGET POST PUT DELETE
Authentication

All API requests require an API key sent in the X-API-Key header.

X-API-Key: uc_your_api_key_here

To obtain an API key, register for a free account. After your account is approved, log in and generate keys from your dashboard.

Keep your API key secret. Do not expose it in client-side code, public repositories, or URLs.
Rate Limiting

API requests are rate-limited per API key. The default limit is 100 requests per minute.

When the limit is exceeded, the API returns a 429 Too Many Requests response with a Retry-After header.

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
    "error": "Rate limit exceeded. Maximum 100 requests per minute.",
    "retry_after": 60
}
Error Handling

The API uses standard HTTP status codes. Error responses include a JSON body with details.

CodeMeaning
200Success
201Created — case submitted for review
400Bad Request — missing or invalid parameters
401Unauthorized — invalid or missing API key
404Not Found — case does not exist or does not belong to your account
405Method Not Allowed
422Validation Error — check the errors array in the response
429Rate Limit Exceeded

Error response format:

{
    "error": "Validation failed",
    "errors": [
        "full_name is required.",
        "state_of_death must be a valid 2-letter US state code."
    ]
}
Case Statuses

Cases go through a lifecycle of statuses. When you submit a case via the API, it starts as pending_review.

StatusDescription
pending_reviewNewly submitted, awaiting admin approval
publishedApproved and visible in public search results
match_requestedA family member has submitted a match request for this case
claimedRemains have been claimed by family
resolvedCase has been resolved (remains disposed or returned)
under_investigationUnder review by DwD administrators
withdrawnWithdrawn by the submitting facility
facility_closedSubmitting facility has closed
archivedArchived by admin

Endpoints

POST /api/v1/cremains

Submit a new unclaimed cremains case. The case will be set to pending_review and must be approved by an administrator before it appears in public search.

Request Body
POST https://unclaimedcremains.org/api/v1/cremains
Content-Type: application/json
X-API-Key: uc_your_api_key_here

{
    "full_name": "John Robert Smith",
    "known_aliases": "Johnny Smith, J.R. Smith",
    "date_of_birth": "1942-03-15",
    "date_of_death": "2019-11-22",
    "state_of_death": "IL",
    "case_type": "Unclaimed",
    "physical_description": "Male, approximately 5'10\", gray hair",
    "is_veteran": true,
    "veteran_branch": "US Army",
    "veteran_war_era": "Vietnam",
    "facility_name": "Oak Grove Funeral Home",
    "facility_case_number": "OG-2019-0847",
    "facility_contact_email": "info@oakgrovefh.com",
    "facility_contact_phone": "217-555-0123"
}
Response 201 Created
{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "pending_review",
    "message": "Case submitted for review"
}
GET /api/v1/cremains

List all cases submitted by your account. Results are paginated.

Query Parameters
ParameterTypeDefaultDescription
pageinteger1Page number
per_pageinteger20Results per page (max 100)
statusstringallFilter by status (see Case Statuses above)
Response 200 OK
{
    "data": [
        {
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "full_name": "John Robert Smith",
            "state_of_death": "IL",
            "case_type": "Unclaimed",
            "status": "published",
            "created_at": "2026-03-22 14:30:00",
            ...
        }
    ],
    "pagination": {
        "total": 142,
        "page": 1,
        "per_page": 20,
        "total_pages": 8
    }
}
GET /api/v1/cremains/{id}

Retrieve a single case by its UUID. You can only access cases submitted by your account.

Response 200 OK
{
    "data": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "full_name": "John Robert Smith",
        "known_aliases": "Johnny Smith, J.R. Smith",
        "date_of_birth": "1942-03-15",
        "date_of_death": "2019-11-22",
        "state_of_death": "IL",
        "physical_description": "Male, approximately 5'10\", gray hair",
        "case_type": "Unclaimed",
        "is_veteran": 1,
        "veteran_branch": "US Army",
        "veteran_service_number": null,
        "veteran_war_era": "Vietnam",
        "facility_name": "Oak Grove Funeral Home",
        "facility_case_number": "OG-2019-0847",
        "facility_contact_email": "info@oakgrovefh.com",
        "facility_contact_phone": "217-555-0123",
        "status": "published",
        "resolution_type": null,
        "source": "funeral_home",
        "research_status": null,
        "created_at": "2026-03-22 14:30:00",
        "updated_at": null
    }
}
SSN is never returned in any API response. It is stored encrypted and used only for internal veteran status verification.
PUT /api/v1/cremains/{id}

Update an existing case. Only send the fields you want to change. You can only update cases submitted by your account.

Request Body
PUT https://unclaimedcremains.org/api/v1/cremains/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Content-Type: application/json
X-API-Key: uc_your_api_key_here

{
    "known_aliases": "Johnny Smith, J.R. Smith, John R. Smith",
    "is_veteran": true,
    "veteran_branch": "US Marine Corps"
}
Response 200 OK
{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "message": "Case updated successfully"
}
DELETE /api/v1/cremains/{id}

Withdraw a case from the registry. This is a soft delete — the case status is changed to withdrawn and it no longer appears in public search results. You can only withdraw cases submitted by your account.

Request
DELETE https://unclaimedcremains.org/api/v1/cremains/a1b2c3d4-e5f6-7890-abcd-ef1234567890
X-API-Key: uc_your_api_key_here
Response 200 OK
{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "message": "Case withdrawn successfully"
}
Field Reference

All fields for creating and updating cases.

FieldTypeRequiredDescription
Identity
full_namestring (255)YesFull legal name of the decedent. Never shown publicly.
known_aliasesstring (1000)NoComma-separated known aliases, maiden names, or alternate spellings
date_of_birthdate (YYYY-MM-DD)NoDate of birth. Only the year is shown publicly.
date_of_deathdate (YYYY-MM-DD)NoDate of death. Only the year is shown publicly.
state_of_deathstring (2)YesTwo-letter US state code where death occurred (e.g. IL)
physical_descriptiontextNoPhysical description for identification purposes
Classification
case_typeenumNoUnclaimed (default), Indigent, or Orphan
is_veteranbooleanNotrue or false. Default: false
veteran_branchstring (100)NoMilitary branch (e.g. US Army, US Navy, US Marine Corps)
veteran_service_numberstring (100)NoMilitary service number, if known
veteran_war_erastring (100)NoWar era (e.g. WWII, Korea, Vietnam, Gulf War)
Facility
facility_namestring (255)NoName of the funeral home holding the remains. Defaults to your account's facility name. Never shown publicly.
facility_case_numberstring (100)NoYour internal case/reference number
facility_contact_emailstring (255)NoEmail for match request notifications. Defaults to your account email. Never shown publicly.
facility_contact_phonestring (20)NoPhone for match request notifications. Never shown publicly.
Privacy by design: Full names, exact dates, facility names, and contact info are never shown in public search results. The public only sees approximate birth/death years, state, case type, veteran status, aliases, and physical description.
Examples
cURL
# Submit a case
curl -X POST https://unclaimedcremains.org/api/v1/cremains \
  -H "Content-Type: application/json" \
  -H "X-API-Key: uc_your_api_key_here" \
  -d '{
    "full_name": "Jane Marie Doe",
    "date_of_birth": "1938-06-12",
    "date_of_death": "2015-01-30",
    "state_of_death": "TX",
    "case_type": "Unclaimed",
    "facility_name": "Peaceful Rest Mortuary",
    "facility_case_number": "PR-2015-0291",
    "facility_contact_email": "info@peacefulrest.com"
  }'

# List your cases
curl -H "X-API-Key: uc_your_api_key_here" \
  "https://unclaimedcremains.org/api/v1/cremains?page=1&per_page=50"

# List only published cases
curl -H "X-API-Key: uc_your_api_key_here" \
  "https://unclaimedcremains.org/api/v1/cremains?status=published"

# Get a single case
curl -H "X-API-Key: uc_your_api_key_here" \
  https://unclaimedcremains.org/api/v1/cremains/a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Update a case
curl -X PUT https://unclaimedcremains.org/api/v1/cremains/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: uc_your_api_key_here" \
  -d '{"is_veteran": true, "veteran_branch": "US Marine Corps"}'

# Withdraw a case
curl -X DELETE https://unclaimedcremains.org/api/v1/cremains/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: uc_your_api_key_here"
PHP
<?php
$api_key = 'uc_your_api_key_here';
$base_url = 'https://unclaimedcremains.org/api/v1';

// Submit a case
$data = [
    'full_name'              => 'Jane Marie Doe',
    'date_of_birth'          => '1938-06-12',
    'date_of_death'          => '2015-01-30',
    'state_of_death'         => 'TX',
    'case_type'              => 'Unclaimed',
    'facility_name'          => 'Peaceful Rest Mortuary',
    'facility_case_number'   => 'PR-2015-0291',
    'facility_contact_email' => 'info@peacefulrest.com',
];

$ch = curl_init("$base_url/cremains");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        "X-API-Key: $api_key",
    ],
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);
echo "Status: $http_code\n";
echo "Case ID: " . ($result['id'] ?? 'error') . "\n";
echo "Case Status: " . ($result['status'] ?? 'unknown') . "\n";
JavaScript (fetch)
const API_KEY = 'uc_your_api_key_here';
const BASE_URL = 'https://unclaimedcremains.org/api/v1';

// Submit a case
const response = await fetch(`${BASE_URL}/cremains`, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY,
    },
    body: JSON.stringify({
        full_name: 'Jane Marie Doe',
        date_of_birth: '1938-06-12',
        date_of_death: '2015-01-30',
        state_of_death: 'TX',
        case_type: 'Unclaimed',
        facility_name: 'Peaceful Rest Mortuary',
        facility_case_number: 'PR-2015-0291',
        facility_contact_email: 'info@peacefulrest.com',
    }),
});

const result = await response.json();
console.log(result);
// { id: "...", status: "pending_review", message: "Case submitted for review" }

Ready to Get Started?

Register your facility to get API keys and start submitting cases to the national registry.

Register Sign In