API Reference
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 URL | https://unclaimedcremains.org/api/v1 |
| Format | JSON (request and response) |
| Encoding | UTF-8 |
| HTTP Methods | GET 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.
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.
| Code | Meaning |
|---|---|
200 | Success |
201 | Created — case submitted for review |
400 | Bad Request — missing or invalid parameters |
401 | Unauthorized — invalid or missing API key |
404 | Not Found — case does not exist or does not belong to your account |
405 | Method Not Allowed |
422 | Validation Error — check the errors array in the response |
429 | Rate 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.
| Status | Description |
|---|---|
pending_review | Newly submitted, awaiting admin approval |
published | Approved and visible in public search results |
match_requested | A family member has submitted a match request for this case |
claimed | Remains have been claimed by family |
resolved | Case has been resolved (remains disposed or returned) |
under_investigation | Under review by DwD administrators |
withdrawn | Withdrawn by the submitting facility |
facility_closed | Submitting facility has closed |
archived | Archived 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
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number |
per_page | integer | 20 | Results per page (max 100) |
status | string | all | Filter 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
}
}
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.
| Field | Type | Required | Description |
|---|---|---|---|
| Identity | |||
full_name | string (255) | Yes | Full legal name of the decedent. Never shown publicly. |
known_aliases | string (1000) | No | Comma-separated known aliases, maiden names, or alternate spellings |
date_of_birth | date (YYYY-MM-DD) | No | Date of birth. Only the year is shown publicly. |
date_of_death | date (YYYY-MM-DD) | No | Date of death. Only the year is shown publicly. |
state_of_death | string (2) | Yes | Two-letter US state code where death occurred (e.g. IL) |
physical_description | text | No | Physical description for identification purposes |
| Classification | |||
case_type | enum | No | Unclaimed (default), Indigent, or Orphan |
is_veteran | boolean | No | true or false. Default: false |
veteran_branch | string (100) | No | Military branch (e.g. US Army, US Navy, US Marine Corps) |
veteran_service_number | string (100) | No | Military service number, if known |
veteran_war_era | string (100) | No | War era (e.g. WWII, Korea, Vietnam, Gulf War) |
| Facility | |||
facility_name | string (255) | No | Name of the funeral home holding the remains. Defaults to your account's facility name. Never shown publicly. |
facility_case_number | string (100) | No | Your internal case/reference number |
facility_contact_email | string (255) | No | Email for match request notifications. Defaults to your account email. Never shown publicly. |
facility_contact_phone | string (20) | No | Phone for match request notifications. Never shown publicly. |
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" }