HomeCareBilling API

GET /api/v1/agency

The agency profile

The agency's name, address, NPI, Tax ID and claim defaults.

• 200 The profile object

  data AgencyProfile, required

  Field	Type	Required	Description
  data	AgencyProfile	yes

• default An error, in the shared envelope. Error

PATCH /api/v1/agency

Change the agency profile

Sets only the fields sent. Needs agency_settings.manage (403 forbidden otherwise). An NPI or Tax ID in the wrong form or held by another agency, a blank name, a week start day other than saturday, sunday or monday, or a default_procedure_codes key other than personal_care and homemaker or a value that is no procedure code ("U2") answers 422 validation_failed naming the field. open_shifts sets the open shifts rules, only the keys sent, in the same transaction as the profile; a refused rule answers 422 naming open_shifts.<field> and saves no part of the body.

• 200 The profile object

  data AgencyProfile, required

  Field	Type	Required	Description
  data	AgencyProfile	yes

• 403 Forbidden, as the operation's description says. Error
• 422 Code validation_failed: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/api-keys

List the agency's API keys

Live keys first, then newest first; never a secret. Needs Agency settings → View (403 forbidden otherwise).

• 200 A page of keys object

  data array of object, required

  data[].created_at string

  When it was created (UTC).

  data[].created_by_id string

  The admin who created it.

  data[].id string, required

  The record's id.

  data[].last_used_at string

  Its last request (UTC).

  data[].name string, required

  The key's name.

  data[].revoked_at string

  When it was revoked (UTC).

  data[].role string, required

  What the key may do.

  limit integer, required

  Rows asked for (default 100); a larger request is served 200.

  offset integer, required

  Rows skipped.

  total integer, required

  Every matching row.

  Field	Type	Required	Description
  data	array of object	yes
  data[].created_at	string	no	When it was created (UTC).
  data[].created_by_id	string	no	The admin who created it.
  data[].id	string	yes	The record's id.
  data[].last_used_at	string	no	Its last request (UTC).
  data[].name	string	yes	The key's name.
  data[].revoked_at	string	no	When it was revoked (UTC).
  data[].role	string	yes	What the key may do.
  limit	integer	yes	Rows asked for (default 100); a larger request is served 200.
  offset	integer	yes	Rows skipped.
  total	integer	yes	Every matching row.

• 403 Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

POST /api/v1/api-keys

Create an API key

Settings → API keys creates one and shows its secret once. The role is mapped onto the agency's Owner and Staff roles; one the agency deleted answers 422 role_unavailable. An API key or AI connection gets 403 web_only: someone holding Agency settings → Manage does this signed in to the web app, in Settings.

• 201 The key and its secret, once object

  data object, required

  data.created_at string

  When it was created (UTC).

  data.created_by_id string

  The admin who created it.

  data.id string, required

  The record's id.

  data.last_used_at string

  Its last request (UTC).

  data.name string, required

  The key's name.

  data.revoked_at string

  When it was revoked (UTC).

  data.role string, required

  What the key may do.

  secret string, required

  The secret, shown this once.

  Field	Type	Required	Description
  data	object	yes
  data.created_at	string	no	When it was created (UTC).
  data.created_by_id	string	no	The admin who created it.
  data.id	string	yes	The record's id.
  data.last_used_at	string	no	Its last request (UTC).
  data.name	string	yes	The key's name.
  data.revoked_at	string	no	When it was revoked (UTC).
  data.role	string	yes	What the key may do.
  secret	string	yes	The secret, shown this once.

• 403 Code web_only: Forbidden, as the operation's description says. Error
• 422 Code role_unavailable: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

DELETE /api/v1/api-keys/{id}

Revoke an API key

Settings → API keys revokes one; it stops working on its next request. An API key or AI connection gets 403 web_only: someone holding Agency settings → Manage does this signed in to the web app, in Settings.

• 200 The key object

  data object, required

  data.created_at string

  When it was created (UTC).

  data.created_by_id string

  The admin who created it.

  data.id string, required

  The record's id.

  data.last_used_at string

  Its last request (UTC).

  data.name string, required

  The key's name.

  data.revoked_at string

  When it was revoked (UTC).

  data.role string, required

  What the key may do.

  Field	Type	Required	Description
  data	object	yes
  data.created_at	string	no	When it was created (UTC).
  data.created_by_id	string	no	The admin who created it.
  data.id	string	yes	The record's id.
  data.last_used_at	string	no	Its last request (UTC).
  data.name	string	yes	The key's name.
  data.revoked_at	string	no	When it was revoked (UTC).
  data.role	string	yes	What the key may do.

• 403 Code web_only: Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/connected-apps

List AI app connections

Live connections, newest first, as /connected-apps lists them: the agency's for a credential whose member holds agency_settings.manage, else the member's own.

• 200 A page of connections object

  data array of object, required

  data[].app_name string, required

  The AI app.

  data[].connected_at string

  When it was connected (UTC).

  data[].id string, required

  The record's id.

  data[].last_used_at string

  Its last request (UTC).

  data[].scopes array of string

  What it may do.

  data[].user_email string

  Their email.

  data[].user_id string, required

  The member who connected it.

  limit integer, required

  Rows asked for (default 100); a larger request is served 200.

  offset integer, required

  Rows skipped.

  total integer, required

  Every matching row.

  Field	Type	Required	Description
  data	array of object	yes
  data[].app_name	string	yes	The AI app.
  data[].connected_at	string	no	When it was connected (UTC).
  data[].id	string	yes	The record's id.
  data[].last_used_at	string	no	Its last request (UTC).
  data[].scopes	array of string	no	What it may do.
  data[].user_email	string	no	Their email.
  data[].user_id	string	yes	The member who connected it.
  limit	integer	yes	Rows asked for (default 100); a larger request is served 200.
  offset	integer	yes	Rows skipped.
  total	integer	yes	Every matching row.

• default An error, in the shared envelope. Error

DELETE /api/v1/connected-apps/{id}

Revoke an AI app connection

Signs the app out at once, as /connected-apps does. A member revokes their own; a member holding agency_settings.manage any of the agency's. Any other id answers 404; one already revoked 422 already_revoked.

• 200 The revoked connection object

  data object, required

  data.id string, required

  The record's id.

  data.revoked_at string, required

  When it was revoked (UTC).

  Field	Type	Required	Description
  data	object	yes
  data.id	string	yes	The record's id.
  data.revoked_at	string	yes	When it was revoked (UTC).

• 404 Not Found, as the operation's description says. Error
• 422 Code already_revoked: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/invitations

List pending invitations

Invitations not yet accepted, revoked or expired, newest first. Needs Team → View (403 forbidden otherwise).

• 200 A page of invitations object

  data array of object, required

  data[].email string, required

  Who was invited.

  data[].expires_at string

  When the link stops working (UTC).

  data[].id string, required

  The record's id.

  data[].invited_at string

  When it was sent (UTC).

  data[].invited_by_id string

  The member who invited.

  data[].role string, required

  The role they join with.

  data[].status string, required

  Where it stands.

  limit integer, required

  Rows asked for (default 100); a larger request is served 200.

  offset integer, required

  Rows skipped.

  total integer, required

  Every matching row.

  Field	Type	Required	Description
  data	array of object	yes
  data[].email	string	yes	Who was invited.
  data[].expires_at	string	no	When the link stops working (UTC).
  data[].id	string	yes	The record's id.
  data[].invited_at	string	no	When it was sent (UTC).
  data[].invited_by_id	string	no	The member who invited.
  data[].role	string	yes	The role they join with.
  data[].status	string	yes	Where it stands.
  limit	integer	yes	Rows asked for (default 100); a larger request is served 200.
  offset	integer	yes	Rows skipped.
  total	integer	yes	Every matching row.

• 403 Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

POST /api/v1/invitations

Invite someone to the agency

Emails an invitation link, valid seven days, as the Team screen's Invite does; the credential's user is named as who invited. An address already a member answers 422 already_member, one with a pending invitation 422 pending_invitation. The role is mapped onto the agency's Owner and Staff roles; one the agency deleted answers 422 role_unavailable, and the invitation's role is the one read back after the write. Needs Team → Manage (403 forbidden otherwise).

• 201 The invitation object

  data object, required

  data.email string, required

  Who was invited.

  data.expires_at string

  When the link stops working (UTC).

  data.id string, required

  The record's id.

  data.invited_at string

  When it was sent (UTC).

  data.invited_by_id string

  The member who invited.

  data.role string, required

  The role they join with.

  data.status string, required

  Where it stands.

  Field	Type	Required	Description
  data	object	yes
  data.email	string	yes	Who was invited.
  data.expires_at	string	no	When the link stops working (UTC).
  data.id	string	yes	The record's id.
  data.invited_at	string	no	When it was sent (UTC).
  data.invited_by_id	string	no	The member who invited.
  data.role	string	yes	The role they join with.
  data.status	string	yes	Where it stands.

• 403 Forbidden, as the operation's description says. Error
• 422 Codes already_member, pending_invitation, role_unavailable: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

DELETE /api/v1/invitations/{id}

Revoke a pending invitation

The link stops working, as the Team screen's Revoke does. One no longer pending answers 422 not_pending. Needs Team → Manage (403 forbidden otherwise).

• 200 The invitation object

  data object, required

  data.email string, required

  Who was invited.

  data.expires_at string

  When the link stops working (UTC).

  data.id string, required

  The record's id.

  data.invited_at string

  When it was sent (UTC).

  data.invited_by_id string

  The member who invited.

  data.role string, required

  The role they join with.

  data.status string, required

  Where it stands.

  Field	Type	Required	Description
  data	object	yes
  data.email	string	yes	Who was invited.
  data.expires_at	string	no	When the link stops working (UTC).
  data.id	string	yes	The record's id.
  data.invited_at	string	no	When it was sent (UTC).
  data.invited_by_id	string	no	The member who invited.
  data.role	string	yes	The role they join with.
  data.status	string	yes	Where it stands.

