Getting started

The Homecare Pro API lets a connected system, such as a recruiting platform, bring Homecare Pro onboarding to its agency customers. You set up each agency's onboarding checklists and send new hires in. Homecare Pro then runs onboarding: it creates the new hire's tasks, reminds and follows up with them, reviews what they provide, and reports progress back to you.

🚧

Beta

The API is in beta. Endpoints and fields may change before general availability.

Get credentials

Contact Homecare Pro to request credentials for your connected system. You'll receive an access token to send with every request; see Authentication.

How it fits together

1. Create an agency for each customer with POST /api/agencies, or ask us to link an agency that already uses Homecare Pro.
2. Create task templates for the items on the agency's onboarding checklist, such as an ID upload or a signed policy.
3. Create roles that group those templates, typically one per job or job type in your platform.
4. Add new hires as agency members, assigning them to a role. Assigning a role starts onboarding.
5. Track progress by reading the new hire's tasks and documents.

All requests must specify their agency ID by providing the X-Agency-Id header, except listing and creating agencies.

Walkthrough

These examples use $TOKEN for your access token. All IDs are UUIDs.

1. Create an agency

curl https://platform.homecarepro.io/api/agencies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": {"name": "Example Home Care", "timezone": "America/Chicago"}}'

The response includes the agency's id. Send it as X-Agency-Id on the requests that follow:

export AGENCY_ID=861d8719-9bf2-45fb-81ba-f1e66d935f6c

2. Create a task template

curl https://platform.homecarepro.io/api/task_templates \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Agency-Id: $AGENCY_ID" \
  -H "Content-Type: application/json" \
  -d '{"data": {
        "name": "Driver'\''s License or State ID",
        "instructions": "Upload a photo of the front of your license or ID.",
        "task_template_type": "upload",
        "responsibility": "caregiver",
        "user_status": "onboarding",
        "expiration_required": true,
        "days_due_after_creation": 7
      }}'

3. Create a role

curl https://platform.homecarepro.io/api/agency_roles \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Agency-Id: $AGENCY_ID" \
  -H "Content-Type: application/json" \
  -d '{"data": {"name": "Personal Care Aide", "task_template_ids": ["f8d872a9-4cb7-45ba-b876-a0e5bf3ba873"]}}'

4. Add a new hire

Use external_id for your own identifier for the candidate, so you can look them up later without storing our ID.

curl https://platform.homecarepro.io/api/agency_members \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Agency-Id: $AGENCY_ID" \
  -H "Content-Type: application/json" \
  -d '{"data": {
        "first_name": "Example",
        "last_name": "Caregiver",
        "email": "[email protected]",
        "phone": "+15555550100",
        "external_id": "candidate-48213",
        "agency_role_ids": ["ce077f28-93d9-46a8-a264-d60927343a73"]
      }}'

Homecare Pro creates a task for each template in the role and contacts the new hire to start onboarding. Tasks are created in the background, so they may take a moment to appear.

5. Track progress

List the new hire's tasks. The -g flag stops curl from treating the square brackets in the filter as a pattern:

curl -g "https://platform.homecarepro.io/api/tasks?filters[agency_member][id][]=2d33762e-1260-4d14-9365-1a4442ec7a3b" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Agency-Id: $AGENCY_ID"

Each task has a status (incomplete, under review, complete, paused or canceled), and the member's onboarding_stage shows where they are overall.

To withdraw a new hire from onboarding, update them with an empty agency_role_ids list.

Next steps

• Authentication: access tokens and the agency header.
• Data model: how agencies, roles, members and tasks relate.
• Pagination and links: reading lists and following links.
• Errors and asynchronous updates: status codes and what a 202 means.