Dala Care GraphQL API

This skill teaches how to interact with the Dala Care healthcare workforce management platform via its GraphQL API.

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: <api-key>

API keys have associated roles that determine access permissions across the organization hierarchy (Tenant > Division > Region > Office).

Endpoints

• EU: https://api.eu.dala.care/graphql
• US: https://api.us.dala.care/graphql

Making Requests

Send POST requests with:

• Content-Type: application/json
• Body: {"query": "...", "variables": {...}}

Date/Time Format

All dates use ISO 8601 format: 2025-01-15T08:00:00.000Z

Core Queries

Get Offices

Returns all offices the authenticated user has access to, with their organizational hierarchy.

query Offices {
  offices {
    id
    name
    type          # OFFICE or CARE_HOME
    region {
      id
      name
      division {
        id
        name
      }
    }
  }
}

Get Care Recipients

List care recipients. Pass empty officeIds array to get all accessible care recipients.

query CareRecipients($officeIds: [String!]!) {
  careRecipients(filter: { officeIds: $officeIds }) {
    id
    firstName
    lastName
    gender          # MALE, FEMALE, OTHER
    email
    phone
    homePhone
    careRecipientRoles {
      deactivatedAt
      office {
        id
        name
      }
    }
  }
}

Variables:

{
  "officeIds": []
}

Get Care Recipient Details

Get comprehensive information including contacts, address, care plan, and files.

query CareRecipientById($id: ID!) {
  careRecipientById(id: $id) {
    id
    firstName
    lastName
    pid
    birthDate
    phone
    homePhone
    email
    gender

    address {
      addressLine1
      addressLine2
      city
      state
      zipCode
      homeInformation
    }

    contacts {
      id
      firstName
      lastName
      relationshipType  # SPOUSE, PARENT, CHILD, SIBLING, etc.
      email
      phone
      isPrimary
      isPayer
      hasPowerOfAttorney
    }

    primaryContact {
      id
      firstName
      lastName
      phone
      email
    }

    careRecipientRoles {
      deactivatedAt
      office {
        id
        name
        type
      }
    }

    carePlan {
      fields {
        ... on RadioField {
          __typename
          id
          name
          description
          availableValues
          value
          required
        }
        ... on CheckboxField {
          __typename
          id
          name
          description
          availableValues
          values
          required
        }
        ... on TextField {
          __typename
          id
          name
          description
          value
          required
        }
        ... on TextArea {
          __typename
          id
          name
          description
          value
          required
        }
        ... on DateField {
          __typename
          id
          name
          description
          value
          required
        }
      }
    }

    files {
      name
      url
    }
  }
}

Get Care Recipients Visits

Query visits for a specific care recipient within a date range.

query CareRecipientVisits($careRecipientId: ID!, $from: String!, $to: String!) {
  visitsByCareRecipientId(
    careRecipientId: $careRecipientId
    from: $from
    to: $to
  ) {
    id
    visitDefinitionId
    officeId
    subjectId
    subjectType       # CARE_RECIPIENT or CARE_HOME
    start
    durationMinutes
    cancelledAt
    cancelledReason   # CANCELLED_BY_CARE_RECIPIENT, CANCELLED_BY_CARE_PROVIDER, etc.

    visitorsV2 {
      id
      firstName
      lastName
      clockInTime
      clockOutTime
    }

    visitType {
      id
      title
      code
    }

    labels {
      id
      name
    }

    visitNotes {
      id
      note
      createdAt
      sentiment {
        positive
        negative
        neutral
        mixed
      }
      author {
        id
        firstName
        lastName
      }
    }
  }
}

Variables:

{
  "careRecipientId": "uuid",
  "from": "2025-01-01T00:00:00.000Z",
  "to": "2025-01-31T23:59:59.999Z"
}

Get Caregivers

List caregivers for specified offices.

query CareGivers($officeIds: [String!]!) {
  careGivers(filter: { officeIds: $officeIds }) {
    id
    firstName
    lastName
    email
    phone
    homePhone
    birthDate
    pid
    lastLogin
    caregiverRoles {
      userId
      hireDate
      deactivatedAt
      office {
        id
        name
      }
    }
  }
}

Get Events by Office (Day Summary)

Get all events (visits and absences) for offices in a date range. This is the primary query for understanding daily scheduling status.

query EventsByOfficeIds($officeIds: [ID!]!, $from: String!, $to: String!) {
  eventsByOfficeIds(officeIds: $officeIds, from: $from, to: $to) {
    ... on Visit {
      id
      visitDefinitionId
      officeId
      subjectId
      subjectType
      start
      durationMinutes
      isVisitLog
      cancelledAt
      cancelledReason
      requiredCaregiversCount

      visitorsV2 {
        id
        firstName
        lastName
        clockInTime
        clockOutTime
      }

      subject {
        ... on CareRecipient {
          id
          firstName
          lastName
        }
        ... on CareHome {
          id
          name
        }
      }

      visitType {
        id
        title
        code
      }

      labels {
        id
        name
      }
    }
    ... on Absence {
      id
      userId
      start
      end
      allDay
      reason
      description
    }
  }
}

