Actions Reference
Care Recipients
Care recipients are the individuals receiving home care services. This domain has the most actions because care recipients are the core of the dala.care data model.
Create Care Recipient:
Creates a new care recipient in dala.care.
Field | Required | Description |
first_name | Yes | First name |
last_name | Yes | Last name |
office | Yes | Select from dropdown — the office this person belongs to |
pid | No | A custom identifier set by your organization (e.g., internal client number, external system ID) |
gender | No | Male, Female, or Other |
birth_date | No | Date of birth (YYYY-MM-DD) |
phone | No | Mobile phone number |
home_phone | No | Home phone number |
No | Email address | |
emergency_contact | No | Emergency contact information |
address_line_1, address_line_2, city, state, zip | No | Full mailing address |
latitude, longitude | No | GPS coordinates for the home address |
home_information | No | Notes about the home (e.g., “Ring doorbell twice, code is 4521”) |
When to use: A new client is referred to your agency and you want to automatically create their profile — for example, when a row is added to a Google Sheet intake form or a record is created in your CRM.
Update Care Recipient
Updates an existing care recipient’s profile.
Field | Required | Description |
care_recipient_id | Yes | The ID of the care recipient to update |
first_name | Yes | First name |
last_name | Yes | Last name |
office | Yes | Select from dropdown |
All other fields from Create | No | Phone, email, address, etc. |
WARNING — Full Replace: This action replaces all fields on the care recipient, not just the ones you provide. Any field you leave blank will be cleared. Always use Get Care Recipient by ID or Search Care Recipient by PID first to fetch the current values, then pass them all back with only the fields you want to change modified. See Tips & Best Practices for a detailed walkthrough.
When to use: Keeping dala.care in sync when a care recipient’s information changes in another system (e.g., a CRM or EHR).
Deactivate Care Recipient
Soft-deletes a care recipient. The record is hidden from active lists but not permanently removed.
Field | Required |
care_recipient_id | Yes |
office | Yes (dropdown) |
When to use: A care recipient is discharged from your agency’s services. Use Reactivate Care Recipient if they return.
Reactivate Care Recipient
Restores a previously deactivated care recipient.
When to use: A previously discharged care recipient resumes services.
Add Care Recipient to Office
Assigns a care recipient to an additional office (does not remove them from their current office).
When to use: A care recipient begins receiving services from a second office location.
Create Contact
Adds a contact person (family member, medical provider, etc.) linked to a care recipient.
Field | Required | Description |
care_recipient_id | Yes | The care recipient this contact belongs to |
first_name | Yes | Contact’s first name |
last_name | Yes | Contact’s last name |
phone | Yes | Contact’s phone number |
relationship_type | Yes | See Relationship Types table |
is_payer | Yes | Is this contact the payer? (true/false) |
has_power_of_attorney | Yes | Does this contact have power of attorney? (true/false) |
is_primary | Yes | Is this the primary contact? (true/false) |
home_phone, birth_date, pid, email | No | Additional contact details |
prefer_email, prefer_postal_mail | No | Communication preferences |
When to use: Adding next-of-kin or medical provider information when onboarding a new care recipient.
Update Contact
Updates an existing contact’s information. Same fields as Create Contact, plus contact_id (required).
WARNING — Full Replace: Same caution as Update Care Recipient. Fetch the contact first using Search Contacts by Care Recipient, then pass all values back.
Create Care Recipient Absence
Records a period when the care recipient is unavailable (e.g., hospitalized, on holiday).
Field | Required | Description |
user_id | Yes | The care recipient’s user ID |
start | Yes | Start date/time (ISO 8601, e.g., 2024-06-01T08:00:00+02:00) |
all_day | Yes | Is this an all-day absence? (true/false) |
reason | Yes | See Care Recipient Absence Reasons |
reported_at | Yes | When the absence was reported (ISO 8601) |
end | No | End date/time (omit for open-ended absences) |
description | No | Free text note |
external_id | No | ID from an external system for reference |
When to use: A care recipient is admitted to the hospital and visits need to be paused.
Care Recipient Searches
Search | Required Fields | Description |
Get Care Recipient by ID | id | Retrieve full details for a single care recipient. Use before updates. |
Search Care Recipient by PID | pid | Find a care recipient by their custom identifier (PID) |
Search Care Recipients by Office | office_id (dropdown) | List all active care recipients in a specific office |
Search Contacts by Care Recipient | care_recipient_id | List all contacts linked to a care recipient |
Find Activities by Care Recipient | care_recipient_id | List all scheduled activities for a care recipient |
Caregivers
Caregivers are the staff members who provide home care services.
Create Caregiver
Field | Required | Description |
first_name | Yes | First name |
last_name | Yes | Last name |
office | Yes | Select from dropdown |
phone | Yes | Mobile phone number |
hire_date | Yes | Date hired (YYYY-MM-DD) |
home_phone, birth_date, pid, email, emergency_contact | No | Additional details |
When to use: A new caregiver is hired and added to your HR system — trigger this action to create their dala.care profile automatically.
Update Caregiver
Same fields as Create Caregiver, plus caregiver_id (required).
WARNING — Full Replace: Fetch the caregiver’s current data first using Get Caregiver by ID or Search Caregiver by PID.
Deactivate / Reactivate Caregiver
Same pattern as care recipients. Requires caregiver_id and office. Deactivation is reversible.
When to use: A caregiver leaves your agency (deactivate) or returns from a long leave (reactivate).
Add Caregiver to Office
Assigns a caregiver to an additional office. Requires caregiver_id, office, hire_date, and optionally emergency_contact.
Create Caregiver Absence
Records a caregiver’s time off.
Field | Required | Description |
user_id | Yes | The caregiver’s user ID |
start | Yes | Start date/time (ISO 8601) |
all_day | Yes | All-day absence? (true/false) |
reason | Yes | See Caregiver Absence Reasons |
reported_at | Yes | When reported (ISO 8601) |
end, description, external_id | No | Optional details |
When to use: A caregiver calls in sick or requests PTO — log it from your scheduling or HR tool.
Caregiver Searches
Search | Required Fields | Description |
Get Caregiver by ID | id | Full caregiver details. Use before updates. |
Search Caregiver by PID | pid | Find by custom identifier (PID) |
Search Caregivers by Office | office_id (dropdown) | List all active caregivers in an office |
Visits
Visits represent scheduled home care sessions — a specific time slot where one or more caregivers visit a care recipient (or care home).
Create Visit
Field | Required | Description |
subject_id | Yes | The care recipient or care home ID |
subject_type | Yes | CARE_RECIPIENT or CARE_HOME |
office | Yes | Select from dropdown |
start | Yes | Visit start time (ISO 8601, e.g., 2024-04-01T09:00:00+02:00) |
duration_minutes | Yes | Visit length in minutes (e.g., 60) |
visitor_ids | No | Comma-separated caregiver UUIDs to assign |
required_caregivers_count | No | How many caregivers are needed |
visit_type | No | Select from dropdown (loaded from your visit types) |
recurrence_type | No | NO_REPEAT, DAILY, WEEKLY, EVERY_WEEKDAY, MONTHLY, or CUSTOM |
Recurrence fields: When you select a recurrence type other than NO_REPEAT, an additional end date field appears. If you select CUSTOM, three more fields appear:
frequency — How often the pattern repeats (Daily, Weekly, Monthly)
interval — The repeat interval number (e.g., every 2 weeks)
weekdays — Which days of the week (e.g., Monday, Wednesday, Friday)
When to use: Scheduling a recurring morning visit for a care recipient, or creating a one-off visit from an intake request.
Update Visit
Updates a single occurrence of a visit (not the entire series).
Field | Required |
visit_instance_id | Yes |
visitor_ids, start, duration_minutes, required_caregivers_count, visit_type | No — but this is a full replace on the instance |
WARNING — Full Replace: This replaces all fields on the visit instance. Fetch current values first with Get Visit by ID.
Cancel Visit
Marks a visit occurrence as cancelled (reversible).
Field | Required | Description |
visit_instance_id | Yes | The specific visit occurrence to cancel |
cancelled_at | Yes | When the cancellation happened (ISO 8601) |
cancelled_reason | Yes | See Cancelled Reasons |
cancelled_additional_information | No | Optional notes or description about the cancellation |
When to use: A care recipient calls to cancel tomorrow’s visit, or the care provider needs to cancel due to staffing or scheduling changes.
Reactivate Visit
Restores a cancelled visit. Requires only visit_instance_id.
Delete Visit
Permanently removes a visit. Cannot be undone.
Field | Required | Description |
visit_instance_id | Yes | The visit to delete |
delete_following | Yes | If true, also deletes all future occurrences in the series |
CAUTION — Permanent: This action cannot be undone. If you only need to temporarily remove a visit, use Cancel Visit instead.
Visit Searches
Search | Required Fields | Description |
Get Visit by ID | visit_instance_id | Full visit details including assigned caregivers, notes, and labels |
Search Visits by Care Recipient | care_recipient_id, from, to | All visits for a care recipient in a date range |
Search Visits by Caregiver | caregiver_id, from, to | All visits assigned to a caregiver in a date range |
Note on date range searches: Both from and to are required and must be in ISO 8601 format. Example: from: 2024-04-01T00:00:00Z, to: 2024-04-30T23:59:59Z.
Activities
Activities are tasks or care actions that need to be performed — like “Administer morning medication” or “Check blood pressure.” They can be one-off tasks or recurring on a schedule.
Create Activity
Field | Required | Description |
subject_id | Yes | The care recipient or care home this activity is for |
subject_type | Yes | CARE_RECIPIENT or CARE_HOME |
title | Yes | Short task name (e.g., “Blood pressure check”) |
description | Yes | Detailed instructions for caregivers |
priority | No | LOW, MEDIUM, HIGH, or OPTIONAL |
activity_type | No | Select from dropdown (loaded from your configured types) |
start_date | No | When the activity begins (YYYY-MM-DD) |
schedule_type | No | How the activity recurs (see below) |
Schedule types and their additional fields:
Schedule Type | Meaning | Additional Fields |
ONE_OFF | Happens once | Time of day |
EVERY_VISIT | Repeats on every visit | End date |
FIXED_RECURRENCE | Repeats on a fixed pattern | Frequency, interval, weekdays, start/end dates |
EVERY_N_DAYS | Repeats every N days | Day interval |
VISIT_SERIES | Tied to a specific visit series | Visit definition IDs |
When to use: Adding a care task to a recipient’s care plan, such as daily medication reminders or weekly wound care checks.
Create and Schedule Activity
Same as Create Activity, but also requires a visit_definition_id to immediately link the activity to a visit series. This is a convenience action that combines Create Activity + Schedule Activity to Visit in a single step.
Update Activity
Field | Required |
activity_id | Yes |
title | Yes |
description | Yes |
priority, start_date, end_date, time_of_day_start, activity_type | No |
When to use: Updating care plan instructions — for example, changing a medication dosage in the activity description.
Schedule Activity to Visit
Links an existing activity to a visit series so the activity appears on every visit in that series.
Field | Required |
activity_id | Yes |
visit_definition_id | Yes |
When to use: After creating an activity, attach it to a recurring visit series so caregivers see the task on every visit.
Delete Activity
Permanently removes an activity. Requires only activity_id.
CAUTION — Permanent: This cannot be undone.
Activity Searches
Search | Required Fields | Description |
Search Activity Types | search (optional) | Browse or search available activity type templates |
Billing / Visit Types
Visit types define the billing structure for visits — hourly vs. fixed rates, time-of-day rate tiers, and billing codes.
Create Visit Type
Field | Required | Description |
title | Yes | Display name (e.g., “Standard Home Visit”) |
code | Yes | Billing code (e.g., “HV-001”) |
billing_type | Yes | FIXED (flat rate per visit) or HOURLY (rate per hour) |
base_rate | Yes | Base rate amount |
base_period_start | Yes | When the base rate period starts (e.g., 06:00) |
evening_rate | No | Evening rate (if different from base) |
evening_period_start | No | When evening rate kicks in (e.g., 18:00) |
night_rate | No | Night rate |
night_period_start | No | When night rate kicks in (e.g., 22:00) |
When to use: Setting up billing structures when your agency introduces a new service type.
Billing Searches
Search | Required Fields | Description |
Search Visit Types | search (optional) | Browse or search configured visit types with their rates and codes |
Offices
Search Offices
Field | Required | Description |
office_search | Yes | Search term — office name or ID |
When to use: Looking up an office ID to use in other actions. Most office fields in other actions provide a dropdown, so you may not need this search often.
Absences
Absences track periods when caregivers or care recipients are unavailable. They are created via the Create Caregiver Absence and Create Care Recipient Absence actions (documented under their respective domains above). This section covers searching and deleting absences.
Absence Searches
Search | Required Fields | Description |
Get Absence by ID | id | Retrieve an absence by its internal UUID |
Get Absence by External ID | external_id | Retrieve an absence by its external system identifier — useful for integrations that track absences using their own IDs |
Search Absences by Office | office_id (dropdown), role_type, from, to | List all absences in an office for a date range, filtered by role type |
Search Absences by Office — Role Type filter:
Value | Description |
CAREGIVER | Caregiver absences |
CARE_RECIPIENT | Care recipient absences |
CONTACT | Contact absences |
SCHEDULING_MANAGER | Scheduling manager absences |
SUCCESS_MANAGER | Success manager absences |
ADMIN | Admin absences |
Tip: For most use cases, you will filter by CAREGIVER or CARE_RECIPIENT.
Delete Absence
Permanently removes an absence record. Two variants are available depending on how you identify the absence:
Action | Required Fields | Description |
Delete Absence | absence_id | Delete by dala.care’s internal UUID |
Delete Absence by External ID | external_id | Delete by the external system identifier |
CAUTION — Permanent: Deletion cannot be undone.
When to use: Removing an absence that was entered in error, or cleaning up absences synced from an external system that have been cancelled there.