> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thefaithapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pastoral Care Integration

> Build a confidential, member-owned Pastoral Care experience with the public v1 API.

## Build Pastoral Care into your app

The Pastoral Care API gives a signed-in member the same confidential workflows
available in TheFaithApp mobile app:

* Share, review, edit, and withdraw a care request.
* See member-safe status, visit, support-plan, and timeline information.
* Manage consent for private follow-up.
* Save or pause a private life-moment date.
* Create a quiet-day window for sensitive seasons.

<Warning>
  Pastoral Care carries sensitive personal information. Never send request
  details, private dates, contact values, quiet-day reasons, or member guidance
  to analytics, crash reporting, application logs, push-notification payloads,
  or AI services.
</Warning>

## Authentication

Every Pastoral Care call requires the partner app key and the signed-in
member's access token:

```http theme={null}
X-API-Key: your-client-api-key
Authorization: Bearer your-member-access-token
Accept: application/json
Content-Type: application/json
```

The app key and member token must resolve to the same church. A mismatch returns
`401 Unauthorized`.

Follow the [Hosted Auth guide](/api-reference/hosted-auth) before integrating
these endpoints.

## Published endpoints

The public contract mirrors the Pastoral Care calls used by TheFaithApp mobile
app.

| Member action                                   | Endpoint                                                                   |
| ----------------------------------------------- | -------------------------------------------------------------------------- |
| Load requests and form options                  | `GET /v1/care-requests`                                                    |
| Share a request                                 | `POST /v1/care-requests`                                                   |
| Edit an open request                            | `PUT /v1/care-requests/{careRequest}`                                      |
| Withdraw an open request                        | `POST /v1/care-requests/{careRequest}/withdraw`                            |
| Load preferences, private dates, and quiet days | `GET /v1/care-life-moments`                                                |
| Update consent and contact preferences          | `PUT /v1/care-life-moments/preferences`                                    |
| Add a private date                              | `POST /v1/care-life-moments/moments`                                       |
| Update or pause a private date                  | `PUT /v1/care-life-moments/moments/{careLifeMoment}`                       |
| Permanently remove a private date               | `DELETE /v1/care-life-moments/moments/{careLifeMoment}`                    |
| Add a quiet day                                 | `POST /v1/care-life-moments/suppressions`                                  |
| Update or deactivate a quiet day                | `PUT /v1/care-life-moments/suppressions/{careCommunicationSuppression}`    |
| Permanently remove a quiet day                  | `DELETE /v1/care-life-moments/suppressions/{careCommunicationSuppression}` |

Staff notes, staff tasks, resolution notes, Care Radar review signals, coverage
rotations, availability, rite runsheets, preaching plans, and staff
coordination are not public partner endpoints.

## Recommended app flow

<Steps>
  <Step title="Load the member's care home">
    Call `GET /v1/care-requests`. Keep the returned `options` with the screen;
    they are the allowed values for care type, privacy, urgency, and contact
    method.

    The list contains active and past requests. Use `can_edit` and
    `can_withdraw` to decide which actions to display.
  </Step>

  <Step title="Let the member review the privacy boundary">
    Explain `care_team` and `pastoral_only` before submission. Counseling,
    benevolence, and crisis requests are always restricted to pastoral staff, even
    if the app sends `care_team`.
  </Step>

  <Step title="Collect explicit contact consent">
    Send `contact_consent: true` only after the member actively confirms that
    the church care team may contact them.

    For phone, text, or email contact, `contact_value` may be omitted when the
    signed-in member profile already has the matching value.
  </Step>

  <Step title="Handle urgent requests responsibly">
    For `urgency: "urgent"` or `type: "crisis_support"`, show a clear notice that
    Pastoral Care is not an emergency service. Submit `emergency_acknowledged:
          true` only after the member confirms the notice.
  </Step>

  <Step title="Refresh after a mutation">
    Use the care request returned by create, update, or withdraw immediately,
    then refresh `GET /v1/care-requests` when the screen resumes or receives a
    generic care-status notification.
  </Step>
</Steps>

## Share a care request

```bash theme={null}
curl -X POST https://api.thefaithapp.com/v1/care-requests \
  -H "X-API-Key: your-client-api-key" \
  -H "Authorization: Bearer your-member-access-token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "hospital_visit",
    "privacy": "care_team",
    "urgency": "soon",
    "details": "Please arrange a hospital visit later this week.",
    "contact_preference": "phone",
    "contact_consent": true
  }'
```

A successful create returns `201 Created` and the new record in
`data.care_request`.

### Care types

Use the values returned in `data.options.types`. The current values are:

| Value                     | Member-facing meaning   |
| ------------------------- | ----------------------- |
| `general_care`            | General care            |
| `hospital_visit`          | Hospital visit          |
| `home_visit`              | Home visit              |
| `new_baby_support`        | New-baby support        |
| `counseling`              | Counseling              |
| `benevolence`             | Benevolence             |
| `grief_support`           | Grief support           |
| `illness_support`         | Illness support         |
| `crisis_support`          | Crisis support          |
| `pastoral_follow_up`      | Pastoral follow-up      |
| `wedding_preparation`     | Wedding preparation     |
| `baby_dedication`         | Baby dedication         |
| `funeral_support`         | Funeral support         |
| `relocation_support`      | Relocation support      |
| `pastoral_recommendation` | Pastoral recommendation |