Visit Status Logic:

• Open: requiredCaregiversCount > visitorsV2.length and not cancelled
• Scheduled: Future visit with sufficient caregivers assigned
• Late: start + durationMinutes < now and has clockInTime but no clockOutTime
• Missed: Past visit with no clockInTime on any visitor
• Cancelled: Has cancelledAt value
• Completed: isVisitLog = true or has clockOutTime on visitors

Check Caregiver Availability

Query which caregivers are available for a proposed visit time.

query CaregiverAvailabilities($officeIds: [ID!]!, $input: VisitorAvailabilityInput!) {
  caregiverAvailabilitiesByOfficeIds(officeIds: $officeIds, input: $input) {
    visitorId
    visitor {
      id
      firstName
      lastName
      email
      phone
    }
    firstVisit         # Available for the first occurrence
    allVisits          # Available for all occurrences (if recurring)
    conflictFirstVisit # Has conflict on first occurrence
    conflictInSeries   # Has conflict somewhere in series
  }
}

Variables:

{
  "officeIds": ["office-uuid"],
  "input": {
    "start": "2025-01-15T09:00:00.000Z",
    "durationMinutes": 60,
    "end": "2025-03-15T09:00:00.000Z",
    "rRule": {
      "frequency": "WEEKLY",
      "weekdays": ["MONDAY", "WEDNESDAY", "FRIDAY"],
      "interval": 1,
      "weekStart": "MONDAY"
    }
  }
}

Core Mutations

Schedule a Visit

Create a new visit (one-time or recurring).

mutation ScheduleVisit($input: VisitCreateInputV2!) {
  visitCreateV2(input: $input) {
    id
    subjectId
    subjectType
    recurrences {
      id
      start
      end
      durationMinutes
      visitorIds
      visitors {
        id
        firstName
        lastName
      }
      rRule {
        frequency
        weekdays
        interval
        weekStart
      }
    }
  }
}

Variables for one-time visit:

{
  "input": {
    "subjectId": "care-recipient-uuid",
    "subjectType": "CARE_RECIPIENT",
    "officeId": "office-uuid",
    "start": "2025-01-15T09:00:00.000Z",
    "durationMinutes": 60,
    "visitorIds": ["caregiver-uuid-1", "caregiver-uuid-2"],
    "requiredCaregiversCount": 1
  }
}

Variables for recurring visit:

{
  "input": {
    "subjectId": "care-recipient-uuid",
    "subjectType": "CARE_RECIPIENT",
    "officeId": "office-uuid",
    "start": "2025-01-15T09:00:00.000Z",
    "end": "2025-06-15T09:00:00.000Z",
    "durationMinutes": 60,
    "visitorIds": ["caregiver-uuid"],
    "requiredCaregiversCount": 1,
    "rRule": {
      "frequency": "WEEKLY",
      "weekdays": ["MONDAY", "WEDNESDAY", "FRIDAY"],
      "interval": 1,
      "weekStart": "MONDAY"
    }
  }
}

Update a Visit (Future)

Modify a future visit instance.

mutation UpdateVisit($input: VisitUpdateInput!) {
  visitUpdate(input: $input) {
    id
    visitDefinitionId
    officeId
    subjectId
    start
    durationMinutes
    requiredCaregiversCount
    visitorsV2 {
      id
      firstName
      lastName
    }
  }
}

Variables:

{
  "input": {
    "visitInstanceId": "visit-uuid",
    "visitorIds": ["caregiver-uuid-1", "caregiver-uuid-2"],
    "durationMinutes": 90,
    "start": "2025-01-15T10:00:00.000Z",
    "requiredCaregiversCount": 2
  }
}

Update a Visit Log (Past)

Modify a past visit (visit log).

mutation UpdateVisitLog($visitInstanceId: ID!, $input: VisitLogUpdateInput!) {
  visitLogUpdate(visitInstanceId: $visitInstanceId, input: $input) {
    id
    visitDefinitionId
    officeId
    subjectId
    start
    durationMinutes
    visitorsV2 {
      id
      firstName
      lastName
    }
  }
}

Variables:

{
  "visitInstanceId": "visit-uuid",
  "input": {
    "visitors": [
      {
        "id": "caregiver-uuid",
        "clockInTime": "2025-01-15T09:00:00.000Z",
        "clockOutTime": "2025-01-15T10:00:00.000Z"
      }
    ],
    "startDate": "2025-01-15T09:00:00.000Z",
    "durationMinutes": 60
  }
}

Update Care Plan