• 403 Forbidden, as the operation's description says. Error
• 422 Code not_pending: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/users

List the agency's members

Every member, by email, as the Settings Team screen lists them. Needs Team → View (403 forbidden otherwise).

• 200 A page of members object

  data array of object, required

  data[].email string, required

  Their sign-in email.

  data[].id string, required

  The member's user id.

  data[].joined_at string

  When they joined (UTC).

  data[].last_seen_at string

  When they last signed in here (UTC).

  data[].name string

  Their display name; null shows the email.

  data[].role string, required

  Their role in this agency.

  data[].status string, required

  Whether they may sign in here.

  limit integer, required

  Rows asked for (default 100); a larger request is served 200.

  offset integer, required

  Rows skipped.

  total integer, required

  Every matching row.

  Field	Type	Required	Description
  data	array of object	yes
  data[].email	string	yes	Their sign-in email.
  data[].id	string	yes	The member's user id.
  data[].joined_at	string	no	When they joined (UTC).
  data[].last_seen_at	string	no	When they last signed in here (UTC).
  data[].name	string	no	Their display name; null shows the email.
  data[].role	string	yes	Their role in this agency.
  data[].status	string	yes	Whether they may sign in here.
  limit	integer	yes	Rows asked for (default 100); a larger request is served 200.
  offset	integer	yes	Rows skipped.
  total	integer	yes	Every matching row.

• 403 Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

DELETE /api/v1/users/{id}

Deactivate a member

Deactivates the member and revokes every API key, AI connection and webhook endpoint they hold here, as the Team screen does. Your own membership answers 422 cannot_deactivate_self; the last active admin of an agency with other members 422 last_admin; another change to the agency's members in progress 409 busy. Needs Team → Manage (403 forbidden otherwise).

• 200 The member object

  data object, required

  data.email string, required

  Their sign-in email.

  data.id string, required

  The member's user id.

  data.joined_at string

  When they joined (UTC).

  data.last_seen_at string

  When they last signed in here (UTC).

  data.name string

  Their display name; null shows the email.

  data.role string, required

  Their role in this agency.

  data.status string, required

  Whether they may sign in here.

  Field	Type	Required	Description
  data	object	yes
  data.email	string	yes	Their sign-in email.
  data.id	string	yes	The member's user id.
  data.joined_at	string	no	When they joined (UTC).
  data.last_seen_at	string	no	When they last signed in here (UTC).
  data.name	string	no	Their display name; null shows the email.
  data.role	string	yes	Their role in this agency.
  data.status	string	yes	Whether they may sign in here.

• 403 Forbidden, as the operation's description says. Error
• 409 Conflict, as the operation's description says. Error
• 422 Codes cannot_deactivate_self, last_admin: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

PATCH /api/v1/users/{id}

Rename a member or change their role

Sets the name, the role or both, as the Team screen does, in one transaction. A blank name clears it. Your own role answers 422 cannot_change_own_role; demoting the last active admin of an agency with other members 422 last_admin; another change to the agency's members in progress 409 busy. The role is mapped onto the agency's Owner and Staff roles (admin to Owner, billing_staff to Staff); one the agency deleted answers 422 role_unavailable. The current role is a no-op, and the member's other roles are kept, so a demotion their custom roles would undo answers 422 role_held_by_custom_role and changes nothing; the member's role in the answer is the one read back after the write. Needs Team → Manage (403 forbidden otherwise).

• 200 The member object

  data object, required

  data.email string, required

  Their sign-in email.

  data.id string, required

  The member's user id.

  data.joined_at string

  When they joined (UTC).

  data.last_seen_at string

  When they last signed in here (UTC).

  data.name string

  Their display name; null shows the email.

  data.role string, required

  Their role in this agency.

  data.status string, required

  Whether they may sign in here.

  Field	Type	Required	Description
  data	object	yes
  data.email	string	yes	Their sign-in email.
  data.id	string	yes	The member's user id.
  data.joined_at	string	no	When they joined (UTC).
  data.last_seen_at	string	no	When they last signed in here (UTC).
  data.name	string	no	Their display name; null shows the email.
  data.role	string	yes	Their role in this agency.
  data.status	string	yes	Whether they may sign in here.

• 403 Forbidden, as the operation's description says. Error
• 409 Conflict, as the operation's description says. Error
• 422 Codes cannot_change_own_role, last_admin, role_held_by_custom_role, role_unavailable: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

POST /api/v1/users/{id}/reactivate

Reactivate a member

Lets a deactivated member sign in again, as the Team screen does. Their revoked keys and connections stay revoked. Needs Team → Manage (403 forbidden otherwise).

• 200 The member object

  data object, required

  data.email string, required

  Their sign-in email.

  data.id string, required

  The member's user id.

  data.joined_at string

  When they joined (UTC).

  data.last_seen_at string

  When they last signed in here (UTC).

  data.name string

  Their display name; null shows the email.

  data.role string, required

  Their role in this agency.

  data.status string, required

  Whether they may sign in here.

  Field	Type	Required	Description
  data	object	yes
  data.email	string	yes	Their sign-in email.
  data.id	string	yes	The member's user id.
  data.joined_at	string	no	When they joined (UTC).
  data.last_seen_at	string	no	When they last signed in here (UTC).
  data.name	string	no	Their display name; null shows the email.
  data.role	string	yes	Their role in this agency.
  data.status	string	yes	Whether they may sign in here.

• 403 Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

POST /api/v1/webhook-deliveries/{id}/resend

Send a delivery again

The same event, a fresh attempt series, as the delivery log's Resend does. One still being sent answers 409 in_flight. Needs Agency settings → Manage (403 forbidden otherwise).

• 200 The delivery object

  data object, required

  data.attempts integer

  Attempts so far.

  data.created_at string

  When the event was queued (UTC).

  data.delivered_at string

  When it was delivered (UTC).

  data.endpoint_id string, required

  The endpoint it went to.

  data.event_id string

  The event's id, the same on every attempt.

  data.event_type string, required

  The event type.

  data.id string, required

  The record's id.

  data.last_error string

  The last failure.

  data.last_status_code integer

  The last HTTP status the endpoint answered.

  data.status string, required

  Where it stands.

  Field	Type	Required	Description
  data	object	yes
  data.attempts	integer	no	Attempts so far.
  data.created_at	string	no	When the event was queued (UTC).
  data.delivered_at	string	no	When it was delivered (UTC).
  data.endpoint_id	string	yes	The endpoint it went to.
  data.event_id	string	no	The event's id, the same on every attempt.
  data.event_type	string	yes	The event type.
  data.id	string	yes	The record's id.
  data.last_error	string	no	The last failure.
  data.last_status_code	integer	no	The last HTTP status the endpoint answered.
  data.status	string	yes	Where it stands.

• 403 Forbidden, as the operation's description says. Error
• 409 Code in_flight: Conflict, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/webhook-endpoints

List the agency's webhook endpoints

Newest first; never a signing secret. Needs Agency settings → View (403 forbidden otherwise).

• 200 A page of endpoints object

  data array of object, required

  data[].active boolean, required

  Whether events are sent.

  data[].created_at string

  When it was registered (UTC).

  data[].events array of string, required

  Event types sent.

  data[].id string, required

  The record's id.

  data[].url string, required

  Where events are posted.

  limit integer, required

  Rows asked for (default 100); a larger request is served 200.

  offset integer, required

  Rows skipped.

  total integer, required

  Every matching row.

  Field	Type	Required	Description
  data	array of object	yes
  data[].active	boolean	yes	Whether events are sent.
  data[].created_at	string	no	When it was registered (UTC).
  data[].events	array of string	yes	Event types sent.
  data[].id	string	yes	The record's id.
  data[].url	string	yes	Where events are posted.
  limit	integer	yes	Rows asked for (default 100); a larger request is served 200.
  offset	integer	yes	Rows skipped.
  total	integer	yes	Every matching row.

• 403 Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

POST /api/v1/webhook-endpoints

Register a webhook endpoint

Settings → Webhooks registers one and shows its signing secret once. An API key or AI connection gets 403 web_only: someone holding Agency settings → Manage does this signed in to the web app, in Settings.

• 201 The endpoint and its secret, once object

  data object, required

  data.active boolean, required

  Whether events are sent.

  data.created_at string

  When it was registered (UTC).

  data.events array of string, required

  Event types sent.

  data.id string, required

  The record's id.

  data.url string, required

  Where events are posted.

  secret string, required

  The signing secret, shown this once.

  Field	Type	Required	Description
  data	object	yes
  data.active	boolean	yes	Whether events are sent.
  data.created_at	string	no	When it was registered (UTC).
  data.events	array of string	yes	Event types sent.
  data.id	string	yes	The record's id.
  data.url	string	yes	Where events are posted.
  secret	string	yes	The signing secret, shown this once.

• 403 Code web_only: Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

DELETE /api/v1/webhook-endpoints/{id}

Remove a webhook endpoint

Settings → Webhooks removes one and its delivery log. An API key or AI connection gets 403 web_only: someone holding Agency settings → Manage does this signed in to the web app, in Settings.

• 200 The endpoint object

  data object, required

  data.active boolean, required

  Whether events are sent.

  data.created_at string

  When it was registered (UTC).

  data.events array of string, required

  Event types sent.

  data.id string, required

  The record's id.

  data.url string, required

  Where events are posted.

  Field	Type	Required	Description
  data	object	yes
  data.active	boolean	yes	Whether events are sent.
  data.created_at	string	no	When it was registered (UTC).
  data.events	array of string	yes	Event types sent.
  data.id	string	yes	The record's id.
  data.url	string	yes	Where events are posted.

• 403 Code web_only: Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

PATCH /api/v1/webhook-endpoints/{id}

