Working with Shiva listings
This page documents the Shiva listing API. Creating or updating a listing requires a personal API token. Published listings can be read without authentication.
Base URL (production app):
https://app.tnuchamu.org/api
Meal-train / food coordinator details and donation URL fields live on the listing
itself (via PATCH /api/shiva-listings/:id).
Authentication
Authenticate API requests with a personal API token. Create a token in your account profile under Developer API Keys, then send it on every authenticated request:
Authorization: Bearer tnc_YOUR_SECRET_HERE
Tokens are prefixed with tnc_. Send them only over HTTPS. Do not put tokens
in query strings, client-side JavaScript, or public repos.
Example: create a listing with a token
curl -X POST https://app.tnuchamu.org/api/shiva-listings \
-H "Authorization: Bearer tnc_YOUR_SECRET_HERE" \
-H "Content-Type: application/json" \
-d @listing.json
Requests without a valid token receive 401 on protected endpoints. See
API tokens for how to create, revoke, and use tokens safely.
API tokens
Create and revoke tokens from your account profile in the app (Developer API Keys). The full secret is shown once at creation. Only a hash is stored server-side; revoked tokens stop working immediately.
What tokens can and cannot do
| Capability | Allowed |
|---|---|
| Create / update / manage your Shiva listings and related resources | Yes |
| Act as your user on ordinary authenticated endpoints | Yes |
| Create or revoke other API tokens | No — manage tokens in the app profile |
Limits and security
- Up to 5 active tokens per user.
- Failed token attempts are rate-limited per IP; valid tokens are rate-limited per token.
- A leaked token cannot mint more tokens — still revoke it immediately.
- Treat tokens like passwords. Prefer short-lived automation accounts when possible.
Create a Shiva listing
POST /api/shiva-listings accepts a JSON body validated by
insertShivaListingSchema. When authenticated with an API token, the server
sets userId from the token owner. New listings are usually created as
draft; publish with a later PATCH.
Create a listing. Returns 201 with the created listing object.
Required fields
| Field | Type | Notes |
|---|---|---|
ownerFullName |
string | Listing owner full name |
ownerEmail |
string | Owner email |
ownerPhone |
string | Primary phone |
niftarFirstName |
string | Niftar first name |
niftarLastName |
string | Niftar last name |
niftarGender |
string | e.g. male / female |
niftarDateOfPassing |
string (date) | YYYY-MM-DD |
Common optional fields
| Field | Type | Notes |
|---|---|---|
status |
string | draft (default), published, archived |
ownerSmsPhone, ownerWhatsappPhone |
string | If different from primary |
ownerPreferredContactMethods |
string[] | e.g. ["email","phone","sms","whatsapp"] |
pocSameAsOwner |
boolean | Point of contact same as owner |
pocFullName, pocEmail, pocPhone |
string | Point of contact (if different) |
niftarPrefix, niftarMiddleName, niftarMaidenName |
string | Additional niftar name fields |
niftarJewishName, niftarBio |
string | Jewish name / biography |
niftarFirstYahrzeit |
string | First yahrzeit text/date |
niftarProfilePicture, niftarVideoUrl |
string | Media URLs |
niftarGallery |
array | Gallery items (JSON) |
isMesMitsvah |
boolean | Meis mitzvah listing |
acceptingDonations, donationUrl |
boolean / string | Memorial donation settings |
foodCoordinator* |
mixed | Meal train / food coordinator fields |
shloshimDate, mishnayosLink |
string | L'ilui Nishmas fields |
whatsappGroupInviteLink |
string | Optional WhatsApp group invite |
hideFamilyName |
boolean | Privacy setting |
*Complete flags |
boolean | Tab completion tracking (e.g. informationComplete) |
Example request body
{
"status": "draft",
"ownerFullName": "Sarah Cohen",
"ownerEmail": "sarah@example.com",
"ownerPhone": "+14155550100",
"ownerSmsUsesPrimary": true,
"ownerWhatsappUsesPrimary": true,
"ownerPreferredContactMethods": ["email", "sms"],
"pocSameAsOwner": true,
"niftarPrefix": "Mr.",
"niftarFirstName": "David",
"niftarMiddleName": "",
"niftarLastName": "Cohen",
"niftarGender": "male",
"niftarJewishName": "David ben Moshe",
"niftarDateOfPassing": "2026-07-28",
"niftarBio": "",
"isMesMitsvah": false,
"acceptingDonations": false,
"foodCoordinatorFirstName": "",
"foodCoordinatorLastName": "",
"foodCoordinatorMealTrainLink": "",
"informationComplete": true,
"levayaComplete": false,
"kevurahComplete": false,
"aveilimComplete": false,
"shivaHouseComplete": false,
"minyanComplete": false,
"mealsAndFoodsComplete": false,
"affiliationsComplete": false,
"liluiNishmasComplete": false
}
Houses, aveilim, visiting times, levaya, and kevurah are created with the related
endpoints below after you have the listing id from this response.
Shiva listings
Core CRUD and nested reads for a listing — including houses, aveilim, visiting times, levaya/kevurah, and comfort messages.
List or search public Shiva listings.
Create a new listing (often as a draft). See Create a Shiva listing for the full request body.
Get a listing by numeric id or slug.
Full nested listing payload (houses, minyanim, and related data).
Validate the ready-to-publish checklist.
Update listing fields (including meals and donation URL).
Delete a listing.
Aveilim on the listing.
Shiva houses for the listing.
Levaya events for the listing.
Kevurah details for the listing.
Listing change history.
Read public comfort messages (nichum).
Post a comfort message (authenticated).
Upload or share a listing photo.
Search niftar names (dedupe helper when creating a listing).