Modify care plan fields for a care recipient.

mutation CareRecipientCarePlanUpsert($careRecipientId: String!, $input: CarePlanInput!) {
  carePlanForCareRecipientUpsert(careRecipientId: $careRecipientId, input: $input) {
    id
  }
}

Variables:

{
  "careRecipientId": "care-recipient-uuid",
  "input": {
    "fields": [
      {
        "id": "field-id-1",
        "type": "RADIO_FIELD",
        "value": "Option A"
      },
      {
        "id": "field-id-2",
        "type": "CHECKBOX_FIELD",
        "value": "Option 1,Option 3"
      },
      {
        "id": "field-id-3",
        "type": "TEXT_FIELD",
        "value": "Some text value"
      },
      {
        "id": "field-id-4",
        "type": "DATE_FIELD",
        "value": "2025-01-15"
      }
    ]
  }
}

Field Types:

• RADIO_FIELD: Single value from availableValues
• CHECKBOX_FIELD: Comma-separated values from availableValues
• TEXT_FIELD: Free text (short)
• TEXT_AREA: Free text (long)
• DATE_FIELD: Date string

Cancel a Visit

mutation CancelVisit(
  $visitInstanceId: ID!
  $cancelledAt: String!
  $cancelledReason: CancelledReason!
  $cancelFollowing: Boolean!
  $cancelledAdditionalInformation: String
) {
  visitCancel(
    visitInstanceId: $visitInstanceId
    cancelledAt: $cancelledAt
    cancelledReason: $cancelledReason
    cancelFollowing: $cancelFollowing
    cancelledAdditionalInformation: $cancelledAdditionalInformation
  ) {
    id
    cancelledAt
    cancelledReason
  }
}

Variables:

{
  "visitInstanceId": "visit-uuid",
  "cancelledAt": "2025-01-15T08:00:00.000Z",
  "cancelledReason": "CANCELLED_BY_CARE_RECIPIENT",
  "cancelFollowing": false,
  "cancelledAdditionalInformation": "Patient hospitalized"
}

Cancellation Reasons:

• CANCELLED_BY_CARE_RECIPIENT
• CANCELLED_BY_CARE_PROVIDER
• HOSPITAL_CARE_FACILITY
• HOLIDAY
• RESCHEDULED
• OTHER

Reference Types

Recurrence (rRule)

input RRuleInput {
  frequency: Frequency!    # DAILY, WEEKLY, MONTHLY
  weekdays: [Weekday!]     # Required for WEEKLY
  interval: Int            # Every N periods (default: 1)
  weekStart: Weekday!      # MONDAY, TUESDAY, etc.
}

Weekdays

MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY

Relationship Types

SPOUSE, PARENT, CHILD, SIBLING, IN_LAW, GRANDPARENT, GRANDCHILD, FAMILY, FRIEND, NEIGHBOR, MEDICAL, THERAPY, OTHER

Absence Reasons (Caregiver)

PAID_LEAVE, UNPAID_LEAVE, PAID_SICK_LEAVE, UNPAID_SICK_LEAVE, SICK_CHILD, UNPAID_SICK_CHILD, TRAINING, OTHER

Absence Reasons (Care Recipient)

CANCELLED_BY_CARE_RECIPIENT, CANCELLED_BY_CARE_PROVIDER, HOSPITAL_CARE_FACILITY, HOLIDAY, OTHER

Role Types

• ADMIN: Full administrative access
• SCHEDULING_MANAGER: Manage schedules and visits
• SUCCESS_MANAGER: Manage care recipients and caregivers
• CAREGIVER: Field worker providing care
• CARE_RECIPIENT: Person receiving care
• CONTACT: Family member or emergency contact

Resource Hierarchy

Tenant (organization)
  └── Division
        └── Region
              └── Office
                    └── Care Recipients & Caregivers

Common Workflows

Find Available Caregivers and Schedule a Visit

1. Query Offices to get office IDs
2. Query CareRecipients to find the care recipient
3. Query CaregiverAvailabilities with proposed time to find available caregivers
4. Execute ScheduleVisit mutation with selected caregivers

View Daily Schedule and Find Open Visits

1. Query EventsByOfficeIds for the target date range
2. Filter visits where requiredCaregiversCount > visitorsV2.length and cancelledAt is null
3. These are visits that need additional caregiver assignments

Assign Caregiver to Existing Visit

1. Determine if visit is future (start > now) or past
2. For future visits: use UpdateVisit mutation with updated visitorIds
3. For past visits: use UpdateVisitLog mutation with visitor details

Update Care Plan Information

1. Query CareRecipientById to get current care plan fields with their IDs and available values
2. For RADIO_FIELD: value must be one of availableValues
3. For CHECKBOX_FIELD: value is comma-separated list from availableValues
4. Execute CareRecipientCarePlanUpsert with field updates