Change a webhook endpoint

Settings → Webhooks changes its events or pauses it. An API key or AI connection gets 403 web_only: someone holding Agency settings → Manage does this signed in to the web app, in Settings.

• 200 The endpoint object

  data object, required

  data.active boolean, required

  Whether events are sent.

  data.created_at string

  When it was registered (UTC).

  data.events array of string, required

  Event types sent.

  data.id string, required

  The record's id.

  data.url string, required

  Where events are posted.

  Field	Type	Required	Description
  data	object	yes
  data.active	boolean	yes	Whether events are sent.
  data.created_at	string	no	When it was registered (UTC).
  data.events	array of string	yes	Event types sent.
  data.id	string	yes	The record's id.
  data.url	string	yes	Where events are posted.

• 403 Code web_only: Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/webhook-endpoints/{id}/deliveries

List an endpoint's deliveries

Newest first, as the delivery log shows them, without payloads. An endpoint of another agency answers 404. Needs Agency settings → View (403 forbidden otherwise).

• 200 A page of deliveries object

  data array of object, required

  data[].attempts integer

  Attempts so far.

  data[].created_at string

  When the event was queued (UTC).

  data[].delivered_at string

  When it was delivered (UTC).

  data[].endpoint_id string, required

  The endpoint it went to.

  data[].event_id string

  The event's id, the same on every attempt.

  data[].event_type string, required

  The event type.

  data[].id string, required

  The record's id.

  data[].last_error string

  The last failure.

  data[].last_status_code integer

  The last HTTP status the endpoint answered.

  data[].status string, required

  Where it stands.

  limit integer, required

  Rows asked for (default 100); a larger request is served 200.

  offset integer, required

  Rows skipped.

  total integer, required

  Every matching row.

  Field	Type	Required	Description
  data	array of object	yes
  data[].attempts	integer	no	Attempts so far.
  data[].created_at	string	no	When the event was queued (UTC).
  data[].delivered_at	string	no	When it was delivered (UTC).
  data[].endpoint_id	string	yes	The endpoint it went to.
  data[].event_id	string	no	The event's id, the same on every attempt.
  data[].event_type	string	yes	The event type.
  data[].id	string	yes	The record's id.
  data[].last_error	string	no	The last failure.
  data[].last_status_code	integer	no	The last HTTP status the endpoint answered.
  data[].status	string	yes	Where it stands.
  limit	integer	yes	Rows asked for (default 100); a larger request is served 200.
  offset	integer	yes	Rows skipped.
  total	integer	yes	Every matching row.

• 403 Forbidden, as the operation's description says. Error
• 404 Not Found, as the operation's description says. Error
• default An error, in the shared envelope. Error

DELETE /api/v1/consents/{purpose}

Revoke a consent

As the tab's revoke does. Revoking external_ai_clients disconnects every AI client; revoking api_access revokes every agency API key, this one included; revoking paper_capture stops scanned forms being read with AI; revoking docusign_agency leaves a connected DocuSign account connected but stops a new one being connected. Nothing current to revoke answers the consent as it stands. Needs agency_settings.manage (403 forbidden otherwise).

• 200 The consent object

  data object, required

  data.accepted boolean, required

  Whether a current consent stands.

  data.accepted_at string

  When it was accepted.

  data.accepted_by_id string

  The member who accepted it.

  data.accepted_disclosure_version integer

  The disclosure version accepted; null when none stands.

  data.disclosure_version integer, required

  The disclosure's current version.

  data.lapsed boolean, required

  Accepted, but the disclosure changed since: accept it again.

  data.purpose string, required

  The consent.

  data.text string, required

  The disclosure a member holding agency_settings.manage accepts.

  data.title string, required

  The disclosure's title.

  Field	Type	Required	Description
  data	object	yes
  data.accepted	boolean	yes	Whether a current consent stands.
  data.accepted_at	string	no	When it was accepted.
  data.accepted_by_id	string	no	The member who accepted it.
  data.accepted_disclosure_version	integer	no	The disclosure version accepted; null when none stands.
  data.disclosure_version	integer	yes	The disclosure's current version.
  data.lapsed	boolean	yes	Accepted, but the disclosure changed since: accept it again.
  data.purpose	string	yes	The consent.
  data.text	string	yes	The disclosure a member holding agency_settings.manage accepts.
  data.title	string	yes	The disclosure's title.

• 403 Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/consents/{purpose}

Read a consent

The agency's consent and the disclosure it accepts, as the AI Access, API Keys or Paper forms tab shows them. Needs agency_settings.manage (403 forbidden otherwise).

• 200 The consent object

  data object, required

  data.accepted boolean, required

  Whether a current consent stands.

  data.accepted_at string

  When it was accepted.

  data.accepted_by_id string

  The member who accepted it.

  data.accepted_disclosure_version integer

  The disclosure version accepted; null when none stands.

  data.disclosure_version integer, required

  The disclosure's current version.

  data.lapsed boolean, required

  Accepted, but the disclosure changed since: accept it again.

  data.purpose string, required

  The consent.

  data.text string, required

  The disclosure a member holding agency_settings.manage accepts.

  data.title string, required

  The disclosure's title.

  Field	Type	Required	Description
  data	object	yes
  data.accepted	boolean	yes	Whether a current consent stands.
  data.accepted_at	string	no	When it was accepted.
  data.accepted_by_id	string	no	The member who accepted it.
  data.accepted_disclosure_version	integer	no	The disclosure version accepted; null when none stands.
  data.disclosure_version	integer	yes	The disclosure's current version.
  data.lapsed	boolean	yes	Accepted, but the disclosure changed since: accept it again.
  data.purpose	string	yes	The consent.
  data.text	string	yes	The disclosure a member holding agency_settings.manage accepts.
  data.title	string	yes	The disclosure's title.

• 403 Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

POST /api/v1/consents/{purpose}

Accept a consent

Accepts the current disclosure, as the tab's Accept does; accepting one already current changes nothing. Needs agency_settings.manage (403 forbidden otherwise).

• 200 The consent object

  data object, required

  data.accepted boolean, required

  Whether a current consent stands.

  data.accepted_at string

  When it was accepted.

  data.accepted_by_id string

  The member who accepted it.

  data.accepted_disclosure_version integer

  The disclosure version accepted; null when none stands.

  data.disclosure_version integer, required

  The disclosure's current version.

  data.lapsed boolean, required

  Accepted, but the disclosure changed since: accept it again.

  data.purpose string, required

  The consent.

  data.text string, required

  The disclosure a member holding agency_settings.manage accepts.

  data.title string, required

  The disclosure's title.

  Field	Type	Required	Description
  data	object	yes
  data.accepted	boolean	yes	Whether a current consent stands.
  data.accepted_at	string	no	When it was accepted.
  data.accepted_by_id	string	no	The member who accepted it.
  data.accepted_disclosure_version	integer	no	The disclosure version accepted; null when none stands.
  data.disclosure_version	integer	yes	The disclosure's current version.
  data.lapsed	boolean	yes	Accepted, but the disclosure changed since: accept it again.
  data.purpose	string	yes	The consent.
  data.text	string	yes	The disclosure a member holding agency_settings.manage accepts.
  data.title	string	yes	The disclosure's title.

• 403 Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/me/reminder-preferences

Read your reminder preferences

The caller's own preferences, as /settings/reminders shows them. Any member, for themselves.

• 200 The preferences object

  data object, required

  data.birthday_lead_days integer, required

  Days of notice before a birthday, 0 to 30.

  data.default_reminder_time string, required

  The time of day reminders are due, as HH:MM:SS in the agency's timezone.

  data.email_digest_enabled boolean, required

  Whether reminders are emailed as a digest.

  data.paused_until string, required

  Reminder email paused until then, an ISO 8601 time in the future; null resumes it.

  data.recert_lead_days integer, required

  Days of notice before a recert, 0 to 180.

  data.supervisor_visit_cadence_mode string, required

  How the next supervisory visit is counted.

  data.supervisor_visit_cadence_value integer, required

  Days or months between supervisory visits, 0 to 365.

  Field	Type	Required	Description
  data	object	yes
  data.birthday_lead_days	integer	yes	Days of notice before a birthday, 0 to 30.
  data.default_reminder_time	string	yes	The time of day reminders are due, as HH:MM:SS in the agency's timezone.
  data.email_digest_enabled	boolean	yes	Whether reminders are emailed as a digest.
  data.paused_until	string	yes	Reminder email paused until then, an ISO 8601 time in the future; null resumes it.
  data.recert_lead_days	integer	yes	Days of notice before a recert, 0 to 180.
  data.supervisor_visit_cadence_mode	string	yes	How the next supervisory visit is counted.
  data.supervisor_visit_cadence_value	integer	yes	Days or months between supervisory visits, 0 to 365.

• default An error, in the shared envelope. Error

PUT /api/v1/me/reminder-preferences

Save your reminder preferences

As /settings/reminders does, for the caller alone; send only what changes. Any member, for themselves.

• 200 The preferences object

  data object, required

  data.birthday_lead_days integer, required

  Days of notice before a birthday, 0 to 30.

  data.default_reminder_time string, required

  The time of day reminders are due, as HH:MM:SS in the agency's timezone.

  data.email_digest_enabled boolean, required

  Whether reminders are emailed as a digest.

  data.paused_until string, required

  Reminder email paused until then, an ISO 8601 time in the future; null resumes it.

  data.recert_lead_days integer, required

  Days of notice before a recert, 0 to 180.

  data.supervisor_visit_cadence_mode string, required

  How the next supervisory visit is counted.

  data.supervisor_visit_cadence_value integer, required

  Days or months between supervisory visits, 0 to 365.

  Field	Type	Required	Description
  data	object	yes
  data.birthday_lead_days	integer	yes	Days of notice before a birthday, 0 to 30.
  data.default_reminder_time	string	yes	The time of day reminders are due, as HH:MM:SS in the agency's timezone.
  data.email_digest_enabled	boolean	yes	Whether reminders are emailed as a digest.
  data.paused_until	string	yes	Reminder email paused until then, an ISO 8601 time in the future; null resumes it.
  data.recert_lead_days	integer	yes	Days of notice before a recert, 0 to 180.
  data.supervisor_visit_cadence_mode	string	yes	How the next supervisory visit is counted.
  data.supervisor_visit_cadence_value	integer	yes	Days or months between supervisory visits, 0 to 365.