## Render a request safely

Each care request can include:

* `status`, `urgency`, and whether a caregiver is assigned.
* `next_follow_up_at` when the care team has scheduled a follow-up.
* Member-visible visit times, location, instructions, and outcome.
* Member-visible support-plan dates, coordinator, and requested support.
* A reduced timeline of safe workflow events.
* `content_purged` when confidential content has reached the end of retention.

The response intentionally omits staff notes, staff tasks, internal review
activity, coverage handoffs, and private resolution summaries.

<Note>
  There is no public single-request `GET` endpoint. Keep the selected item from
  `GET /v1/care-requests`, and refresh the list when current data is needed.
</Note>

## Edit and withdraw

`PUT /v1/care-requests/{careRequest}` is a full form update. Send all required
request fields, not only the changed field.

Use `POST /v1/care-requests/{careRequest}/withdraw` only after a confirmation
step. Withdrawal is final. The response sets `can_edit` and `can_withdraw` to
`false`.

Resolved, withdrawn, and retention-purged requests cannot be edited.

## Member-controlled follow-up

Call `GET /v1/care-life-moments` to load:

* `preferences`: current consent and contact choices.
* `life_moments`: private dates owned by the member.
* `suppressions`: the member's quiet-day windows.
* `options`: the supported enum values for your controls.

All reminder and Care Radar consent starts disabled.

### Update preferences

Preference updates are partial. Send only the settings the member changed:

```bash theme={null}
curl -X PUT https://api.thefaithapp.com/v1/care-life-moments/preferences \
  -H "X-API-Key: your-client-api-key" \
  -H "Authorization: Bearer your-member-access-token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "reminders_enabled": true,
    "grief_follow_up_enabled": true,
    "hard_anniversary_follow_up_enabled": true,
    "contact_preference": "text",
    "acknowledgment_style": "ask_first"
  }'
```

Enabling a specific kind does not bypass the master `reminders_enabled`
setting. Care Radar participation and Community Group participation follow-up
also require their own separate member choices.

### Save a private life moment

```bash theme={null}
curl -X POST https://api.thefaithapp.com/v1/care-life-moments/moments \
  -H "X-API-Key: your-client-api-key" \
  -H "Authorization: Bearer your-member-access-token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "grief_anniversary",
    "status": "active",
    "title": "Remember Mum",
    "event_date": "2026-09-14",
    "recurrence": "yearly",
    "reminder_lead_days": 7,
    "member_note": "Please ask before calling."
  }'
```

One-time dates must be today or later. Yearly dates can retain an earlier
calendar year because the next reminder is calculated from the next
anniversary.

Set `status: "paused"` to keep the private date without creating pending
follow-up. `DELETE` permanently removes the date and its pending reminders.

### Create a quiet day

```bash theme={null}
curl -X POST https://api.thefaithapp.com/v1/care-life-moments/suppressions \
  -H "X-API-Key: your-client-api-key" \
  -H "Authorization: Bearer your-member-access-token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "all_celebrations",
    "starts_on": "2026-09-01",
    "ends_on": "2026-09-30",
    "pastoral_acknowledgment": true,
    "reason": "A sensitive family season.",
    "member_guidance": "A private text from a pastor is welcome."
  }'
```

New quiet days are active by default. The end date must be on or after the
start date. Setting `active: false` keeps the preference for later reuse;
deleting it removes the record permanently.

## Error handling

| Status | Meaning for Pastoral Care                                                                         |
| ------ | ------------------------------------------------------------------------------------------------- |
| `401`  | API key or member token is missing, invalid, expired, or belongs to another church.               |
| `404`  | The resource does not exist or is not owned by the signed-in member.                              |
| `422`  | Required values, consent, date rules, enum values, or emergency acknowledgment failed validation. |
| `429`  | The partner API rate limit was reached. Honor `Retry-After` and retry with backoff.               |

Treat `404` as a final resource miss. Do not reveal whether the identifier
belongs to another member or church.

Display validation messages beside their matching fields, but keep raw request
payloads out of logs and support diagnostics.

## Integration checklist

* Use hosted member sign-in and keep both credentials in secure storage.
* Build controls from the returned option arrays instead of hard-coding them.
* Require explicit contact consent.
* Show the non-emergency notice for urgent and crisis requests.
* Use `can_edit` and `can_withdraw` from the API response.
* Do not add Pastoral Care payloads to offline caches or analytics.
* Clear sensitive view state when the member signs out or changes church.
* Use generic push-notification copy and fetch current data after the member
  opens the app.
* Test with two members and two churches to verify ownership boundaries.

<CardGroup cols={2}>
  <Card title="List care requests" icon="list" href="/api-reference/endpoints/pastoral-care/list-my-care-requests">
    Review the complete response contract and try the request.
  </Card>

  <Card title="Load care preferences" icon="sliders" href="/api-reference/endpoints/pastoral-care/get-pastoral-care-preferences">
    See private dates, quiet days, and supported option values.
  </Card>
</CardGroup>