• default An error, in the shared envelope. Error

GET /api/v1/settings/adp

Read the ADP settings

As Settings > Payroll shows them: company code, batch description, overtime, pay rates, pay period and earning codes. Needs agency_settings.manage (403 forbidden otherwise).

• 200 The settings object

  data object, required

  data.adp_batch_description string, required

  The batch description; null clears it.

  data.adp_co_code string, required

  The ADP company code; null clears it.

  data.adp_earning_code_map object, required

  Attendant hours to an ADP Hours column, as the tab's JSON; an empty object leaves the column out.

  data.biweekly_anchor_date string, required

  The first day of any one biweekly pay period, such as 2026-10-02: biweekly periods run every 14 days from it, across month ends. Read only while pay_period_frequency is biweekly; null starts each month's periods on the 1st. Exports already made keep their dates.

  data.cash_advance_in_adp_run boolean, required

  Whether the ADP Run file deducts each caregiver's cash advance as a negative Misc Amount.

  data.daily_overtime_enabled boolean, required

  Whether daily overtime is reported.

  data.default_attendant_pay_rate string, required

  The attendant hourly rate, such as 18.50: above zero, two decimals; null clears it.

  data.holiday_pay_rate string, required

  The holiday hourly rate: above zero, two decimals; null clears it.

  data.mileage_pay_rate string, required

  The rate per mile, such as 0.67: above zero, two decimals; null clears it.

  data.pay_period_frequency string, required

  The pay period.

  Field	Type	Required	Description
  data	object	yes
  data.adp_batch_description	string	yes	The batch description; null clears it.
  data.adp_co_code	string	yes	The ADP company code; null clears it.
  data.adp_earning_code_map	object	yes	Attendant hours to an ADP Hours column, as the tab's JSON; an empty object leaves the column out.
  data.biweekly_anchor_date	string	yes	The first day of any one biweekly pay period, such as 2026-10-02: biweekly periods run every 14 days from it, across month ends. Read only while pay_period_frequency is biweekly; null starts each month's periods on the 1st. Exports already made keep their dates.
  data.cash_advance_in_adp_run	boolean	yes	Whether the ADP Run file deducts each caregiver's cash advance as a negative Misc Amount.
  data.daily_overtime_enabled	boolean	yes	Whether daily overtime is reported.
  data.default_attendant_pay_rate	string	yes	The attendant hourly rate, such as 18.50: above zero, two decimals; null clears it.
  data.holiday_pay_rate	string	yes	The holiday hourly rate: above zero, two decimals; null clears it.
  data.mileage_pay_rate	string	yes	The rate per mile, such as 0.67: above zero, two decimals; null clears it.
  data.pay_period_frequency	string	yes	The pay period.

• 403 Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

PATCH /api/v1/settings/adp

Save the ADP settings

As the tab's Save does, through the same checks; send only what changes. A value the tab refuses answers 422 naming the field. Needs agency_settings.manage (403 forbidden otherwise).

• 200 The settings object

  data object, required

  data.adp_batch_description string, required

  The batch description; null clears it.

  data.adp_co_code string, required

  The ADP company code; null clears it.

  data.adp_earning_code_map object, required

  Attendant hours to an ADP Hours column, as the tab's JSON; an empty object leaves the column out.

  data.biweekly_anchor_date string, required

  The first day of any one biweekly pay period, such as 2026-10-02: biweekly periods run every 14 days from it, across month ends. Read only while pay_period_frequency is biweekly; null starts each month's periods on the 1st. Exports already made keep their dates.

  data.cash_advance_in_adp_run boolean, required

  Whether the ADP Run file deducts each caregiver's cash advance as a negative Misc Amount.

  data.daily_overtime_enabled boolean, required

  Whether daily overtime is reported.

  data.default_attendant_pay_rate string, required

  The attendant hourly rate, such as 18.50: above zero, two decimals; null clears it.

  data.holiday_pay_rate string, required

  The holiday hourly rate: above zero, two decimals; null clears it.

  data.mileage_pay_rate string, required

  The rate per mile, such as 0.67: above zero, two decimals; null clears it.

  data.pay_period_frequency string, required

  The pay period.

  Field	Type	Required	Description
  data	object	yes
  data.adp_batch_description	string	yes	The batch description; null clears it.
  data.adp_co_code	string	yes	The ADP company code; null clears it.
  data.adp_earning_code_map	object	yes	Attendant hours to an ADP Hours column, as the tab's JSON; an empty object leaves the column out.
  data.biweekly_anchor_date	string	yes	The first day of any one biweekly pay period, such as 2026-10-02: biweekly periods run every 14 days from it, across month ends. Read only while pay_period_frequency is biweekly; null starts each month's periods on the 1st. Exports already made keep their dates.
  data.cash_advance_in_adp_run	boolean	yes	Whether the ADP Run file deducts each caregiver's cash advance as a negative Misc Amount.
  data.daily_overtime_enabled	boolean	yes	Whether daily overtime is reported.
  data.default_attendant_pay_rate	string	yes	The attendant hourly rate, such as 18.50: above zero, two decimals; null clears it.
  data.holiday_pay_rate	string	yes	The holiday hourly rate: above zero, two decimals; null clears it.
  data.mileage_pay_rate	string	yes	The rate per mile, such as 0.67: above zero, two decimals; null clears it.
  data.pay_period_frequency	string	yes	The pay period.

• 403 Forbidden, as the operation's description says. Error
• 422 Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/settings/csv-mapping

Read the CSV column mapping

As Settings > CSV Mapping shows it: the agency's column for each claim field it renamed, and every field an upload reads. Needs agency_settings.manage (403 forbidden otherwise).

• 200 The mapping object

  data object, required

  data.mapping object, required

  Claim field (the read lists them) to the agency's column name, such as {"member_id": "Medicaid #"}; a field left out, or mapped to a blank column, reads its own name.

  data.optional_fields array of string, required

  The claim fields an upload may carry.

  data.required_fields array of string, required

  The claim fields an upload must carry.

  Field	Type	Required	Description
  data	object	yes
  data.mapping	object	yes	Claim field (the read lists them) to the agency's column name, such as {"member_id": "Medicaid #"}; a field left out, or mapped to a blank column, reads its own name.
  data.optional_fields	array of string	yes	The claim fields an upload may carry.
  data.required_fields	array of string	yes	The claim fields an upload must carry.

• 403 Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

PUT /api/v1/settings/csv-mapping

Replace the CSV column mapping

As the tab's Save does: the mapping sent replaces the saved one, a blank or null column reads the field's own name, and an empty mapping is the tab's Reset. A field the upload does not read answers 422 naming it. Needs agency_settings.manage (403 forbidden otherwise).

• 200 The mapping object

  data object, required

  data.mapping object, required

  Claim field (the read lists them) to the agency's column name, such as {"member_id": "Medicaid #"}; a field left out, or mapped to a blank column, reads its own name.

  data.optional_fields array of string, required

  The claim fields an upload may carry.

  data.required_fields array of string, required

  The claim fields an upload must carry.

  Field	Type	Required	Description
  data	object	yes
  data.mapping	object	yes	Claim field (the read lists them) to the agency's column name, such as {"member_id": "Medicaid #"}; a field left out, or mapped to a blank column, reads its own name.
  data.optional_fields	array of string	yes	The claim fields an upload may carry.
  data.required_fields	array of string	yes	The claim fields an upload must carry.

• 403 Forbidden, as the operation's description says. Error
• 422 Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/settings/evv-collection

Read the EVV rollout

As Settings > EVV Rules shows it under EVV in HCB: who HCB collects EVV for, from which day, and how many caregivers are enrolled in the pilot. Needs agency_settings.manage (403 forbidden otherwise).

• 200 The rollout object

  data object, required

  data.enrolled_caregivers integer, required

  How many caregivers are enrolled in the EVV pilot.

  data.evv_collected_from string, required

  The agency's calendar day HCB starts collecting EVV; null for no start day.

  data.evv_rollout string, required

  Who HCB collects EVV for: off (alerts start with the agency's first clock-in), pilot (enrolled caregivers only) or all.

  Field	Type	Required	Description
  data	object	yes
  data.enrolled_caregivers	integer	yes	How many caregivers are enrolled in the EVV pilot.
  data.evv_collected_from	string	yes	The agency's calendar day HCB starts collecting EVV; null for no start day.
  data.evv_rollout	string	yes	Who HCB collects EVV for: off (alerts start with the agency's first clock-in), pilot (enrolled caregivers only) or all.

• 403 Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

PATCH /api/v1/settings/evv-collection

Save the EVV rollout

As the EVV in HCB card's Save does; send only what changes. A rollout other than off, pilot or all, or a date that does not parse, answers 422. Needs agency_settings.manage (403 forbidden otherwise).

• 200 The rollout object

  data object, required

  data.enrolled_caregivers integer, required

  How many caregivers are enrolled in the EVV pilot.

  data.evv_collected_from string, required

  The agency's calendar day HCB starts collecting EVV; null for no start day.

  data.evv_rollout string, required

  Who HCB collects EVV for: off (alerts start with the agency's first clock-in), pilot (enrolled caregivers only) or all.

  Field	Type	Required	Description
  data	object	yes
  data.enrolled_caregivers	integer	yes	How many caregivers are enrolled in the EVV pilot.
  data.evv_collected_from	string	yes	The agency's calendar day HCB starts collecting EVV; null for no start day.
  data.evv_rollout	string	yes	Who HCB collects EVV for: off (alerts start with the agency's first clock-in), pilot (enrolled caregivers only) or all.

• 403 Forbidden, as the operation's description says. Error
• 422 Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/settings/notifications

Read the notification settings

As Settings > Notifications shows them: which EDI events (a submission, a TA1, a 999, a claim acknowledgment, an 835) email the agency. Needs agency_settings.manage (403 forbidden otherwise).

• 200 The settings object

  data object, required

  data.notify_on_277ca boolean, required

  Whether the agency is emailed for this event.

  data.notify_on_835 boolean, required

  Whether the agency is emailed for this event.

  data.notify_on_999 boolean, required

  Whether the agency is emailed for this event.

  data.notify_on_submission boolean, required

  Whether the agency is emailed for this event.

  data.notify_on_ta1 boolean, required

  Whether the agency is emailed for this event.

  data.remittance_review_email boolean, required

  Whether the agency is emailed for this event.

  data.text_caregivers_before_expiry boolean, required

  Whether each caregiver is texted a month, and again a week, before a dated credential of theirs expires.

  Field	Type	Required	Description
  data	object	yes
  data.notify_on_277ca	boolean	yes	Whether the agency is emailed for this event.
  data.notify_on_835	boolean	yes	Whether the agency is emailed for this event.
  data.notify_on_999	boolean	yes	Whether the agency is emailed for this event.
  data.notify_on_submission	boolean	yes	Whether the agency is emailed for this event.
  data.notify_on_ta1	boolean	yes	Whether the agency is emailed for this event.
  data.remittance_review_email	boolean	yes	Whether the agency is emailed for this event.
  data.text_caregivers_before_expiry	boolean	yes	Whether each caregiver is texted a month, and again a week, before a dated credential of theirs expires.

• 403 Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

PATCH /api/v1/settings/notifications

Save the notification settings

As the tab's checkboxes do; send only what changes. Needs agency_settings.manage (403 forbidden otherwise).

• 200 The settings object

  data object, required

  data.notify_on_277ca boolean, required

  Whether the agency is emailed for this event.

  data.notify_on_835 boolean, required

  Whether the agency is emailed for this event.

  data.notify_on_999 boolean, required

  Whether the agency is emailed for this event.

  data.notify_on_submission boolean, required

  Whether the agency is emailed for this event.

  data.notify_on_ta1 boolean, required

  Whether the agency is emailed for this event.

  data.remittance_review_email boolean, required

  Whether the agency is emailed for this event.

  data.text_caregivers_before_expiry boolean, required

  Whether each caregiver is texted a month, and again a week, before a dated credential of theirs expires.

  Field	Type	Required	Description
  data	object	yes
  data.notify_on_277ca	boolean	yes	Whether the agency is emailed for this event.
  data.notify_on_835	boolean	yes	Whether the agency is emailed for this event.
  data.notify_on_999	boolean	yes	Whether the agency is emailed for this event.
  data.notify_on_submission	boolean	yes	Whether the agency is emailed for this event.
  data.notify_on_ta1	boolean	yes	Whether the agency is emailed for this event.
  data.remittance_review_email	boolean	yes	Whether the agency is emailed for this event.
  data.text_caregivers_before_expiry	boolean	yes	Whether each caregiver is texted a month, and again a week, before a dated credential of theirs expires.

• 403 Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/settings/security

Read the security settings

As Settings > Security shows them: whether two-factor is required, and the session timeout. Needs agency_settings.manage (403 forbidden otherwise).

• 200 The settings object

  data object, required

  data.require_two_factor boolean, required

  Whether every member must sign in with two-factor.

  data.session_timeout_minutes integer, required

  Minutes idle before sign-out.

  Field	Type	Required	Description
  data	object	yes
  data.require_two_factor	boolean	yes	Whether every member must sign in with two-factor.
  data.session_timeout_minutes	integer	yes	Minutes idle before sign-out.

• 403 Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

PUT /api/v1/settings/security

Save the security settings

As the Security tab does; send only what changes. Requiring two-factor needs the caller's own two-factor on first (422 enable_yours_first); turning the requirement off needs code, a current code from the caller's authenticator app (422 invalid_code). Both change in one transaction: if either is refused, neither is saved. Needs agency_settings.manage (403 forbidden otherwise).

• 200 The settings object

  data object, required

  data.require_two_factor boolean, required

  Whether every member must sign in with two-factor.

  data.session_timeout_minutes integer, required

  Minutes idle before sign-out.

  Field	Type	Required	Description
  data	object	yes
  data.require_two_factor	boolean	yes	Whether every member must sign in with two-factor.
  data.session_timeout_minutes	integer	yes	Minutes idle before sign-out.

• 403 Forbidden, as the operation's description says. Error
• 422 Codes enable_yours_first, invalid_code: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/settings/tpid-authorized

Read the Trading Partner authorization

Whether the agency has confirmed it authorized HomeCareBilling as its Trading Partner, as the Agency tab shows it. Needs agency_settings.manage (403 forbidden otherwise).

• 200 The authorization object

  data object, required

  data.tpid_authorized boolean, required

  Whether the agency confirmed its Trading Partner authorization.

  Field	Type	Required	Description
  data	object	yes
  data.tpid_authorized	boolean	yes	Whether the agency confirmed its Trading Partner authorization.

• 403 Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

PUT /api/v1/settings/tpid-authorized

Set the Trading Partner authorization

As the Agency tab's toggle does. Needs agency_settings.manage (403 forbidden otherwise).

• 200 The authorization object

  data object, required

  data.tpid_authorized boolean, required

  Whether the agency confirmed its Trading Partner authorization.

  Field	Type	Required	Description
  data	object	yes
  data.tpid_authorized	boolean	yes	Whether the agency confirmed its Trading Partner authorization.

• 403 Forbidden, as the operation's description says. Error
• default An error, in the shared envelope. Error

POST /api/v1/users/{id}/two-factor/reset

Reset a member's two-factor

As the Users list's reset does: turns off the member's two-factor so they set it up again, and emails them. Only a member of this agency and no other, never yourself (422 not_allowed); an id that is no member of this agency answers 404. Needs agency_settings.manage (403 forbidden otherwise).

• 200 Reset object

  data object, required

  data.two_factor_enabled boolean, required

  Always false once reset.

  data.user_id string, required

  The record's id.

  Field	Type	Required	Description
  data	object	yes
  data.two_factor_enabled	boolean	yes	Always false once reset.
  data.user_id	string	yes	The record's id.

• 403 Forbidden, as the operation's description says. Error
• 404 Not Found, as the operation's description says. Error
• 422 Code not_allowed: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/agenda/today

Get today's agenda

What the agency needs to deal with today: reminders due now, reminders already overdue, client and caregiver birthdays, and the billing work waiting. The day is Mountain time's. Each reminder list holds at most 100, says how many there are in all, and is read on with its own offset.

• 200 The agenda object

  data Agenda, required

  Field	Type	Required	Description
  data	Agenda	yes

• default An error, in the shared envelope. Error

GET /api/v1/attention

List what needs attention

Everything about a client or caregiver that needs doing, as the Today page and needs_attention list it: reminders due today and overdue, compliance documents, OIG matches, supervisory visits, outstanding recertifications, PARs ending within 30 days and open monthly follow-ups. Overdue first (oldest first, undated last among them), then soonest due. The day is Mountain time's. An unknown kind is 422.

• 200 A page of rows object

  data array of AttentionRow, required

  limit integer, required

  Rows asked for (default 100); a larger request is served 200.

  offset integer, required

  Rows skipped.

  total integer, required

  Every matching row.

  Field	Type	Required	Description
  data	array of AttentionRow	yes
  limit	integer	yes	Rows asked for (default 100); a larger request is served 200.
  offset	integer	yes	Rows skipped.
  total	integer	yes	Every matching row.

• 422 Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

POST /api/v1/reminders/{id}/complete

Mark a reminder done

As the Today page's Done button: closes the reminder, and never completes or signs the visit or form behind it. Completing a recurring reminder schedules its next one. Already done is 200 with changed false; already dismissed is 422 already_closed. Another agency's reminder is 404.

• 200 The reminder object

  data ReminderClosed, required

  Field	Type	Required	Description
  data	ReminderClosed	yes

• 404 Not Found, as the operation's description says. Error
• 422 Code already_closed: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

POST /api/v1/reminders/{id}/dismiss

Dismiss a reminder

As the Today page's Dismiss button: removes the reminder without doing it. Dismissing a recurring reminder ends its series. Already dismissed is 200 with changed false; already done is 422 already_closed. Another agency's reminder is 404.

• 200 The reminder object

  data ReminderClosed, required

  Field	Type	Required	Description
  data	ReminderClosed	yes

• 404 Not Found, as the operation's description says. Error
• 422 Code already_closed: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/assignments

List assignments

Which caregiver serves which client, under which billing code. The agency's assignments in effective-date order, newest first. With updated_since the order is change order, for a sync that pages with after_id.

• 200 A page of assignments object

  data array of Assignment, required

  limit integer, required

  Rows asked for (default 100); a larger request is served 200.

  offset integer, required

  Rows skipped.

  total integer, required

  Every matching row.

  Field	Type	Required	Description
  data	array of Assignment	yes
  limit	integer	yes	Rows asked for (default 100); a larger request is served 200.
  offset	integer	yes	Rows skipped.
  total	integer	yes	Every matching row.

• 400 Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message. Error
• default An error, in the shared envelope. Error

POST /api/v1/assignments

Create a assignment

• 201 The created assignment object

  data Assignment, required

  Field	Type	Required	Description
  data	Assignment	yes

• 422 Code validation_failed: a field was refused; details names each field and why. Nothing was saved. Error
• default An error, in the shared envelope. Error

POST /api/v1/assignments/schedule-import

Import InMyTeam's weekly schedule PDF

Reads InMyTeam's weekly schedule as Import Assignments does: each caregiver-client pair and service becomes an item, matched by name among this agency's clients and caregivers only. new: a pair with no active or open temporary assignment, added with the file's days; changed: an assignment whose days differ, its days replaced; unchanged; not_imported: a name or service that did not resolve, with the reason; not_on_schedule: an active assignment, or a temporary one with no end date, that the file does not name, left as it is. Needs imports.manage and scheduling.manage. With dry_run true the answer is the items and nothing is written. Sending the same file again writes nothing twice (imported 0, updated 0); when two sends run at once, a pair the other created first is skipped as already_on_file. Refusals: 403 forbidden naming the missing permission; 422 not_a_schedule, unreadable_pdf (also when reading the PDF takes over 15 s), file_required (no file, or one that is not a PDF), file_too_large, invalid_dry_run; none writes anything.

• 200 What the import did, or with dry_run true would do object

  data ScheduleImportResult, required

  Field	Type	Required	Description
  data	ScheduleImportResult	yes

• 403 Forbidden, as the operation's description says. Error
• 422 Code not_a_schedule: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/assignments/{id}

Get a assignment

Which caregiver serves which client, under which billing code.

• 200 The assignment object

  data Assignment, required

  Field	Type	Required	Description
  data	Assignment	yes

• 404 Code not_found: no assignment with that id in this agency, including another agency's. Error
• default An error, in the shared envelope. Error

PATCH /api/v1/assignments/{id}

Update a assignment

Sets only the fields sent. lock_version is required: send the value you read, and a record changed since answers 409 stale_record.

• 200 The updated assignment object

  data Assignment, required

  Field	Type	Required	Description
  data	Assignment	yes

• 404 Code not_found: no assignment with that id in this agency, including another agency's. Error
• 409 Code stale_record: the assignment changed since the lock_version sent was read, or while this request ran. Nothing was saved; read it again and retry. Error
• 422 Code validation_failed: a field was refused; details names each field and why. Nothing was saved. Error
• default An error, in the shared envelope. Error

GET /api/v1/assignments/{id}/schedule

Read an assignment's weekly schedule

Its shifts and the days each one works, in the shape a save sends: the days the office entered and the days its standing Work Orders place, each of the latter naming its WO # in work_order_number.

• 200 The schedule object

  data AssignmentSchedule, required

  Field	Type	Required	Description
  data	AssignmentSchedule	yes

• default An error, in the shared envelope. Error

PUT /api/v1/assignments/{id}/schedule

Save one shift of an assignment's weekly schedule

Replaces the days of the shift named by shift_number in the body or the shift query parameter (1 to 4, default 1) with the days sent, as the page's schedule editor does; an empty list clears the shift. A day may carry ends_next_day (default false) for a shift that ends after midnight. A refused day (an end before its start without ends_next_day, a day overlapping another shift, across midnight too) answers 422 invalid_schedule naming it, and nothing is written. A day identical to one a Work Order places (same day, shift, start and end) is that Work Order's and writes nothing, so sending the read shape back changes nothing. lock_version is the assignment's as read: a change since answers 409 stale_record, and a save moves it. Answers the whole schedule.

• 200 The schedule object

  data AssignmentSchedule, required

  Field	Type	Required	Description
  data	AssignmentSchedule	yes

• 409 Code stale_record: Conflict, as the operation's description says. Error
• 422 Code invalid_schedule: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

POST /api/v1/assignments/{id}/transition

Change an assignment's status

Moves the assignment to status, with an optional reason, as the page's status dialog does. A transition its status does not allow answers 422 invalid_transition; closing one with open timesheets 422 has_active_timesheets; lock_version is the one the assignment was read with: one changed since answers 409 stale_record.

• 200 The assignment object

  data Assignment, required

  Field	Type	Required	Description
  data	Assignment	yes

• 409 Code stale_record: Conflict, as the operation's description says. Error
• 422 Codes has_active_timesheets, invalid_transition: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/batches

List batches

A batch is one uploaded claims file and the claims made from it. The agency's batches in upload order, newest first. With updated_since the order is change order, for a sync that pages with after_id.

• 200 A page of batches object

  data array of Batch, required

  limit integer, required

  Rows asked for (default 100); a larger request is served 200.

  offset integer, required

  Rows skipped.

  total integer, required

  Every matching row.

  Field	Type	Required	Description
  data	array of Batch	yes
  limit	integer	yes	Rows asked for (default 100); a larger request is served 200.
  offset	integer	yes	Rows skipped.
  total	integer	yes	Every matching row.

• 400 Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message. Error
• default An error, in the shared envelope. Error

POST /api/v1/batches

Upload a claims file

Creates a batch from a CSV or XLSX file of up to 10 MB, mapped with the agency's saved column mapping (Settings, CSV mapping). The batch validates in the background and is never submitted automatically. Refused, creating nothing: 422 unmapped_columns, patient_limit_exceeded, unsupported_file_type or invalid_file, and 403 submission_blocked when the agency may not submit claims.

• 201 The created batch, and any warning object

  data Batch, required

  warnings array of object, required

  Field	Type	Required	Description
  data	Batch	yes
  warnings	array of object	yes

• 403 Code submission_blocked: Forbidden, as the operation's description says. Error
• 422 Code unmapped_columns: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

POST /api/v1/batches/validate

Validate a claims file without storing it

Each row's validation errors and warnings, as a batch made from the file would get them. A warning (a part-unit on a 15-minute code, a Location/Rendering Provider ID that is not digits only, a patient_account_number another row repeats or a claim in progress or paid already uses, which the upload replaces with a generated one and keeps as replaced_account_number) never stops the row from being submitted. Nothing is stored, so it needs no Idempotency-Key and is allowed with a read-only key, on a read-only account, and while claim submission is blocked. It counts against the write rate limit, as parsing a file is the heaviest request.

• 200 Every row, its errors and its warnings object

  data array of object, required

  data[].errors array of object, required

  data[].errors[].code string

  Stable, e.g. required or invalid_format.

  data[].errors[].field string

  The claim field.

  data[].errors[].message string

  For a person to read.

  data[].row_number integer, required

  data[].warnings array of object, required

  Problems that do not stop the row from being submitted: a part-unit on a 15-minute code, or a Location/Rendering Provider ID that is not digits only.

  data[].warnings[].code string

  Stable, e.g. required or invalid_format.

  data[].warnings[].field string

  The claim field.

  data[].warnings[].message string

  For a person to read.

  Field	Type	Required	Description
  data	array of object	yes
  data[].errors	array of object	yes
  data[].errors[].code	string	no	Stable, e.g. required or invalid_format.
  data[].errors[].field	string	no	The claim field.
  data[].errors[].message	string	no	For a person to read.
  data[].row_number	integer	yes
  data[].warnings	array of object	yes	Problems that do not stop the row from being submitted: a part-unit on a 15-minute code, or a Location/Rendering Provider ID that is not digits only.
  data[].warnings[].code	string	no	Stable, e.g. required or invalid_format.
  data[].warnings[].field	string	no	The claim field.
  data[].warnings[].message	string	no	For a person to read.

• default An error, in the shared envelope. Error

GET /api/v1/batches/{id}

Get a batch

A batch is one uploaded claims file and the claims made from it.

• 200 The batch object

  data Batch, required

  Field	Type	Required	Description
  data	Batch	yes

• 404 Code not_found: no batch with that id in this agency, including another agency's. Error
• default An error, in the shared envelope. Error

GET /api/v1/batches/{id}/837

Download a batch's 837 file

The generated 837 file exactly as Batch Detail's Download 837 serves it, under its HCPF file name. 404 not_found for a batch this agency does not have, and for one with no 837 yet (it is made when the batch is generated). The read is recorded on the PHI access log.

• 200 The 837 file string
• 404 Code not_found: Not Found, as the operation's description says. Error
• default An error, in the shared envelope. Error

POST /api/v1/batches/{id}/submit

Submit a batch to HCPF

A generated batch is sent to HCPF; a validated batch made from an uploaded file is generated first and sent as soon as its 837P exists. Either way the answer is 202 at once: poll GET /api/v1/batches/{id} for the outcome. A generated batch is held, sending nothing, while a claim includes days already billed in another batch or the duplicate check did not complete: 422 submission_held says which; review the batch in the app to send it anyway. A validated batch is compared once it is generated, so a hold found then leaves it at generated, and the next submit answers 422 submission_held. Refused, sending nothing: 422 batch_not_submittable when the batch cannot be submitted now (any other status, or already on its way, which is never sent twice), 422 submission_blocked when the agency's setup blocks submission, 403 submission_blocked when its billing does, 403 read_only or insufficient_scope for a key that may not write, and 404 for a batch this agency does not have. The Idempotency-Key binds the FIRST answer: repeat the key to recover a lost 202, and send a NEW key to try again after a refusal is fixed or after a 500.

• 202 The batch, as it stands once the submission is queued object

  data Batch, required

  Field	Type	Required	Description
  data	Batch	yes

• 403 Codes read_only, submission_blocked: Forbidden, as the operation's description says. Error
• 404 Not Found, as the operation's description says. Error
• 422 Codes batch_not_submittable, submission_blocked, submission_held: Unprocessable Content, as the operation's description says. Error
• 500 Internal Server Error, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/billing-codes

List billing codes

The billing codes this product bills, in code order, each with the modifiers the fee schedules use. A work order also takes another code whose units can be computed (a catalog.unknown_code warning names one no fee schedule prices), and other modifiers in valid 837P format, within the limits the BillingCode schema states. The same for every agency.

• 200 A page of billing codes object

  data array of BillingCode, required

  limit integer, required

  Rows asked for (default 100); a larger request is served 200.

  offset integer, required

  Rows skipped.

  total integer, required

  Every matching row.

  Field	Type	Required	Description
  data	array of BillingCode	yes
  limit	integer	yes	Rows asked for (default 100); a larger request is served 200.
  offset	integer	yes	Rows skipped.
  total	integer	yes	Every matching row.

• default An error, in the shared envelope. Error

GET /api/v1/broadcasts

List broadcasts

The agency's broadcasts, newest first, as the broadcast page's Recent Broadcasts lists them, each with how many caregivers texted back and how many said yes.

• 200 A page of broadcasts object

  data array of object, required

  data[].delivery_method string, required

  How it went out.

  data[].id string, required

  The record's id.

  data[].message string

  What it said.

  data[].recipient_count integer, required

  Caregivers sent to.

  data[].reply_count integer

  Caregivers who texted back to it.

  data[].sent_at string

  When it was sent (UTC).

  data[].skipped_count integer

  Caregivers skipped: no contact for the method, or opted out of SMS.

  data[].yes_count integer

  Of those, how many replies read as a yes.

  limit integer, required

  Rows asked for (default 100); a larger request is served 200.

  offset integer, required

  Rows skipped.

  total integer, required

  Every matching row.

  Field	Type	Required	Description
  data	array of object	yes
  data[].delivery_method	string	yes	How it went out.
  data[].id	string	yes	The record's id.
  data[].message	string	no	What it said.
  data[].recipient_count	integer	yes	Caregivers sent to.
  data[].reply_count	integer	no	Caregivers who texted back to it.
  data[].sent_at	string	no	When it was sent (UTC).
  data[].skipped_count	integer	no	Caregivers skipped: no contact for the method, or opted out of SMS.
  data[].yes_count	integer	no	Of those, how many replies read as a yes.
  limit	integer	yes	Rows asked for (default 100); a larger request is served 200.
  offset	integer	yes	Rows skipped.
  total	integer	yes	Every matching row.

• default An error, in the shared envelope. Error

POST /api/v1/broadcasts

Send a broadcast to caregivers

Sends a message to the agency's active caregivers, as the broadcast page does: by email (default), SMS or both, to everyone (default), one compliance group (expired, expiring_soon, training, evaluation), or pick: the caregivers named in caregiver_ids (former ones included) and those carrying tag (active only unless include_former). A caregiver without the contact method, or opted out of SMS, is skipped and counted; an opted-out number is never texted. An id that is not one of the agency's caregivers answers 422 validation_failed; an empty group 422 no_recipients; a texted (sms or both) message that, with the agency name before it and the STOP line after it, would pass 1,600 characters 422 validation_failed, naming the agency's limit; the same message by the same method within a minute 409 duplicate; past the daily limit 429 rate_limited.

• 201 The broadcast sent object

  data object, required

  data.delivery_method string, required

  How it went out.

  data.id string, required

  The record's id.

  data.recipient_count integer, required

  Caregivers sent to.

  data.recipient_scope string

  Who it went to.

  data.reply_count integer

  Caregivers who texted back to it (#2567).

  data.sent_at string

  When it was sent (UTC).

  data.skipped_count integer

  Caregivers skipped: no contact for the method, or opted out of SMS.

  data.yes_count integer

  Of those, how many replies read as a yes.

  Field	Type	Required	Description
  data	object	yes
  data.delivery_method	string	yes	How it went out.
  data.id	string	yes	The record's id.
  data.recipient_count	integer	yes	Caregivers sent to.
  data.recipient_scope	string	no	Who it went to.
  data.reply_count	integer	no	Caregivers who texted back to it (#2567).
  data.sent_at	string	no	When it was sent (UTC).
  data.skipped_count	integer	no	Caregivers skipped: no contact for the method, or opted out of SMS.
  data.yes_count	integer	no	Of those, how many replies read as a yes.

• 409 Conflict, as the operation's description says. Error
• 422 Codes no_recipients, validation_failed: Unprocessable Content, as the operation's description says. Error
• 429 Code rate_limited: Too Many Requests, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/broadcasts/{id}/replies

List a broadcast's replies

The caregivers who texted back to one of the agency's broadcasts, latest reply first, as the broadcast page's Replies list shows them; yes marks a reply that reads as a yes. Another agency's broadcast answers 404.

• 200 A page of replies object

  data array of object, required

  data[].caregiver_id string, required

  The caregiver who replied.

  data[].caregiver_name string

  The caregiver, last name first.

  data[].replied_at string

  When it arrived (UTC).

  data[].reply string, required

  Their latest text back.

  data[].yes boolean, required

  Whether the reply reads as a yes.

  limit integer, required

  Rows asked for (default 100); a larger request is served 200.

  offset integer, required

  Rows skipped.

  total integer, required

  Every matching row.

  Field	Type	Required	Description
  data	array of object	yes
  data[].caregiver_id	string	yes	The caregiver who replied.
  data[].caregiver_name	string	no	The caregiver, last name first.
  data[].replied_at	string	no	When it arrived (UTC).
  data[].reply	string	yes	Their latest text back.
  data[].yes	boolean	yes	Whether the reply reads as a yes.
  limit	integer	yes	Rows asked for (default 100); a larger request is served 200.
  offset	integer	yes	Rows skipped.
  total	integer	yes	Every matching row.

• 404 Not Found, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/notifications

List your notifications

The credential's member's notifications, newest first, as the notification bell lists them. read=unread lists only unread ones, read=read only read ones.

• 200 A page of notifications object

  data array of object, required

  data[].body string

  Its text.

  data[].created_at string

  When it was raised (UTC).

  data[].id string, required

  The record's id.

  data[].priority string

  How urgent it is.

  data[].read_at string

  When it was read (UTC).

  data[].resolved_at string

  When it was resolved (UTC).

  data[].source_id string

  The record it is about.

  data[].source_type string

  The kind of record it is about.

  data[].title string, required

  Its headline.

  data[].type string, required

  The kind of notification.

  limit integer, required

  Rows asked for (default 100); a larger request is served 200.

  offset integer, required

  Rows skipped.

  total integer, required

  Every matching row.

  Field	Type	Required	Description
  data	array of object	yes
  data[].body	string	no	Its text.
  data[].created_at	string	no	When it was raised (UTC).
  data[].id	string	yes	The record's id.
  data[].priority	string	no	How urgent it is.
  data[].read_at	string	no	When it was read (UTC).
  data[].resolved_at	string	no	When it was resolved (UTC).
  data[].source_id	string	no	The record it is about.
  data[].source_type	string	no	The kind of record it is about.
  data[].title	string	yes	Its headline.
  data[].type	string	yes	The kind of notification.
  limit	integer	yes	Rows asked for (default 100); a larger request is served 200.
  offset	integer	yes	Rows skipped.
  total	integer	yes	Every matching row.

• default An error, in the shared envelope. Error

POST /api/v1/notifications/read-all

Mark all your notifications read

As the bell's Mark all read does. Answers how many were marked.

• 200 How many were marked object

  data object, required

  data.marked integer, required

  Notifications marked read.

  Field	Type	Required	Description
  data	object	yes
  data.marked	integer	yes	Notifications marked read.

• default An error, in the shared envelope. Error

POST /api/v1/notifications/{id}/read

Mark a notification read

As opening it from the bell does. Another member's notification, or another agency's, answers 404.

• 200 The notification object

  data object, required

  data.body string

  Its text.

  data.created_at string

  When it was raised (UTC).

  data.id string, required

  The record's id.

  data.priority string

  How urgent it is.

  data.read_at string

  When it was read (UTC).

  data.resolved_at string

  When it was resolved (UTC).

  data.source_id string

  The record it is about.

  data.source_type string

  The kind of record it is about.

  data.title string, required

  Its headline.

  data.type string, required

  The kind of notification.

  Field	Type	Required	Description
  data	object	yes
  data.body	string	no	Its text.
  data.created_at	string	no	When it was raised (UTC).
  data.id	string	yes	The record's id.
  data.priority	string	no	How urgent it is.
  data.read_at	string	no	When it was read (UTC).
  data.resolved_at	string	no	When it was resolved (UTC).
  data.source_id	string	no	The record it is about.
  data.source_type	string	no	The kind of record it is about.
  data.title	string	yes	Its headline.
  data.type	string	yes	The kind of notification.

• 404 Not Found, as the operation's description says. Error
• default An error, in the shared envelope. Error

POST /api/v1/notifications/{id}/resolve

Resolve a notification

Marks it resolved, and read, as the notifications page's Resolve does, with optional notes for the record. One already resolved is answered as it stands. Another agency's answers 404.

• 200 The notification object

  data object, required

  data.body string

  Its text.

  data.created_at string

  When it was raised (UTC).

  data.id string, required

  The record's id.

  data.priority string

  How urgent it is.

  data.read_at string

  When it was read (UTC).

  data.resolved_at string

  When it was resolved (UTC).

  data.source_id string

  The record it is about.

  data.source_type string

  The kind of record it is about.

  data.title string, required

  Its headline.

  data.type string, required

  The kind of notification.

  Field	Type	Required	Description
  data	object	yes
  data.body	string	no	Its text.
  data.created_at	string	no	When it was raised (UTC).
  data.id	string	yes	The record's id.
  data.priority	string	no	How urgent it is.
  data.read_at	string	no	When it was read (UTC).
  data.resolved_at	string	no	When it was resolved (UTC).
  data.source_id	string	no	The record it is about.
  data.source_type	string	no	The kind of record it is about.
  data.title	string	yes	Its headline.
  data.type	string	yes	The kind of notification.

• 404 Not Found, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/care-logs

List care logs

As the /care-logs list: newest service date first, each with its task counts (done, refused, not_needed, unmarked). Filters: client_id, caregiver_id, from and to (service dates, inclusive), source, state and needs_signature. The read is recorded on the PHI access log.

• 200 A page of care logs object

  data array of CareLog, required

  limit integer, required

  Rows asked for (default 100); a larger request is served 200.

  offset integer, required

  Rows skipped.

  total integer, required

  Every matching row.

  Field	Type	Required	Description
  data	array of CareLog	yes
  limit	integer	yes	Rows asked for (default 100); a larger request is served 200.
  offset	integer	yes	Rows skipped.
  total	integer	yes	Every matching row.

• default An error, in the shared envelope. Error

POST /api/v1/care-logs

Start a care log

As New care log: starts the care log of the client, caregiver, day, service and shift with source office, seeded with the tasks the Work Orders in force plan for the day. A key that already holds a live care log answers 200 with that one, never a second; a new one answers 201. A client or caregiver that is not the agency's is 404 not_found, a Visit that is not the day's 422 visit_mismatch.

• 200 The care log already holding the day object

  data CareLogDetail, required

  Field	Type	Required	Description
  data	CareLogDetail	yes

• 201 The care log started object

  data CareLogDetail, required

  Field	Type	Required	Description
  data	CareLogDetail	yes

• 404 Code not_found: Not Found, as the operation's description says. Error
• 422 Code visit_mismatch: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/care-logs/{id}

Read a care log

As the /care-logs/:id screen: the day with its tasks, times, warnings and live signatures. The read is recorded on the PHI access log.

• 200 The care log object

  data CareLogDetail, required

  Field	Type	Required	Description
  data	CareLogDetail	yes

• default An error, in the shared envelope. Error

PATCH /api/v1/care-logs/{id}

Edit a care log's notes and times

As the screen's notes and times: sets the fields sent. lock_version must be the value read; a care log changed since answers 409 stale_record. time_out before time_in is 422 validation_failed. A care log that is not a draft answers 409 record_locked and nothing changes; another agency's id answers 404, whatever the body holds.

• 200 The care log object

  data CareLogDetail, required

  Field	Type	Required	Description
  data	CareLogDetail	yes

• 404 Not Found, as the operation's description says. Error
• 409 Codes record_locked, stale_record: Conflict, as the operation's description says. Error
• 422 Code validation_failed: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

POST /api/v1/care-logs/{id}/finish

Finish a care log

As the screen's Finish: marks the care log finished, once; finishing a finished care log changes nothing. Warnings never refuse it. A care log that is not a draft answers 409 record_locked and nothing changes; another agency's id answers 404, whatever the body holds.

• 200 The care log object

  data CareLogDetail, required

  Field	Type	Required	Description
  data	CareLogDetail	yes

• 404 Not Found, as the operation's description says. Error
• 409 Code record_locked: Conflict, as the operation's description says. Error
• default An error, in the shared envelope. Error

POST /api/v1/care-logs/{id}/paper-on-file

Mark a care log's paper signature on file

As the screen's Client signed on paper: the client's paper signature is recorded as on file (method paper_on_file, channel office), which signs and locks the day. Send a multipart scan in the field file (stored as a document of the client's, up to 50 MB), or JSON with the document_id of one already on the client's file, or neither. The same mark again answers the same signature. A document that is not the client's, or is not one a person uploaded (a paper-capture scan, a true copy), is 422 document_not_found; a scan or document that is not a PDF, JPEG or PNG, or is over the size, 422 invalid_scan; a document whose virus scan has not finished 409 scan_pending, or found it infected or failed, 422 scan_not_clean; a client line already signed 409 role_already_signed. A care log that is not a draft answers 409 record_locked and nothing changes; another agency's id answers 404, whatever the body holds. An agency API key answers 403 signature_requires_person: a key is not a person and signs nothing; a member signs in the web app or through an AI app they connected.

• 201 The care log, signed object

  data CareLogDetail, required

  Field	Type	Required	Description
  data	CareLogDetail	yes

• 403 Code signature_requires_person: Forbidden, as the operation's description says. Error
• 404 Not Found, as the operation's description says. Error
• 409 Codes record_locked, role_already_signed, scan_pending: Conflict, as the operation's description says. Error
• 422 Codes document_not_found, invalid_scan, scan_not_clean: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

POST /api/v1/care-logs/{id}/tasks

Add a task to a care log

As the screen's Add task: adds an unplanned task, done unless status says otherwise; a task the care log already holds is set instead, so a retried add writes nothing new. A task that is not the agency's or a system one is 422 task_definition_not_found. A care log that is not a draft answers 409 record_locked and nothing changes; another agency's id answers 404, whatever the body holds.

• 200 The care log object

  data CareLogDetail, required

  Field	Type	Required	Description
  data	CareLogDetail	yes

• 404 Not Found, as the operation's description says. Error
• 409 Code record_locked: Conflict, as the operation's description says. Error
• 422 Code task_definition_not_found: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

POST /api/v1/care-logs/{id}/tasks/{task_id}/mark

Mark a care log's task

As the screen's Done, Refused and Not needed buttons: SETS the task's status, reason and count; a mark that changes nothing writes nothing. A task the care log does not hold is 422 task_not_on_log (add it with POST /care-logs/{id}/tasks). A care log that is not a draft answers 409 record_locked and nothing changes; another agency's id answers 404, whatever the body holds.

• 200 The care log object

  data CareLogDetail, required

  Field	Type	Required	Description
  data	CareLogDetail	yes

• 404 Not Found, as the operation's description says. Error
• 409 Code record_locked: Conflict, as the operation's description says. Error
• 422 Code task_not_on_log: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/half-month-summaries

Read a half-month summary

The client's half of a month with one caregiver for one service, as the evidence grid shows it: the live summary of the client, caregiver, service and half (a draft is shown re-read from the grid on every read, and the read stores nothing; the first signature freezes it). signing says from which day it may be signed and which lines are signed. A client or caregiver that is not the agency's, or a half with no summary yet, is 404; a period_start that is not the 1st or the 16th 422 validation_failed, and so is a service_type left out on a half with care for more than one service. The read is recorded on the PHI access log.

• 200 The summary object

  data HalfMonthSummary, required

  Field	Type	Required	Description
  data	HalfMonthSummary	yes

• 404 Not Found, as the operation's description says. Error
• 422 Code validation_failed: Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

GET /api/v1/phone-care-logs/exceptions

List incomplete phone care logs

As /visits/phone-care-logs: the agency's live phone care logs with no task entered, a call that ended before it was finished, or no client attestation, each with its reasons, newest service date first. A log is listed 15 minutes after its call, once the call has settled, and leaves the list when it is dismissed. Filter by reason and by from and to (service dates, inclusive). recording_document_id names the client's kept recording, readable with GET /documents/{id}/file. The read is recorded on the PHI access log.

• 200 A page of incomplete phone care logs object

  data array of PhoneCareLogException, required

  limit integer, required

  Rows asked for (default 100); a larger request is served 200.

  offset integer, required

  Rows skipped.

  total integer, required

  Every matching row.

  Field	Type	Required	Description
  data	array of PhoneCareLogException	yes
  limit	integer	yes	Rows asked for (default 100); a larger request is served 200.
  offset	integer	yes	Rows skipped.
  total	integer	yes	Every matching row.

• default An error, in the shared envelope. Error

POST /api/v1/phone-care-logs/{id}/dismiss

Dismiss an incomplete phone care log

As the screen's Dismiss: records why the log needs no more work, and it leaves the list. The care log itself does not change; it can still be finished and signed. A blank reason is 422 ("Say why you are dismissing this."). Dismissing it again answers 200 with already_dismissed true and the first dismissal. Another agency's care log, or one that is not a live phone care log, answers 404 whatever the body holds.

• 200 Already dismissed object

  data EvidenceDismissal, required

  Field	Type	Required	Description
  data	EvidenceDismissal	yes

• 201 The dismissal object

  data EvidenceDismissal, required

  Field	Type	Required	Description
  data	EvidenceDismissal	yes

• 404 Not Found, as the operation's description says. Error
• 422 Unprocessable Content, as the operation's description says. Error
• default An error, in the shared envelope. Error

POST /api/v1/caregiver-sessions

Sign in a caregiver

Signs the caregiver in with the agency code, employee id and PIN, and returns a device token for /api/v1/me. A wrong agency code, employee id or PIN all answer 401 invalid_credentials. Repeated failures answer 429 rate_limited with a Retry-After header.

• 201 The device token object

  data CaregiverSession, required

  Field	Type	Required	Description
  data	CaregiverSession	yes

• 401 Code invalid_credentials: Unauthorized, as the operation's description says. Error
• 429 Code rate_limited: Too Many Requests, as the operation's description says. Error
• default An error, in the shared envelope. Error

DELETE /api/v1/caregiver-sessions/current

Sign out this device

Revokes the device token sent as the bearer credential. The token is refused from then on, here and in the caregiver web app.

• 204 Signed out
• default An error, in the shared envelope. Error

GET /api/v1/me

The signed-in caregiver

• 200 The caregiver object

  data Me, required

  Field	Type	Required	Description
  data	Me	yes

• default An error, in the shared envelope. Error

GET /api/v1/me/care-logs

List my unfinished care logs

Your care logs not finished yet, as the app's dashboard lists them: drafts with no finished_at, of the last 90 days, newest day first, at most 20 a page. Empty when your agency has not turned care logs on for you. The read is recorded on the PHI access log.

• 200 A page of care logs object

  data array of MeCareLog, required

  limit integer, required

  Rows asked for (default 100); a larger request is served 200.

  offset integer, required

  Rows skipped.

  total integer, required

  Every matching row.

  Field	Type	Required	Description
  data	array of MeCareLog	yes
  limit	integer	yes	Rows asked for (default 100); a larger request is served 200.
  offset	integer	yes	Rows skipped.
  total	integer	yes	Every matching row.

• default An error, in the shared envelope. Error