{ "components": { "parameters": { "IdempotencyKey": { "description": "1-255 printable ASCII characters, unique per intended write and scoped to the API key sending it. A retry with the same key and the same request (method, path, query string and body) replays the first answer; the same key with any other request is 422. While the first request is still running, a retry is 409: wait and retry. An answer that says nothing persisted leaves the key free, so a retry with it runs again: a 503 with Retry-After, a 500 for a failure on our side that changed nothing (a file store refusal, an audit record that could not be written), and a 410 file_missing. Keys bind for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 255, "minLength": 1, "type": "string" } } }, "responses": {}, "schemas": { "AccountSidSet": { "properties": { "masked": { "description": "Its last four characters, as ****1234; empty when none.", "nullable": true, "type": "string" }, "set": { "description": "Whether an Account SID is saved.", "type": "boolean" } }, "required": [ "set", "masked" ], "title": "AccountSidSet", "type": "object" }, "AdpSettings": { "properties": { "adp_batch_description": { "description": "The batch description; null clears it.", "nullable": true, "type": "string" }, "adp_co_code": { "description": "The ADP company code; null clears it.", "nullable": true, "type": "string" }, "adp_earning_code_map": { "additionalProperties": true, "description": "Attendant hours to an ADP Hours column, as the tab's JSON; an empty object leaves the column out.", "type": "object" }, "biweekly_anchor_date": { "description": "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.", "format": "date", "nullable": true, "type": "string" }, "cash_advance_in_adp_run": { "description": "Whether the ADP Run file deducts each caregiver's cash advance as a negative Misc Amount.", "type": "boolean" }, "daily_overtime_enabled": { "description": "Whether daily overtime is reported.", "type": "boolean" }, "default_attendant_pay_rate": { "description": "The attendant hourly rate, such as 18.50: above zero, two decimals; null clears it.", "format": "decimal", "nullable": true, "type": "string" }, "holiday_pay_rate": { "description": "The holiday hourly rate: above zero, two decimals; null clears it.", "format": "decimal", "nullable": true, "type": "string" }, "mileage_pay_rate": { "description": "The rate per mile, such as 0.67: above zero, two decimals; null clears it.", "format": "decimal", "nullable": true, "type": "string" }, "pay_period_frequency": { "description": "The pay period.", "enum": [ "weekly", "biweekly", "semi_monthly", "monthly" ], "type": "string" } }, "required": [ "adp_batch_description", "adp_co_code", "adp_earning_code_map", "biweekly_anchor_date", "cash_advance_in_adp_run", "daily_overtime_enabled", "default_attendant_pay_rate", "holiday_pay_rate", "mileage_pay_rate", "pay_period_frequency" ], "title": "AdpSettings", "type": "object" }, "AdpSettingsUpdate": { "properties": { "adp_batch_description": { "description": "The batch description; null clears it.", "nullable": true, "type": "string" }, "adp_co_code": { "description": "The ADP company code; null clears it.", "nullable": true, "type": "string" }, "adp_earning_code_map": { "additionalProperties": true, "description": "Attendant hours to an ADP Hours column, as the tab's JSON; an empty object leaves the column out.", "type": "object" }, "biweekly_anchor_date": { "description": "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.", "format": "date", "nullable": true, "type": "string" }, "cash_advance_in_adp_run": { "description": "Whether the ADP Run file deducts each caregiver's cash advance as a negative Misc Amount.", "type": "boolean" }, "daily_overtime_enabled": { "description": "Whether daily overtime is reported.", "type": "boolean" }, "default_attendant_pay_rate": { "description": "The attendant hourly rate, such as 18.50: above zero, two decimals; null clears it.", "format": "decimal", "nullable": true, "type": "string" }, "holiday_pay_rate": { "description": "The holiday hourly rate: above zero, two decimals; null clears it.", "format": "decimal", "nullable": true, "type": "string" }, "mileage_pay_rate": { "description": "The rate per mile, such as 0.67: above zero, two decimals; null clears it.", "format": "decimal", "nullable": true, "type": "string" }, "pay_period_frequency": { "description": "The pay period.", "enum": [ "weekly", "biweekly", "semi_monthly", "monthly" ], "type": "string" } }, "title": "AdpSettingsUpdate", "type": "object" }, "AgencyApiKey": { "properties": { "created_at": { "description": "When it was created (UTC).", "format": "date-time", "type": "string" }, "created_by_id": { "description": "The admin who created it.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_used_at": { "description": "Its last request (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "name": { "description": "The key's name.", "nullable": true, "type": "string" }, "revoked_at": { "description": "When it was revoked (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "role": { "description": "What the key may do.", "enum": [ "admin", "billing_staff" ], "type": "string" } }, "required": [ "id", "name", "role" ], "title": "AgencyApiKey", "type": "object" }, "AgencyApiKeyCreate": { "properties": { "name": { "description": "A name for the integration.", "type": "string" }, "role": { "description": "What the key may do.", "enum": [ "admin", "billing_staff" ], "type": "string" } }, "required": [ "name", "role" ], "title": "AgencyApiKeyCreate", "type": "object" }, "AgencyApiKeyCreated": { "properties": { "data": { "properties": { "created_at": { "description": "When it was created (UTC).", "format": "date-time", "type": "string" }, "created_by_id": { "description": "The admin who created it.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_used_at": { "description": "Its last request (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "name": { "description": "The key's name.", "nullable": true, "type": "string" }, "revoked_at": { "description": "When it was revoked (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "role": { "description": "What the key may do.", "enum": [ "admin", "billing_staff" ], "type": "string" } }, "required": [ "id", "name", "role" ], "title": "AgencyApiKey", "type": "object" }, "secret": { "description": "The secret, shown this once.", "nullable": true, "type": "string" } }, "required": [ "data", "secret" ], "title": "AgencyApiKeyCreated", "type": "object" }, "AgencyApiKeyPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "created_at": { "description": "When it was created (UTC).", "format": "date-time", "type": "string" }, "created_by_id": { "description": "The admin who created it.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_used_at": { "description": "Its last request (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "name": { "description": "The key's name.", "nullable": true, "type": "string" }, "revoked_at": { "description": "When it was revoked (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "role": { "description": "What the key may do.", "enum": [ "admin", "billing_staff" ], "type": "string" } }, "required": [ "id", "name", "role" ], "title": "AgencyApiKey", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "AgencyApiKeyPage", "type": "object" }, "AgencyInvitation": { "properties": { "email": { "description": "Who was invited.", "nullable": true, "type": "string" }, "expires_at": { "description": "When the link stops working (UTC).", "format": "date-time", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "invited_at": { "description": "When it was sent (UTC).", "format": "date-time", "type": "string" }, "invited_by_id": { "description": "The member who invited.", "format": "uuid", "nullable": true, "type": "string" }, "role": { "description": "The role they join with.", "enum": [ "admin", "billing_staff" ], "type": "string" }, "status": { "description": "Where it stands.", "enum": [ "pending", "accepted", "revoked", "expired" ], "type": "string" } }, "required": [ "id", "email", "role", "status" ], "title": "AgencyInvitation", "type": "object" }, "AgencyInvitationCreate": { "properties": { "email": { "description": "Their email address.", "type": "string" }, "role": { "description": "The role they join with.", "enum": [ "admin", "billing_staff" ], "type": "string" } }, "required": [ "email", "role" ], "title": "AgencyInvitationCreate", "type": "object" }, "AgencyInvitationPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "email": { "description": "Who was invited.", "nullable": true, "type": "string" }, "expires_at": { "description": "When the link stops working (UTC).", "format": "date-time", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "invited_at": { "description": "When it was sent (UTC).", "format": "date-time", "type": "string" }, "invited_by_id": { "description": "The member who invited.", "format": "uuid", "nullable": true, "type": "string" }, "role": { "description": "The role they join with.", "enum": [ "admin", "billing_staff" ], "type": "string" }, "status": { "description": "Where it stands.", "enum": [ "pending", "accepted", "revoked", "expired" ], "type": "string" } }, "required": [ "id", "email", "role", "status" ], "title": "AgencyInvitation", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "AgencyInvitationPage", "type": "object" }, "AgencyMember": { "properties": { "email": { "description": "Their sign-in email.", "nullable": true, "type": "string" }, "id": { "description": "The member's user id.", "format": "uuid", "type": "string" }, "joined_at": { "description": "When they joined (UTC).", "format": "date-time", "type": "string" }, "last_seen_at": { "description": "When they last signed in here (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "name": { "description": "Their display name; null shows the email.", "nullable": true, "type": "string" }, "role": { "description": "Their role in this agency.", "enum": [ "admin", "billing_staff" ], "type": "string" }, "status": { "description": "Whether they may sign in here.", "enum": [ "active", "deactivated" ], "type": "string" } }, "required": [ "id", "email", "role", "status" ], "title": "AgencyMember", "type": "object" }, "AgencyMemberPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "email": { "description": "Their sign-in email.", "nullable": true, "type": "string" }, "id": { "description": "The member's user id.", "format": "uuid", "type": "string" }, "joined_at": { "description": "When they joined (UTC).", "format": "date-time", "type": "string" }, "last_seen_at": { "description": "When they last signed in here (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "name": { "description": "Their display name; null shows the email.", "nullable": true, "type": "string" }, "role": { "description": "Their role in this agency.", "enum": [ "admin", "billing_staff" ], "type": "string" }, "status": { "description": "Whether they may sign in here.", "enum": [ "active", "deactivated" ], "type": "string" } }, "required": [ "id", "email", "role", "status" ], "title": "AgencyMember", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "AgencyMemberPage", "type": "object" }, "AgencyMemberUpdate": { "properties": { "name": { "description": "Their display name; null or blank clears it, showing the email.", "nullable": true, "type": "string" }, "role": { "description": "Their role.", "enum": [ "admin", "billing_staff" ], "type": "string" } }, "title": "AgencyMemberUpdate", "type": "object" }, "AgencyProfile": { "description": "The agency's identity, address and claim defaults. Changing them needs agency_settings.manage.", "properties": { "address_line1": { "description": "Street address.", "nullable": true, "type": "string" }, "address_line2": { "description": "Suite or unit.", "nullable": true, "type": "string" }, "city": { "description": "City.", "nullable": true, "type": "string" }, "default_diagnosis_code": { "description": "The default primary diagnosis code (ICD-10) for new claims.", "nullable": true, "type": "string" }, "default_place_of_service": { "description": "The default place of service code for new claims.", "nullable": true, "type": "string" }, "default_procedure_codes": { "additionalProperties": { "type": "string" }, "description": "The procedure code (billing code, then its modifiers) each service's generated Work Orders bill under when the client has no billing assignment and the Plan of Care names no code (US-107.4). Keys personal_care and homemaker only. Sending it replaces the whole object: a service left out or blank has no default, and {} clears both.", "properties": { "homemaker": { "description": "The Homemaker code, such as \"S5130 U2\".", "nullable": true, "type": "string" }, "personal_care": { "description": "The Personal Care code, such as \"T1019 U2\".", "nullable": true, "type": "string" } }, "type": "object" }, "default_rendering_npi": { "description": "The default Medicaid provider (location) id claims carry as rendering provider.", "nullable": true, "type": "string" }, "emergency_phone": { "description": "The number a caregiver calls in an emergency, printed on the emergency form and wallet card; the main phone prints while it is empty.", "nullable": true, "type": "string" }, "fax": { "description": "Fax number.", "nullable": true, "type": "string" }, "name": { "description": "The agency's name, as claims and printed forms carry it.", "nullable": true, "type": "string" }, "npi": { "description": "The agency's 10-digit NPI.", "nullable": true, "type": "string" }, "open_shifts": { "$ref": "#/components/schemas/OpenShiftSettings" }, "phone": { "description": "Phone number.", "nullable": true, "type": "string" }, "state": { "description": "Two-letter state code.", "nullable": true, "type": "string" }, "tax_id": { "description": "The agency's Tax ID, NN-NNNNNNN.", "nullable": true, "type": "string" }, "week_start_day": { "description": "The day the agency's printed weeks start on.", "enum": [ "saturday", "sunday", "monday" ], "type": "string" }, "work_order_print_certification": { "description": "Whether a printed Work Order carries the notice, certification and signature lines (US-102.30); on unless the agency turns it off.", "type": "boolean" }, "zip": { "description": "ZIP code, 5 or 9 digits.", "nullable": true, "type": "string" } }, "required": [ "name" ], "title": "AgencyProfile", "type": "object" }, "AgencyProfileUpdate": { "description": "The profile fields to change; a field left out keeps its value. The agency has no lock_version: the update sets only what it sends.", "properties": { "address_line1": { "description": "Street address.", "nullable": true, "type": "string" }, "address_line2": { "description": "Suite or unit.", "nullable": true, "type": "string" }, "city": { "description": "City.", "nullable": true, "type": "string" }, "default_diagnosis_code": { "description": "The default primary diagnosis code (ICD-10) for new claims; cannot be cleared.", "type": "string" }, "default_place_of_service": { "description": "The default place of service code for new claims; cannot be cleared.", "type": "string" }, "default_procedure_codes": { "additionalProperties": { "type": "string" }, "description": "The procedure code (billing code, then its modifiers) each service's generated Work Orders bill under when the client has no billing assignment and the Plan of Care names no code (US-107.4). Keys personal_care and homemaker only. Sending it replaces the whole object: a service left out or blank has no default, and {} clears both.", "properties": { "homemaker": { "description": "The Homemaker code, such as \"S5130 U2\".", "nullable": true, "type": "string" }, "personal_care": { "description": "The Personal Care code, such as \"T1019 U2\".", "nullable": true, "type": "string" } }, "type": "object" }, "default_rendering_npi": { "description": "The default Medicaid provider (location) id claims carry as rendering provider.", "nullable": true, "type": "string" }, "emergency_phone": { "description": "The number a caregiver calls in an emergency, printed on the emergency form and wallet card; the main phone prints while it is empty.", "nullable": true, "type": "string" }, "fax": { "description": "Fax number.", "nullable": true, "type": "string" }, "name": { "description": "The agency's name, as claims and printed forms carry it.", "nullable": false, "type": "string" }, "npi": { "description": "The agency's 10-digit NPI.", "nullable": true, "type": "string" }, "open_shifts": { "$ref": "#/components/schemas/OpenShiftSettings" }, "phone": { "description": "Phone number.", "nullable": true, "type": "string" }, "state": { "description": "Two-letter state code.", "nullable": true, "type": "string" }, "tax_id": { "description": "The agency's Tax ID, NN-NNNNNNN.", "nullable": true, "type": "string" }, "week_start_day": { "description": "The day the agency's printed weeks start on.", "enum": [ "saturday", "sunday", "monday" ], "type": "string" }, "work_order_print_certification": { "description": "Whether a printed Work Order carries the notice, certification and signature lines (US-102.30); on unless the agency turns it off.", "type": "boolean" }, "zip": { "description": "ZIP code, 5 or 9 digits.", "nullable": true, "type": "string" } }, "title": "AgencyProfileUpdate", "type": "object" }, "Agenda": { "description": "What the agency needs to deal with on one day: reminders due that day, reminders already overdue, client and caregiver birthdays, and the billing work waiting.", "properties": { "billing": { "description": "The billing work waiting, for the day's month. Work orders and batches are null for a caller whose roles do not grant billing.view.", "properties": { "batches_ready_to_submit": { "nullable": true, "type": "integer" }, "timesheets_awaiting_approval": { "type": "integer" }, "work_orders_ready_to_bill": { "nullable": true, "type": "integer" } }, "required": [ "work_orders_ready_to_bill", "timesheets_awaiting_approval", "batches_ready_to_submit" ], "type": "object" }, "birthdays": { "items": { "$ref": "#/components/schemas/AgendaBirthday" }, "type": "array" }, "caregiver_birthdays": { "items": { "$ref": "#/components/schemas/AgendaCaregiverBirthday" }, "type": "array" }, "date": { "description": "The agenda's day (Mountain time).", "format": "date", "nullable": true, "type": "string" }, "due_today": { "description": "Open reminders due on the day, morning to evening, untimed ones last; due_today_offset reads past the first page.", "properties": { "events": { "items": { "$ref": "#/components/schemas/Reminder" }, "type": "array" }, "limit": { "description": "The most events one answer holds (100).", "type": "integer" }, "offset": { "description": "How many were skipped.", "type": "integer" }, "total": { "description": "How many there are in all.", "type": "integer" }, "truncated": { "description": "True when there are more than events holds; read on with the offset.", "type": "boolean" } }, "required": [ "events", "total", "truncated", "limit", "offset" ], "type": "object" }, "overdue": { "description": "Open reminders due before the day, most recently missed first; overdue_offset reads past the first page.", "properties": { "events": { "items": { "$ref": "#/components/schemas/Reminder" }, "type": "array" }, "limit": { "description": "The most events one answer holds (100).", "type": "integer" }, "offset": { "description": "How many were skipped.", "type": "integer" }, "total": { "description": "How many there are in all.", "type": "integer" }, "truncated": { "description": "True when there are more than events holds; read on with the offset.", "type": "boolean" } }, "required": [ "events", "total", "truncated", "limit", "offset" ], "type": "object" } }, "required": [ "date", "due_today", "overdue", "birthdays", "caregiver_birthdays", "billing" ], "title": "Agenda", "type": "object" }, "AgendaBirthday": { "description": "A client whose birthday falls on the agenda's day, as the Today page and the daily digest show it. Sample clients are left out.", "properties": { "client_first_name": { "description": "The client's first name.", "nullable": true, "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "client_last_name": { "description": "The client's last name.", "nullable": true, "type": "string" }, "date": { "description": "The agenda's day.", "format": "date", "nullable": true, "type": "string" }, "title": { "description": "The agenda line, e.g. \"Jane Doe's Birthday (age 82)\".", "nullable": true, "type": "string" } }, "required": [ "client_id", "date" ], "title": "AgendaBirthday", "type": "object" }, "AgendaCaregiverBirthday": { "description": "An active caregiver whose birthday falls on the agenda's day, as the Today page and the daily digest show it. Sample caregivers are left out.", "properties": { "caregiver_first_name": { "description": "The caregiver's first name.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "caregiver_last_name": { "description": "The caregiver's last name.", "nullable": true, "type": "string" }, "date": { "description": "The agenda's day.", "format": "date", "nullable": true, "type": "string" }, "title": { "description": "The agenda line, e.g. \"Jane Doe's Birthday (caregiver, age 41)\".", "nullable": true, "type": "string" } }, "required": [ "caregiver_id", "date" ], "title": "AgendaCaregiverBirthday", "type": "object" }, "Assignment": { "description": "A caregiver serving a client, under one billing code.", "properties": { "billing_code": { "description": "The HCPCS code billed for the service.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver serving.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client served.", "format": "uuid", "type": "string" }, "effective_date": { "format": "date", "nullable": true, "type": "string" }, "end_date": { "format": "date", "nullable": true, "type": "string" }, "evv_exemption_date": { "format": "date", "nullable": true, "type": "string" }, "evv_exemption_on_file": { "type": "boolean" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the record was created.", "format": "date-time", "type": "string" }, "live_in": { "type": "boolean" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "modifiers": { "description": "Billing code modifiers.", "items": { "type": "string" }, "type": "array" }, "provider_type": { "enum": [ "pcp", "pcp_cfc", "pcp_ihss", "hmkr", "hmkr_ihss", "hma", "attendant", "ihss" ], "type": "string" }, "relative_provider": { "description": "The caregiver is a relative of the client.", "type": "boolean" }, "status": { "enum": [ "active", "inactive", "temporary", "closed" ], "type": "string" }, "updated_at": { "description": "When the record last changed.", "format": "date-time", "type": "string" }, "work_order_number": { "description": "The work order number the office typed on the assignment.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "id", "client_id", "caregiver_id", "status", "lock_version" ], "title": "Assignment", "type": "object" }, "AssignmentCreate": { "description": "A new assignment. The client and caregiver must be active members of the agency, and the pair must not already have an open assignment for the provider type.", "properties": { "billing_code": { "description": "The HCPCS code billed for the service.", "nullable": false, "type": "string" }, "caregiver_id": { "description": "The caregiver serving.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client served.", "format": "uuid", "type": "string" }, "effective_date": { "format": "date", "nullable": false, "type": "string" }, "end_date": { "format": "date", "nullable": true, "type": "string" }, "evv_exemption_date": { "format": "date", "nullable": true, "type": "string" }, "evv_exemption_on_file": { "type": "boolean" }, "live_in": { "type": "boolean" }, "modifiers": { "description": "Billing code modifiers.", "items": { "type": "string" }, "type": "array" }, "notes": { "description": "Free text; written, never returned.", "nullable": true, "type": "string" }, "provider_type": { "enum": [ "pcp", "pcp_cfc", "pcp_ihss", "hmkr", "hmkr_ihss", "hma", "attendant", "ihss" ], "type": "string" }, "relative_provider": { "description": "The caregiver is a relative of the client.", "type": "boolean" }, "work_order_number": { "description": "The work order number the office typed on the assignment.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "client_id", "caregiver_id", "provider_type", "billing_code", "effective_date" ], "title": "AssignmentCreate", "type": "object" }, "AssignmentPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Assignment" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "AssignmentPage", "type": "object" }, "AssignmentSchedule": { "properties": { "assignment_id": { "description": "The assignment.", "format": "uuid", "type": "string" }, "lock_version": { "description": "The assignment's lock_version, which the next schedule save sends.", "type": "integer" }, "shifts": { "description": "Each shift that has days, in shift order.", "items": { "properties": { "days": { "items": { "properties": { "day_of_week": { "enum": [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" ], "type": "string" }, "end_time": { "type": "string" }, "ends_next_day": { "description": "The shift ends after midnight, on the next day.", "type": "boolean" }, "hours": { "description": "The day's hours, a decimal.", "nullable": true, "type": "string" }, "start_time": { "type": "string" }, "work_order_number": { "description": "The WO # of the Work Order that places this day (\"12\"); null on a day the office entered. A save that sends a placed day back unchanged writes nothing for it.", "nullable": true, "type": "string" } }, "required": [ "day_of_week", "start_time", "end_time", "ends_next_day" ], "type": "object" }, "type": "array" }, "shift_number": { "minimum": 1, "type": "integer" } }, "required": [ "shift_number", "days" ], "type": "object" }, "type": "array" } }, "required": [ "assignment_id", "lock_version", "shifts" ], "title": "AssignmentSchedule", "type": "object" }, "AssignmentScheduleSave": { "properties": { "days": { "description": "The shift's days; an empty list clears the shift.", "items": { "properties": { "day_of_week": { "description": "The day.", "enum": [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" ], "type": "string" }, "end_time": { "description": "HH:MM or HH:MM:SS, 24-hour; after start_time, or at or before it when ends_next_day is true.", "type": "string" }, "ends_next_day": { "default": false, "description": "True for a shift that ends after midnight, on the next day (22:30 to 00:30); default false.", "type": "boolean" }, "start_time": { "description": "HH:MM or HH:MM:SS, 24-hour.", "type": "string" } }, "required": [ "day_of_week", "start_time", "end_time" ], "type": "object" }, "type": "array" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "shift_number": { "description": "The shift to save, 1 to 4, as GET names it; default 1. The shift query parameter does the same.", "maximum": 4, "minimum": 1, "type": "integer" } }, "required": [ "days", "lock_version" ], "title": "AssignmentScheduleSave", "type": "object" }, "AssignmentTransition": { "properties": { "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "reason": { "description": "Why, kept in the status history.", "maxLength": 1000, "nullable": true, "type": "string" }, "status": { "description": "The new status.", "enum": [ "active", "inactive", "temporary", "closed" ], "type": "string" } }, "required": [ "status", "lock_version" ], "title": "AssignmentTransition", "type": "object" }, "AssignmentUpdate": { "description": "Fields to change, plus the lock_version you read (required).", "properties": { "billing_code": { "description": "The HCPCS code billed for the service.", "nullable": false, "type": "string" }, "effective_date": { "format": "date", "nullable": false, "type": "string" }, "end_date": { "format": "date", "nullable": true, "type": "string" }, "evv_exemption_date": { "format": "date", "nullable": true, "type": "string" }, "evv_exemption_on_file": { "type": "boolean" }, "live_in": { "type": "boolean" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "modifiers": { "description": "Billing code modifiers.", "items": { "type": "string" }, "type": "array" }, "notes": { "description": "Free text; written, never returned.", "nullable": true, "type": "string" }, "provider_type": { "enum": [ "pcp", "pcp_cfc", "pcp_ihss", "hmkr", "hmkr_ihss", "hma", "attendant", "ihss" ], "type": "string" }, "relative_provider": { "description": "The caregiver is a relative of the client.", "type": "boolean" }, "work_order_number": { "description": "The work order number the office typed on the assignment.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "title": "AssignmentUpdate", "type": "object" }, "AttentionRow": { "description": "Something about a client or caregiver that needs doing. An agency reminder names no subject and points at /today.", "properties": { "action_label": { "description": "What to do, e.g. \"Renew by Nov 3\".", "nullable": true, "type": "string" }, "due_on": { "description": "When it is due, or since when it has waited; null when no date applies.", "format": "date", "nullable": true, "type": "string" }, "kind": { "description": "Where the row comes from.", "enum": [ "due_today", "overdue", "compliance", "oig", "supervisory_visit", "recertification", "authorization_ending", "follow_up" ], "type": "string" }, "path": { "description": "The app page that does it, with its tab.", "nullable": true, "type": "string" }, "subject_id": { "description": "The client's or caregiver's id; null for the agency.", "format": "uuid", "nullable": true, "type": "string" }, "subject_name": { "description": "Last name, first name; null for the agency.", "nullable": true, "type": "string" }, "subject_type": { "description": "Whom the row is about.", "enum": [ "client", "caregiver", "agency" ], "type": "string" } }, "required": [ "kind", "subject_type", "action_label", "path" ], "title": "AttentionRow", "type": "object" }, "AttentionRowPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/AttentionRow" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "AttentionRowPage", "type": "object" }, "AuditReadiness": { "description": "The agency's audit readiness: the summary's counts, and a page of the clients and caregivers with a gap (an item missing or expiring soon), most missing first.", "properties": { "caregivers_needing_attention": { "items": { "$ref": "#/components/schemas/FileGaps" }, "type": "array" }, "caregivers_needing_attention_total": { "description": "How many caregivers have a gap.", "nullable": true, "type": "integer" }, "clients_needing_attention": { "items": { "$ref": "#/components/schemas/FileGaps" }, "type": "array" }, "clients_needing_attention_total": { "description": "How many clients have a gap.", "nullable": true, "type": "integer" }, "limit": { "description": "The page size of the two lists.", "nullable": true, "type": "integer" }, "offset": { "description": "The offset of the two lists.", "nullable": true, "type": "integer" }, "overall_readiness_percentage": { "description": "Overall readiness, 0 to 100.", "type": "number" } }, "required": [ "clients_needing_attention", "caregivers_needing_attention" ], "title": "AuditReadiness", "type": "object" }, "Batch": { "description": "One uploaded claims file and the claims made from it. A batch can be deleted only before it is submitted, and it is then removed with its claims: no list or sync reports the removal, and GET of its id answers 404. So a client holding a batch with no submitted_at should re-read it by id to learn whether it still exists; a batch with submitted_at is never deleted.", "properties": { "auto_submit_requested": { "description": "Submit as soon as it validates.", "type": "boolean" }, "claim_count": { "description": "Claims in the batch.", "nullable": true, "type": "integer" }, "claim_type": { "enum": [ "professional", "institutional" ], "type": "string" }, "completed_at": { "description": "When processing finished.", "format": "date-time", "type": "string" }, "error_message": { "description": "Why the batch failed, when it did.", "nullable": true, "type": "string" }, "failed_count": { "description": "Claims refused.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the record was created.", "format": "date-time", "type": "string" }, "original_filename": { "description": "The uploaded file's name.", "nullable": true, "type": "string" }, "source": { "description": "Where the batch came from, e.g. upload.", "nullable": true, "type": "string" }, "status": { "description": "The batch's processing status, which the status filter matches. A delivered batch stays submitted: whether its claims were paid is on the claims (their status and paid fields), which change with their updated_at. completed and partially_completed occur only on sample (demo) batches.", "enum": [ "pending", "validating", "validated", "generating", "generated", "submitting", "submitted", "processing", "completed", "partially_completed", "failed", "cancelled" ], "type": "string" }, "submitted_at": { "description": "When the batch was sent to HCPF.", "format": "date-time", "type": "string" }, "successful_count": { "description": "Claims accepted.", "nullable": true, "type": "integer" }, "updated_at": { "description": "When the record last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "status" ], "title": "Batch", "type": "object" }, "BatchPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Batch" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "BatchPage", "type": "object" }, "BillingCode": { "description": "A billing code a work order may carry, with the modifiers the Colorado fee schedules use. A work order also takes other modifiers in valid 837P format (two letters or digits), at most 4 and at most one program modifier; otherwise it answers 422 on modifiers.", "properties": { "code": { "description": "The HCPCS code.", "nullable": true, "type": "string" }, "modifiers": { "description": "The modifiers the fee schedules use; the same list for every code.", "items": { "type": "string" }, "type": "array" } }, "required": [ "code", "modifiers" ], "title": "BillingCode", "type": "object" }, "BillingCodePage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/BillingCode" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "BillingCodePage", "type": "object" }, "Broadcast": { "properties": { "delivery_method": { "description": "How it went out.", "enum": [ "email", "sms", "both" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "recipient_count": { "description": "Caregivers sent to.", "type": "integer" }, "recipient_scope": { "description": "Who it went to.", "enum": [ "all", "expired", "expiring_soon", "training", "evaluation", "pick" ], "type": "string" }, "reply_count": { "description": "Caregivers who texted back to it (#2567).", "type": "integer" }, "sent_at": { "description": "When it was sent (UTC).", "format": "date-time", "type": "string" }, "skipped_count": { "description": "Caregivers skipped: no contact for the method, or opted out of SMS.", "type": "integer" }, "yes_count": { "description": "Of those, how many replies read as a yes.", "type": "integer" } }, "required": [ "id", "delivery_method", "recipient_count" ], "title": "Broadcast", "type": "object" }, "BroadcastCreate": { "properties": { "caregiver_ids": { "description": "pick: the caregivers to send to, whatever their status (former ones included). At most 1000.", "items": { "description": "A caregiver of the agency.", "format": "uuid", "type": "string" }, "type": "array" }, "delivery_method": { "description": "How to send it: email, sms or both. Leave it out for email.", "enum": [ "email", "sms", "both" ], "type": "string" }, "include_former": { "description": "With tag: also caregivers no longer active. Leave it out for active only.", "type": "boolean" }, "message": { "description": "The message.", "type": "string" }, "recipient_scope": { "description": "Who to send it to. Leave it out for all, or for pick when caregiver_ids or tag is given.", "enum": [ "all", "expired", "expiring_soon", "training", "evaluation", "pick" ], "type": "string" }, "tag": { "description": "pick: every caregiver carrying this tag (any case).", "type": "string" } }, "required": [ "message" ], "title": "BroadcastCreate", "type": "object" }, "BroadcastPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "delivery_method": { "description": "How it went out.", "enum": [ "email", "sms", "both" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "message": { "description": "What it said.", "nullable": true, "type": "string", "x-untrusted": "text" }, "recipient_count": { "description": "Caregivers sent to.", "type": "integer" }, "reply_count": { "description": "Caregivers who texted back to it.", "type": "integer" }, "sent_at": { "description": "When it was sent (UTC).", "format": "date-time", "type": "string" }, "skipped_count": { "description": "Caregivers skipped: no contact for the method, or opted out of SMS.", "type": "integer" }, "yes_count": { "description": "Of those, how many replies read as a yes.", "type": "integer" } }, "required": [ "id", "delivery_method", "recipient_count" ], "title": "BroadcastSummary", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "BroadcastPage", "type": "object" }, "BroadcastReply": { "properties": { "caregiver_id": { "description": "The caregiver who replied.", "format": "uuid", "type": "string" }, "caregiver_name": { "description": "The caregiver, last name first.", "nullable": true, "type": "string", "x-untrusted": "text" }, "replied_at": { "description": "When it arrived (UTC).", "format": "date-time", "type": "string" }, "reply": { "description": "Their latest text back.", "nullable": true, "type": "string", "x-untrusted": "text" }, "yes": { "description": "Whether the reply reads as a yes.", "type": "boolean" } }, "required": [ "caregiver_id", "reply", "yes" ], "title": "BroadcastReply", "type": "object" }, "BroadcastReplyPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "caregiver_id": { "description": "The caregiver who replied.", "format": "uuid", "type": "string" }, "caregiver_name": { "description": "The caregiver, last name first.", "nullable": true, "type": "string", "x-untrusted": "text" }, "replied_at": { "description": "When it arrived (UTC).", "format": "date-time", "type": "string" }, "reply": { "description": "Their latest text back.", "nullable": true, "type": "string", "x-untrusted": "text" }, "yes": { "description": "Whether the reply reads as a yes.", "type": "boolean" } }, "required": [ "caregiver_id", "reply", "yes" ], "title": "BroadcastReply", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "BroadcastReplyPage", "type": "object" }, "BroadcastSummary": { "properties": { "delivery_method": { "description": "How it went out.", "enum": [ "email", "sms", "both" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "message": { "description": "What it said.", "nullable": true, "type": "string", "x-untrusted": "text" }, "recipient_count": { "description": "Caregivers sent to.", "type": "integer" }, "reply_count": { "description": "Caregivers who texted back to it.", "type": "integer" }, "sent_at": { "description": "When it was sent (UTC).", "format": "date-time", "type": "string" }, "skipped_count": { "description": "Caregivers skipped: no contact for the method, or opted out of SMS.", "type": "integer" }, "yes_count": { "description": "Of those, how many replies read as a yes.", "type": "integer" } }, "required": [ "id", "delivery_method", "recipient_count" ], "title": "BroadcastSummary", "type": "object" }, "CareLog": { "description": "One caregiver's day for one client, for one service and shift, as the /care-logs list shows it, with its task counts.", "properties": { "attestation_skip_note": { "description": "The caregiver's note on that reason (required for other); null when none.", "nullable": true, "type": "string", "x-untrusted": "text" }, "attestation_skip_reason": { "description": "Why the client did not sign, as the caregiver gave it with Client can't sign (US-101.20); the day stays a draft for the office to collect a signature. null when none was given.", "enum": [ "client_asleep_or_unwell", "client_not_present", "client_declined_to_sign", "client_unable_to_sign", "other" ], "nullable": true, "type": "string" }, "attestation_skipped_at": { "description": "When the reason was given; null when none was.", "format": "date-time", "nullable": true, "type": "string" }, "attestation_skipped_by_caregiver_id": { "description": "The caregiver who gave the reason; null when none was.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "finished_at": { "description": "When it was marked finished; null while open.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was started.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "notes": { "description": "The day's notes.", "nullable": true, "type": "string", "x-untrusted": "text" }, "record_state": { "description": "draft until the client's signature (or a paper signature on file) locks it; then signed, amended (an addendum was signed) or voided (corrected by a new draft).", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "replaces_id": { "description": "The voided care log this draft corrects; null when none.", "format": "uuid", "nullable": true, "type": "string" }, "service_date": { "description": "The day.", "format": "date", "nullable": true, "type": "string" }, "service_type": { "description": "The service, as the Work Order's.", "enum": [ "personal_care", "homemaker", "legacy" ], "type": "string" }, "shift_number": { "description": "The shift, 1 to 4.", "maximum": 4, "minimum": 1, "type": "integer" }, "signed_at": { "description": "When it was first signed; null for a draft.", "format": "date-time", "nullable": true, "type": "string" }, "source": { "description": "Where it was captured: hcb_app, hcb_phone, office, paper_scan or import.", "enum": [ "hcb_app", "hcb_phone", "office", "paper_scan", "import" ], "type": "string" }, "task_counts": { "properties": { "done": { "description": "Tasks done.", "minimum": 0, "type": "integer" }, "not_needed": { "description": "Tasks not needed.", "minimum": 0, "type": "integer" }, "refused": { "description": "Tasks refused.", "minimum": 0, "type": "integer" }, "unmarked": { "description": "Tasks not marked yet.", "minimum": 0, "type": "integer" } }, "required": [ "done", "refused", "not_needed", "unmarked" ], "title": "CareLogTaskCounts", "type": "object" }, "time_in": { "description": "The entered start time, used only when no Visit is linked.", "format": "date-time", "nullable": true, "type": "string" }, "time_out": { "description": "The entered end time, used only when no Visit is linked.", "format": "date-time", "nullable": true, "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" }, "visit_id": { "description": "The Visit linked to the day, whose times are the care log's; null when none.", "format": "uuid", "nullable": true, "type": "string" }, "voided_at": { "description": "When it was voided; null unless voided.", "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "id", "client_id", "caregiver_id", "service_date", "record_state", "task_counts" ], "title": "CareLog", "type": "object" }, "CareLogDetail": { "description": "One care log as its /care-logs/:id screen shows it: the day, its tasks, its times, the differences from the plan to explain (warnings never refuse a save, a finish or a signature) and its live signatures.", "properties": { "attestation_skip_note": { "description": "The caregiver's note on that reason (required for other); null when none.", "nullable": true, "type": "string", "x-untrusted": "text" }, "attestation_skip_reason": { "description": "Why the client did not sign, as the caregiver gave it with Client can't sign (US-101.20); the day stays a draft for the office to collect a signature. null when none was given.", "enum": [ "client_asleep_or_unwell", "client_not_present", "client_declined_to_sign", "client_unable_to_sign", "other" ], "nullable": true, "type": "string" }, "attestation_skipped_at": { "description": "When the reason was given; null when none was.", "format": "date-time", "nullable": true, "type": "string" }, "attestation_skipped_by_caregiver_id": { "description": "The caregiver who gave the reason; null when none was.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "finished_at": { "description": "When it was marked finished; null while open.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was started.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "notes": { "description": "The day's notes.", "nullable": true, "type": "string", "x-untrusted": "text" }, "record_state": { "description": "draft until the client's signature (or a paper signature on file) locks it; then signed, amended (an addendum was signed) or voided (corrected by a new draft).", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "replaced_by_id": { "description": "The draft that corrects this voided care log; null when none.", "format": "uuid", "nullable": true, "type": "string" }, "replaces_id": { "description": "The voided care log this draft corrects; null when none.", "format": "uuid", "nullable": true, "type": "string" }, "service_date": { "description": "The day.", "format": "date", "nullable": true, "type": "string" }, "service_type": { "description": "The service, as the Work Order's.", "enum": [ "personal_care", "homemaker", "legacy" ], "type": "string" }, "shift_number": { "description": "The shift, 1 to 4.", "maximum": 4, "minimum": 1, "type": "integer" }, "signatures": { "description": "The live signatures, oldest first, without their images.", "items": { "properties": { "channel": { "description": "Where it was captured.", "nullable": true, "type": "string" }, "evidence_document_id": { "description": "The client's document holding the paper scan; null when none.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The signature.", "format": "uuid", "type": "string" }, "method": { "description": "How it was signed; paper_on_file for a paper signature the office marked as on file.", "enum": [ "drawn", "initials", "typed", "pin", "voice", "docusign_agency", "docusign_platform", "paper_on_file", "imported" ], "type": "string" }, "role": { "description": "The line signed (client, caregiver, ...).", "nullable": true, "type": "string" }, "signed_at": { "description": "When it was signed.", "format": "date-time", "type": "string" }, "signer_name": { "description": "The name the line is signed under.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "id", "role", "method", "signed_at" ], "title": "CareLogSignature", "type": "object" }, "type": "array" }, "signed_at": { "description": "When it was first signed; null for a draft.", "format": "date-time", "nullable": true, "type": "string" }, "source": { "description": "Where it was captured: hcb_app, hcb_phone, office, paper_scan or import.", "enum": [ "hcb_app", "hcb_phone", "office", "paper_scan", "import" ], "type": "string" }, "tasks": { "description": "Planned tasks first, then those added off the plan.", "items": { "properties": { "code": { "description": "The task's code.", "nullable": true, "type": "string" }, "count": { "description": "How many times.", "minimum": 1, "type": "integer" }, "id": { "description": "The care log's task.", "format": "uuid", "type": "string" }, "name": { "description": "The task's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "planned": { "description": "Whether a Work Order in force planned it for the day; false for one added off the plan.", "type": "boolean" }, "reason_code": { "description": "Why it was refused, not needed or added.", "enum": [ "client_declined", "client_not_home", "client_asleep_or_unwell", "done_by_someone_else", "not_needed_today", "client_requested", "care_need_changed", "other" ], "nullable": true, "type": "string" }, "reason_note": { "description": "The reason in words.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "done, refused or not_needed; null when unmarked.", "enum": [ "done", "refused", "not_needed" ], "nullable": true, "type": "string" }, "task_definition_id": { "description": "The agency's task; the {task_id} a mark is sent to (POST /care-logs/{id}/tasks/{task_id}/mark).", "format": "uuid", "type": "string" } }, "required": [ "id", "task_definition_id", "planned", "count" ], "title": "CareLogTask", "type": "object" }, "type": "array" }, "time_in": { "description": "The entered start time, used only when no Visit is linked.", "format": "date-time", "nullable": true, "type": "string" }, "time_out": { "description": "The entered end time, used only when no Visit is linked.", "format": "date-time", "nullable": true, "type": "string" }, "times": { "properties": { "end": { "description": "When it ended.", "format": "date-time", "nullable": true, "type": "string" }, "source": { "description": "visit: the linked Visit's billable times (adjusted, else actual, else scheduled); entered: time_in and time_out, when no Visit is linked.", "enum": [ "visit", "entered" ], "type": "string" }, "start": { "description": "When the day's care started.", "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "source" ], "title": "CareLogTimes", "type": "object" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" }, "visit_id": { "description": "The Visit linked to the day, whose times are the care log's; null when none.", "format": "uuid", "nullable": true, "type": "string" }, "voided_at": { "description": "When it was voided; null unless voided.", "format": "date-time", "nullable": true, "type": "string" }, "warnings": { "description": "The differences from the plan the care log should explain.", "items": { "properties": { "code": { "description": "What differs from the plan. times_missing: no Visit is linked and the time in or time out is empty, so the day counts 0 hours. A care_logs.* code is a finding the save just answered raised: past the weekly or daily caregiver limit, past the Work Order's planned hours, entered times off the clocked Visit by more than 30 minutes, a day the Work Order withdrew, or time out equal to time in (0 hours). None refuses the save.", "enum": [ "times_missing", "planned_unmarked", "reason_missing", "unplanned_without_reason", "care_logs.over_weekly_limit", "care_logs.over_daily_limit", "care_logs.over_plan_ceiling", "care_logs.visit_disagrees", "care_logs.day_withdrawn", "care_logs.zero_length", "care_logs.delivered_after_submit", "care_logs.imported_for_billed_day", "care_logs.typed_times_set_aside", "care_logs.future_date" ], "type": "string" }, "message": { "description": "The warning in words.", "nullable": true, "type": "string" }, "task_definition_id": { "description": "The task it is about; null for a warning about the day (times_missing).", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "code", "message" ], "title": "CareLogWarning", "type": "object" }, "type": "array" } }, "required": [ "id", "client_id", "caregiver_id", "service_date", "record_state", "tasks", "times", "warnings", "signatures" ], "title": "CareLogDetail", "type": "object" }, "CareLogPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/CareLog" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "CareLogPage", "type": "object" }, "CareLogPaperOnFile": { "properties": { "document_id": { "description": "A document already on the client's file holding the paper scan; left out, the mark carries no scan.", "format": "uuid", "nullable": true, "type": "string" } }, "title": "CareLogPaperOnFile", "type": "object" }, "CareLogSignature": { "properties": { "channel": { "description": "Where it was captured.", "nullable": true, "type": "string" }, "evidence_document_id": { "description": "The client's document holding the paper scan; null when none.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The signature.", "format": "uuid", "type": "string" }, "method": { "description": "How it was signed; paper_on_file for a paper signature the office marked as on file.", "enum": [ "drawn", "initials", "typed", "pin", "voice", "docusign_agency", "docusign_platform", "paper_on_file", "imported" ], "type": "string" }, "role": { "description": "The line signed (client, caregiver, ...).", "nullable": true, "type": "string" }, "signed_at": { "description": "When it was signed.", "format": "date-time", "type": "string" }, "signer_name": { "description": "The name the line is signed under.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "id", "role", "method", "signed_at" ], "title": "CareLogSignature", "type": "object" }, "CareLogStart": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "notes": { "description": "The day's notes.", "nullable": true, "type": "string", "x-untrusted": "text" }, "service_date": { "description": "The day.", "format": "date", "nullable": false, "type": "string" }, "service_type": { "description": "The service, as the Work Order's.", "enum": [ "personal_care", "homemaker", "legacy" ], "type": "string" }, "shift_number": { "description": "The shift, 1 to 4 (default 1).", "maximum": 4, "minimum": 1, "type": "integer" }, "time_in": { "description": "The start time, ISO 8601. Sent with time_out or notes, the start records the day: a care log already on the key with the same content is answered as it is, one with different content 409 stale.", "format": "date-time", "nullable": true, "type": "string" }, "time_out": { "description": "The end time, ISO 8601, at or after time_in.", "format": "date-time", "nullable": true, "type": "string" }, "visit_id": { "description": "The Visit to link: the agency's, of the same client, caregiver and day. Left out, the day's one such Visit is linked when exactly one exists.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "client_id", "caregiver_id", "service_date", "service_type" ], "title": "CareLogStart", "type": "object" }, "CareLogTask": { "properties": { "code": { "description": "The task's code.", "nullable": true, "type": "string" }, "count": { "description": "How many times.", "minimum": 1, "type": "integer" }, "id": { "description": "The care log's task.", "format": "uuid", "type": "string" }, "name": { "description": "The task's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "planned": { "description": "Whether a Work Order in force planned it for the day; false for one added off the plan.", "type": "boolean" }, "reason_code": { "description": "Why it was refused, not needed or added.", "enum": [ "client_declined", "client_not_home", "client_asleep_or_unwell", "done_by_someone_else", "not_needed_today", "client_requested", "care_need_changed", "other" ], "nullable": true, "type": "string" }, "reason_note": { "description": "The reason in words.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "done, refused or not_needed; null when unmarked.", "enum": [ "done", "refused", "not_needed" ], "nullable": true, "type": "string" }, "task_definition_id": { "description": "The agency's task; the {task_id} a mark is sent to (POST /care-logs/{id}/tasks/{task_id}/mark).", "format": "uuid", "type": "string" } }, "required": [ "id", "task_definition_id", "planned", "count" ], "title": "CareLogTask", "type": "object" }, "CareLogTaskAdd": { "properties": { "count": { "description": "How many times; 1 when left out.", "minimum": 1, "type": "integer" }, "reason_code": { "description": "Why it was done off the plan.", "enum": [ "client_declined", "client_not_home", "client_asleep_or_unwell", "done_by_someone_else", "not_needed_today", "client_requested", "care_need_changed", "other" ], "nullable": true, "type": "string" }, "reason_note": { "description": "The reason in words.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "Its status; done when left out.", "enum": [ "done", "refused", "not_needed" ], "type": "string" }, "task_definition_id": { "description": "The task to add: one of the agency's tasks or a system one.", "format": "uuid", "type": "string" } }, "required": [ "task_definition_id" ], "title": "CareLogTaskAdd", "type": "object" }, "CareLogTaskCounts": { "properties": { "done": { "description": "Tasks done.", "minimum": 0, "type": "integer" }, "not_needed": { "description": "Tasks not needed.", "minimum": 0, "type": "integer" }, "refused": { "description": "Tasks refused.", "minimum": 0, "type": "integer" }, "unmarked": { "description": "Tasks not marked yet.", "minimum": 0, "type": "integer" } }, "required": [ "done", "refused", "not_needed", "unmarked" ], "title": "CareLogTaskCounts", "type": "object" }, "CareLogTaskMark": { "properties": { "count": { "description": "How many times; unchanged when left out.", "minimum": 1, "type": "integer" }, "reason_code": { "description": "Why a task was refused or not needed; left out or null clears it, as a mark on the screen does.", "enum": [ "client_declined", "client_not_home", "client_asleep_or_unwell", "done_by_someone_else", "not_needed_today", "client_requested", "care_need_changed", "other" ], "nullable": true, "type": "string" }, "reason_note": { "description": "The reason in words; left out or null clears it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "The status to SET: done, refused or not_needed; null clears it. Sending the status the task already has changes nothing.", "enum": [ "done", "refused", "not_needed" ], "nullable": true, "type": "string" } }, "required": [ "status" ], "title": "CareLogTaskMark", "type": "object" }, "CareLogTimes": { "properties": { "end": { "description": "When it ended.", "format": "date-time", "nullable": true, "type": "string" }, "source": { "description": "visit: the linked Visit's billable times (adjusted, else actual, else scheduled); entered: time_in and time_out, when no Visit is linked.", "enum": [ "visit", "entered" ], "type": "string" }, "start": { "description": "When the day's care started.", "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "source" ], "title": "CareLogTimes", "type": "object" }, "CareLogUpdate": { "properties": { "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "notes": { "description": "The day's notes; null clears them.", "nullable": true, "type": "string", "x-untrusted": "text" }, "time_in": { "description": "The start time, ISO 8601; used only when no Visit is linked. null clears it.", "format": "date-time", "nullable": true, "type": "string" }, "time_out": { "description": "The end time, ISO 8601, after time_in; used only when no Visit is linked. null clears it.", "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "lock_version" ], "title": "CareLogUpdate", "type": "object" }, "CareLogWarning": { "properties": { "code": { "description": "What differs from the plan. times_missing: no Visit is linked and the time in or time out is empty, so the day counts 0 hours. A care_logs.* code is a finding the save just answered raised: past the weekly or daily caregiver limit, past the Work Order's planned hours, entered times off the clocked Visit by more than 30 minutes, a day the Work Order withdrew, or time out equal to time in (0 hours). None refuses the save.", "enum": [ "times_missing", "planned_unmarked", "reason_missing", "unplanned_without_reason", "care_logs.over_weekly_limit", "care_logs.over_daily_limit", "care_logs.over_plan_ceiling", "care_logs.visit_disagrees", "care_logs.day_withdrawn", "care_logs.zero_length", "care_logs.delivered_after_submit", "care_logs.imported_for_billed_day", "care_logs.typed_times_set_aside", "care_logs.future_date" ], "type": "string" }, "message": { "description": "The warning in words.", "nullable": true, "type": "string" }, "task_definition_id": { "description": "The task it is about; null for a warning about the day (times_missing).", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "code", "message" ], "title": "CareLogWarning", "type": "object" }, "Caregiver": { "description": "A person who delivers care for the agency.", "properties": { "address": { "nullable": true, "type": "string", "x-untrusted": "text" }, "cell_phone": { "nullable": true, "type": "string" }, "city": { "nullable": true, "type": "string", "x-untrusted": "text" }, "date_of_birth": { "description": "Usually YYYY-MM-DD. Stored as entered: a record imported from older software can hold other text.", "nullable": true, "type": "string", "x-untrusted": "date_of_birth" }, "deleted_at": { "description": "Set when the agency deleted the record. Only a list with include_deleted=true returns deleted records.", "format": "date-time", "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" }, "emergency_contact_name": { "description": "The person to call in an emergency, as the caregiver page shows it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "emergency_contact_phone": { "description": "The emergency contact's phone, 10 digits.", "nullable": true, "type": "string" }, "emergency_contact_relationship": { "description": "How the emergency contact is related to the caregiver.", "nullable": true, "type": "string", "x-untrusted": "text" }, "employee_id": { "description": "The agency's own employee number.", "nullable": true, "type": "string" }, "end_of_employment_date": { "format": "date", "nullable": true, "type": "string" }, "evv_enrolled_on": { "description": "The day this caregiver joins the agency's EVV pilot (US-121.8); null when not enrolled.", "format": "date", "nullable": true, "type": "string" }, "first_name": { "type": "string" }, "gender": { "nullable": true, "type": "string", "x-untrusted": "text" }, "hire_date": { "format": "date", "nullable": true, "type": "string" }, "home_phone": { "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the record was created.", "format": "date-time", "type": "string" }, "last_name": { "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "middle_name": { "nullable": true, "type": "string" }, "position": { "description": "The job title the agency gives the caregiver, as the agency writes it (Caregiver, PCW, Homemaker). Up to 200 characters.", "nullable": true, "type": "string", "x-untrusted": "text" }, "ssn_masked": { "description": "The SSN as the page shows it, ***-**- and its last four digits; null when none is on file. The full SSN is never returned; send ssn on a create or update to set it.", "nullable": true, "type": "string" }, "state": { "nullable": true, "type": "string" }, "status": { "enum": [ "active", "inactive", "on_leave", "terminated", "potential" ], "type": "string" }, "text_status": { "description": "Whether the agency can text this caregiver, and if not why, as the Caregivers list's Texting column shows it (US-122.26): the first that holds of no_cell_phone, opted_out (they replied STOP), no_consent, not_verified and phone_changed (open-shift texts only, and only while the agency has open shifts on), last_text_failed (the newest open-shift text failed), else can_text. Read-only: it follows the caregiver's phone, consent and opt-out.", "enum": [ "can_text", "no_cell_phone", "opted_out", "no_consent", "not_verified", "phone_changed", "last_text_failed" ], "nullable": true, "type": "string" }, "text_status_detail": { "description": "opted_out: the day they replied STOP (YYYY-MM-DD), null when none was recorded. last_text_failed: the provider's reason. Null for every other value.", "nullable": true, "type": "string", "x-untrusted": "text" }, "updated_at": { "description": "When the record last changed.", "format": "date-time", "type": "string" }, "worker_classification": { "description": "w2, a W-2 employee (the default), or 1099, an independent contractor: payroll pays a contractor no overtime and leaves them out of the ADP file. Payroll data: null for a credential without Payroll → View.", "enum": [ "w2", "1099" ], "nullable": true, "type": "string" }, "zip": { "description": "5 digits or ZIP+4, like \"80202\" or \"80202-1234\". A number sent here is read as its digits.", "nullable": true, "type": "string" } }, "required": [ "id", "first_name", "last_name", "status", "lock_version" ], "title": "Caregiver", "type": "object" }, "CaregiverAppPin": { "properties": { "new_pin": { "description": "The PIN.", "type": "string" } }, "required": [ "new_pin" ], "title": "CaregiverAppPin", "type": "object" }, "CaregiverBulkResult": { "properties": { "caregivers": { "description": "Active caregivers it covered.", "nullable": true, "type": "integer" }, "records": { "description": "Records written.", "nullable": true, "type": "integer" }, "replaced": { "description": "Existing dates it updated.", "nullable": true, "type": "integer" }, "skipped": { "description": "Records left as they were.", "nullable": true, "type": "integer" } }, "required": [ "caregivers", "records" ], "title": "CaregiverBulkResult", "type": "object" }, "CaregiverCompliance": { "description": "One caregiver's compliance: training by course, vaccinations by year, the annual evaluation and the credential dates. Never the compliance record's notes or custom items.", "properties": { "caregiver_name": { "description": "The caregiver's name.", "nullable": true, "type": "string" }, "credentials": { "additionalProperties": true, "description": "Credential dates by credential (criminal_background, dora, caps, driver_license, main_training).", "type": "object" }, "evaluation": { "properties": { "days_since_last": { "description": "Days since the last evaluation.", "nullable": true, "type": "integer" }, "last_evaluation_date": { "description": "The last evaluation.", "format": "date", "nullable": true, "type": "string" }, "status": { "description": "The annual evaluation's standing.", "nullable": true, "type": "string" } }, "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "needs_attention": { "description": "What needs attention, as the caregiver page's header counts it: each dated credential expired or expiring within 30 days, each training course expiring, expired or missing, this year's flu record when neither vaccinated nor medically declined, and the annual evaluation when expiring, overdue or never done. Empty when every paper is current.", "items": { "properties": { "item": { "description": "The credential (criminal_background, dora, caps, driver_license, main_training, or credentials when there is no compliance record), the training course, flu or evaluation.", "nullable": true, "type": "string" }, "state": { "description": "expired, expiring, missing, no_record, overdue, never_evaluated, or the flu record's status.", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "oig": { "description": "The latest OIG exclusion check, as oig_screening_status reads it.", "properties": { "checked_on": { "description": "When it was checked; null when never.", "format": "date", "nullable": true, "type": "string" }, "result": { "description": "clear, review or excluded; null when never checked.", "nullable": true, "type": "string" }, "status": { "description": "current: clear within the monthly window; overdue: the last clear check is older; missing: never checked; review: a possible match not yet compared; excluded: on the list.", "enum": [ "current", "overdue", "missing", "review", "excluded" ], "type": "string" } }, "type": "object" }, "training": { "additionalProperties": { "properties": { "expiry_date": { "description": "When it expires.", "format": "date", "nullable": true, "type": "string" }, "last_completed": { "description": "When last completed.", "format": "date", "nullable": true, "type": "string" }, "status": { "description": "The course's standing.", "nullable": true, "type": "string" } }, "type": "object" }, "description": "Training standing by course.", "type": "object" }, "vaccinations": { "items": { "properties": { "status": { "description": "Vaccinated, declined, and so on.", "nullable": true, "type": "string" }, "type": { "description": "The vaccine.", "nullable": true, "type": "string" }, "vaccination_date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "year": { "description": "The year.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" } }, "required": [ "id" ], "title": "CaregiverCompliance", "type": "object" }, "CaregiverComplianceInput": { "properties": { "caps_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "caps_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "criminal_background_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "criminal_background_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "custom": { "additionalProperties": { "type": "object" }, "description": "The agency's custom checklist items by key, each {date, expiry, completed}; the keys sent are set and the others kept.", "type": "object" }, "dora_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "dora_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "driver_license_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "lock_version": { "description": "On a change: the lock_version it was read with.", "nullable": true, "type": "integer" }, "main_training_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "main_training_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "notes": { "description": "Notes, up to 2000 characters.", "nullable": true, "type": "string" } }, "title": "CaregiverComplianceInput", "type": "object" }, "CaregiverComplianceRecord": { "properties": { "caps_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "caps_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "criminal_background_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "criminal_background_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "custom_items": { "additionalProperties": { "type": "object" }, "description": "The agency's custom checklist items by key, each {date, expiry, completed}; the keys sent are set and the others kept.", "type": "object" }, "dora_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "dora_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "driver_license_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "lock_version": { "description": "Its version; send it back to change it.", "nullable": true, "type": "integer" }, "main_training_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "main_training_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "notes": { "description": "Notes, up to 2000 characters.", "nullable": true, "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "caregiver_id", "lock_version" ], "title": "CaregiverComplianceRecord", "type": "object" }, "CaregiverEvaluation": { "description": "One evaluation of a caregiver; at most one of a type a day.", "properties": { "caregiver_id": { "description": "The caregiver evaluated.", "format": "uuid", "type": "string" }, "evaluation_date": { "description": "The day of the evaluation.", "format": "date", "nullable": true, "type": "string" }, "evaluation_type": { "description": "The kind of evaluation.", "enum": [ "annual", "probationary", "performance_improvement", "other" ], "type": "string" }, "evaluator_name": { "description": "Who evaluated.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the record was made.", "format": "date-time", "type": "string" }, "rating": { "description": "The rating.", "enum": [ "exceeds", "meets", "needs_improvement", "unsatisfactory" ], "nullable": true, "type": "string" }, "updated_at": { "description": "When the record last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "caregiver_id", "evaluation_date", "evaluation_type" ], "title": "CaregiverEvaluation", "type": "object" }, "CaregiverEvaluationInput": { "description": "An evaluation's fields. Evaluations carry no lock_version: an update locks and re-reads the row and must change something. One on the date and type of another evaluation is 422 already_recorded, with that one's id in details.evaluation_id.", "properties": { "evaluation_date": { "description": "The day of the evaluation.", "format": "date", "nullable": true, "type": "string" }, "evaluation_type": { "description": "The kind of evaluation.", "enum": [ "annual", "probationary", "performance_improvement", "other" ], "type": "string" }, "evaluator_name": { "description": "Who evaluated.", "nullable": true, "type": "string" }, "notes": { "description": "Notes. Written, never returned.", "nullable": true, "type": "string" }, "rating": { "description": "The rating.", "enum": [ "exceeds", "meets", "needs_improvement", "unsatisfactory" ], "nullable": true, "type": "string" } }, "title": "CaregiverEvaluationInput", "type": "object" }, "CaregiverEvaluationPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/CaregiverEvaluation" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "CaregiverEvaluationPage", "type": "object" }, "CaregiverFileChecklist": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "completed": { "description": "How many items are done.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "items": { "description": "The agency's active items, in its order.", "items": { "properties": { "completed": { "description": "Whether it is done.", "type": "boolean" }, "date": { "description": "Its date, as entered.", "nullable": true, "type": "string" }, "key": { "description": "The item's key.", "nullable": true, "type": "string" }, "notes": { "description": "Its notes.", "nullable": true, "type": "string" }, "text": { "description": "What it asks for.", "nullable": true, "type": "string" } }, "required": [ "key", "text", "completed" ], "title": "CaregiverFileChecklistItem", "type": "object" }, "type": "array" }, "last_reviewed_at": { "description": "When it was last reviewed.", "format": "date-time", "nullable": true, "type": "string" }, "lock_version": { "description": "Its version.", "nullable": true, "type": "integer" }, "percentage": { "description": "completed of total, in percent.", "type": "number" }, "reviewed_by_id": { "description": "Who reviewed it.", "format": "uuid", "nullable": true, "type": "string" }, "total": { "description": "How many items there are.", "nullable": true, "type": "integer" } }, "required": [ "id", "caregiver_id", "items", "lock_version" ], "title": "CaregiverFileChecklist", "type": "object" }, "CaregiverFileChecklistItem": { "properties": { "completed": { "description": "Whether it is done.", "type": "boolean" }, "date": { "description": "Its date, as entered.", "nullable": true, "type": "string" }, "key": { "description": "The item's key.", "nullable": true, "type": "string" }, "notes": { "description": "Its notes.", "nullable": true, "type": "string" }, "text": { "description": "What it asks for.", "nullable": true, "type": "string" } }, "required": [ "key", "text", "completed" ], "title": "CaregiverFileChecklistItem", "type": "object" }, "CaregiverFileChecklistItemUpdate": { "properties": { "completed": { "description": "Whether it is done.", "type": "boolean" }, "date": { "description": "Its date; blank clears it.", "nullable": true, "type": "string" }, "notes": { "description": "Its notes; blank clears them.", "nullable": true, "type": "string" } }, "title": "CaregiverFileChecklistItemUpdate", "type": "object" }, "CaregiverFileChecklistReview": { "properties": { "lock_version": { "description": "The lock_version it was read with.", "nullable": true, "type": "integer" } }, "title": "CaregiverFileChecklistReview", "type": "object" }, "CaregiverFileChecklistUpdate": { "properties": { "items": { "additionalProperties": { "properties": { "completed": { "description": "Whether it is done.", "type": "boolean" }, "date": { "description": "Its date; blank clears it.", "nullable": true, "type": "string" }, "notes": { "description": "Its notes; blank clears them.", "nullable": true, "type": "string" } }, "title": "CaregiverFileChecklistItemUpdate", "type": "object" }, "description": "Item key => {completed, date, notes}; a blank date or note clears it. Keys are get_caregiver_file_checklist's.", "type": "object" } }, "required": [ "items" ], "title": "CaregiverFileChecklistUpdate", "type": "object" }, "CaregiverInput": { "description": "Fields to set. A create needs first_name and last_name. An update sends only what changes, plus the lock_version it read (required).", "properties": { "address": { "nullable": true, "type": "string", "x-untrusted": "text" }, "cell_phone": { "nullable": true, "type": "string" }, "city": { "nullable": true, "type": "string", "x-untrusted": "text" }, "date_of_birth": { "description": "Usually YYYY-MM-DD. Stored as entered: a record imported from older software can hold other text.", "nullable": true, "type": "string", "x-untrusted": "date_of_birth" }, "email": { "nullable": true, "type": "string" }, "emergency_contact_name": { "description": "The person to call in an emergency, as the caregiver page shows it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "emergency_contact_phone": { "description": "The emergency contact's phone, 10 digits.", "nullable": true, "type": "string" }, "emergency_contact_relationship": { "description": "How the emergency contact is related to the caregiver.", "nullable": true, "type": "string", "x-untrusted": "text" }, "employee_id": { "description": "The agency's own employee number.", "nullable": true, "type": "string" }, "end_of_employment_date": { "format": "date", "nullable": true, "type": "string" }, "evv_enrolled_on": { "description": "The day this caregiver joins the agency's EVV pilot (US-121.8); null when not enrolled.", "format": "date", "nullable": true, "type": "string" }, "first_name": { "type": "string" }, "gender": { "nullable": true, "type": "string", "x-untrusted": "text" }, "hire_date": { "format": "date", "nullable": true, "type": "string" }, "home_phone": { "nullable": true, "type": "string" }, "last_name": { "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "middle_name": { "nullable": true, "type": "string" }, "position": { "description": "The job title the agency gives the caregiver, as the agency writes it (Caregiver, PCW, Homemaker). Up to 200 characters.", "nullable": true, "type": "string", "x-untrusted": "text" }, "ssn": { "description": "The full SSN, 9 digits, dashes allowed; null clears it. Answers show only ssn_masked.", "nullable": true, "type": "string" }, "state": { "nullable": true, "type": "string" }, "status": { "enum": [ "active", "inactive", "on_leave", "terminated", "potential" ], "type": "string" }, "worker_classification": { "description": "w2 or 1099. Payroll data: written only for a credential holding Payroll → Manage, and left out of the write otherwise, the rest of the body saving; a body carrying nothing else is refused 403 naming payroll.manage.", "enum": [ "w2", "1099" ], "type": "string" }, "zip": { "description": "5 digits or ZIP+4, like \"80202\" or \"80202-1234\". A number sent here is read as its digits.", "nullable": true, "type": "string" } }, "title": "CaregiverInput", "type": "object" }, "CaregiverNote": { "description": "A note in a caregiver's communication log. compliance_relevant marks one that belongs in the caregiver's compliance file. written_via names the channel that last changed its text: mcp or api, or none for the HomeCareBilling app.", "properties": { "attachment_count": { "description": "How many files are attached; the files are not returned.", "type": "integer" }, "caregiver_id": { "description": "The caregiver the note is about.", "format": "uuid", "type": "string" }, "compliance_relevant": { "description": "Whether it belongs in the compliance file.", "type": "boolean" }, "contact_type": { "description": "How the contact happened.", "enum": [ "phone", "email", "in_person", "text_message", "other" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the note was created.", "format": "date-time", "type": "string" }, "manager_initials": { "description": "The initials of who took the note (taken by).", "nullable": true, "type": "string" }, "note_date": { "description": "The day of the contact.", "format": "date", "nullable": true, "type": "string" }, "note_text": { "description": "What was said or done.", "nullable": true, "type": "string" }, "time_of_contact": { "description": "The time of the contact, HH:MM or HH:MM:SS, as typed (no time zone).", "nullable": true, "type": "string" }, "updated_at": { "description": "When the note last changed.", "format": "date-time", "type": "string" }, "written_via": { "description": "The channel that last changed the note's text (mcp, api); none for the HomeCareBilling app.", "nullable": true, "type": "string" } }, "required": [ "id", "caregiver_id", "note_date", "contact_type", "note_text" ], "title": "CaregiverNote", "type": "object" }, "CaregiverNoteInput": { "description": "Fields to set. A create needs note_date, contact_type and note_text; manager_initials defaults to the API key's user's initials. An update sends only what changes, and must change something. Notes carry no lock_version.", "properties": { "compliance_relevant": { "description": "Whether it belongs in the compliance file.", "type": "boolean" }, "contact_type": { "description": "How the contact happened.", "enum": [ "phone", "email", "in_person", "text_message", "other" ], "type": "string" }, "manager_initials": { "description": "The initials of who took the note (taken by).", "nullable": true, "type": "string" }, "note_date": { "description": "The day of the contact.", "format": "date", "nullable": false, "type": "string" }, "note_text": { "description": "What was said or done.", "nullable": false, "type": "string" }, "time_of_contact": { "description": "The time of the contact, HH:MM or HH:MM:SS, as typed (no time zone).", "nullable": true, "type": "string" } }, "title": "CaregiverNoteInput", "type": "object" }, "CaregiverNotePage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/CaregiverNote" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "CaregiverNotePage", "type": "object" }, "CaregiverPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Caregiver" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "CaregiverPage", "type": "object" }, "CaregiverPayRate": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client a work rate is for; null is the general rate.", "format": "uuid", "nullable": true, "type": "string" }, "effective_date": { "description": "When it starts.", "format": "date", "nullable": true, "type": "string" }, "end_date": { "description": "When a newer rate of its type ended it.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "rate": { "description": "Dollars an hour.", "format": "decimal", "nullable": true, "type": "string" }, "rate_type": { "enum": [ "work", "attendant", "travel" ], "type": "string" } }, "required": [ "id", "caregiver_id", "rate_type", "rate", "effective_date" ], "title": "CaregiverPayRate", "type": "object" }, "CaregiverPayRateCreate": { "properties": { "client_id": { "description": "A work rate for this one client: that client's hours are paid at it instead of the general work rate. Absent or null is the general rate.", "format": "uuid", "nullable": true, "type": "string" }, "effective_date": { "description": "When it starts, YYYY-MM-DD.", "format": "date", "type": "string" }, "rate": { "description": "Dollars an hour, e.g. 18.50.", "format": "decimal", "type": "string" }, "rate_type": { "description": "The kind of rate.", "enum": [ "work", "attendant", "travel" ], "type": "string" } }, "required": [ "rate_type", "rate", "effective_date" ], "title": "CaregiverPayRateCreate", "type": "object" }, "CaregiverPayRatePage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client a work rate is for; null is the general rate.", "format": "uuid", "nullable": true, "type": "string" }, "effective_date": { "description": "When it starts.", "format": "date", "nullable": true, "type": "string" }, "end_date": { "description": "When a newer rate of its type ended it.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "rate": { "description": "Dollars an hour.", "format": "decimal", "nullable": true, "type": "string" }, "rate_type": { "enum": [ "work", "attendant", "travel" ], "type": "string" } }, "required": [ "id", "caregiver_id", "rate_type", "rate", "effective_date" ], "title": "CaregiverPayRate", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "CaregiverPayRatePage", "type": "object" }, "CaregiverPinStatus": { "properties": { "app_pin_set": { "description": "Whether the caregiver has an app PIN.", "type": "boolean" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "telephony_pin_set": { "description": "Whether the caregiver has a telephony PIN (the PIN is never returned).", "type": "boolean" } }, "required": [ "caregiver_id" ], "title": "CaregiverPinStatus", "type": "object" }, "CaregiverRestored": { "properties": { "data": { "$ref": "#/components/schemas/Caregiver" }, "meta": { "properties": { "new_pin": { "description": "The reissued PIN, when pin_resolution is regenerated.", "nullable": true, "type": "string" }, "pin_resolution": { "description": "What happened to the PIN.", "enum": [ "noop", "regenerated", "cleared" ], "type": "string" } }, "required": [ "pin_resolution" ], "type": "object" } }, "required": [ "data", "meta" ], "title": "CaregiverRestored", "type": "object" }, "CaregiverSession": { "description": "A device token for the caregiver app. Send it as Authorization: Bearer on every /api/v1/me request. It is shown once and expires at expires_at; sign in again after that.", "properties": { "caregiver": { "$ref": "#/components/schemas/Me" }, "expires_at": { "description": "When the token stops working.", "format": "date-time", "type": "string" }, "token": { "description": "The device token. Store it in the device's secure storage.", "nullable": true, "type": "string" } }, "required": [ "token", "expires_at", "caregiver" ], "title": "CaregiverSession", "type": "object" }, "CaregiverSessionInput": { "properties": { "agency_code": { "description": "The agency's code, as on the caregiver's login card.", "nullable": true, "type": "string" }, "device_id": { "description": "A stable id the app generates once per install; the agency sees it in the caregiver's device list.", "nullable": true, "type": "string" }, "employee_id": { "description": "The caregiver's employee id at the agency.", "nullable": true, "type": "string" }, "pin": { "description": "The caregiver's PIN.", "nullable": true, "type": "string" } }, "required": [ "agency_code", "employee_id", "pin", "device_id" ], "title": "CaregiverSessionInput", "type": "object" }, "CaregiverStatusesUpdate": { "properties": { "caregiver_ids": { "description": "The caregivers to set, at most 200, from find_caregiver or the caregivers list.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "maxItems": 200, "minItems": 1, "type": "array" }, "status": { "description": "The status to set on every caregiver named.", "enum": [ "active", "inactive", "on_leave", "terminated", "potential" ], "type": "string" } }, "required": [ "caregiver_ids", "status" ], "title": "CaregiverStatusesUpdate", "type": "object" }, "CaregiverStatusesUpdateResult": { "properties": { "failed": { "description": "Not set, each with the reason in words: an id that is not this agency's caregiver (name null), an archived caregiver, or what the caregiver's card refused.", "items": { "properties": { "id": { "description": "The id as sent.", "type": "string" }, "name": { "description": "Last, First; null when no caregiver was found.", "nullable": true, "type": "string" }, "reason": { "description": "Why it was not set, in words.", "type": "string" } }, "required": [ "id", "name", "reason" ], "type": "object" }, "type": "array" }, "updated": { "description": "Caregivers that now hold the status, those that already did included (no audit row for them).", "type": "integer" } }, "required": [ "updated", "failed" ], "title": "CaregiverStatusesUpdateResult", "type": "object" }, "CaregiverTraining": { "description": "One training course for one year. A caregiver has at most one record per course a year (an \"other\" course has one slot a year).", "properties": { "caregiver_id": { "description": "The caregiver trained.", "format": "uuid", "type": "string" }, "completed": { "description": "Whether the course is completed.", "nullable": true, "type": "boolean" }, "completed_date": { "description": "When it was completed; cleared when marked not completed.", "format": "date", "nullable": true, "type": "string" }, "expiry_date": { "description": "When the training expires.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the record was made.", "format": "date-time", "type": "string" }, "training_type": { "description": "The course.", "enum": [ "basic_first_aid_home_safety", "mental_illness_behavior_mgmt", "professional_boundaries", "disaster_emergency_procedures", "infection_control_universal_precautions", "elder_abuse_neglect", "lifting_back_protection", "personal_care", "specific_personal_care_tasks", "personal_care_vs_homemaking", "homemaking_services", "change_in_client_condition", "effective_communication", "dementia_care", "skin_care", "oral_care", "hair_care", "bathing", "dressing", "toileting", "incontinence_care", "feeding", "meal_planning", "laundry", "fall_prevention", "walker_use", "general_safety", "hoarding_clients", "illness_prevention_emergency", "employee_performance_evaluation", "first_aid", "cpr", "medication_administration", "infection_control", "body_mechanics", "fire_safety", "client_rights", "hipaa", "other" ], "type": "string" }, "training_type_other": { "description": "The course's name, for an \"other\" course.", "nullable": true, "type": "string" }, "updated_at": { "description": "When the record last changed.", "format": "date-time", "type": "string" }, "year": { "description": "The training year.", "nullable": true, "type": "integer" } }, "required": [ "id", "caregiver_id", "year", "training_type" ], "title": "CaregiverTraining", "type": "object" }, "CaregiverTrainingCreate": { "description": "Records one course for one year. A course already on file for that year is 422 already_recorded, with its id in details.training_id.", "properties": { "completed": { "description": "Whether the course is completed.", "nullable": false, "type": "boolean" }, "completed_date": { "description": "When it was completed; cleared when marked not completed.", "format": "date", "nullable": true, "type": "string" }, "expiry_date": { "description": "When the training expires. On a completed course, null or an empty string sets it to a year after completed_date; a course not completed has none.", "format": "date", "nullable": true, "type": "string" }, "notes": { "description": "Notes. Written, never returned.", "nullable": true, "type": "string" }, "training_type": { "description": "The course.", "enum": [ "basic_first_aid_home_safety", "mental_illness_behavior_mgmt", "professional_boundaries", "disaster_emergency_procedures", "infection_control_universal_precautions", "elder_abuse_neglect", "lifting_back_protection", "personal_care", "specific_personal_care_tasks", "personal_care_vs_homemaking", "homemaking_services", "change_in_client_condition", "effective_communication", "dementia_care", "skin_care", "oral_care", "hair_care", "bathing", "dressing", "toileting", "incontinence_care", "feeding", "meal_planning", "laundry", "fall_prevention", "walker_use", "general_safety", "hoarding_clients", "illness_prevention_emergency", "employee_performance_evaluation", "first_aid", "cpr", "medication_administration", "infection_control", "body_mechanics", "fire_safety", "client_rights", "hipaa", "other" ], "type": "string" }, "training_type_other": { "description": "The course's name, for an \"other\" course.", "nullable": true, "type": "string" }, "year": { "description": "The training year.", "nullable": true, "type": "integer" } }, "required": [ "year", "training_type" ], "title": "CaregiverTrainingCreate", "type": "object" }, "CaregiverTrainingInput": { "description": "Fields to change. Training records carry no lock_version: the row is locked and re-read for the change, which must change something. Marking a course not completed clears its completion date.", "properties": { "completed": { "description": "Whether the course is completed.", "nullable": false, "type": "boolean" }, "completed_date": { "description": "When it was completed; cleared when marked not completed.", "format": "date", "nullable": true, "type": "string" }, "expiry_date": { "description": "When the training expires. On a completed course, null or an empty string sets it to a year after completed_date; a course not completed has none.", "format": "date", "nullable": true, "type": "string" }, "notes": { "description": "Notes. Written, never returned.", "nullable": true, "type": "string" }, "training_type_other": { "description": "The course's name, for an \"other\" course.", "nullable": true, "type": "string" } }, "title": "CaregiverTrainingInput", "type": "object" }, "CaregiverTrainingPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/CaregiverTraining" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "CaregiverTrainingPage", "type": "object" }, "CaregiverVaccination": { "description": "One vaccination for one year and type; a caregiver has at most one per type a year, and it is addressed by year and type, never by id.", "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the record was made.", "format": "date-time", "type": "string" }, "status": { "description": "Vaccinated, declined, and so on.", "enum": [ "vaccinated", "declined_medical", "declined_other", "unknown" ], "nullable": true, "type": "string" }, "updated_at": { "description": "When the record last changed.", "format": "date-time", "type": "string" }, "vaccination_date": { "description": "When; only a vaccinated record has one.", "format": "date", "nullable": true, "type": "string" }, "vaccination_type": { "description": "The vaccine.", "enum": [ "flu", "covid_19", "hepatitis_b", "tb_test", "other" ], "type": "string" }, "year": { "description": "The vaccination year.", "nullable": true, "type": "integer" } }, "required": [ "id", "caregiver_id", "year", "vaccination_type" ], "title": "CaregiverVaccination", "type": "object" }, "CaregiverVaccinationInput": { "description": "Records the vaccination for year and vaccination_type: 201 when none was recorded (status is then required), 200 when it updates the one recorded, which must change something. A status other than vaccinated clears the date unless one is sent.", "properties": { "notes": { "description": "Notes. Written, never returned.", "nullable": true, "type": "string" }, "status": { "description": "Vaccinated, declined, and so on.", "enum": [ "vaccinated", "declined_medical", "declined_other", "unknown" ], "nullable": true, "type": "string" }, "vaccination_date": { "description": "When; only a vaccinated record has one.", "format": "date", "nullable": true, "type": "string" }, "vaccination_type": { "description": "The vaccine.", "enum": [ "flu", "covid_19", "hepatitis_b", "tb_test", "other" ], "type": "string" }, "year": { "description": "The vaccination year.", "nullable": true, "type": "integer" } }, "required": [ "year", "vaccination_type" ], "title": "CaregiverVaccinationInput", "type": "object" }, "CaregiverVaccinationPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/CaregiverVaccination" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "CaregiverVaccinationPage", "type": "object" }, "CaregiverW4Sent": { "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "w4_changed_at": { "description": "null: the payroll processor has been sent the change.", "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "id", "w4_changed_at" ], "title": "CaregiverW4Sent", "type": "object" }, "CaregiverW4SentInput": { "properties": { "w4_changed_at": { "description": "The time of the change as it was read; refused with 409 stale_record when the W-4 changed again since. Not sent: the change waiting now is marked sent.", "format": "date-time", "type": "string" } }, "title": "CaregiverW4SentInput", "type": "object" }, "CaregiverWriteResult": { "properties": { "data": { "$ref": "#/components/schemas/Caregiver" }, "warnings": { "description": "What the act was done with that the agency may want to fix; usually empty. Never a refusal: the act was done.", "items": { "properties": { "fix": { "description": "Where it is fixed, when a page fixes it.", "nullable": true, "properties": { "label": { "description": "What the link says.", "type": "string" }, "path": { "description": "The app route that fixes it.", "type": "string" } }, "required": [ "path", "label" ], "type": "object" }, "id": { "description": "The rule that raised it, stable, e.g. client_care.medicaid_id_pending.", "type": "string" }, "message": { "description": "For a person to read.", "type": "string" } }, "required": [ "id", "message" ], "title": "Warning", "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "title": "CaregiverWriteResult", "type": "object" }, "CashAdvance": { "properties": { "advance_date": { "format": "date", "nullable": true, "type": "string" }, "amount": { "description": "The amount advanced.", "format": "decimal", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "caregiver_name": { "description": "\"Last, First\". In GET /cash-advances; a write's answer leaves it out.", "nullable": true, "type": "string" }, "check_number": { "description": "The check the advance was paid by.", "nullable": true, "type": "string" }, "deduct_in_month": { "description": "The 1st of the payroll month the advance is deducted in.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reason": { "description": "Why it was advanced, as typed.", "nullable": true, "type": "string", "x-untrusted": "text" }, "remaining_balance": { "description": "What is still owed.", "format": "decimal", "nullable": true, "type": "string" }, "status": { "description": "outstanding, partially_repaid, fully_repaid or written_off.", "nullable": true, "type": "string" } }, "title": "CashAdvance", "type": "object" }, "CashAdvancePage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "advance_date": { "format": "date", "nullable": true, "type": "string" }, "amount": { "description": "The amount advanced.", "format": "decimal", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "caregiver_name": { "description": "\"Last, First\". In GET /cash-advances; a write's answer leaves it out.", "nullable": true, "type": "string" }, "check_number": { "description": "The check the advance was paid by.", "nullable": true, "type": "string" }, "deduct_in_month": { "description": "The 1st of the payroll month the advance is deducted in.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reason": { "description": "Why it was advanced, as typed.", "nullable": true, "type": "string", "x-untrusted": "text" }, "remaining_balance": { "description": "What is still owed.", "format": "decimal", "nullable": true, "type": "string" }, "status": { "description": "outstanding, partially_repaid, fully_repaid or written_off.", "nullable": true, "type": "string" } }, "title": "CashAdvance", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" }, "totals": { "description": "Over every advance the filters match, not this page.", "properties": { "amount": { "description": "The amounts advanced.", "format": "decimal", "nullable": true, "type": "string" }, "remaining_balance": { "description": "What is still owed.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "required": [ "totals", "data", "limit", "offset", "total" ], "title": "CashAdvancePage", "type": "object" }, "CertificationCase": { "properties": { "applied": { "description": "Round 2: whether the case's change was made. Null in round 1.", "nullable": true, "type": "boolean" }, "blocked": { "description": "Why a send is refused now; null when it is not.", "nullable": true, "type": "string" }, "id": { "description": "The case's id, as POST /settings/sandata/certification/cases/{id} takes it.", "nullable": true, "type": "string" }, "records": { "description": "How many records it sends.", "type": "integer" }, "round": { "description": "1: the sample records as created. 2: changes to records Sandata accepted.", "type": "integer" }, "scenario": { "description": "The Sandata scenario it covers.", "nullable": true, "type": "string" }, "state": { "additionalProperties": { "type": "integer" }, "description": "Of those records, how many Sandata holds as they are now (accepted), are waiting for Sandata's answer (waiting), were refused as they are now and go again on a send (refused), were refused too often to go again until they change (parked), cannot be sent as they are (held_back), and are left to send (to_send); each record is in exactly one. Null while Sandata is paused or not set up.", "nullable": true, "type": "object" }, "title": { "description": "What the page calls it.", "nullable": true, "type": "string" } }, "required": [ "id", "round", "title", "scenario", "records" ], "title": "CertificationCase", "type": "object" }, "CertificationCaseRefusal": { "description": "POST /settings/sandata/certification/send only: present when this case was refused while the other went; it changed nothing.", "properties": { "code": { "description": "The refusal's code, as an error carries it.", "nullable": true, "type": "string" }, "message": { "description": "Why the case was not sent.", "nullable": true, "type": "string" } }, "required": [ "code", "message" ], "title": "CertificationCaseRefusal", "type": "object" }, "CertificationCaseResult": { "properties": { "case": { "description": "The case's id.", "nullable": true, "type": "string" }, "dry_run": { "description": "True: written to the server log, nothing sent to Sandata and nothing changed.", "type": "boolean" }, "records": { "description": "How many records the case holds.", "type": "integer" }, "refused": { "description": "POST /settings/sandata/certification/send only: present when this case was refused while the other went; it changed nothing.", "properties": { "code": { "description": "The refusal's code, as an error carries it.", "nullable": true, "type": "string" }, "message": { "description": "Why the case was not sent.", "nullable": true, "type": "string" } }, "required": [ "code", "message" ], "title": "CertificationCaseRefusal", "type": "object" }, "sending": { "description": "Live: how many of them were queued, those Sandata does not hold as they are now, a record it refused included until it is parked. Dry run: how many were written to the server log.", "type": "integer" } }, "required": [ "case", "records", "sending", "dry_run" ], "title": "CertificationCaseResult", "type": "object" }, "CertificationDomainReport": { "properties": { "errors": { "description": "One per failed record.", "items": { "properties": { "error": { "description": "What the mapper refused.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "description": "The sample record's name.", "nullable": true, "type": "string" } }, "required": [ "name", "id", "error" ], "title": "CertificationRecordError", "type": "object" }, "type": "array" }, "failed": { "description": "Those that did not.", "type": "integer" }, "passed": { "description": "Those that mapped cleanly.", "type": "integer" }, "total": { "description": "Sample records checked.", "type": "integer" } }, "required": [ "total", "passed", "failed", "errors" ], "title": "CertificationDomainReport", "type": "object" }, "CertificationDryRunUpdate": { "properties": { "dry_run": { "description": "True writes what would be sent to the server log and sends nothing; false sends to Sandata.", "type": "boolean" } }, "required": [ "dry_run" ], "title": "CertificationDryRunUpdate", "type": "object" }, "CertificationParty": { "properties": { "batch": { "description": "Its latest batch's status; null when never sent.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "kind": { "description": "Client or employee.", "enum": [ "client", "employee" ], "type": "string" }, "name": { "description": "Its name.", "nullable": true, "type": "string" }, "state": { "description": "Where it stands with Sandata.", "enum": [ "accepted", "refused", "waiting", "unanswered", "not_sent" ], "type": "string" } }, "required": [ "kind", "id", "name", "state" ], "title": "CertificationParty", "type": "object" }, "CertificationRecordError": { "properties": { "error": { "description": "What the mapper refused.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "description": "The sample record's name.", "nullable": true, "type": "string" } }, "required": [ "name", "id", "error" ], "title": "CertificationRecordError", "type": "object" }, "CertificationReport": { "properties": { "clients": { "properties": { "errors": { "description": "One per failed record.", "items": { "properties": { "error": { "description": "What the mapper refused.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "description": "The sample record's name.", "nullable": true, "type": "string" } }, "required": [ "name", "id", "error" ], "title": "CertificationRecordError", "type": "object" }, "type": "array" }, "failed": { "description": "Those that did not.", "type": "integer" }, "passed": { "description": "Those that mapped cleanly.", "type": "integer" }, "total": { "description": "Sample records checked.", "type": "integer" } }, "required": [ "total", "passed", "failed", "errors" ], "title": "CertificationDomainReport", "type": "object" }, "credential_error": { "description": "Set when the Sandata settings are incomplete; null otherwise.", "nullable": true, "type": "string" }, "employees": { "properties": { "errors": { "description": "One per failed record.", "items": { "properties": { "error": { "description": "What the mapper refused.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "description": "The sample record's name.", "nullable": true, "type": "string" } }, "required": [ "name", "id", "error" ], "title": "CertificationRecordError", "type": "object" }, "type": "array" }, "failed": { "description": "Those that did not.", "type": "integer" }, "passed": { "description": "Those that mapped cleanly.", "type": "integer" }, "total": { "description": "Sample records checked.", "type": "integer" } }, "required": [ "total", "passed", "failed", "errors" ], "title": "CertificationDomainReport", "type": "object" }, "overall_pass": { "description": "Every sample record mapped cleanly.", "type": "boolean" }, "visits": { "properties": { "errors": { "description": "One per failed record.", "items": { "properties": { "error": { "description": "What the mapper refused.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "description": "The sample record's name.", "nullable": true, "type": "string" } }, "required": [ "name", "id", "error" ], "title": "CertificationRecordError", "type": "object" }, "type": "array" }, "failed": { "description": "Those that did not.", "type": "integer" }, "passed": { "description": "Those that mapped cleanly.", "type": "integer" }, "total": { "description": "Sample records checked.", "type": "integer" } }, "required": [ "total", "passed", "failed", "errors" ], "title": "CertificationDomainReport", "type": "object" } }, "required": [ "clients", "employees", "visits", "overall_pass" ], "title": "CertificationReport", "type": "object" }, "CertificationStep": { "properties": { "category": { "description": "Its section on the page.", "nullable": true, "type": "string" }, "completed": { "description": "Whether it is done.", "type": "boolean" }, "date": { "description": "The day it was marked done; null when not done.", "format": "date", "nullable": true, "type": "string" }, "key": { "description": "The step's key.", "nullable": true, "type": "string" }, "notes": { "description": "Its notes; null when none.", "nullable": true, "type": "string" }, "text": { "description": "What the page calls it.", "nullable": true, "type": "string" } }, "required": [ "key", "text", "category", "completed" ], "title": "CertificationStep", "type": "object" }, "CertificationStepUpdate": { "properties": { "completed": { "description": "Done or not done.", "type": "boolean" }, "notes": { "description": "The notes; null or blank empties them.", "nullable": true, "type": "string" } }, "title": "CertificationStepUpdate", "type": "object" }, "CfcImportJob": { "properties": { "client_id": { "description": "The client whose calculator it reads.", "format": "uuid", "type": "string" }, "completed_at": { "format": "date-time", "nullable": true, "type": "string" }, "error": { "description": "A failed job's reason: unreadable_calculator, paper_capture_consent_required (a scan, and the agency has not accepted Paper forms; not retried), import_refused, not_found, audit_log_failed, extraction_unavailable (the extraction service did not answer through every retry), internal_error, abandoned (stuck past its bound).", "nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "filename": { "description": "The file's name as sent.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was started.", "format": "date-time", "type": "string" }, "mode": { "enum": [ "preview", "import" ], "type": "string" }, "plans": { "description": "A succeeded import's new Plans of Care, with their tasks.", "items": { "$ref": "#/components/schemas/PlanOfCare" }, "nullable": true, "type": "array" }, "rows": { "description": "A succeeded preview's tasks and their per-day minutes.", "items": { "$ref": "#/components/schemas/CfcPreviewRow" }, "nullable": true, "type": "array" }, "status": { "enum": [ "queued", "running", "succeeded", "failed" ], "type": "string" }, "warnings": { "description": "Unmatched tasks, a Medicaid ID other than the client's; they never block.", "items": { "type": "string" }, "nullable": true, "type": "array" } }, "required": [ "id", "client_id", "mode", "status" ], "title": "CfcImportJob", "type": "object" }, "CfcNewClient": { "properties": { "client_id": { "description": "created: the new client; existing: the client already on file the calculator is imported for; conflict: the client on file holding the card's Medicaid ID.", "format": "uuid", "type": "string" }, "import": { "allOf": [ { "$ref": "#/components/schemas/CfcImportJob" } ], "description": "The import job for the client; null for a conflict, which writes nothing.", "nullable": true }, "message": { "description": "What happened, in the words the import page uses; null for a new client.", "nullable": true, "type": "string" }, "outcome": { "enum": [ "created", "existing", "conflict" ], "type": "string" }, "warnings": { "description": "What a created client was saved despite, as POST /api/v1/clients answers it: medicaid_id_pending on field medicaid_id (the card had no Medicaid ID, so the client cannot be billed until one is added); client_care.active_without_start_date on field service_start_date (the client is active with no service start date). Empty for an existing client or a conflict.", "items": { "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "outcome", "client_id", "import", "message" ], "title": "CfcNewClient", "type": "object" }, "CfcPreviewRow": { "properties": { "category": { "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "matched": { "description": "Whether the task matched one the agency knows; an unmatched one needs mapping.", "type": "boolean" }, "minutes_per_task": { "description": "Minutes each time.", "format": "decimal", "nullable": true, "type": "string" }, "over_cap": { "description": "True when the task cannot be placed within the client's days.", "type": "boolean" }, "per_day": { "description": "Minutes on each day, sun to sat; null when over_cap.", "nullable": true, "properties": { "fri": { "type": "integer" }, "mon": { "type": "integer" }, "sat": { "type": "integer" }, "sun": { "type": "integer" }, "thu": { "type": "integer" }, "tue": { "type": "integer" }, "wed": { "type": "integer" } }, "type": "object" }, "task_name": { "description": "The task, as the calculator names it.", "nullable": true, "type": "string" }, "times_per_week": { "description": "Times a week.", "nullable": true, "type": "integer" } }, "required": [ "category", "task_name", "over_cap" ], "title": "CfcPreviewRow", "type": "object" }, "CfcProgram": { "properties": { "active": { "description": "Whether the agency offers it.", "type": "boolean" }, "category": { "description": "The category.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" }, "position": { "description": "Its place.", "type": "integer" }, "tasks": { "description": "Its tasks, in order.", "items": { "properties": { "active": { "description": "Whether it is offered.", "type": "boolean" }, "category": { "description": "Its category.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "minutes_per_task": { "description": "Minutes each time.", "format": "decimal", "nullable": true, "type": "string" }, "position": { "description": "Its place in the category.", "type": "integer" }, "task_name": { "description": "The task.", "nullable": true, "type": "string" }, "times_per_week": { "description": "Times a week.", "type": "integer" } }, "required": [ "id", "category", "task_name", "active" ], "title": "CfcTask", "type": "object" }, "type": "array" } }, "required": [ "category", "active", "tasks" ], "title": "CfcProgram", "type": "object" }, "CfcProgramActive": { "properties": { "active": { "description": "Whether it is offered.", "type": "boolean" }, "category": { "description": "The category.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" } }, "required": [ "category", "active" ], "title": "CfcProgramActive", "type": "object" }, "CfcProgramUpdate": { "properties": { "active": { "description": "Whether the agency offers it.", "type": "boolean" } }, "required": [ "active" ], "title": "CfcProgramUpdate", "type": "object" }, "CfcPrograms": { "items": { "properties": { "active": { "description": "Whether the agency offers it.", "type": "boolean" }, "category": { "description": "The category.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" }, "position": { "description": "Its place.", "type": "integer" }, "tasks": { "description": "Its tasks, in order.", "items": { "properties": { "active": { "description": "Whether it is offered.", "type": "boolean" }, "category": { "description": "Its category.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "minutes_per_task": { "description": "Minutes each time.", "format": "decimal", "nullable": true, "type": "string" }, "position": { "description": "Its place in the category.", "type": "integer" }, "task_name": { "description": "The task.", "nullable": true, "type": "string" }, "times_per_week": { "description": "Times a week.", "type": "integer" } }, "required": [ "id", "category", "task_name", "active" ], "title": "CfcTask", "type": "object" }, "type": "array" } }, "required": [ "category", "active", "tasks" ], "title": "CfcProgram", "type": "object" }, "title": "CfcPrograms", "type": "array" }, "CfcTask": { "properties": { "active": { "description": "Whether it is offered.", "type": "boolean" }, "category": { "description": "Its category.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "minutes_per_task": { "description": "Minutes each time.", "format": "decimal", "nullable": true, "type": "string" }, "position": { "description": "Its place in the category.", "type": "integer" }, "task_name": { "description": "The task.", "nullable": true, "type": "string" }, "times_per_week": { "description": "Times a week.", "type": "integer" } }, "required": [ "id", "category", "task_name", "active" ], "title": "CfcTask", "type": "object" }, "CfcTaskCreate": { "properties": { "minutes_per_task": { "description": "Minutes each time.", "format": "decimal", "nullable": false, "type": "string" }, "task_name": { "description": "The task.", "maxLength": 200, "type": "string" }, "times_per_week": { "description": "Times a week.", "type": "integer" } }, "required": [ "task_name", "minutes_per_task", "times_per_week" ], "title": "CfcTaskCreate", "type": "object" }, "CfcTaskUpdate": { "properties": { "minutes_per_task": { "description": "Minutes each time.", "format": "decimal", "nullable": false, "type": "string" }, "task_name": { "description": "The task.", "maxLength": 200, "type": "string" }, "times_per_week": { "description": "Times a week.", "type": "integer" } }, "title": "CfcTaskUpdate", "type": "object" }, "CfcTasksMoved": { "items": { "properties": { "active": { "description": "Whether it is offered.", "type": "boolean" }, "category": { "description": "Its category.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "minutes_per_task": { "description": "Minutes each time.", "format": "decimal", "nullable": true, "type": "string" }, "position": { "description": "Its place in the category.", "type": "integer" }, "task_name": { "description": "The task.", "nullable": true, "type": "string" }, "times_per_week": { "description": "Times a week.", "type": "integer" } }, "required": [ "id", "category", "task_name", "active" ], "title": "CfcTask", "type": "object" }, "title": "CfcTasksMoved", "type": "array" }, "ChecklistItem": { "properties": { "active": { "description": "Whether it is shown.", "type": "boolean" }, "checklist": { "description": "Which checklist.", "enum": [ "employee_file", "compliance" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_key": { "description": "The key caregivers' records are kept under; never changes.", "nullable": true, "type": "string" }, "item_type": { "description": "How it is kept.", "enum": [ "checkbox", "date_expiry", "attestation_link" ], "type": "string" }, "label": { "description": "What the item is called.", "nullable": true, "type": "string" }, "position": { "description": "Its place in the checklist.", "type": "integer" } }, "required": [ "id", "checklist", "item_key", "label", "active" ], "title": "ChecklistItem", "type": "object" }, "ChecklistItemCreate": { "properties": { "item_type": { "description": "Compliance only.", "enum": [ "checkbox", "date_expiry" ], "type": "string" }, "label": { "description": "What the item is called.", "type": "string" } }, "required": [ "label" ], "title": "ChecklistItemCreate", "type": "object" }, "ChecklistItemRename": { "properties": { "label": { "description": "The new label.", "type": "string" } }, "required": [ "label" ], "title": "ChecklistItemRename", "type": "object" }, "ChecklistItems": { "items": { "properties": { "active": { "description": "Whether it is shown.", "type": "boolean" }, "checklist": { "description": "Which checklist.", "enum": [ "employee_file", "compliance" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_key": { "description": "The key caregivers' records are kept under; never changes.", "nullable": true, "type": "string" }, "item_type": { "description": "How it is kept.", "enum": [ "checkbox", "date_expiry", "attestation_link" ], "type": "string" }, "label": { "description": "What the item is called.", "nullable": true, "type": "string" }, "position": { "description": "Its place in the checklist.", "type": "integer" } }, "required": [ "id", "checklist", "item_key", "label", "active" ], "title": "ChecklistItem", "type": "object" }, "title": "ChecklistItems", "type": "array" }, "ChecklistItemsMoved": { "items": { "properties": { "active": { "description": "Whether it is shown.", "type": "boolean" }, "checklist": { "description": "Which checklist.", "enum": [ "employee_file", "compliance" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_key": { "description": "The key caregivers' records are kept under; never changes.", "nullable": true, "type": "string" }, "item_type": { "description": "How it is kept.", "enum": [ "checkbox", "date_expiry", "attestation_link" ], "type": "string" }, "label": { "description": "What the item is called.", "nullable": true, "type": "string" }, "position": { "description": "Its place in the checklist.", "type": "integer" } }, "required": [ "id", "checklist", "item_key", "label", "active" ], "title": "ChecklistItem", "type": "object" }, "title": "ChecklistItemsMoved", "type": "array" }, "Claim": { "description": "One billed service line, from a batch.", "properties": { "adjustment_reason_codes": { "description": "Claim adjustment reason codes.", "items": { "type": "string" }, "type": "array" }, "batch_id": { "description": "The batch the claim belongs to.", "format": "uuid", "type": "string" }, "charge_amount": { "description": "Amount billed.", "format": "decimal", "nullable": true, "type": "string" }, "claim_frequency": { "description": "CLM05-3: 1 bills a new claim, 7 replaces a paid claim, 8 voids one.", "enum": [ "1", "7", "8" ], "type": "string" }, "diagnosis_code_1": { "nullable": true, "type": "string" }, "diagnosis_code_2": { "nullable": true, "type": "string" }, "diagnosis_code_3": { "nullable": true, "type": "string" }, "diagnosis_code_4": { "nullable": true, "type": "string" }, "duplicate_of_claim_id": { "format": "uuid", "nullable": true, "type": "string" }, "evv_validation_status": { "enum": [ "passed", "warning", "exempt", "overridden" ], "nullable": true, "type": "string" }, "icn": { "description": "HCPF's internal control number.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "investigation_status": { "description": "Where the agency's investigation of a denial stands.", "enum": [ "unresolved", "investigating", "corrected", "resubmitted", "written_off" ], "type": "string" }, "member_id": { "description": "The Medicaid member id.", "nullable": true, "type": "string" }, "modifier_1": { "nullable": true, "type": "string" }, "modifier_2": { "nullable": true, "type": "string" }, "modifier_3": { "nullable": true, "type": "string" }, "modifier_4": { "nullable": true, "type": "string" }, "original_icn": { "description": "The ICN of the paid claim an uploaded replace (7) or void (8) row named.", "nullable": true, "type": "string" }, "paid_amount": { "description": "Amount paid.", "format": "decimal", "nullable": true, "type": "string" }, "paid_date": { "format": "date", "nullable": true, "type": "string" }, "par_number": { "description": "The prior authorization request number.", "nullable": true, "type": "string" }, "patient_account_number": { "nullable": true, "type": "string" }, "patient_first_name": { "nullable": true, "type": "string" }, "patient_last_name": { "nullable": true, "type": "string" }, "payment_status_code": { "nullable": true, "type": "string" }, "place_of_service": { "nullable": true, "type": "string" }, "procedure_code": { "description": "The HCPCS code billed.", "nullable": true, "type": "string" }, "reconciled_at": { "description": "When it was marked reconciled with its payment, if it was.", "format": "date-time", "type": "string" }, "remark_codes": { "description": "Remittance remark codes.", "items": { "type": "object" }, "type": "array" }, "replaced_account_number": { "description": "The account number the uploaded file gave this claim, when another row or a claim in progress or paid already used it and it was not kept; patient_account_number is the claim's own.", "nullable": true, "type": "string" }, "resolution_notes": { "description": "The agency's notes on resolving a denial.", "nullable": true, "type": "string", "x-untrusted": "text" }, "row_number": { "description": "Its row in the uploaded file.", "nullable": true, "type": "integer" }, "service_date_from": { "format": "date", "nullable": true, "type": "string" }, "service_date_to": { "format": "date", "nullable": true, "type": "string" }, "status": { "enum": [ "pending", "validated", "invalid", "submitted", "accepted", "not_accepted", "rejected", "paid" ], "type": "string" }, "unit_type": { "nullable": true, "type": "string" }, "units": { "description": "Units billed.", "format": "decimal", "nullable": true, "type": "string" }, "updated_at": { "description": "When the record last changed.", "format": "date-time", "type": "string" }, "validation_errors": { "description": "Why the claim is invalid, if it is.", "items": { "properties": { "code": { "description": "Stable, e.g. required or invalid_format.", "type": "string" }, "field": { "description": "The claim field.", "type": "string" }, "message": { "description": "For a person to read.", "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "id", "batch_id", "status" ], "title": "Claim", "type": "object" }, "ClaimEvvCorrection": { "description": "A claim's units set to its verified EVV visits' units, and the figures before.", "nullable": true, "properties": { "applied_at": { "format": "date-time", "type": "string" }, "applied_by_id": { "description": "The record's id.", "format": "uuid", "nullable": true, "type": "string" }, "batch_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "claim_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "evv_units": { "description": "Units the verified EVV visits add up to.", "nullable": true, "type": "integer" }, "from_charge": { "description": "Charge before.", "format": "decimal", "nullable": true, "type": "string" }, "from_units": { "description": "Units the claim billed before.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "to_charge": { "description": "Charge after, at the claim's own price per unit.", "format": "decimal", "nullable": true, "type": "string" }, "to_units": { "description": "Units it bills after: the EVV units.", "format": "decimal", "nullable": true, "type": "string" }, "undone_at": { "format": "date-time", "nullable": true, "type": "string" }, "undone_by_id": { "description": "The record's id.", "format": "uuid", "nullable": true, "type": "string" }, "visit_ids": { "description": "The visits counted.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "type": "array" } }, "title": "ClaimEvvCorrection", "type": "object" }, "ClaimEvvCorrectionProposal": { "properties": { "billed_units": { "description": "Units the claim bills now.", "format": "decimal", "nullable": true, "type": "string" }, "claim_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "correction": { "description": "A claim's units set to its verified EVV visits' units, and the figures before.", "nullable": true, "properties": { "applied_at": { "format": "date-time", "type": "string" }, "applied_by_id": { "description": "The record's id.", "format": "uuid", "nullable": true, "type": "string" }, "batch_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "claim_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "evv_units": { "description": "Units the verified EVV visits add up to.", "nullable": true, "type": "integer" }, "from_charge": { "description": "Charge before.", "format": "decimal", "nullable": true, "type": "string" }, "from_units": { "description": "Units the claim billed before.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "to_charge": { "description": "Charge after, at the claim's own price per unit.", "format": "decimal", "nullable": true, "type": "string" }, "to_units": { "description": "Units it bills after: the EVV units.", "format": "decimal", "nullable": true, "type": "string" }, "undone_at": { "format": "date-time", "nullable": true, "type": "string" }, "undone_by_id": { "description": "The record's id.", "format": "uuid", "nullable": true, "type": "string" }, "visit_ids": { "description": "The visits counted.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "type": "array" } }, "title": "ClaimEvvCorrection", "type": "object" }, "current_charge": { "description": "The claim's charge now.", "format": "decimal", "nullable": true, "type": "string" }, "evv_units": { "description": "Units its verified EVV visits add up to; null when it is not compared.", "nullable": true, "type": "integer" }, "proposed_charge": { "description": "The charge at evv_units, at the claim's own price per unit, rounded to cents; null when it has no charge or bills 0 units, and then applying leaves the charge as it is.", "format": "decimal", "nullable": true, "type": "string" }, "refusal": { "description": "Null when applying now would succeed; otherwise what it would answer: code and message.", "nullable": true, "properties": { "code": { "nullable": true, "type": "string" }, "message": { "nullable": true, "type": "string" } }, "type": "object" }, "visit_ids": { "description": "The visits counted.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "type": "array" } }, "required": [ "claim_id", "billed_units", "visit_ids", "refusal", "correction" ], "title": "ClaimEvvCorrectionProposal", "type": "object" }, "ClaimPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Claim" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClaimPage", "type": "object" }, "Client": { "description": "A person the agency serves.", "properties": { "acp_address_line1": { "description": "The ACP substitute street address; with no substitute, Sandata gets no address.", "nullable": true, "type": "string", "x-untrusted": "text" }, "acp_city": { "description": "The ACP substitute address's city.", "nullable": true, "type": "string", "x-untrusted": "text" }, "acp_phone": { "description": "The ACP substitute phone.", "nullable": true, "type": "string" }, "acp_protected": { "description": "In Colorado's Address Confidentiality Program: the real address, phones and every call location are withheld from Sandata, and the acp_ substitute below goes instead. Set with POST /api/v1/clients/{id}/acp-protection.", "type": "boolean" }, "acp_state": { "description": "The ACP substitute address's state.", "nullable": true, "type": "string" }, "acp_zip": { "description": "The ACP substitute address's zip.", "nullable": true, "type": "string" }, "address": { "nullable": true, "type": "string", "x-untrusted": "text" }, "address_line_2": { "description": "Apartment, suite or unit; sent to Sandata as ClientAddressLine2.", "nullable": true, "type": "string", "x-untrusted": "text" }, "agency_services_only": { "description": "The client has no outside providers (Access's MHS ONLY). Set with POST /api/v1/clients/{id}/agency-services-only.", "type": "boolean" }, "city": { "nullable": true, "type": "string", "x-untrusted": "text" }, "client_type": { "enum": [ "medicaid", "private_insurance", "ihss" ], "type": "string" }, "county": { "description": "A Colorado county name; sent to Sandata as ClientCounty.", "nullable": true, "type": "string", "x-untrusted": "text" }, "date_of_birth": { "description": "Usually YYYY-MM-DD. Stored as entered: a record imported from older software can hold other text.", "nullable": true, "type": "string", "x-untrusted": "date_of_birth" }, "deleted_at": { "description": "Set when the agency deleted the record. Only a list with include_deleted=true returns deleted records.", "format": "date-time", "nullable": true, "type": "string" }, "eligibility_end_date": { "format": "date", "nullable": true, "type": "string" }, "eligibility_start_date": { "format": "date", "nullable": true, "type": "string" }, "eligibility_verified_at": { "description": "When the agency last marked the client's Medicaid eligibility verified.", "format": "date-time", "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" }, "emergency_contact_name": { "deprecated": true, "description": "Deprecated: use /api/v1/clients/{id}/relations. Served until 2027-05-31. The client's emergency contact 1, as the client page's People section shows it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "emergency_contact_phone": { "deprecated": true, "description": "Deprecated: use /api/v1/clients/{id}/relations. Served until 2027-05-31. Emergency contact 1's phone, 10 digits.", "nullable": true, "type": "string" }, "first_name": { "type": "string" }, "gender": { "nullable": true, "type": "string", "x-untrusted": "text" }, "home_phone": { "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "ihss_client": { "description": "An IHSS client (Access's IHSSClient box), whatever client_type says; the PAR panel then shows the IHSS column. A client typed ihss is always one.", "type": "boolean" }, "ihss_code": { "description": "The IHSS billing code and modifiers off the client's IHSS PAR, as the agency writes them (US-102.17).", "nullable": true, "type": "string", "x-untrusted": "text" }, "ihss_par_weeks": { "description": "The weeks the client's IHSS PAR runs.", "format": "decimal", "nullable": true, "type": "string" }, "ihss_units_on_par": { "description": "The units the client's IHSS PAR authorizes; the PAR panel shows them as hours a week, units / 4 / weeks.", "nullable": true, "type": "integer" }, "inserted_at": { "description": "When the record was created.", "format": "date-time", "type": "string" }, "intake_missing": { "description": "The intake forms the client page warns are not signed yet (US-101.42): the agency disclosure notice, the client rights acknowledgement and the emergency information, each counted once a record of it is signed or amended. Empty when the page shows no warning: services started one business day ago or less, before the warning's start date, or not at all; nothing missing; or the warning dismissed with nothing missing since. Dismiss it with POST /api/v1/clients/{id}/intake-warning-dismissals. It never blocks anything.", "items": { "enum": [ "agency_disclosure_notice", "client_rights_acknowledgement", "emergency_information" ], "type": "string" }, "type": "array" }, "language_preference": { "nullable": true, "type": "string", "x-untrusted": "text" }, "last_name": { "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "medicaid_id": { "description": "The Colorado Medicaid id.", "nullable": true, "type": "string" }, "middle_name": { "nullable": true, "type": "string" }, "mobile_phone": { "nullable": true, "type": "string" }, "payer_program": { "description": "The program that pays for the client's care.", "nullable": true, "type": "string", "x-untrusted": "text" }, "planned_supervisory_day": { "description": "The day all four quarters' slots share; null when the quarters differ or no day is chosen. Each quarter's own day is planned_supervisory_qN_day. Set with POST /api/v1/clients/{id}/supervisory-plan.", "nullable": true, "type": "integer" }, "planned_supervisory_offset": { "description": "The month of the quarter (1, 2 or 3) all four quarters' slots share; null when the quarters differ or none is planned. Each quarter's own slot is planned_supervisory_qN_offset (#2606). Set with POST /api/v1/clients/{id}/supervisory-plan.", "nullable": true, "type": "integer" }, "planned_supervisory_q1_day": { "description": "Quarter 1's planned supervisory day of that month; null when no day is chosen.", "nullable": true, "type": "integer" }, "planned_supervisory_q1_offset": { "description": "Quarter 1's planned supervisory month, the month of that quarter (1, 2 or 3); null when quarter 1 is unplanned.", "nullable": true, "type": "integer" }, "planned_supervisory_q2_day": { "description": "Quarter 2's planned supervisory day of that month; null when no day is chosen.", "nullable": true, "type": "integer" }, "planned_supervisory_q2_offset": { "description": "Quarter 2's planned supervisory month, the month of that quarter (1, 2 or 3); null when quarter 2 is unplanned.", "nullable": true, "type": "integer" }, "planned_supervisory_q3_day": { "description": "Quarter 3's planned supervisory day of that month; null when no day is chosen.", "nullable": true, "type": "integer" }, "planned_supervisory_q3_offset": { "description": "Quarter 3's planned supervisory month, the month of that quarter (1, 2 or 3); null when quarter 3 is unplanned.", "nullable": true, "type": "integer" }, "planned_supervisory_q4_day": { "description": "Quarter 4's planned supervisory day of that month; null when no day is chosen.", "nullable": true, "type": "integer" }, "planned_supervisory_q4_offset": { "description": "Quarter 4's planned supervisory month, the month of that quarter (1, 2 or 3); null when quarter 4 is unplanned.", "nullable": true, "type": "integer" }, "private_insurance_client": { "description": "The client has private insurance (Access's Private box), whatever client_type says. A client typed private_insurance always has.", "type": "boolean" }, "service_end_date": { "format": "date", "nullable": true, "type": "string" }, "service_start_date": { "format": "date", "nullable": true, "type": "string" }, "ssn_masked": { "description": "The SSN as the page shows it, ***-**- and its last four digits; null when none is on file. The full SSN is never returned; send ssn on a create or update to set it.", "nullable": true, "type": "string" }, "state": { "nullable": true, "type": "string" }, "status": { "enum": [ "active", "inactive", "potential", "discharged" ], "type": "string" }, "temporary": { "description": "A short-term client, whatever pays for them; the app's active client list hides them by default.", "type": "boolean" }, "updated_at": { "description": "When the record last changed.", "format": "date-time", "type": "string" }, "zip": { "description": "5 digits or ZIP+4, like \"80202\" or \"80202-1234\". A number sent here is read as its digits.", "nullable": true, "type": "string" } }, "required": [ "id", "first_name", "last_name", "status", "client_type", "lock_version" ], "title": "Client", "type": "object" }, "ClientAcpProtection": { "properties": { "acp_address_line1": { "description": "The ACP substitute street address, sent in place of the real one.", "nullable": true, "type": "string" }, "acp_city": { "description": "The ACP substitute address's city.", "nullable": true, "type": "string" }, "acp_phone": { "description": "The ACP substitute phone, sent in place of the client's phones.", "nullable": true, "type": "string" }, "acp_state": { "description": "The ACP substitute address's state, two letters.", "nullable": true, "type": "string" }, "acp_zip": { "description": "The ACP substitute address's zip, 5 or 9 digits.", "nullable": true, "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "protected": { "description": "true: the client is in Colorado's Address Confidentiality Program (PM 20-007): its real address, phones and every call location are withheld from Sandata, and the ACP substitute address and phone given here go in their place. false removes the mark and clears the substitute.", "type": "boolean" }, "reason": { "description": "Required with protected false: why the mark is removed, at least 10 characters.", "nullable": true, "type": "string" } }, "required": [ "protected", "lock_version" ], "title": "ClientAcpProtection", "type": "object" }, "ClientAgencyServicesOnly": { "properties": { "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "value": { "description": "true: the client has no outside providers (Access's MHS ONLY). false clears it.", "type": "boolean" } }, "required": [ "value", "lock_version" ], "title": "ClientAgencyServicesOnly", "type": "object" }, "ClientCalendarEvent": { "properties": { "client_id": { "description": "The client it is about.", "format": "uuid", "type": "string" }, "completed_at": { "description": "When it was done.", "format": "date-time", "nullable": true, "type": "string" }, "description": { "description": "More about it.", "nullable": true, "type": "string" }, "due_date": { "description": "The day it is due.", "format": "date", "nullable": true, "type": "string" }, "due_time": { "description": "A time of day, HH:MM:SS (Mountain time).", "nullable": true, "type": "string" }, "event_type": { "enum": [ "supervisory_visit", "recertification", "follow_up", "custom" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "lock_version": { "description": "Its version.", "nullable": true, "type": "integer" }, "status": { "enum": [ "upcoming", "overdue", "completed", "dismissed" ], "type": "string" }, "title": { "description": "What is due.", "nullable": true, "type": "string" } }, "required": [ "id", "client_id", "event_type", "title", "due_date", "status", "lock_version" ], "title": "ClientCalendarEvent", "type": "object" }, "ClientCalendarEventCreate": { "properties": { "description": { "description": "More about it, up to 5000 characters.", "nullable": true, "type": "string" }, "due_date": { "description": "The day it is due, YYYY-MM-DD.", "format": "date", "type": "string" }, "due_time": { "description": "The time it is due, HH:MM:SS, Mountain time.", "nullable": true, "type": "string" }, "title": { "description": "What is due, up to 200 characters.", "type": "string" } }, "required": [ "title", "due_date" ], "title": "ClientCalendarEventCreate", "type": "object" }, "ClientCalendarEventPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "client_id": { "description": "The client it is about.", "format": "uuid", "type": "string" }, "completed_at": { "description": "When it was done.", "format": "date-time", "nullable": true, "type": "string" }, "description": { "description": "More about it.", "nullable": true, "type": "string" }, "due_date": { "description": "The day it is due.", "format": "date", "nullable": true, "type": "string" }, "due_time": { "description": "A time of day, HH:MM:SS (Mountain time).", "nullable": true, "type": "string" }, "event_type": { "enum": [ "supervisory_visit", "recertification", "follow_up", "custom" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "lock_version": { "description": "Its version.", "nullable": true, "type": "integer" }, "status": { "enum": [ "upcoming", "overdue", "completed", "dismissed" ], "type": "string" }, "title": { "description": "What is due.", "nullable": true, "type": "string" } }, "required": [ "id", "client_id", "event_type", "title", "due_date", "status", "lock_version" ], "title": "ClientCalendarEvent", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClientCalendarEventPage", "type": "object" }, "ClientCalendarEventRestore": { "properties": { "due_date": { "description": "The day it was due, YYYY-MM-DD.", "format": "date", "nullable": true, "type": "string" }, "due_time": { "description": "The time it was due, HH:MM:SS, Mountain time.", "nullable": true, "type": "string" }, "status": { "description": "The status it had.", "enum": [ "upcoming", "overdue" ], "type": "string" } }, "required": [ "status" ], "title": "ClientCalendarEventRestore", "type": "object" }, "ClientCertification": { "description": "One certification period; periods for a client may not overlap.", "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "county": { "description": "The county.", "nullable": true, "type": "string", "x-untrusted": "text" }, "effective_date": { "description": "When the period starts.", "format": "date", "nullable": true, "type": "string" }, "expiry_date": { "description": "When it ends.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was recorded.", "format": "date-time", "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "client_id", "effective_date", "expiry_date" ], "title": "ClientCertification", "type": "object" }, "ClientCertificationInput": { "description": "A period overlapping another of the client's answers 422 naming effective_date.", "properties": { "county": { "description": "The county.", "nullable": true, "type": "string" }, "effective_date": { "description": "When the period starts, YYYY-MM-DD.", "format": "date", "nullable": false, "type": "string" }, "expiry_date": { "description": "When it ends, YYYY-MM-DD.", "format": "date", "nullable": false, "type": "string" } }, "title": "ClientCertificationInput", "type": "object" }, "ClientCertificationPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ClientCertification" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClientCertificationPage", "type": "object" }, "ClientChartAddendum": { "properties": { "body": { "description": "What it adds.", "nullable": true, "type": "string", "x-untrusted": "text" }, "id": { "description": "The addendum.", "format": "uuid", "type": "string" }, "reason": { "description": "Why it was added.", "nullable": true, "type": "string", "x-untrusted": "text" }, "signatures": { "description": "Its live signatures, oldest first.", "items": { "properties": { "channel": { "description": "Where it was signed.", "enum": [ "app", "phone", "office", "scan", "docusign", "import" ], "nullable": true, "type": "string" }, "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin", "voice", "docusign_agency", "docusign_platform", "paper_on_file", "imported" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "caregiver", "supervisor", "pcp", "office" ], "type": "string" }, "role_label": { "description": "The line as the record names it, e.g. \"complainant\".", "nullable": true, "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed, as given.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "role_label", "signer_name", "method", "signed_at" ], "title": "ClientChartSignature", "type": "object" }, "type": "array" }, "signed_at": { "description": "When it was signed.", "format": "date-time", "type": "string" }, "state": { "description": "The addendum's own state.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "true_copy": { "properties": { "document_id": { "description": "The true copy, at /documents/{id}/download, once stored.", "format": "uuid", "nullable": true, "type": "string" }, "status": { "description": "none for a draft, an incomplete signing or a record signed before the electronic record; pending while the copy is made; stored once filed; failed when it could not be made.", "enum": [ "none", "pending", "stored", "failed" ], "type": "string" } }, "required": [ "status" ], "title": "ClientChartTrueCopy", "type": "object" } }, "required": [ "id", "body", "signed_at", "signatures", "true_copy" ], "title": "ClientChartAddendum", "type": "object" }, "ClientChartCareLog": { "nullable": true, "properties": { "attested": { "description": "Whether the client's attestation is on it: a client or representative signature, or recorded words.", "type": "boolean" }, "source": { "description": "Where the log was kept.", "enum": [ "hcb_app", "hcb_phone", "office", "paper_scan", "import" ], "type": "string" } }, "required": [ "source", "attested" ], "title": "ClientChartCareLog", "type": "object" }, "ClientChartDocument": { "nullable": true, "properties": { "file_name": { "description": "Its file name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "id": { "description": "The document.", "format": "uuid", "type": "string" }, "scan_status": { "description": "Its virus scan; only a clean document can be downloaded.", "enum": [ "pending", "clean", "infected", "error", "rejected" ], "type": "string" } }, "required": [ "id", "file_name", "scan_status" ], "title": "ClientChartDocument", "type": "object" }, "ClientChartEntry": { "properties": { "addenda": { "description": "The record's signed addenda, in signing order.", "items": { "properties": { "body": { "description": "What it adds.", "nullable": true, "type": "string", "x-untrusted": "text" }, "id": { "description": "The addendum.", "format": "uuid", "type": "string" }, "reason": { "description": "Why it was added.", "nullable": true, "type": "string", "x-untrusted": "text" }, "signatures": { "description": "Its live signatures, oldest first.", "items": { "properties": { "channel": { "description": "Where it was signed.", "enum": [ "app", "phone", "office", "scan", "docusign", "import" ], "nullable": true, "type": "string" }, "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin", "voice", "docusign_agency", "docusign_platform", "paper_on_file", "imported" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "caregiver", "supervisor", "pcp", "office" ], "type": "string" }, "role_label": { "description": "The line as the record names it, e.g. \"complainant\".", "nullable": true, "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed, as given.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "role_label", "signer_name", "method", "signed_at" ], "title": "ClientChartSignature", "type": "object" }, "type": "array" }, "signed_at": { "description": "When it was signed.", "format": "date-time", "type": "string" }, "state": { "description": "The addendum's own state.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "true_copy": { "properties": { "document_id": { "description": "The true copy, at /documents/{id}/download, once stored.", "format": "uuid", "nullable": true, "type": "string" }, "status": { "description": "none for a draft, an incomplete signing or a record signed before the electronic record; pending while the copy is made; stored once filed; failed when it could not be made.", "enum": [ "none", "pending", "stored", "failed" ], "type": "string" } }, "required": [ "status" ], "title": "ClientChartTrueCopy", "type": "object" } }, "required": [ "id", "body", "signed_at", "signatures", "true_copy" ], "title": "ClientChartAddendum", "type": "object" }, "type": "array" }, "care_log": { "nullable": true, "properties": { "attested": { "description": "Whether the client's attestation is on it: a client or representative signature, or recorded words.", "type": "boolean" }, "source": { "description": "Where the log was kept.", "enum": [ "hcb_app", "hcb_phone", "office", "paper_scan", "import" ], "type": "string" } }, "required": [ "source", "attested" ], "title": "ClientChartCareLog", "type": "object" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_name": { "description": "The caregiver's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "document": { "nullable": true, "properties": { "file_name": { "description": "Its file name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "id": { "description": "The document.", "format": "uuid", "type": "string" }, "scan_status": { "description": "Its virus scan; only a clean document can be downloaded.", "enum": [ "pending", "clean", "infected", "error", "rejected" ], "type": "string" } }, "required": [ "id", "file_name", "scan_status" ], "title": "ClientChartDocument", "type": "object" }, "kind": { "description": "The kind of record.", "enum": [ "supervisory_visit", "plan_of_care", "monthly_client_report", "complaint", "critical_incident", "consent_notice", "emergency_information", "care_log", "half_month_summary", "document", "legacy_scan" ], "type": "string" }, "legacy_signed": { "description": "True for a record signed before the electronic record: its signatures are on paper, and it has no true copy.", "type": "boolean" }, "missing_signers": { "description": "Each required line no live signature fills, e.g. \"caregiver or PCP\"; empty unless the record is signed or amended.", "items": { "type": "string" }, "type": "array" }, "occurred_on": { "description": "The date the entry is filed under: the visit, effective, service or complaint date, the first of a report's month, the first signature (Mountain) of a notice or emergency information, a scan's paper date, else the upload date (Mountain).", "format": "date", "nullable": true, "type": "string" }, "path": { "description": "The app page the title opens, or a document's download; null for a document whose virus scan is not clean.", "nullable": true, "type": "string" }, "record_id": { "description": "The record, or for a document or scan the document.", "format": "uuid", "type": "string" }, "service_type": { "description": "The service.", "enum": [ "personal_care", "homemaker", "hma", "legacy" ], "nullable": true, "type": "string" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "channel": { "description": "Where it was signed.", "enum": [ "app", "phone", "office", "scan", "docusign", "import" ], "nullable": true, "type": "string" }, "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin", "voice", "docusign_agency", "docusign_platform", "paper_on_file", "imported" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "caregiver", "supervisor", "pcp", "office" ], "type": "string" }, "role_label": { "description": "The line as the record names it, e.g. \"complainant\".", "nullable": true, "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed, as given.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "role_label", "signer_name", "method", "signed_at" ], "title": "ClientChartSignature", "type": "object" }, "type": "array" }, "state": { "description": "The record's state; null for a document.", "enum": [ "draft", "signed", "amended", "voided" ], "nullable": true, "type": "string" }, "title": { "description": "The entry's title, as the chart shows it.", "nullable": true, "type": "string" }, "true_copy": { "properties": { "document_id": { "description": "The true copy, at /documents/{id}/download, once stored.", "format": "uuid", "nullable": true, "type": "string" }, "status": { "description": "none for a draft, an incomplete signing or a record signed before the electronic record; pending while the copy is made; stored once filed; failed when it could not be made.", "enum": [ "none", "pending", "stored", "failed" ], "type": "string" } }, "required": [ "status" ], "title": "ClientChartTrueCopy", "type": "object" }, "void": { "nullable": true, "properties": { "actor_name": { "description": "Who voided it; null for an API key.", "nullable": true, "type": "string", "x-untrusted": "text" }, "reason": { "description": "Why it was voided.", "nullable": true, "type": "string", "x-untrusted": "text" }, "replaced_by_id": { "description": "The draft made to replace it, when one was made.", "format": "uuid", "nullable": true, "type": "string" }, "voided_at": { "description": "When it was voided.", "format": "date-time", "type": "string" } }, "required": [ "voided_at", "reason" ], "title": "ClientChartVoid", "type": "object" }, "work_order_id": { "description": "A Monthly Client Report's Work Order.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "kind", "record_id", "occurred_on", "title", "legacy_signed", "signatures", "missing_signers", "true_copy", "addenda" ], "title": "ClientChartEntry", "type": "object" }, "ClientChartPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "addenda": { "description": "The record's signed addenda, in signing order.", "items": { "properties": { "body": { "description": "What it adds.", "nullable": true, "type": "string", "x-untrusted": "text" }, "id": { "description": "The addendum.", "format": "uuid", "type": "string" }, "reason": { "description": "Why it was added.", "nullable": true, "type": "string", "x-untrusted": "text" }, "signatures": { "description": "Its live signatures, oldest first.", "items": { "properties": { "channel": { "description": "Where it was signed.", "enum": [ "app", "phone", "office", "scan", "docusign", "import" ], "nullable": true, "type": "string" }, "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin", "voice", "docusign_agency", "docusign_platform", "paper_on_file", "imported" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "caregiver", "supervisor", "pcp", "office" ], "type": "string" }, "role_label": { "description": "The line as the record names it, e.g. \"complainant\".", "nullable": true, "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed, as given.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "role_label", "signer_name", "method", "signed_at" ], "title": "ClientChartSignature", "type": "object" }, "type": "array" }, "signed_at": { "description": "When it was signed.", "format": "date-time", "type": "string" }, "state": { "description": "The addendum's own state.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "true_copy": { "properties": { "document_id": { "description": "The true copy, at /documents/{id}/download, once stored.", "format": "uuid", "nullable": true, "type": "string" }, "status": { "description": "none for a draft, an incomplete signing or a record signed before the electronic record; pending while the copy is made; stored once filed; failed when it could not be made.", "enum": [ "none", "pending", "stored", "failed" ], "type": "string" } }, "required": [ "status" ], "title": "ClientChartTrueCopy", "type": "object" } }, "required": [ "id", "body", "signed_at", "signatures", "true_copy" ], "title": "ClientChartAddendum", "type": "object" }, "type": "array" }, "care_log": { "nullable": true, "properties": { "attested": { "description": "Whether the client's attestation is on it: a client or representative signature, or recorded words.", "type": "boolean" }, "source": { "description": "Where the log was kept.", "enum": [ "hcb_app", "hcb_phone", "office", "paper_scan", "import" ], "type": "string" } }, "required": [ "source", "attested" ], "title": "ClientChartCareLog", "type": "object" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_name": { "description": "The caregiver's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "document": { "nullable": true, "properties": { "file_name": { "description": "Its file name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "id": { "description": "The document.", "format": "uuid", "type": "string" }, "scan_status": { "description": "Its virus scan; only a clean document can be downloaded.", "enum": [ "pending", "clean", "infected", "error", "rejected" ], "type": "string" } }, "required": [ "id", "file_name", "scan_status" ], "title": "ClientChartDocument", "type": "object" }, "kind": { "description": "The kind of record.", "enum": [ "supervisory_visit", "plan_of_care", "monthly_client_report", "complaint", "critical_incident", "consent_notice", "emergency_information", "care_log", "half_month_summary", "document", "legacy_scan" ], "type": "string" }, "legacy_signed": { "description": "True for a record signed before the electronic record: its signatures are on paper, and it has no true copy.", "type": "boolean" }, "missing_signers": { "description": "Each required line no live signature fills, e.g. \"caregiver or PCP\"; empty unless the record is signed or amended.", "items": { "type": "string" }, "type": "array" }, "occurred_on": { "description": "The date the entry is filed under: the visit, effective, service or complaint date, the first of a report's month, the first signature (Mountain) of a notice or emergency information, a scan's paper date, else the upload date (Mountain).", "format": "date", "nullable": true, "type": "string" }, "path": { "description": "The app page the title opens, or a document's download; null for a document whose virus scan is not clean.", "nullable": true, "type": "string" }, "record_id": { "description": "The record, or for a document or scan the document.", "format": "uuid", "type": "string" }, "service_type": { "description": "The service.", "enum": [ "personal_care", "homemaker", "hma", "legacy" ], "nullable": true, "type": "string" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "channel": { "description": "Where it was signed.", "enum": [ "app", "phone", "office", "scan", "docusign", "import" ], "nullable": true, "type": "string" }, "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin", "voice", "docusign_agency", "docusign_platform", "paper_on_file", "imported" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "caregiver", "supervisor", "pcp", "office" ], "type": "string" }, "role_label": { "description": "The line as the record names it, e.g. \"complainant\".", "nullable": true, "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed, as given.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "role_label", "signer_name", "method", "signed_at" ], "title": "ClientChartSignature", "type": "object" }, "type": "array" }, "state": { "description": "The record's state; null for a document.", "enum": [ "draft", "signed", "amended", "voided" ], "nullable": true, "type": "string" }, "title": { "description": "The entry's title, as the chart shows it.", "nullable": true, "type": "string" }, "true_copy": { "properties": { "document_id": { "description": "The true copy, at /documents/{id}/download, once stored.", "format": "uuid", "nullable": true, "type": "string" }, "status": { "description": "none for a draft, an incomplete signing or a record signed before the electronic record; pending while the copy is made; stored once filed; failed when it could not be made.", "enum": [ "none", "pending", "stored", "failed" ], "type": "string" } }, "required": [ "status" ], "title": "ClientChartTrueCopy", "type": "object" }, "void": { "nullable": true, "properties": { "actor_name": { "description": "Who voided it; null for an API key.", "nullable": true, "type": "string", "x-untrusted": "text" }, "reason": { "description": "Why it was voided.", "nullable": true, "type": "string", "x-untrusted": "text" }, "replaced_by_id": { "description": "The draft made to replace it, when one was made.", "format": "uuid", "nullable": true, "type": "string" }, "voided_at": { "description": "When it was voided.", "format": "date-time", "type": "string" } }, "required": [ "voided_at", "reason" ], "title": "ClientChartVoid", "type": "object" }, "work_order_id": { "description": "A Monthly Client Report's Work Order.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "kind", "record_id", "occurred_on", "title", "legacy_signed", "signatures", "missing_signers", "true_copy", "addenda" ], "title": "ClientChartEntry", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClientChartPage", "type": "object" }, "ClientChartSignature": { "properties": { "channel": { "description": "Where it was signed.", "enum": [ "app", "phone", "office", "scan", "docusign", "import" ], "nullable": true, "type": "string" }, "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin", "voice", "docusign_agency", "docusign_platform", "paper_on_file", "imported" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "caregiver", "supervisor", "pcp", "office" ], "type": "string" }, "role_label": { "description": "The line as the record names it, e.g. \"complainant\".", "nullable": true, "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed, as given.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "role_label", "signer_name", "method", "signed_at" ], "title": "ClientChartSignature", "type": "object" }, "ClientChartTrueCopy": { "properties": { "document_id": { "description": "The true copy, at /documents/{id}/download, once stored.", "format": "uuid", "nullable": true, "type": "string" }, "status": { "description": "none for a draft, an incomplete signing or a record signed before the electronic record; pending while the copy is made; stored once filed; failed when it could not be made.", "enum": [ "none", "pending", "stored", "failed" ], "type": "string" } }, "required": [ "status" ], "title": "ClientChartTrueCopy", "type": "object" }, "ClientChartVoid": { "nullable": true, "properties": { "actor_name": { "description": "Who voided it; null for an API key.", "nullable": true, "type": "string", "x-untrusted": "text" }, "reason": { "description": "Why it was voided.", "nullable": true, "type": "string", "x-untrusted": "text" }, "replaced_by_id": { "description": "The draft made to replace it, when one was made.", "format": "uuid", "nullable": true, "type": "string" }, "voided_at": { "description": "When it was voided.", "format": "date-time", "type": "string" } }, "required": [ "voided_at", "reason" ], "title": "ClientChartVoid", "type": "object" }, "ClientConsentForm": { "properties": { "answers": { "description": "The answers, by question key: a disclosure item's responsible party (agency or consumer), the complaint contact.", "type": "object" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "declined_reason": { "description": "Why the client declined to sign a disclosure notice; the office then signs that it was conveyed verbally.", "nullable": true, "type": "string", "x-untrusted": "text" }, "defaulted_keys": { "description": "The choices still holding the answer the notice was prefilled with (its first option): defaults nobody has chosen.", "items": { "type": "string" }, "type": "array" }, "form_type": { "description": "agency_disclosure_notice (Chapter 26 6.7) or client_rights_acknowledgement (6.4).", "enum": [ "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the notice was started.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "missing_signers": { "description": "Each required line no live signature fills yet, in order; empty when complete or voided.", "items": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "type": "array" }, "record_state": { "description": "draft until the first signature; signed notices are corrected by addendum or void.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "signer_name", "method", "signed_at" ], "title": "RecordSignatureSummary", "type": "object" }, "type": "array" }, "signed_at": { "description": "When the first signature locked it; null on a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing_complete": { "description": "True once the record is signed or amended and every required line holds a signature. A signed record can be false: signed by one line, with another still open. A voided record is always false, whatever it holds, and its missing_signers is empty: nothing can sign it, and its replacement is the record to complete.", "type": "boolean" } }, "required": [ "id", "client_id", "form_type", "record_state", "answers", "lock_version" ], "title": "ClientConsentForm", "type": "object" }, "ClientConsentFormAnswers": { "properties": { "answers": { "description": "Answers by question key; a key sent counts as chosen, and a blank clears its answer. Keys not sent keep their answer.", "type": "object" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": [ "answers", "lock_version" ], "title": "ClientConsentFormAnswers", "type": "object" }, "ClientConsentFormPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "answers": { "description": "The answers, by question key: a disclosure item's responsible party (agency or consumer), the complaint contact.", "type": "object" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "declined_reason": { "description": "Why the client declined to sign a disclosure notice; the office then signs that it was conveyed verbally.", "nullable": true, "type": "string", "x-untrusted": "text" }, "defaulted_keys": { "description": "The choices still holding the answer the notice was prefilled with (its first option): defaults nobody has chosen.", "items": { "type": "string" }, "type": "array" }, "form_type": { "description": "agency_disclosure_notice (Chapter 26 6.7) or client_rights_acknowledgement (6.4).", "enum": [ "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the notice was started.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "missing_signers": { "description": "Each required line no live signature fills yet, in order; empty when complete or voided.", "items": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "type": "array" }, "record_state": { "description": "draft until the first signature; signed notices are corrected by addendum or void.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "signer_name", "method", "signed_at" ], "title": "RecordSignatureSummary", "type": "object" }, "type": "array" }, "signed_at": { "description": "When the first signature locked it; null on a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing_complete": { "description": "True once the record is signed or amended and every required line holds a signature. A signed record can be false: signed by one line, with another still open. A voided record is always false, whatever it holds, and its missing_signers is empty: nothing can sign it, and its replacement is the record to complete.", "type": "boolean" } }, "required": [ "id", "client_id", "form_type", "record_state", "answers", "lock_version" ], "title": "ClientConsentForm", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClientConsentFormPage", "type": "object" }, "ClientConsentFormSignature": { "properties": { "declined_reason": { "description": "On a draft disclosure notice: why the client declined to sign. Saved with the office signature in one step, that the notice was conveyed verbally.", "nullable": true, "type": "string", "x-untrusted": "text" }, "role": { "description": "office: agency staff, signed as you. A rights acknowledgement is complete with it; a disclosure notice takes it only with declined_reason. client and representative are drawn on the device in the app and answer 422 drawn_required here.", "enum": [ "client", "representative", "office" ], "type": "string" } }, "required": [ "role" ], "title": "ClientConsentFormSignature", "type": "object" }, "ClientConsentFormStart": { "properties": { "form_type": { "description": "The notice to start.", "enum": [ "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" } }, "required": [ "form_type" ], "title": "ClientConsentFormStart", "type": "object" }, "ClientEmergencyInfo": { "properties": { "answers": { "description": "The answers, by question key.", "type": "object" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When this revision was saved.", "format": "date-time", "type": "string" }, "missing_signers": { "description": "Each required line no live signature fills yet, in order; empty when complete or voided.", "items": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "type": "array" }, "record_state": { "description": "draft until the first signature (US-101.32). A signed revision is never deleted or changed: it is corrected with an addendum, voided, or followed by a new revision.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "signer_name", "method", "signed_at" ], "title": "RecordSignatureSummary", "type": "object" }, "type": "array" }, "signed_at": { "description": "When the first signature locked it; null on a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing_complete": { "description": "True once the record is signed or amended and every required line holds a signature. A signed record can be false: signed by one line, with another still open. A voided record is always false, whatever it holds, and its missing_signers is empty: nothing can sign it, and its replacement is the record to complete.", "type": "boolean" }, "superseded": { "description": "True for a draft never signed whose client has a later signed revision: it is no longer the sheet in force, and may still be deleted.", "type": "boolean" }, "version": { "description": "Its revision number.", "type": "integer" } }, "required": [ "id", "client_id", "version", "answers", "record_state" ], "title": "ClientEmergencyInfo", "type": "object" }, "ClientEmergencyInfoInput": { "properties": { "answers": { "description": "Answers by question key.", "type": "object" } }, "required": [ "answers" ], "title": "ClientEmergencyInfoInput", "type": "object" }, "ClientEmergencyInfoPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "answers": { "description": "The answers, by question key.", "type": "object" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When this revision was saved.", "format": "date-time", "type": "string" }, "missing_signers": { "description": "Each required line no live signature fills yet, in order; empty when complete or voided.", "items": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "type": "array" }, "record_state": { "description": "draft until the first signature (US-101.32). A signed revision is never deleted or changed: it is corrected with an addendum, voided, or followed by a new revision.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "signer_name", "method", "signed_at" ], "title": "RecordSignatureSummary", "type": "object" }, "type": "array" }, "signed_at": { "description": "When the first signature locked it; null on a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing_complete": { "description": "True once the record is signed or amended and every required line holds a signature. A signed record can be false: signed by one line, with another still open. A voided record is always false, whatever it holds, and its missing_signers is empty: nothing can sign it, and its replacement is the record to complete.", "type": "boolean" }, "superseded": { "description": "True for a draft never signed whose client has a later signed revision: it is no longer the sheet in force, and may still be deleted.", "type": "boolean" }, "version": { "description": "Its revision number.", "type": "integer" } }, "required": [ "id", "client_id", "version", "answers", "record_state" ], "title": "ClientEmergencyInfo", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClientEmergencyInfoPage", "type": "object" }, "ClientEmergencyInfoSignature": { "properties": { "role": { "description": "Whose line to sign: office, agency staff, signed as you. The client's or authorized representative's line is drawn on the device in the app and answers 422 drawn_required here.", "enum": [ "client", "representative", "office" ], "type": "string" } }, "required": [ "role" ], "title": "ClientEmergencyInfoSignature", "type": "object" }, "ClientHealthSummary": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "edited_at": { "description": "When it was last edited.", "format": "date-time", "nullable": true, "type": "string" }, "generated_at": { "description": "When it was written.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "lock_version": { "description": "Its version; send it back to edit.", "nullable": true, "type": "integer" }, "model_used": { "description": "The AI model that wrote it.", "nullable": true, "type": "string" }, "text": { "description": "The summary, in Markdown.", "nullable": true, "type": "string" } }, "required": [ "id", "client_id", "text", "lock_version" ], "title": "ClientHealthSummary", "type": "object" }, "ClientHealthSummaryUpdate": { "properties": { "lock_version": { "description": "The lock_version it was read with.", "nullable": true, "type": "integer" }, "text": { "description": "The summary, in Markdown.", "type": "string" } }, "required": [ "text", "lock_version" ], "title": "ClientHealthSummaryUpdate", "type": "object" }, "ClientInformationSheetSaved": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "fields": { "description": "The fields written.", "items": { "type": "string" }, "type": "array" } }, "required": [ "client_id", "fields" ], "title": "ClientInformationSheetSaved", "type": "object" }, "ClientInformationSheetUpdate": { "properties": { "address": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "allergies": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "city": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "clinic_name": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "date_of_birth": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "doctor_address": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "doctor_name": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "doctor_phone": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "emergency_contact_name": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "emergency_contact_phone": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "field_staff_instructions": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "first_name": { "description": "As the Information Sheet names it; never blank.", "type": "string" }, "gender": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "home_phone": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "last_name": { "description": "As the Information Sheet names it; never blank.", "type": "string" }, "manager_email": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "manager_fax": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "manager_name": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "manager_phone": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "medicaid_id": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "medications": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "mobile_phone": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "other_conditions": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "physical_conditions": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "ssn": { "description": "The client's SSN, never returned; leave it out to keep the stored one.", "type": "string" }, "state": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "supervisor_name": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "supervisor_phone": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "zip": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" } }, "title": "ClientInformationSheetUpdate", "type": "object" }, "ClientInput": { "description": "Fields to set. A create needs first_name and last_name. A Medicaid client (client_type medicaid, the default) saved without medicaid_id is saved with a medicaid_id_pending warning and cannot be billed until the ID is added; never send a placeholder ID. An update sends only what changes, plus the lock_version it read (required).", "properties": { "address": { "nullable": true, "type": "string", "x-untrusted": "text" }, "address_line_2": { "description": "Apartment, suite or unit; sent to Sandata as ClientAddressLine2.", "nullable": true, "type": "string", "x-untrusted": "text" }, "city": { "nullable": true, "type": "string", "x-untrusted": "text" }, "client_type": { "enum": [ "medicaid", "private_insurance", "ihss" ], "type": "string" }, "county": { "description": "A Colorado county name; sent to Sandata as ClientCounty.", "nullable": true, "type": "string", "x-untrusted": "text" }, "date_of_birth": { "description": "Usually YYYY-MM-DD. Stored as entered: a record imported from older software can hold other text.", "nullable": true, "type": "string", "x-untrusted": "date_of_birth" }, "eligibility_end_date": { "format": "date", "nullable": true, "type": "string" }, "eligibility_start_date": { "format": "date", "nullable": true, "type": "string" }, "email": { "nullable": true, "type": "string" }, "emergency_contact_name": { "deprecated": true, "description": "Deprecated: use /api/v1/clients/{id}/relations. Served until 2027-05-31. The client's emergency contact 1, as the client page's People section shows it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "emergency_contact_phone": { "deprecated": true, "description": "Deprecated: use /api/v1/clients/{id}/relations. Served until 2027-05-31. Emergency contact 1's phone, 10 digits.", "nullable": true, "type": "string" }, "first_name": { "type": "string" }, "gender": { "nullable": true, "type": "string", "x-untrusted": "text" }, "home_phone": { "nullable": true, "type": "string" }, "ihss_client": { "description": "An IHSS client (Access's IHSSClient box), whatever client_type says; the PAR panel then shows the IHSS column. A client typed ihss is always one.", "type": "boolean" }, "ihss_code": { "description": "The IHSS billing code and modifiers off the client's IHSS PAR, as the agency writes them (US-102.17).", "nullable": true, "type": "string", "x-untrusted": "text" }, "ihss_par_weeks": { "description": "The weeks the client's IHSS PAR runs.", "format": "decimal", "nullable": true, "type": "string" }, "ihss_units_on_par": { "description": "The units the client's IHSS PAR authorizes; the PAR panel shows them as hours a week, units / 4 / weeks.", "nullable": true, "type": "integer" }, "language_preference": { "nullable": true, "type": "string", "x-untrusted": "text" }, "last_name": { "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "medicaid_id": { "description": "The Colorado Medicaid id.", "nullable": true, "type": "string" }, "middle_name": { "nullable": true, "type": "string" }, "mobile_phone": { "nullable": true, "type": "string" }, "payer_program": { "description": "The program that pays for the client's care.", "nullable": true, "type": "string", "x-untrusted": "text" }, "private_insurance_client": { "description": "The client has private insurance (Access's Private box), whatever client_type says. A client typed private_insurance always has.", "type": "boolean" }, "service_end_date": { "format": "date", "nullable": true, "type": "string" }, "service_start_date": { "format": "date", "nullable": true, "type": "string" }, "ssn": { "description": "The full SSN, 9 digits, dashes allowed; null clears it. Answers show only ssn_masked.", "nullable": true, "type": "string" }, "state": { "nullable": true, "type": "string" }, "status": { "enum": [ "active", "inactive", "potential", "discharged" ], "type": "string" }, "temporary": { "description": "A short-term client, whatever pays for them; the app's active client list hides them by default.", "type": "boolean" }, "zip": { "description": "5 digits or ZIP+4, like \"80202\" or \"80202-1234\". A number sent here is read as its digits.", "nullable": true, "type": "string" } }, "title": "ClientInput", "type": "object" }, "ClientMedical": { "properties": { "allergies": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "clinic_name": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "doctor_address": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "doctor_name": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "doctor_phone": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "field_staff_instructions": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "functional_limitations": { "description": "The Functional Limitations checkboxes and their Other text; null when none were ever saved. A write changes only the keys sent.", "nullable": true, "properties": { "breathing": { "description": "Whether the client has this limitation.", "type": "boolean" }, "hearing": { "description": "Whether the client has this limitation.", "type": "boolean" }, "mobility": { "description": "Whether the client has this limitation.", "type": "boolean" }, "other": { "description": "Any other limitation.", "nullable": true, "type": "string" }, "special_diet": { "description": "Whether the client has this limitation.", "type": "boolean" }, "speech": { "description": "Whether the client has this limitation.", "type": "boolean" }, "swallowing": { "description": "Whether the client has this limitation.", "type": "boolean" }, "vision": { "description": "Whether the client has this limitation.", "type": "boolean" } }, "type": "object" }, "medications": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "other_conditions": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "physical_conditions": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "special_needs": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "surgeries": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" } }, "required": [ "client_id" ], "title": "ClientMedical", "type": "object" }, "ClientMedicalSaved": { "properties": { "allergies": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "clinic_name": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "doctor_address": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "doctor_name": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "doctor_phone": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "field_staff_instructions": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "functional_limitations": { "description": "The Functional Limitations checkboxes and their Other text; null when none were ever saved. A write changes only the keys sent.", "nullable": true, "properties": { "breathing": { "description": "Whether the client has this limitation.", "type": "boolean" }, "hearing": { "description": "Whether the client has this limitation.", "type": "boolean" }, "mobility": { "description": "Whether the client has this limitation.", "type": "boolean" }, "other": { "description": "Any other limitation.", "nullable": true, "type": "string" }, "special_diet": { "description": "Whether the client has this limitation.", "type": "boolean" }, "speech": { "description": "Whether the client has this limitation.", "type": "boolean" }, "swallowing": { "description": "Whether the client has this limitation.", "type": "boolean" }, "vision": { "description": "Whether the client has this limitation.", "type": "boolean" } }, "type": "object" }, "medications": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "other_conditions": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "physical_conditions": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "special_needs": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "surgeries": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" } }, "required": [ "client_id" ], "title": "ClientMedicalSaved", "type": "object" }, "ClientMedicalUpdate": { "properties": { "allergies": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "clinic_name": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "doctor_address": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "doctor_name": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "doctor_phone": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "field_staff_instructions": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "functional_limitations": { "description": "The Functional Limitations checkboxes and their Other text; null when none were ever saved. A write changes only the keys sent.", "nullable": true, "properties": { "breathing": { "description": "Whether the client has this limitation.", "type": "boolean" }, "hearing": { "description": "Whether the client has this limitation.", "type": "boolean" }, "mobility": { "description": "Whether the client has this limitation.", "type": "boolean" }, "other": { "description": "Any other limitation.", "nullable": true, "type": "string" }, "special_diet": { "description": "Whether the client has this limitation.", "type": "boolean" }, "speech": { "description": "Whether the client has this limitation.", "type": "boolean" }, "swallowing": { "description": "Whether the client has this limitation.", "type": "boolean" }, "vision": { "description": "Whether the client has this limitation.", "type": "boolean" } }, "type": "object" }, "medications": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "other_conditions": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "physical_conditions": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "special_needs": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "surgeries": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" } }, "title": "ClientMedicalUpdate", "type": "object" }, "ClientMonthEvidence": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "days": { "description": "Every calendar day of the month, in order.", "items": { "properties": { "care_logs": { "items": { "properties": { "attestation_method": { "description": "How the client or representative signed it, if they did.", "nullable": true, "type": "string" }, "attestation_skip_reason": { "description": "Why the client could not sign, when the caregiver said.", "nullable": true, "type": "string" }, "care_log_id": { "description": "The care log.", "format": "uuid", "type": "string" }, "comparisons": { "items": { "properties": { "conflict_key": { "description": "The conflict's key, on a conflict only; dismiss it as a visit conflict is dismissed.", "nullable": true, "type": "string" }, "fields": { "description": "On a conflict, the fields that differ: start, end, tasks or attestation.", "items": { "type": "string" }, "type": "array" }, "kind": { "description": "What was compared: the care log's times with the visit evidence, its done tasks with the Work Order's office-typed marks, or the client's signature with the visit's client verification.", "enum": [ "care_log_times", "care_log_tasks", "attestation" ], "type": "string" }, "only_care_log": { "description": "Task codes done on the care log and not marked on the Work Order.", "items": { "type": "string" }, "type": "array" }, "only_work_order": { "description": "Task codes marked on the Work Order and not done on the care log.", "items": { "type": "string" }, "type": "array" }, "state": { "description": "The comparison's state.", "enum": [ "conflict", "conflict_dismissed", "corroborated", "single_source" ], "type": "string" }, "visit_id": { "description": "The visit it was compared with, when one was.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "kind", "state", "fields", "only_care_log", "only_work_order" ], "title": "ClientMonthEvidenceCareLogComparison", "type": "object" }, "type": "array" }, "end": { "description": "Its end (the linked visit's, else entered).", "format": "date-time", "nullable": true, "type": "string" }, "service_type": { "description": "Its service.", "nullable": true, "type": "string" }, "shift_number": { "description": "Its shift of the day.", "nullable": true, "type": "integer" }, "source": { "description": "How the care log was captured.", "enum": [ "hcb_app", "hcb_phone", "office", "paper_scan", "import" ], "type": "string" }, "start": { "description": "Its start (the linked visit's, else entered).", "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "care_log_id", "source", "service_type", "shift_number", "comparisons" ], "title": "ClientMonthEvidenceCareLog", "type": "object" }, "type": "array" }, "claim_changes": { "items": { "properties": { "batch_id": { "description": "The claim's batch.", "format": "uuid", "type": "string" }, "care_log_ids": { "description": "The care logs of the day that changed.", "items": { "type": "string" }, "type": "array" }, "claim_id": { "description": "The claim sent before the day's care log changed.", "format": "uuid", "type": "string" }, "fingerprint": { "description": "The warning's fingerprint; dismiss it through POST /api/v1/revenue-warnings/dismissals with the claim_id as subject_id.", "nullable": true, "type": "string" }, "kind": { "description": "changed_after_claim.", "nullable": true, "type": "string" }, "state": { "description": "Whether the warning is open or dismissed.", "enum": [ "conflict", "conflict_dismissed" ], "type": "string" } }, "required": [ "claim_id", "batch_id", "kind", "fingerprint", "state", "care_log_ids" ], "title": "ClientMonthEvidenceClaimChange", "type": "object" }, "type": "array" }, "date": { "description": "The day (Mountain).", "format": "date", "nullable": true, "type": "string" }, "dismissals": { "items": { "properties": { "conflict_key": { "description": "The conflict dismissed.", "nullable": true, "type": "string" }, "dismissed_at": { "description": "When it was dismissed.", "format": "date-time", "type": "string" }, "dismissed_by": { "description": "Who dismissed it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "dismissed_by_user_id": { "description": "The member who dismissed it; null for an API key.", "format": "uuid", "nullable": true, "type": "string" }, "reason": { "description": "Why it was dismissed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "conflict_key", "dismissed_by", "dismissed_at", "reason" ], "title": "ClientMonthEvidenceDismissal", "type": "object" }, "type": "array" }, "open_conflict_keys": { "description": "The keys of the day's visit, care-log and timesheet-drift conflicts nobody has dismissed.", "items": { "type": "string" }, "type": "array" }, "sources": { "items": { "properties": { "source": { "description": "The evidence source; paper_scan, on a day with no visit, is the times of its paper-scan care log.", "enum": [ "sandata", "other_evv", "hcb_app", "hcb_phone", "office", "paper_scan" ], "type": "string" }, "visits": { "items": { "properties": { "care_log_id": { "description": "On a paper_scan row, the paper-scan care log whose times it shows.", "format": "uuid", "nullable": true, "type": "string" }, "conflict_key": { "description": "The entry's conflict key, on a conflict only.", "nullable": true, "type": "string" }, "end": { "description": "Its billable end; null while it is open.", "format": "date-time", "nullable": true, "type": "string" }, "procedure_code": { "description": "Its procedure code.", "nullable": true, "type": "string" }, "start": { "description": "Its billable start (adjusted, else actual).", "format": "date-time", "nullable": true, "type": "string" }, "state": { "description": "The state of the reconciliation entry the visit is in.", "enum": [ "conflict", "conflict_dismissed", "corroborated", "single_source" ], "type": "string" }, "visit_id": { "description": "The visit; null on a paper_scan row, which has none.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "visit_id", "state" ], "title": "ClientMonthEvidenceVisit", "type": "object" }, "type": "array" } }, "required": [ "source", "visits" ], "title": "ClientMonthEvidenceSource", "type": "object" }, "type": "array" }, "state": { "description": "The day's state, the worst of its entries; none with no evidence.", "enum": [ "none", "conflict", "conflict_dismissed", "corroborated", "single_source" ], "type": "string" }, "timesheet_drifts": { "deprecated": true, "description": "Deprecated, always empty: a Timesheet day now references the day's care log itself, so the two cannot differ. Kept for one release; read nothing from it.", "items": { "properties": { "care_log_id": { "description": "The care log of the day.", "format": "uuid", "type": "string" }, "conflict_key": { "description": "The drift's key, built from the differing values; dismiss it through POST /api/v1/evidence-dismissals (or the month through POST /api/v1/clients/{id}/evidence/dismissals).", "nullable": true, "type": "string" }, "dismissed": { "description": "Whether it has been dismissed.", "type": "boolean" }, "fields": { "description": "The fields that differ: time_in, time_out or tasks.", "items": { "type": "string" }, "type": "array" }, "only_other": { "description": "Task names done on the other record and not on the timesheet.", "items": { "type": "string" }, "type": "array" }, "only_timesheet": { "description": "Task names done on the timesheet and not on the other record.", "items": { "type": "string" }, "type": "array" }, "other": { "properties": { "tasks": { "description": "The names of the tasks marked done that day.", "items": { "type": "string" }, "type": "array" }, "time_in": { "description": "Time In, Mountain, HH:MM; null when it has none.", "nullable": true, "type": "string" }, "time_out": { "description": "Time Out, Mountain, HH:MM; null when it has none.", "nullable": true, "type": "string" } }, "required": [ "time_in", "time_out", "tasks" ], "title": "ClientMonthEvidenceDriftSide", "type": "object" }, "source": { "description": "What the returned timesheet's day was compared with: the care log, or the Work Order entry and marks assembled from it.", "enum": [ "care_log", "work_order" ], "type": "string" }, "state": { "description": "Whether the warning is open or dismissed.", "enum": [ "conflict", "conflict_dismissed" ], "type": "string" }, "timesheet": { "properties": { "tasks": { "description": "The names of the tasks marked done that day.", "items": { "type": "string" }, "type": "array" }, "time_in": { "description": "Time In, Mountain, HH:MM; null when it has none.", "nullable": true, "type": "string" }, "time_out": { "description": "Time Out, Mountain, HH:MM; null when it has none.", "nullable": true, "type": "string" } }, "required": [ "time_in", "time_out", "tasks" ], "title": "ClientMonthEvidenceDriftSide", "type": "object" }, "timesheet_id": { "description": "The month's returned timesheet.", "format": "uuid", "type": "string" } }, "required": [ "source", "state", "fields", "conflict_key", "care_log_id", "timesheet_id", "dismissed", "timesheet", "other", "only_timesheet", "only_other" ], "title": "ClientMonthEvidenceTimesheetDrift", "type": "object" }, "type": "array" }, "visit_evidence": { "description": "The day's visit evidence: visits when it has one, else paper_scan when a paper-scan care log holds its times, else none.", "enum": [ "visits", "paper_scan", "none" ], "type": "string" } }, "required": [ "date", "state", "visit_evidence", "sources", "care_logs", "timesheet_drifts", "claim_changes", "open_conflict_keys", "dismissals" ], "title": "ClientMonthEvidenceDay", "type": "object" }, "type": "array" }, "month": { "description": "YYYY-MM.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" }, "open_conflicts": { "description": "How many conflicts in the month are open.", "nullable": true, "type": "integer" } }, "required": [ "client_id", "caregiver_id", "month", "open_conflicts", "days" ], "title": "ClientMonthEvidence", "type": "object" }, "ClientMonthEvidenceCareLog": { "properties": { "attestation_method": { "description": "How the client or representative signed it, if they did.", "nullable": true, "type": "string" }, "attestation_skip_reason": { "description": "Why the client could not sign, when the caregiver said.", "nullable": true, "type": "string" }, "care_log_id": { "description": "The care log.", "format": "uuid", "type": "string" }, "comparisons": { "items": { "properties": { "conflict_key": { "description": "The conflict's key, on a conflict only; dismiss it as a visit conflict is dismissed.", "nullable": true, "type": "string" }, "fields": { "description": "On a conflict, the fields that differ: start, end, tasks or attestation.", "items": { "type": "string" }, "type": "array" }, "kind": { "description": "What was compared: the care log's times with the visit evidence, its done tasks with the Work Order's office-typed marks, or the client's signature with the visit's client verification.", "enum": [ "care_log_times", "care_log_tasks", "attestation" ], "type": "string" }, "only_care_log": { "description": "Task codes done on the care log and not marked on the Work Order.", "items": { "type": "string" }, "type": "array" }, "only_work_order": { "description": "Task codes marked on the Work Order and not done on the care log.", "items": { "type": "string" }, "type": "array" }, "state": { "description": "The comparison's state.", "enum": [ "conflict", "conflict_dismissed", "corroborated", "single_source" ], "type": "string" }, "visit_id": { "description": "The visit it was compared with, when one was.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "kind", "state", "fields", "only_care_log", "only_work_order" ], "title": "ClientMonthEvidenceCareLogComparison", "type": "object" }, "type": "array" }, "end": { "description": "Its end (the linked visit's, else entered).", "format": "date-time", "nullable": true, "type": "string" }, "service_type": { "description": "Its service.", "nullable": true, "type": "string" }, "shift_number": { "description": "Its shift of the day.", "nullable": true, "type": "integer" }, "source": { "description": "How the care log was captured.", "enum": [ "hcb_app", "hcb_phone", "office", "paper_scan", "import" ], "type": "string" }, "start": { "description": "Its start (the linked visit's, else entered).", "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "care_log_id", "source", "service_type", "shift_number", "comparisons" ], "title": "ClientMonthEvidenceCareLog", "type": "object" }, "ClientMonthEvidenceCareLogComparison": { "properties": { "conflict_key": { "description": "The conflict's key, on a conflict only; dismiss it as a visit conflict is dismissed.", "nullable": true, "type": "string" }, "fields": { "description": "On a conflict, the fields that differ: start, end, tasks or attestation.", "items": { "type": "string" }, "type": "array" }, "kind": { "description": "What was compared: the care log's times with the visit evidence, its done tasks with the Work Order's office-typed marks, or the client's signature with the visit's client verification.", "enum": [ "care_log_times", "care_log_tasks", "attestation" ], "type": "string" }, "only_care_log": { "description": "Task codes done on the care log and not marked on the Work Order.", "items": { "type": "string" }, "type": "array" }, "only_work_order": { "description": "Task codes marked on the Work Order and not done on the care log.", "items": { "type": "string" }, "type": "array" }, "state": { "description": "The comparison's state.", "enum": [ "conflict", "conflict_dismissed", "corroborated", "single_source" ], "type": "string" }, "visit_id": { "description": "The visit it was compared with, when one was.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "kind", "state", "fields", "only_care_log", "only_work_order" ], "title": "ClientMonthEvidenceCareLogComparison", "type": "object" }, "ClientMonthEvidenceClaimChange": { "properties": { "batch_id": { "description": "The claim's batch.", "format": "uuid", "type": "string" }, "care_log_ids": { "description": "The care logs of the day that changed.", "items": { "type": "string" }, "type": "array" }, "claim_id": { "description": "The claim sent before the day's care log changed.", "format": "uuid", "type": "string" }, "fingerprint": { "description": "The warning's fingerprint; dismiss it through POST /api/v1/revenue-warnings/dismissals with the claim_id as subject_id.", "nullable": true, "type": "string" }, "kind": { "description": "changed_after_claim.", "nullable": true, "type": "string" }, "state": { "description": "Whether the warning is open or dismissed.", "enum": [ "conflict", "conflict_dismissed" ], "type": "string" } }, "required": [ "claim_id", "batch_id", "kind", "fingerprint", "state", "care_log_ids" ], "title": "ClientMonthEvidenceClaimChange", "type": "object" }, "ClientMonthEvidenceDay": { "properties": { "care_logs": { "items": { "properties": { "attestation_method": { "description": "How the client or representative signed it, if they did.", "nullable": true, "type": "string" }, "attestation_skip_reason": { "description": "Why the client could not sign, when the caregiver said.", "nullable": true, "type": "string" }, "care_log_id": { "description": "The care log.", "format": "uuid", "type": "string" }, "comparisons": { "items": { "properties": { "conflict_key": { "description": "The conflict's key, on a conflict only; dismiss it as a visit conflict is dismissed.", "nullable": true, "type": "string" }, "fields": { "description": "On a conflict, the fields that differ: start, end, tasks or attestation.", "items": { "type": "string" }, "type": "array" }, "kind": { "description": "What was compared: the care log's times with the visit evidence, its done tasks with the Work Order's office-typed marks, or the client's signature with the visit's client verification.", "enum": [ "care_log_times", "care_log_tasks", "attestation" ], "type": "string" }, "only_care_log": { "description": "Task codes done on the care log and not marked on the Work Order.", "items": { "type": "string" }, "type": "array" }, "only_work_order": { "description": "Task codes marked on the Work Order and not done on the care log.", "items": { "type": "string" }, "type": "array" }, "state": { "description": "The comparison's state.", "enum": [ "conflict", "conflict_dismissed", "corroborated", "single_source" ], "type": "string" }, "visit_id": { "description": "The visit it was compared with, when one was.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "kind", "state", "fields", "only_care_log", "only_work_order" ], "title": "ClientMonthEvidenceCareLogComparison", "type": "object" }, "type": "array" }, "end": { "description": "Its end (the linked visit's, else entered).", "format": "date-time", "nullable": true, "type": "string" }, "service_type": { "description": "Its service.", "nullable": true, "type": "string" }, "shift_number": { "description": "Its shift of the day.", "nullable": true, "type": "integer" }, "source": { "description": "How the care log was captured.", "enum": [ "hcb_app", "hcb_phone", "office", "paper_scan", "import" ], "type": "string" }, "start": { "description": "Its start (the linked visit's, else entered).", "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "care_log_id", "source", "service_type", "shift_number", "comparisons" ], "title": "ClientMonthEvidenceCareLog", "type": "object" }, "type": "array" }, "claim_changes": { "items": { "properties": { "batch_id": { "description": "The claim's batch.", "format": "uuid", "type": "string" }, "care_log_ids": { "description": "The care logs of the day that changed.", "items": { "type": "string" }, "type": "array" }, "claim_id": { "description": "The claim sent before the day's care log changed.", "format": "uuid", "type": "string" }, "fingerprint": { "description": "The warning's fingerprint; dismiss it through POST /api/v1/revenue-warnings/dismissals with the claim_id as subject_id.", "nullable": true, "type": "string" }, "kind": { "description": "changed_after_claim.", "nullable": true, "type": "string" }, "state": { "description": "Whether the warning is open or dismissed.", "enum": [ "conflict", "conflict_dismissed" ], "type": "string" } }, "required": [ "claim_id", "batch_id", "kind", "fingerprint", "state", "care_log_ids" ], "title": "ClientMonthEvidenceClaimChange", "type": "object" }, "type": "array" }, "date": { "description": "The day (Mountain).", "format": "date", "nullable": true, "type": "string" }, "dismissals": { "items": { "properties": { "conflict_key": { "description": "The conflict dismissed.", "nullable": true, "type": "string" }, "dismissed_at": { "description": "When it was dismissed.", "format": "date-time", "type": "string" }, "dismissed_by": { "description": "Who dismissed it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "dismissed_by_user_id": { "description": "The member who dismissed it; null for an API key.", "format": "uuid", "nullable": true, "type": "string" }, "reason": { "description": "Why it was dismissed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "conflict_key", "dismissed_by", "dismissed_at", "reason" ], "title": "ClientMonthEvidenceDismissal", "type": "object" }, "type": "array" }, "open_conflict_keys": { "description": "The keys of the day's visit, care-log and timesheet-drift conflicts nobody has dismissed.", "items": { "type": "string" }, "type": "array" }, "sources": { "items": { "properties": { "source": { "description": "The evidence source; paper_scan, on a day with no visit, is the times of its paper-scan care log.", "enum": [ "sandata", "other_evv", "hcb_app", "hcb_phone", "office", "paper_scan" ], "type": "string" }, "visits": { "items": { "properties": { "care_log_id": { "description": "On a paper_scan row, the paper-scan care log whose times it shows.", "format": "uuid", "nullable": true, "type": "string" }, "conflict_key": { "description": "The entry's conflict key, on a conflict only.", "nullable": true, "type": "string" }, "end": { "description": "Its billable end; null while it is open.", "format": "date-time", "nullable": true, "type": "string" }, "procedure_code": { "description": "Its procedure code.", "nullable": true, "type": "string" }, "start": { "description": "Its billable start (adjusted, else actual).", "format": "date-time", "nullable": true, "type": "string" }, "state": { "description": "The state of the reconciliation entry the visit is in.", "enum": [ "conflict", "conflict_dismissed", "corroborated", "single_source" ], "type": "string" }, "visit_id": { "description": "The visit; null on a paper_scan row, which has none.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "visit_id", "state" ], "title": "ClientMonthEvidenceVisit", "type": "object" }, "type": "array" } }, "required": [ "source", "visits" ], "title": "ClientMonthEvidenceSource", "type": "object" }, "type": "array" }, "state": { "description": "The day's state, the worst of its entries; none with no evidence.", "enum": [ "none", "conflict", "conflict_dismissed", "corroborated", "single_source" ], "type": "string" }, "timesheet_drifts": { "deprecated": true, "description": "Deprecated, always empty: a Timesheet day now references the day's care log itself, so the two cannot differ. Kept for one release; read nothing from it.", "items": { "properties": { "care_log_id": { "description": "The care log of the day.", "format": "uuid", "type": "string" }, "conflict_key": { "description": "The drift's key, built from the differing values; dismiss it through POST /api/v1/evidence-dismissals (or the month through POST /api/v1/clients/{id}/evidence/dismissals).", "nullable": true, "type": "string" }, "dismissed": { "description": "Whether it has been dismissed.", "type": "boolean" }, "fields": { "description": "The fields that differ: time_in, time_out or tasks.", "items": { "type": "string" }, "type": "array" }, "only_other": { "description": "Task names done on the other record and not on the timesheet.", "items": { "type": "string" }, "type": "array" }, "only_timesheet": { "description": "Task names done on the timesheet and not on the other record.", "items": { "type": "string" }, "type": "array" }, "other": { "properties": { "tasks": { "description": "The names of the tasks marked done that day.", "items": { "type": "string" }, "type": "array" }, "time_in": { "description": "Time In, Mountain, HH:MM; null when it has none.", "nullable": true, "type": "string" }, "time_out": { "description": "Time Out, Mountain, HH:MM; null when it has none.", "nullable": true, "type": "string" } }, "required": [ "time_in", "time_out", "tasks" ], "title": "ClientMonthEvidenceDriftSide", "type": "object" }, "source": { "description": "What the returned timesheet's day was compared with: the care log, or the Work Order entry and marks assembled from it.", "enum": [ "care_log", "work_order" ], "type": "string" }, "state": { "description": "Whether the warning is open or dismissed.", "enum": [ "conflict", "conflict_dismissed" ], "type": "string" }, "timesheet": { "properties": { "tasks": { "description": "The names of the tasks marked done that day.", "items": { "type": "string" }, "type": "array" }, "time_in": { "description": "Time In, Mountain, HH:MM; null when it has none.", "nullable": true, "type": "string" }, "time_out": { "description": "Time Out, Mountain, HH:MM; null when it has none.", "nullable": true, "type": "string" } }, "required": [ "time_in", "time_out", "tasks" ], "title": "ClientMonthEvidenceDriftSide", "type": "object" }, "timesheet_id": { "description": "The month's returned timesheet.", "format": "uuid", "type": "string" } }, "required": [ "source", "state", "fields", "conflict_key", "care_log_id", "timesheet_id", "dismissed", "timesheet", "other", "only_timesheet", "only_other" ], "title": "ClientMonthEvidenceTimesheetDrift", "type": "object" }, "type": "array" }, "visit_evidence": { "description": "The day's visit evidence: visits when it has one, else paper_scan when a paper-scan care log holds its times, else none.", "enum": [ "visits", "paper_scan", "none" ], "type": "string" } }, "required": [ "date", "state", "visit_evidence", "sources", "care_logs", "timesheet_drifts", "claim_changes", "open_conflict_keys", "dismissals" ], "title": "ClientMonthEvidenceDay", "type": "object" }, "ClientMonthEvidenceDismissal": { "properties": { "conflict_key": { "description": "The conflict dismissed.", "nullable": true, "type": "string" }, "dismissed_at": { "description": "When it was dismissed.", "format": "date-time", "type": "string" }, "dismissed_by": { "description": "Who dismissed it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "dismissed_by_user_id": { "description": "The member who dismissed it; null for an API key.", "format": "uuid", "nullable": true, "type": "string" }, "reason": { "description": "Why it was dismissed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "conflict_key", "dismissed_by", "dismissed_at", "reason" ], "title": "ClientMonthEvidenceDismissal", "type": "object" }, "ClientMonthEvidenceDismissed": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "dismissed": { "description": "How many conflicts this request dismissed; 0 when none was open.", "nullable": true, "type": "integer" }, "month": { "description": "YYYY-MM.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } }, "required": [ "client_id", "caregiver_id", "month", "dismissed" ], "title": "ClientMonthEvidenceDismissed", "type": "object" }, "ClientMonthEvidenceDriftSide": { "properties": { "tasks": { "description": "The names of the tasks marked done that day.", "items": { "type": "string" }, "type": "array" }, "time_in": { "description": "Time In, Mountain, HH:MM; null when it has none.", "nullable": true, "type": "string" }, "time_out": { "description": "Time Out, Mountain, HH:MM; null when it has none.", "nullable": true, "type": "string" } }, "required": [ "time_in", "time_out", "tasks" ], "title": "ClientMonthEvidenceDriftSide", "type": "object" }, "ClientMonthEvidenceSource": { "properties": { "source": { "description": "The evidence source; paper_scan, on a day with no visit, is the times of its paper-scan care log.", "enum": [ "sandata", "other_evv", "hcb_app", "hcb_phone", "office", "paper_scan" ], "type": "string" }, "visits": { "items": { "properties": { "care_log_id": { "description": "On a paper_scan row, the paper-scan care log whose times it shows.", "format": "uuid", "nullable": true, "type": "string" }, "conflict_key": { "description": "The entry's conflict key, on a conflict only.", "nullable": true, "type": "string" }, "end": { "description": "Its billable end; null while it is open.", "format": "date-time", "nullable": true, "type": "string" }, "procedure_code": { "description": "Its procedure code.", "nullable": true, "type": "string" }, "start": { "description": "Its billable start (adjusted, else actual).", "format": "date-time", "nullable": true, "type": "string" }, "state": { "description": "The state of the reconciliation entry the visit is in.", "enum": [ "conflict", "conflict_dismissed", "corroborated", "single_source" ], "type": "string" }, "visit_id": { "description": "The visit; null on a paper_scan row, which has none.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "visit_id", "state" ], "title": "ClientMonthEvidenceVisit", "type": "object" }, "type": "array" } }, "required": [ "source", "visits" ], "title": "ClientMonthEvidenceSource", "type": "object" }, "ClientMonthEvidenceTimesheetDrift": { "properties": { "care_log_id": { "description": "The care log of the day.", "format": "uuid", "type": "string" }, "conflict_key": { "description": "The drift's key, built from the differing values; dismiss it through POST /api/v1/evidence-dismissals (or the month through POST /api/v1/clients/{id}/evidence/dismissals).", "nullable": true, "type": "string" }, "dismissed": { "description": "Whether it has been dismissed.", "type": "boolean" }, "fields": { "description": "The fields that differ: time_in, time_out or tasks.", "items": { "type": "string" }, "type": "array" }, "only_other": { "description": "Task names done on the other record and not on the timesheet.", "items": { "type": "string" }, "type": "array" }, "only_timesheet": { "description": "Task names done on the timesheet and not on the other record.", "items": { "type": "string" }, "type": "array" }, "other": { "properties": { "tasks": { "description": "The names of the tasks marked done that day.", "items": { "type": "string" }, "type": "array" }, "time_in": { "description": "Time In, Mountain, HH:MM; null when it has none.", "nullable": true, "type": "string" }, "time_out": { "description": "Time Out, Mountain, HH:MM; null when it has none.", "nullable": true, "type": "string" } }, "required": [ "time_in", "time_out", "tasks" ], "title": "ClientMonthEvidenceDriftSide", "type": "object" }, "source": { "description": "What the returned timesheet's day was compared with: the care log, or the Work Order entry and marks assembled from it.", "enum": [ "care_log", "work_order" ], "type": "string" }, "state": { "description": "Whether the warning is open or dismissed.", "enum": [ "conflict", "conflict_dismissed" ], "type": "string" }, "timesheet": { "properties": { "tasks": { "description": "The names of the tasks marked done that day.", "items": { "type": "string" }, "type": "array" }, "time_in": { "description": "Time In, Mountain, HH:MM; null when it has none.", "nullable": true, "type": "string" }, "time_out": { "description": "Time Out, Mountain, HH:MM; null when it has none.", "nullable": true, "type": "string" } }, "required": [ "time_in", "time_out", "tasks" ], "title": "ClientMonthEvidenceDriftSide", "type": "object" }, "timesheet_id": { "description": "The month's returned timesheet.", "format": "uuid", "type": "string" } }, "required": [ "source", "state", "fields", "conflict_key", "care_log_id", "timesheet_id", "dismissed", "timesheet", "other", "only_timesheet", "only_other" ], "title": "ClientMonthEvidenceTimesheetDrift", "type": "object" }, "ClientMonthEvidenceVisit": { "properties": { "care_log_id": { "description": "On a paper_scan row, the paper-scan care log whose times it shows.", "format": "uuid", "nullable": true, "type": "string" }, "conflict_key": { "description": "The entry's conflict key, on a conflict only.", "nullable": true, "type": "string" }, "end": { "description": "Its billable end; null while it is open.", "format": "date-time", "nullable": true, "type": "string" }, "procedure_code": { "description": "Its procedure code.", "nullable": true, "type": "string" }, "start": { "description": "Its billable start (adjusted, else actual).", "format": "date-time", "nullable": true, "type": "string" }, "state": { "description": "The state of the reconciliation entry the visit is in.", "enum": [ "conflict", "conflict_dismissed", "corroborated", "single_source" ], "type": "string" }, "visit_id": { "description": "The visit; null on a paper_scan row, which has none.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "visit_id", "state" ], "title": "ClientMonthEvidenceVisit", "type": "object" }, "ClientNote": { "description": "A note in a client's communication log: when the agency was in touch, with whom, about which caregivers, and what was said. written_via names the channel that last changed its text: mcp or api, or none for the HomeCareBilling app.", "properties": { "attachment_count": { "description": "How many files are attached; the files are not returned.", "type": "integer" }, "caregiver_ids": { "description": "The agency's caregivers the note concerns (their ids). A caregiver of another agency is refused.", "items": { "format": "uuid", "type": "string" }, "type": "array" }, "client_id": { "description": "The client the note is about.", "format": "uuid", "type": "string" }, "contact_types": { "description": "Every party the contact was with, one or more: the consumer, the case manager, an employee, or other.", "items": { "enum": [ "case_manager", "consumer", "employee", "other" ], "type": "string" }, "minItems": 1, "type": "array" }, "employee_names": { "description": "Employees the note names who are not linked from the caregiver list (caregiver_ids).", "items": { "type": "string" }, "type": "array" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the note was created.", "format": "date-time", "type": "string" }, "manager_initials": { "description": "The initials of who took the note (taken by).", "nullable": true, "type": "string" }, "note_date": { "description": "The day of the contact.", "format": "date", "nullable": true, "type": "string" }, "note_text": { "description": "What was said or done.", "nullable": true, "type": "string" }, "time_of_contact": { "description": "The time of the contact, HH:MM or HH:MM:SS, as typed (no time zone).", "nullable": true, "type": "string" }, "updated_at": { "description": "When the note last changed.", "format": "date-time", "type": "string" }, "written_via": { "description": "The channel that last changed the note's text (mcp, api); none for the HomeCareBilling app.", "nullable": true, "type": "string" } }, "required": [ "id", "client_id", "note_date", "contact_types", "note_text" ], "title": "ClientNote", "type": "object" }, "ClientNoteInput": { "description": "Fields to set. A create needs note_date, contact_types and note_text; manager_initials defaults to the API key's user's initials. An update sends only what changes, and must change something. Notes carry no lock_version.", "properties": { "caregiver_ids": { "description": "The agency's caregivers the note concerns (their ids). A caregiver of another agency is refused.", "items": { "format": "uuid", "type": "string" }, "type": "array" }, "contact_types": { "description": "Every party the contact was with, one or more: the consumer, the case manager, an employee, or other.", "items": { "enum": [ "case_manager", "consumer", "employee", "other" ], "type": "string" }, "minItems": 1, "type": "array" }, "employee_names": { "description": "Employees the note names who are not linked from the caregiver list (caregiver_ids).", "items": { "type": "string" }, "type": "array" }, "manager_initials": { "description": "The initials of who took the note (taken by).", "nullable": true, "type": "string" }, "note_date": { "description": "The day of the contact.", "format": "date", "nullable": false, "type": "string" }, "note_text": { "description": "What was said or done.", "nullable": false, "type": "string" }, "time_of_contact": { "description": "The time of the contact, HH:MM or HH:MM:SS, as typed (no time zone).", "nullable": true, "type": "string" } }, "title": "ClientNoteInput", "type": "object" }, "ClientNotePage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ClientNote" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClientNotePage", "type": "object" }, "ClientOtherService": { "description": "One outside provider serving the client; the scheduler reads its days so a caregiver is not booked over it.", "properties": { "address": { "description": "The provider's address.", "nullable": true, "type": "string", "x-untrusted": "text" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "company": { "description": "The provider's company.", "nullable": true, "type": "string", "x-untrusted": "text" }, "days": { "description": "The weekdays it comes, as su mo tu we th fr sa, in week order.", "items": { "enum": [ "su", "mo", "tu", "we", "th", "fr", "sa" ], "type": "string" }, "type": "array" }, "description": { "description": "What the provider does for the client.", "nullable": true, "type": "string", "x-untrusted": "text" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was recorded.", "format": "date-time", "type": "string" }, "kind": { "description": "Adult day care, a CNA, an RN, PT, or another.", "enum": [ "adult_day", "cna", "rn", "pt", "other" ], "type": "string" }, "phone": { "description": "The provider's phone.", "nullable": true, "type": "string", "x-untrusted": "text" }, "times": { "description": "A time for a chosen day, keyed by its code; a day with none is absent.", "properties": { "fr": { "description": "The time on Friday.", "nullable": true, "type": "string", "x-untrusted": "text" }, "mo": { "description": "The time on Monday.", "nullable": true, "type": "string", "x-untrusted": "text" }, "sa": { "description": "The time on Saturday.", "nullable": true, "type": "string", "x-untrusted": "text" }, "su": { "description": "The time on Sunday.", "nullable": true, "type": "string", "x-untrusted": "text" }, "th": { "description": "The time on Thursday.", "nullable": true, "type": "string", "x-untrusted": "text" }, "tu": { "description": "The time on Tuesday.", "nullable": true, "type": "string", "x-untrusted": "text" }, "we": { "description": "The time on Wednesday.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "type": "object" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "client_id", "kind", "days", "times" ], "title": "ClientOtherService", "type": "object" }, "ClientOtherServiceInput": { "description": "A record with no kind, an unknown day, or a field past its length answers 422 naming the field.", "properties": { "address": { "description": "The provider's address, at most 255 characters.", "nullable": true, "type": "string", "x-untrusted": "text" }, "company": { "description": "The provider's company, at most 255 characters.", "nullable": true, "type": "string", "x-untrusted": "text" }, "days": { "description": "The weekdays it comes, any of su mo tu we th fr sa; stored in week order, each once.", "items": { "enum": [ "su", "mo", "tu", "we", "th", "fr", "sa" ], "type": "string" }, "type": "array" }, "description": { "description": "What the provider does, at most 2000 characters.", "nullable": true, "type": "string", "x-untrusted": "text" }, "kind": { "description": "Required on a create: adult_day, cna, rn, pt or other.", "enum": [ "adult_day", "cna", "rn", "pt", "other" ], "type": "string" }, "phone": { "description": "The provider's phone, at most 255 characters.", "nullable": true, "type": "string", "x-untrusted": "text" }, "times": { "description": "A time for a chosen day, keyed by its code, at most 50 characters; a time for a day not chosen is dropped.", "properties": { "fr": { "description": "The time on Friday.", "nullable": true, "type": "string", "x-untrusted": "text" }, "mo": { "description": "The time on Monday.", "nullable": true, "type": "string", "x-untrusted": "text" }, "sa": { "description": "The time on Saturday.", "nullable": true, "type": "string", "x-untrusted": "text" }, "su": { "description": "The time on Sunday.", "nullable": true, "type": "string", "x-untrusted": "text" }, "th": { "description": "The time on Thursday.", "nullable": true, "type": "string", "x-untrusted": "text" }, "tu": { "description": "The time on Tuesday.", "nullable": true, "type": "string", "x-untrusted": "text" }, "we": { "description": "The time on Wednesday.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "type": "object" } }, "title": "ClientOtherServiceInput", "type": "object" }, "ClientOtherServicePage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ClientOtherService" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClientOtherServicePage", "type": "object" }, "ClientPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Client" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClientPage", "type": "object" }, "ClientRelation": { "description": "\"Maria Lopez is the client's responsible party since 2025-03-01\". ends_on null means current; a current relation of a kind the client holds one of (responsible_party, representative, case_manager, case_manager_supervisor, cma_office) is replaced, never doubled.", "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "contact": { "description": "A responsible party, representative, emergency contact, case manager, physician, pharmacy or key holder. One contact can serve several clients; an edit reaches every one of them.", "properties": { "address": { "nullable": true, "type": "string", "x-untrusted": "text" }, "address_line_2": { "description": "Apartment, suite or unit.", "nullable": true, "type": "string", "x-untrusted": "text" }, "alt_phone": { "description": "A second phone, 10 digits.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver this person is, when the contact is one.", "format": "uuid", "nullable": true, "type": "string" }, "city": { "nullable": true, "type": "string", "x-untrusted": "text" }, "client_ids": { "description": "On a merge's answer only: the clients those relations serve; each one's page shows this contact.", "items": { "format": "uuid", "type": "string" }, "type": "array" }, "email": { "nullable": true, "type": "string" }, "fax": { "description": "10 digits.", "nullable": true, "type": "string" }, "first_name": { "nullable": true, "type": "string", "x-untrusted": "text" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was recorded.", "format": "date-time", "type": "string" }, "last_name": { "nullable": true, "type": "string", "x-untrusted": "text" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "organization": { "description": "The organization, such as the pharmacy's name or a CMA office's county.", "nullable": true, "type": "string", "x-untrusted": "text" }, "phone": { "description": "10 digits.", "nullable": true, "type": "string" }, "relation_ids": { "description": "On a merge's answer only: the relations the merge moved onto this contact.", "items": { "format": "uuid", "type": "string" }, "type": "array" }, "state": { "nullable": true, "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" }, "zip": { "description": "5 digits or ZIP+4.", "nullable": true, "type": "string" } }, "required": [ "id", "lock_version" ], "title": "Contact", "type": "object" }, "contact_id": { "description": "The contact.", "format": "uuid", "type": "string" }, "ends_on": { "description": "Until when; null while current.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was recorded.", "format": "date-time", "type": "string" }, "kind": { "description": "What the person is to the client.", "enum": [ "responsible_party", "representative", "emergency", "case_manager", "case_manager_supervisor", "cma_office", "physician", "pharmacy", "key_holder" ], "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "notes": { "nullable": true, "type": "string", "x-untrusted": "text" }, "rank": { "description": "The order among the client's current relations of the kind: emergency contact 1, 2, 3.", "nullable": true, "type": "integer" }, "relationship": { "description": "The relationship, as a closed value.", "enum": [ "spouse", "parent", "guardian", "child", "sibling", "other_relative", "friend", "professional", "other" ], "nullable": true, "type": "string" }, "relationship_label": { "description": "The relationship as the agency wrote it, such as \"Daughter\".", "nullable": true, "type": "string", "x-untrusted": "text" }, "starts_on": { "description": "Since when; null when the date is not known.", "format": "date", "nullable": true, "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "client_id", "contact_id", "kind", "rank", "lock_version", "contact" ], "title": "ClientRelation", "type": "object" }, "ClientRelationEnd": { "properties": { "ends_on": { "description": "YYYY-MM-DD; today (Mountain) when left out.", "format": "date", "nullable": true, "type": "string" } }, "title": "ClientRelationEnd", "type": "object" }, "ClientRelationInput": { "description": "Name the person by contact_id (a contact already on file, on a client you may open) or give its fields as contact. An unknown kind, or a contact with every field blank, answers 422 naming the field.", "properties": { "contact": { "description": "The new contact's fields, when contact_id is not sent.", "properties": { "address": { "nullable": true, "type": "string", "x-untrusted": "text" }, "address_line_2": { "description": "Apartment, suite or unit.", "nullable": true, "type": "string", "x-untrusted": "text" }, "alt_phone": { "description": "A second phone, 10 digits.", "nullable": true, "type": "string" }, "city": { "nullable": true, "type": "string", "x-untrusted": "text" }, "email": { "nullable": true, "type": "string" }, "fax": { "description": "10 digits.", "nullable": true, "type": "string" }, "first_name": { "nullable": true, "type": "string", "x-untrusted": "text" }, "last_name": { "nullable": true, "type": "string", "x-untrusted": "text" }, "lock_version": { "description": "Required on PATCH /api/v1/contacts/{id}: the value it was read with; if it changed since, the answer is 409 stale_record. Not read inside a new relation's contact.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "organization": { "description": "The organization, such as the pharmacy's name or, for a CMA office, a Colorado county.", "nullable": true, "type": "string", "x-untrusted": "text" }, "phone": { "description": "10 digits.", "nullable": true, "type": "string" }, "state": { "nullable": true, "type": "string" }, "zip": { "description": "5 digits or ZIP+4.", "nullable": true, "type": "string" } }, "title": "ContactInput", "type": "object" }, "contact_id": { "description": "A contact already on file.", "format": "uuid", "nullable": true, "type": "string" }, "kind": { "description": "What the person is to the client.", "enum": [ "responsible_party", "representative", "emergency", "case_manager", "case_manager_supervisor", "cma_office", "physician", "pharmacy", "key_holder" ], "type": "string" }, "notes": { "nullable": true, "type": "string", "x-untrusted": "text" }, "rank": { "description": "The order among the client's current relations of the kind, 1 when left out. A current relation of the same kind and rank is ended by the new one. Current ranks stay contiguous: a rank past the kind's last current one becomes the next free rank, which the response carries.", "nullable": true, "type": "integer" }, "relationship": { "description": "The relationship as a closed value; read from relationship_label when left out.", "enum": [ "spouse", "parent", "guardian", "child", "sibling", "other_relative", "friend", "professional", "other" ], "nullable": true, "type": "string" }, "relationship_label": { "description": "The relationship as the agency writes it, such as \"Daughter\".", "nullable": true, "type": "string", "x-untrusted": "text" }, "replaces": { "description": "The current relation this one replaces, as it was read. Required when the kind is one the client holds one of (responsible_party, representative, case_manager, case_manager_supervisor, cma_office) and the client has a current one; left out, or naming a relation no longer current or at an old lock_version, it answers 409 stale_record and nothing is saved.", "nullable": true, "properties": { "id": { "description": "The current relation's id.", "format": "uuid", "type": "string" }, "lock_version": { "description": "Its lock_version, as read.", "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": [ "id", "lock_version" ], "type": "object" }, "starts_on": { "description": "Since when; today (Mountain) when left out.", "format": "date", "nullable": true, "type": "string" } }, "required": [ "kind" ], "title": "ClientRelationInput", "type": "object" }, "ClientRelationPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ClientRelation" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClientRelationPage", "type": "object" }, "ClientSupervisoryPlan": { "properties": { "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "planned_supervisory_day": { "description": "One day of the month for all four quarters, used only when no per-quarter field is sent. A day needs a month.", "maximum": 31, "minimum": 1, "nullable": true, "type": "integer" }, "planned_supervisory_offset": { "description": "One month of the quarter (1, 2 or 3) for all four quarters, used only when no per-quarter field is sent. null clears every quarter's month.", "maximum": 3, "minimum": 1, "nullable": true, "type": "integer" }, "planned_supervisory_q1_day": { "description": "Quarter 1's planned day of that month, 1-31. null leaves the day unchosen. A day needs planned_supervisory_q1_offset.", "maximum": 31, "minimum": 1, "nullable": true, "type": "integer" }, "planned_supervisory_q1_offset": { "description": "Quarter 1's planned month: 1, 2 or 3, the month of that quarter. null, with planned_supervisory_q1_day null too, leaves quarter 1 unplanned.", "maximum": 3, "minimum": 1, "nullable": true, "type": "integer" }, "planned_supervisory_q2_day": { "description": "Quarter 2's planned day of that month, 1-31. null leaves the day unchosen. A day needs planned_supervisory_q2_offset.", "maximum": 31, "minimum": 1, "nullable": true, "type": "integer" }, "planned_supervisory_q2_offset": { "description": "Quarter 2's planned month: 1, 2 or 3, the month of that quarter. null, with planned_supervisory_q2_day null too, leaves quarter 2 unplanned.", "maximum": 3, "minimum": 1, "nullable": true, "type": "integer" }, "planned_supervisory_q3_day": { "description": "Quarter 3's planned day of that month, 1-31. null leaves the day unchosen. A day needs planned_supervisory_q3_offset.", "maximum": 31, "minimum": 1, "nullable": true, "type": "integer" }, "planned_supervisory_q3_offset": { "description": "Quarter 3's planned month: 1, 2 or 3, the month of that quarter. null, with planned_supervisory_q3_day null too, leaves quarter 3 unplanned.", "maximum": 3, "minimum": 1, "nullable": true, "type": "integer" }, "planned_supervisory_q4_day": { "description": "Quarter 4's planned day of that month, 1-31. null leaves the day unchosen. A day needs planned_supervisory_q4_offset.", "maximum": 31, "minimum": 1, "nullable": true, "type": "integer" }, "planned_supervisory_q4_offset": { "description": "Quarter 4's planned month: 1, 2 or 3, the month of that quarter. null, with planned_supervisory_q4_day null too, leaves quarter 4 unplanned.", "maximum": 3, "minimum": 1, "nullable": true, "type": "integer" } }, "required": [ "lock_version" ], "title": "ClientSupervisoryPlan", "type": "object" }, "ClientWriteResult": { "properties": { "data": { "$ref": "#/components/schemas/Client" }, "warnings": { "description": "What the write was saved despite, one item per finding: medicaid_id_pending on field medicaid_id (a Medicaid client with no Medicaid ID yet, which cannot be billed until it is added); medicaid_id_removed on field medicaid_id (an update erased the Medicaid ID the client had); client_care.status_off_path on field status (an update moved the status to one the usual path does not offer from the old status; the move was saved); client_care.active_without_start_date on field service_start_date (the saved client is active with no service start date: a create, whose status defaults to active, or an update that made it active).", "items": { "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "title": "ClientWriteResult", "type": "object" }, "CloseDocument": { "properties": { "generated_at": { "description": "When it was generated.", "format": "date-time", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "summary": { "description": "The snapshot: client and caregiver, service, month, close reason and date, hours and billing code. Its close notes are left out, as from every Work Order read.", "type": "object" }, "work_order_id": { "description": "The Work Order it closes.", "format": "uuid", "type": "string" } }, "required": [ "id", "work_order_id", "generated_at", "summary" ], "title": "CloseDocument", "type": "object" }, "Complaint": { "description": "A complaint about the agency's care, from intake to resolution. The status moves intake, investigating, interviewing, visiting, following up, resolved; closed from any open phase. A move to a phase fills in its date when none is given.", "properties": { "answers": { "additionalProperties": { "properties": { "answer": { "description": "The answer: text, true or false, or a list of choices." }, "question": { "description": "The question, as the agency asks it.", "nullable": true, "type": "string" } }, "type": "object" }, "description": "The answers recorded, by the agency's question key.", "type": "object" }, "caregiver_id": { "description": "The caregiver it concerns, if any.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_interview_date": { "description": "When the caregiver was interviewed.", "format": "date", "nullable": true, "type": "string" }, "caregiver_name": { "description": "The caregiver's name, as recorded.", "nullable": true, "type": "string" }, "case_manager_followup_date": { "description": "When the case manager followed up.", "format": "date", "nullable": true, "type": "string" }, "client_id": { "description": "The client the complaint is about.", "format": "uuid", "type": "string" }, "client_name": { "description": "The client's name, as recorded on the complaint.", "nullable": true, "type": "string" }, "complainant_name": { "description": "Who complained.", "nullable": true, "type": "string" }, "complaint_date": { "description": "The day it was received.", "format": "date", "nullable": true, "type": "string" }, "complaint_location": { "description": "Where it arose.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the complaint was logged.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "missing_signers": { "description": "Each required line no live signature fills yet, in order; empty when complete or voided.", "items": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "type": "array" }, "proposed_resolution": { "description": "The resolution proposed.", "nullable": true, "type": "string" }, "record_state": { "description": "Where the complaint stands as a signed record (US-101.31): draft (it changes here), signed or amended (locked: only its status moves; corrected with an addendum, or voided and copied into a new draft on the complaint page), voided. signing_complete says whether every required line is signed.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "resolution_date": { "description": "When it was resolved.", "format": "date", "nullable": true, "type": "string" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "signer_name", "method", "signed_at" ], "title": "RecordSignatureSummary", "type": "object" }, "type": "array" }, "signed_at": { "description": "When the first signature locked it; null on a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing_complete": { "description": "True once the record is signed or amended and every required line holds a signature. A signed record can be false: signed by one line, with another still open. A voided record is always false, whatever it holds, and its missing_signers is empty: nothing can sign it, and its replacement is the record to complete.", "type": "boolean" }, "status": { "description": "The complaint's phase.", "enum": [ "intake", "investigating", "interviewing", "visiting", "following_up", "resolved", "closed" ], "type": "string" }, "supervisory_visit_date": { "description": "When the supervisory visit took place.", "format": "date", "nullable": true, "type": "string" }, "updated_at": { "description": "When the complaint last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "client_id", "status" ], "title": "Complaint", "type": "object" }, "ComplaintCreate": { "description": "Logs a complaint at intake for a client of the agency. client_id is required; caregiver_id is optional; complaint_date defaults to today.", "properties": { "answers": { "additionalProperties": true, "description": "Answers by the agency's question key: text, true or false for a yes/no, or a list of choices. An empty answer clears it.", "type": "object" }, "caregiver_id": { "description": "The caregiver it concerns, if any.", "format": "uuid", "nullable": true, "type": "string" }, "client_id": { "description": "The client the complaint is about.", "format": "uuid", "type": "string" }, "complainant_email": { "description": "The complainant's email. Written, never returned.", "nullable": true, "type": "string" }, "complainant_name": { "description": "Who complained.", "nullable": true, "type": "string" }, "complainant_phone": { "description": "The complainant's phone. Written, never returned.", "nullable": true, "type": "string" }, "complaint_date": { "description": "The day it was received.", "format": "date", "nullable": true, "type": "string" }, "complaint_location": { "description": "Where it arose.", "nullable": true, "type": "string" }, "proposed_resolution": { "description": "The resolution proposed.", "nullable": true, "type": "string" } }, "required": [ "client_id" ], "title": "ComplaintCreate", "type": "object" }, "ComplaintInput": { "description": "Fields to change, plus the lock_version read (required). status moves only along the complaint's phases (422 invalid_transition otherwise); a move fills in that phase's date when none is sent or stored.", "properties": { "answers": { "additionalProperties": true, "description": "Answers by the agency's question key: text, true or false for a yes/no, or a list of choices. An empty answer clears it.", "type": "object" }, "caregiver_interview_date": { "description": "When the caregiver was interviewed.", "format": "date", "nullable": true, "type": "string" }, "case_manager_followup_date": { "description": "When the case manager followed up.", "format": "date", "nullable": true, "type": "string" }, "complainant_name": { "description": "Who complained.", "nullable": true, "type": "string" }, "complaint_date": { "description": "The day it was received.", "format": "date", "nullable": true, "type": "string" }, "complaint_location": { "description": "Where it arose.", "nullable": true, "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "proposed_resolution": { "description": "The resolution proposed.", "nullable": true, "type": "string" }, "resolution_date": { "description": "When it was resolved.", "format": "date", "nullable": true, "type": "string" }, "status": { "description": "The complaint's phase.", "enum": [ "intake", "investigating", "interviewing", "visiting", "following_up", "resolved", "closed" ], "type": "string" }, "supervisory_visit_date": { "description": "When the supervisory visit took place.", "format": "date", "nullable": true, "type": "string" } }, "title": "ComplaintInput", "type": "object" }, "ComplaintPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Complaint" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ComplaintPage", "type": "object" }, "ComplaintSignature": { "properties": { "role": { "description": "Whose line to sign: office, the investigator, signed as you. The complainant's line (client when the complainant is the client, representative for anyone else) is drawn on the device in the app and answers 422 drawn_required here.", "enum": [ "client", "representative", "office" ], "type": "string" } }, "required": [ "role" ], "title": "ComplaintSignature", "type": "object" }, "ComplianceAlert": { "description": "One caregiver with the asked-for kind of compliance problem: who, their credential dates, and their training and annual-evaluation standing.", "properties": { "alert_types": { "description": "Every kind of compliance problem the caregiver has (US-109.14), of the seven alert_type values.", "items": { "type": "string" }, "type": "array" }, "caregiver_name": { "description": "The caregiver's name.", "nullable": true, "type": "string" }, "credentials": { "additionalProperties": true, "description": "Credential dates by credential.", "type": "object" }, "evaluation": { "properties": { "last_evaluation_date": { "description": "The last evaluation.", "format": "date", "nullable": true, "type": "string" }, "status": { "description": "The annual evaluation's standing.", "nullable": true, "type": "string" } }, "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "training_status": { "description": "Training standing.", "nullable": true, "type": "string" } }, "required": [ "id" ], "title": "ComplianceAlert", "type": "object" }, "ComplianceAlertPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ComplianceAlert" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ComplianceAlertPage", "type": "object" }, "ConnectedApp": { "properties": { "app_name": { "description": "The AI app.", "nullable": true, "type": "string" }, "connected_at": { "description": "When it was connected (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_used_at": { "description": "Its last request (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "scopes": { "description": "What it may do.", "items": { "type": "string" }, "type": "array" }, "user_email": { "description": "Their email.", "nullable": true, "type": "string" }, "user_id": { "description": "The member who connected it.", "format": "uuid", "type": "string" } }, "required": [ "id", "app_name", "user_id" ], "title": "ConnectedApp", "type": "object" }, "ConnectedAppPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "app_name": { "description": "The AI app.", "nullable": true, "type": "string" }, "connected_at": { "description": "When it was connected (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_used_at": { "description": "Its last request (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "scopes": { "description": "What it may do.", "items": { "type": "string" }, "type": "array" }, "user_email": { "description": "Their email.", "nullable": true, "type": "string" }, "user_id": { "description": "The member who connected it.", "format": "uuid", "type": "string" } }, "required": [ "id", "app_name", "user_id" ], "title": "ConnectedApp", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ConnectedAppPage", "type": "object" }, "ConnectedAppRevoked": { "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "revoked_at": { "description": "When it was revoked (UTC).", "format": "date-time", "type": "string" } }, "required": [ "id", "revoked_at" ], "title": "ConnectedAppRevoked", "type": "object" }, "Consent": { "properties": { "accepted": { "description": "Whether a current consent stands.", "type": "boolean" }, "accepted_at": { "description": "When it was accepted.", "format": "date-time", "nullable": true, "type": "string" }, "accepted_by_id": { "description": "The member who accepted it.", "format": "uuid", "nullable": true, "type": "string" }, "accepted_disclosure_version": { "description": "The disclosure version accepted; null when none stands.", "nullable": true, "type": "integer" }, "disclosure_version": { "description": "The disclosure's current version.", "type": "integer" }, "lapsed": { "description": "Accepted, but the disclosure changed since: accept it again.", "type": "boolean" }, "purpose": { "description": "The consent.", "enum": [ "external_ai_clients", "api_access", "paper_capture", "docusign_agency" ], "type": "string" }, "text": { "description": "The disclosure a member holding agency_settings.manage accepts.", "nullable": true, "type": "string" }, "title": { "description": "The disclosure's title.", "nullable": true, "type": "string" } }, "required": [ "purpose", "accepted", "lapsed", "disclosure_version", "title", "text" ], "title": "Consent", "type": "object" }, "Contact": { "description": "A responsible party, representative, emergency contact, case manager, physician, pharmacy or key holder. One contact can serve several clients; an edit reaches every one of them.", "properties": { "address": { "nullable": true, "type": "string", "x-untrusted": "text" }, "address_line_2": { "description": "Apartment, suite or unit.", "nullable": true, "type": "string", "x-untrusted": "text" }, "alt_phone": { "description": "A second phone, 10 digits.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver this person is, when the contact is one.", "format": "uuid", "nullable": true, "type": "string" }, "city": { "nullable": true, "type": "string", "x-untrusted": "text" }, "client_ids": { "description": "On a merge's answer only: the clients those relations serve; each one's page shows this contact.", "items": { "format": "uuid", "type": "string" }, "type": "array" }, "email": { "nullable": true, "type": "string" }, "fax": { "description": "10 digits.", "nullable": true, "type": "string" }, "first_name": { "nullable": true, "type": "string", "x-untrusted": "text" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was recorded.", "format": "date-time", "type": "string" }, "last_name": { "nullable": true, "type": "string", "x-untrusted": "text" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "organization": { "description": "The organization, such as the pharmacy's name or a CMA office's county.", "nullable": true, "type": "string", "x-untrusted": "text" }, "phone": { "description": "10 digits.", "nullable": true, "type": "string" }, "relation_ids": { "description": "On a merge's answer only: the relations the merge moved onto this contact.", "items": { "format": "uuid", "type": "string" }, "type": "array" }, "state": { "nullable": true, "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" }, "zip": { "description": "5 digits or ZIP+4.", "nullable": true, "type": "string" } }, "required": [ "id", "lock_version" ], "title": "Contact", "type": "object" }, "ContactHistoryEntry": { "description": "One edit of a contact: when it was saved, who saved it, and the names of the fields it changed. The values themselves, old or new, are never returned.", "properties": { "changed_fields": { "description": "The names of the fields the edit changed, sorted.", "items": { "type": "string" }, "type": "array" }, "inserted_at": { "description": "When the edit was saved.", "format": "date-time", "type": "string" }, "user_name": { "description": "The member who saved it, or \"System\" when no member is recorded.", "type": "string" } }, "required": [ "inserted_at", "user_name", "changed_fields" ], "title": "ContactHistoryEntry", "type": "object" }, "ContactHistoryPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ContactHistoryEntry" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ContactHistoryPage", "type": "object" }, "ContactInput": { "description": "The new contact's fields, when contact_id is not sent.", "properties": { "address": { "nullable": true, "type": "string", "x-untrusted": "text" }, "address_line_2": { "description": "Apartment, suite or unit.", "nullable": true, "type": "string", "x-untrusted": "text" }, "alt_phone": { "description": "A second phone, 10 digits.", "nullable": true, "type": "string" }, "city": { "nullable": true, "type": "string", "x-untrusted": "text" }, "email": { "nullable": true, "type": "string" }, "fax": { "description": "10 digits.", "nullable": true, "type": "string" }, "first_name": { "nullable": true, "type": "string", "x-untrusted": "text" }, "last_name": { "nullable": true, "type": "string", "x-untrusted": "text" }, "lock_version": { "description": "Required on PATCH /api/v1/contacts/{id}: the value it was read with; if it changed since, the answer is 409 stale_record. Not read inside a new relation's contact.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "organization": { "description": "The organization, such as the pharmacy's name or, for a CMA office, a Colorado county.", "nullable": true, "type": "string", "x-untrusted": "text" }, "phone": { "description": "10 digits.", "nullable": true, "type": "string" }, "state": { "nullable": true, "type": "string" }, "zip": { "description": "5 digits or ZIP+4.", "nullable": true, "type": "string" } }, "title": "ContactInput", "type": "object" }, "ContactMerge": { "properties": { "loser_ids": { "description": "The contacts that are the same person as the one in the path: each one's relations move to it and it is deleted. 1 to 50 ids, not including the path's.", "items": { "format": "uuid", "type": "string" }, "maxItems": 50, "minItems": 1, "type": "array" } }, "required": [ "loser_ids" ], "title": "ContactMerge", "type": "object" }, "ContactPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Contact" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ContactPage", "type": "object" }, "Critical incidentPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/CriticalIncident" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Critical incidentPage", "type": "object" }, "CriticalIncident": { "description": "A critical incident the agency recorded: what happened, who was told, and how it was followed up. The status moves draft, reported, under investigation, resolved; closed from any active phase.", "properties": { "action_steps_taken": { "description": "What was done at once.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver involved, if any.", "format": "uuid", "nullable": true, "type": "string" }, "client_id": { "description": "The client the incident is about.", "format": "uuid", "type": "string" }, "follow_up_plan": { "description": "The follow-up plan.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "incident_date": { "description": "The day it happened.", "format": "date", "nullable": true, "type": "string" }, "incident_description": { "description": "What happened.", "nullable": true, "type": "string" }, "incident_location": { "description": "Where it happened.", "nullable": true, "type": "string" }, "incident_time": { "description": "The time it happened, HH:MM:SS.", "format": "time", "nullable": true, "type": "string" }, "incident_type": { "description": "The kind of incident.", "enum": [ "death", "abuse_neglect_exploitation", "serious_injury", "property_damage_theft", "medication_management", "other_high_risk" ], "nullable": true, "type": "string" }, "inserted_at": { "description": "When the incident was recorded.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "missing_signers": { "description": "Each required line no live signature fills yet, in order; empty when complete or voided.", "items": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "type": "array" }, "notifications": { "description": "Who was notified: the case manager, family and HCPF.", "properties": { "case_manager": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "notified": { "description": "Whether they were notified; null when not recorded.", "nullable": true, "type": "boolean" } }, "type": "object" }, "family": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "notified": { "description": "Whether they were notified; null when not recorded.", "nullable": true, "type": "boolean" } }, "type": "object" }, "hcpf": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "notified": { "description": "Whether they were notified; null when not recorded.", "nullable": true, "type": "boolean" } }, "type": "object" } }, "type": "object" }, "record_state": { "description": "Where the incident stands as a signed record (US-101.31): draft (it changes here), signed or amended (locked: only its status moves; corrected with an addendum, or voided), voided. signing_complete says whether every required line is signed: the office line (reported by) and the supervisor review.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "referrals": { "description": "The referrals made; a list sent replaces the one stored.", "items": { "properties": { "contact_name": { "description": "The contact's name.", "nullable": true, "type": "string" }, "contact_phone": { "description": "The contact's phone.", "nullable": true, "type": "string" }, "type": { "description": "Who the referral went to.", "enum": [ "law_enforcement", "emergency_department", "ambulance", "fire", "mental_health_provider", "pcp" ], "type": "string" } }, "type": "object" }, "type": "array" }, "referrals_made": { "description": "The referrals made, as text.", "nullable": true, "type": "string" }, "reports": { "description": "The mandatory reports: APS, CPS, CDPHE and law enforcement, plus other reports as text.", "properties": { "aps": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "reported": { "description": "Whether it was reported; null when not recorded.", "nullable": true, "type": "boolean" }, "worker_name": { "description": "The worker who took the report.", "nullable": true, "type": "string" } }, "type": "object" }, "cdphe": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "reported": { "description": "Whether it was reported; null when not recorded.", "nullable": true, "type": "boolean" }, "worker_name": { "description": "The worker who took the report.", "nullable": true, "type": "string" } }, "type": "object" }, "cps": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "reported": { "description": "Whether it was reported; null when not recorded.", "nullable": true, "type": "boolean" }, "worker_name": { "description": "The worker who took the report.", "nullable": true, "type": "string" } }, "type": "object" }, "law_enforcement": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "reported": { "description": "Whether it was reported; null when not recorded.", "nullable": true, "type": "boolean" } }, "type": "object" }, "other": { "description": "Other reports made.", "nullable": true, "type": "string" } }, "type": "object" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "signer_name", "method", "signed_at" ], "title": "RecordSignatureSummary", "type": "object" }, "type": "array" }, "signed_at": { "description": "When the first signature locked it; null on a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing_complete": { "description": "True once the record is signed or amended and every required line holds a signature. A signed record can be false: signed by one line, with another still open. A voided record is always false, whatever it holds, and its missing_signers is empty: nothing can sign it, and its replacement is the record to complete.", "type": "boolean" }, "status": { "description": "The incident's phase.", "enum": [ "draft", "reported", "under_investigation", "resolved", "closed" ], "type": "string" }, "updated_at": { "description": "When the incident last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "client_id", "status" ], "title": "CriticalIncident", "type": "object" }, "CriticalIncidentCreate": { "description": "Reports a draft incident for a client of the agency, reported by the API key's user. client_id and what happened (date, type, location, description, the steps taken at once) are required; caregiver_id is optional.", "properties": { "action_steps_taken": { "description": "What was done at once.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver involved, if any.", "format": "uuid", "nullable": true, "type": "string" }, "client_id": { "description": "The client the incident is about.", "format": "uuid", "type": "string" }, "follow_up_plan": { "description": "The follow-up plan.", "nullable": true, "type": "string" }, "incident_date": { "description": "The day it happened.", "format": "date", "nullable": true, "type": "string" }, "incident_description": { "description": "What happened.", "nullable": true, "type": "string" }, "incident_location": { "description": "Where it happened.", "nullable": true, "type": "string" }, "incident_time": { "description": "The time it happened, HH:MM:SS.", "format": "time", "nullable": true, "type": "string" }, "incident_type": { "description": "The kind of incident.", "enum": [ "death", "abuse_neglect_exploitation", "serious_injury", "property_damage_theft", "medication_management", "other_high_risk" ], "nullable": true, "type": "string" }, "notifications": { "description": "Who was notified: the case manager, family and HCPF.", "properties": { "case_manager": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "notified": { "description": "Whether they were notified; null when not recorded.", "nullable": true, "type": "boolean" } }, "type": "object" }, "family": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "notified": { "description": "Whether they were notified; null when not recorded.", "nullable": true, "type": "boolean" } }, "type": "object" }, "hcpf": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "notified": { "description": "Whether they were notified; null when not recorded.", "nullable": true, "type": "boolean" } }, "type": "object" } }, "type": "object" }, "referrals": { "description": "The referrals made; a list sent replaces the one stored.", "items": { "properties": { "contact_name": { "description": "The contact's name.", "nullable": true, "type": "string" }, "contact_phone": { "description": "The contact's phone.", "nullable": true, "type": "string" }, "type": { "description": "Who the referral went to.", "enum": [ "law_enforcement", "emergency_department", "ambulance", "fire", "mental_health_provider", "pcp" ], "type": "string" } }, "type": "object" }, "type": "array" }, "referrals_made": { "description": "The referrals made, as text.", "nullable": true, "type": "string" }, "reports": { "description": "The mandatory reports: APS, CPS, CDPHE and law enforcement, plus other reports as text.", "properties": { "aps": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "reported": { "description": "Whether it was reported; null when not recorded.", "nullable": true, "type": "boolean" }, "worker_name": { "description": "The worker who took the report.", "nullable": true, "type": "string" } }, "type": "object" }, "cdphe": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "reported": { "description": "Whether it was reported; null when not recorded.", "nullable": true, "type": "boolean" }, "worker_name": { "description": "The worker who took the report.", "nullable": true, "type": "string" } }, "type": "object" }, "cps": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "reported": { "description": "Whether it was reported; null when not recorded.", "nullable": true, "type": "boolean" }, "worker_name": { "description": "The worker who took the report.", "nullable": true, "type": "string" } }, "type": "object" }, "law_enforcement": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "reported": { "description": "Whether it was reported; null when not recorded.", "nullable": true, "type": "boolean" } }, "type": "object" }, "other": { "description": "Other reports made.", "nullable": true, "type": "string" } }, "type": "object" } }, "required": [ "client_id", "incident_date", "incident_type", "incident_location", "incident_description", "action_steps_taken" ], "title": "CriticalIncidentCreate", "type": "object" }, "CriticalIncidentInput": { "description": "Fields to change, plus the lock_version read (required). reports and notifications hold only the legs and fields being changed, merged over what is stored; referrals replaces the list. status moves only along the incident's transitions (422 invalid_transition otherwise).", "properties": { "action_steps_taken": { "description": "What was done at once.", "nullable": true, "type": "string" }, "follow_up_plan": { "description": "The follow-up plan.", "nullable": true, "type": "string" }, "incident_date": { "description": "The day it happened.", "format": "date", "nullable": true, "type": "string" }, "incident_description": { "description": "What happened.", "nullable": true, "type": "string" }, "incident_location": { "description": "Where it happened.", "nullable": true, "type": "string" }, "incident_time": { "description": "The time it happened, HH:MM:SS.", "format": "time", "nullable": true, "type": "string" }, "incident_type": { "description": "The kind of incident.", "enum": [ "death", "abuse_neglect_exploitation", "serious_injury", "property_damage_theft", "medication_management", "other_high_risk" ], "nullable": true, "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "notifications": { "description": "Who was notified: the case manager, family and HCPF.", "properties": { "case_manager": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "notified": { "description": "Whether they were notified; null when not recorded.", "nullable": true, "type": "boolean" } }, "type": "object" }, "family": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "notified": { "description": "Whether they were notified; null when not recorded.", "nullable": true, "type": "boolean" } }, "type": "object" }, "hcpf": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "notified": { "description": "Whether they were notified; null when not recorded.", "nullable": true, "type": "boolean" } }, "type": "object" } }, "type": "object" }, "referrals": { "description": "The referrals made; a list sent replaces the one stored.", "items": { "properties": { "contact_name": { "description": "The contact's name.", "nullable": true, "type": "string" }, "contact_phone": { "description": "The contact's phone.", "nullable": true, "type": "string" }, "type": { "description": "Who the referral went to.", "enum": [ "law_enforcement", "emergency_department", "ambulance", "fire", "mental_health_provider", "pcp" ], "type": "string" } }, "type": "object" }, "type": "array" }, "referrals_made": { "description": "The referrals made, as text.", "nullable": true, "type": "string" }, "reports": { "description": "The mandatory reports: APS, CPS, CDPHE and law enforcement, plus other reports as text.", "properties": { "aps": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "reported": { "description": "Whether it was reported; null when not recorded.", "nullable": true, "type": "boolean" }, "worker_name": { "description": "The worker who took the report.", "nullable": true, "type": "string" } }, "type": "object" }, "cdphe": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "reported": { "description": "Whether it was reported; null when not recorded.", "nullable": true, "type": "boolean" }, "worker_name": { "description": "The worker who took the report.", "nullable": true, "type": "string" } }, "type": "object" }, "cps": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "reported": { "description": "Whether it was reported; null when not recorded.", "nullable": true, "type": "boolean" }, "worker_name": { "description": "The worker who took the report.", "nullable": true, "type": "string" } }, "type": "object" }, "law_enforcement": { "properties": { "date": { "description": "When.", "format": "date", "nullable": true, "type": "string" }, "reported": { "description": "Whether it was reported; null when not recorded.", "nullable": true, "type": "boolean" } }, "type": "object" }, "other": { "description": "Other reports made.", "nullable": true, "type": "string" } }, "type": "object" }, "status": { "description": "The incident's phase.", "enum": [ "draft", "reported", "under_investigation", "resolved", "closed" ], "type": "string" } }, "title": "CriticalIncidentInput", "type": "object" }, "CriticalIncidentSignature": { "properties": { "role": { "description": "Whose line to sign, as you: office (reported by) or supervisor (supervisor review).", "enum": [ "office", "supervisor" ], "type": "string" } }, "required": [ "role" ], "title": "CriticalIncidentSignature", "type": "object" }, "CsvMapping": { "properties": { "mapping": { "additionalProperties": { "type": "string" }, "description": "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.", "type": "object" }, "optional_fields": { "description": "The claim fields an upload may carry.", "items": { "type": "string" }, "type": "array" }, "required_fields": { "description": "The claim fields an upload must carry.", "items": { "type": "string" }, "type": "array" } }, "required": [ "mapping", "required_fields", "optional_fields" ], "title": "CsvMapping", "type": "object" }, "CsvMappingUpdate": { "properties": { "mapping": { "additionalProperties": { "type": "string" }, "description": "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.", "type": "object" } }, "required": [ "mapping" ], "title": "CsvMappingUpdate", "type": "object" }, "DeletedPlanOfCare": { "properties": { "deleted_at": { "description": "When it was deleted (UTC).", "format": "date-time", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "required": [ "id", "deleted_at" ], "title": "DeletedPlanOfCare", "type": "object" }, "DeletedSatisfactionSurvey": { "properties": { "deleted_at": { "description": "When it was deleted (UTC).", "format": "date-time", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "required": [ "id", "deleted_at" ], "title": "DeletedSatisfactionSurvey", "type": "object" }, "DeletedVisit": { "properties": { "data": { "$ref": "#/components/schemas/Visit" }, "meta": { "properties": { "exceptions_dismissed": { "minimum": 0, "type": "integer" }, "links": { "$ref": "#/components/schemas/VisitDeleteLinks" } }, "required": [ "exceptions_dismissed", "links" ], "type": "object" }, "warnings": { "description": "What the delete left resting on the visit, in words (US-116.18), beside meta.links; usually empty. Never a refusal: the visit is deleted. Each id is one of visits.delete_keeps_entry_times (one item for the timesheet entries whose EVV times came from it) and visits.delete_reopens_month (one per Work Order month its signature alone froze, open to edits again).", "items": { "properties": { "fix": { "description": "Where it is fixed, when a page fixes it.", "nullable": true, "properties": { "label": { "description": "What the link says.", "type": "string" }, "path": { "description": "The app route that fixes it.", "type": "string" } }, "required": [ "path", "label" ], "type": "object" }, "id": { "description": "The rule that raised it, stable, e.g. client_care.medicaid_id_pending.", "type": "string" }, "message": { "description": "For a person to read.", "type": "string" } }, "required": [ "id", "message" ], "title": "Warning", "type": "object" }, "type": "array" } }, "required": [ "data", "meta", "warnings" ], "title": "DeletedVisit", "type": "object" }, "Denial": { "description": "A claim Colorado Medicaid did not pay, with the reasons it gave.", "properties": { "adjustment_codes": { "description": "The claim adjustment reason codes (CARC) on the remittance.", "items": { "properties": { "amount": { "description": "The amount adjusted.", "format": "decimal", "nullable": true, "type": "string" }, "group_code": { "description": "The CARC group code, such as CO or PR.", "nullable": true, "type": "string" }, "meaning": { "description": "What Colorado Medicaid's code means, in plain English.", "nullable": true, "type": "string" }, "reason_code": { "description": "The CARC reason code, such as 45.", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "adjustment_reason_codes": { "description": "Claim adjustment reason codes.", "items": { "type": "string" }, "type": "array" }, "batch_id": { "description": "The batch the claim belongs to.", "format": "uuid", "type": "string" }, "charge_amount": { "description": "Amount billed.", "format": "decimal", "nullable": true, "type": "string" }, "claim_frequency": { "description": "CLM05-3: 1 bills a new claim, 7 replaces a paid claim, 8 voids one.", "enum": [ "1", "7", "8" ], "type": "string" }, "diagnosis_code_1": { "nullable": true, "type": "string" }, "diagnosis_code_2": { "nullable": true, "type": "string" }, "diagnosis_code_3": { "nullable": true, "type": "string" }, "diagnosis_code_4": { "nullable": true, "type": "string" }, "duplicate_of_claim_id": { "format": "uuid", "nullable": true, "type": "string" }, "evv_validation_status": { "enum": [ "passed", "warning", "exempt", "overridden" ], "nullable": true, "type": "string" }, "icn": { "description": "HCPF's internal control number.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "investigation_status": { "description": "Where the agency's investigation of a denial stands.", "enum": [ "unresolved", "investigating", "corrected", "resubmitted", "written_off" ], "type": "string" }, "member_id": { "description": "The Medicaid member id.", "nullable": true, "type": "string" }, "modifier_1": { "nullable": true, "type": "string" }, "modifier_2": { "nullable": true, "type": "string" }, "modifier_3": { "nullable": true, "type": "string" }, "modifier_4": { "nullable": true, "type": "string" }, "original_icn": { "description": "The ICN of the paid claim an uploaded replace (7) or void (8) row named.", "nullable": true, "type": "string" }, "paid_amount": { "description": "Amount paid.", "format": "decimal", "nullable": true, "type": "string" }, "paid_date": { "format": "date", "nullable": true, "type": "string" }, "par_number": { "description": "The prior authorization request number.", "nullable": true, "type": "string" }, "patient_account_number": { "nullable": true, "type": "string" }, "patient_first_name": { "nullable": true, "type": "string" }, "patient_last_name": { "nullable": true, "type": "string" }, "payment_status_code": { "nullable": true, "type": "string" }, "place_of_service": { "nullable": true, "type": "string" }, "procedure_code": { "description": "The HCPCS code billed.", "nullable": true, "type": "string" }, "reconciled_at": { "description": "When it was marked reconciled with its payment, if it was.", "format": "date-time", "type": "string" }, "remark_codes": { "description": "The remittance advice remark codes (RARC) on the remittance.", "items": { "properties": { "code": { "description": "The RARC, such as N821.", "nullable": true, "type": "string" }, "meaning": { "description": "What the remark code means, in plain English.", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "replaced_account_number": { "description": "The account number the uploaded file gave this claim, when another row or a claim in progress or paid already used it and it was not kept; patient_account_number is the claim's own.", "nullable": true, "type": "string" }, "resolution_notes": { "description": "The agency's notes on resolving a denial.", "nullable": true, "type": "string", "x-untrusted": "text" }, "row_number": { "description": "Its row in the uploaded file.", "nullable": true, "type": "integer" }, "service_date_from": { "format": "date", "nullable": true, "type": "string" }, "service_date_to": { "format": "date", "nullable": true, "type": "string" }, "status": { "enum": [ "pending", "validated", "invalid", "submitted", "accepted", "not_accepted", "rejected", "paid" ], "type": "string" }, "unit_type": { "nullable": true, "type": "string" }, "units": { "description": "Units billed.", "format": "decimal", "nullable": true, "type": "string" }, "updated_at": { "description": "When the record last changed.", "format": "date-time", "type": "string" }, "validation_errors": { "description": "Why the claim is invalid, if it is.", "items": { "properties": { "code": { "description": "Stable, e.g. required or invalid_format.", "type": "string" }, "field": { "description": "The claim field.", "type": "string" }, "message": { "description": "For a person to read.", "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "id", "batch_id", "status" ], "title": "Denial", "type": "object" }, "DenialPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Denial" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "DenialPage", "type": "object" }, "DocuSignAgencyConnection": { "description": "The agency's own DocuSign connection, null when it never connected. A disconnected one stays here for its history; account_kind says which account a send goes through.", "nullable": true, "properties": { "account_name": { "description": "The DocuSign account's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "connect_hmac_key_set": { "description": "Whether a Connect HMAC key is stored. The key itself is never shown.", "type": "boolean" }, "connect_hmac_key_set_at": { "description": "When the Connect HMAC key was stored.", "format": "date-time", "nullable": true, "type": "string" }, "connected_at": { "description": "When it was connected.", "format": "date-time", "nullable": true, "type": "string" }, "connected_by": { "description": "Who connected it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "disconnected_at": { "description": "When it was disconnected.", "format": "date-time", "nullable": true, "type": "string" }, "docusign_account_id": { "description": "The DocuSign account id.", "nullable": true, "type": "string" }, "docusign_user_email": { "description": "The DocuSign user who connected it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "The agency's own DocuSign connection.", "enum": [ "active", "needs_reconnect", "disconnected" ], "type": "string" } }, "required": [ "status", "connect_hmac_key_set" ], "title": "DocuSignAgencyConnection", "type": "object" }, "DocuSignConnectHmacKey": { "properties": { "hmac_key": { "description": "The HMAC key from the agency's DocuSign Connect configuration, which must be 16 to 256 characters with no spaces. It is stored encrypted and never shown again.", "nullable": true, "type": "string" } }, "required": [ "hmac_key" ], "title": "DocuSignConnectHmacKey", "type": "object" }, "DocuSignEnvelope": { "properties": { "account_kind": { "description": "The DocuSign account it was sent through.", "enum": [ "agency", "platform" ], "type": "string" }, "completed_at": { "description": "When every signer had signed.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The envelope's id.", "format": "uuid", "type": "string" }, "recipients": { "description": "Its signers.", "items": { "properties": { "email": { "description": "Where DocuSign sent the signing link.", "nullable": true, "type": "string", "x-untrusted": "text" }, "name": { "description": "The signer's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "role": { "description": "Who signs.", "enum": [ "client", "representative" ], "type": "string" } }, "required": [ "name", "role", "email" ], "title": "DocuSignEnvelopeRecipient", "type": "object" }, "type": "array" }, "record_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "record_type": { "description": "The record's type.", "nullable": true, "type": "string" }, "sent_at": { "description": "When DocuSign accepted it.", "format": "date-time", "nullable": true, "type": "string" }, "status": { "description": "Where the envelope is.", "enum": [ "sending", "sent", "delivered", "completed", "declined", "voided", "failed", "superseded" ], "type": "string" } }, "required": [ "id", "status", "account_kind", "recipients" ], "title": "DocuSignEnvelope", "type": "object" }, "DocuSignEnvelopePage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "account_kind": { "description": "The DocuSign account it was sent through.", "enum": [ "agency", "platform" ], "type": "string" }, "completed_at": { "description": "When every signer had signed.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The envelope's id.", "format": "uuid", "type": "string" }, "recipients": { "description": "Its signers.", "items": { "properties": { "email": { "description": "Where DocuSign sent the signing link.", "nullable": true, "type": "string", "x-untrusted": "text" }, "name": { "description": "The signer's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "role": { "description": "Who signs.", "enum": [ "client", "representative" ], "type": "string" } }, "required": [ "name", "role", "email" ], "title": "DocuSignEnvelopeRecipient", "type": "object" }, "type": "array" }, "record_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "record_type": { "description": "The record's type.", "nullable": true, "type": "string" }, "sent_at": { "description": "When DocuSign accepted it.", "format": "date-time", "nullable": true, "type": "string" }, "status": { "description": "Where the envelope is.", "enum": [ "sending", "sent", "delivered", "completed", "declined", "voided", "failed", "superseded" ], "type": "string" } }, "required": [ "id", "status", "account_kind", "recipients" ], "title": "DocuSignEnvelope", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "DocuSignEnvelopePage", "type": "object" }, "DocuSignEnvelopeRecipient": { "properties": { "email": { "description": "Where DocuSign sent the signing link.", "nullable": true, "type": "string", "x-untrusted": "text" }, "name": { "description": "The signer's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "role": { "description": "Who signs.", "enum": [ "client", "representative" ], "type": "string" } }, "required": [ "name", "role", "email" ], "title": "DocuSignEnvelopeRecipient", "type": "object" }, "DocuSignEnvelopeSent": { "properties": { "account_kind": { "description": "The DocuSign account it was sent through.", "enum": [ "agency", "platform" ], "type": "string" }, "available_balance_microdollars": { "description": "A send through HomeCareBilling's account: the prepaid credit left after the hold.", "nullable": true, "type": "integer" }, "completed_at": { "description": "When every signer had signed.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The envelope's id.", "format": "uuid", "type": "string" }, "price_microdollars": { "description": "A send through HomeCareBilling's account: the prepaid credit held for it, in millionths of a dollar.", "nullable": true, "type": "integer" }, "recipients": { "description": "Its signers.", "items": { "properties": { "email": { "description": "Where DocuSign sent the signing link.", "nullable": true, "type": "string", "x-untrusted": "text" }, "name": { "description": "The signer's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "role": { "description": "Who signs.", "enum": [ "client", "representative" ], "type": "string" } }, "required": [ "name", "role", "email" ], "title": "DocuSignEnvelopeRecipient", "type": "object" }, "type": "array" }, "record_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "record_type": { "description": "The record's type.", "nullable": true, "type": "string" }, "sent_at": { "description": "When DocuSign accepted it.", "format": "date-time", "nullable": true, "type": "string" }, "status": { "description": "Where the envelope is.", "enum": [ "sending", "sent", "delivered", "completed", "declined", "voided", "failed", "superseded" ], "type": "string" } }, "required": [ "id", "status", "account_kind", "recipients" ], "title": "DocuSignEnvelopeSent", "type": "object" }, "DocuSignOwnKey": { "properties": { "integration_key": { "description": "The integration key of a Private custom integration in the agency's own DocuSign account: must be a UUID, as DocuSign shows it. It is stored encrypted and never shown again.", "nullable": true, "type": "string" }, "secret_key": { "description": "The secret of that integration key, which must be 8 to 256 characters with no spaces. It is stored encrypted and never shown again.", "nullable": true, "type": "string" } }, "required": [ "integration_key", "secret_key" ], "title": "DocuSignOwnKey", "type": "object" }, "DocuSignRecipientInput": { "properties": { "email": { "description": "Where DocuSign sends the signing link.", "nullable": true, "type": "string" }, "name": { "description": "The signer's name, as it prints.", "nullable": true, "type": "string" }, "role": { "description": "Who signs.", "enum": [ "client", "representative" ], "type": "string" } }, "required": [ "role", "name", "email" ], "title": "DocuSignRecipientInput", "type": "object" }, "DocuSignSend": { "properties": { "recipients": { "description": "Who signs. Left out, the record's client and its designated representative, where the record has a representative's line, each with an email on file, as the page's Send dialog offers them.", "items": { "properties": { "email": { "description": "Where DocuSign sends the signing link.", "nullable": true, "type": "string" }, "name": { "description": "The signer's name, as it prints.", "nullable": true, "type": "string" }, "role": { "description": "Who signs.", "enum": [ "client", "representative" ], "type": "string" } }, "required": [ "role", "name", "email" ], "title": "DocuSignRecipientInput", "type": "object" }, "type": "array" } }, "title": "DocuSignSend", "type": "object" }, "DocuSignSettings": { "properties": { "account_kind": { "description": "The account a send goes through: the agency's own, HomeCareBilling's (paid from prepaid credit), or null when neither is available.", "enum": [ "agency", "platform" ], "nullable": true, "type": "string" }, "agency_connection": { "description": "The agency's own DocuSign connection, null when it never connected. A disconnected one stays here for its history; account_kind says which account a send goes through.", "nullable": true, "properties": { "account_name": { "description": "The DocuSign account's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "connect_hmac_key_set": { "description": "Whether a Connect HMAC key is stored. The key itself is never shown.", "type": "boolean" }, "connect_hmac_key_set_at": { "description": "When the Connect HMAC key was stored.", "format": "date-time", "nullable": true, "type": "string" }, "connected_at": { "description": "When it was connected.", "format": "date-time", "nullable": true, "type": "string" }, "connected_by": { "description": "Who connected it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "disconnected_at": { "description": "When it was disconnected.", "format": "date-time", "nullable": true, "type": "string" }, "docusign_account_id": { "description": "The DocuSign account id.", "nullable": true, "type": "string" }, "docusign_user_email": { "description": "The DocuSign user who connected it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "The agency's own DocuSign connection.", "enum": [ "active", "needs_reconnect", "disconnected" ], "type": "string" } }, "required": [ "status", "connect_hmac_key_set" ], "title": "DocuSignAgencyConnection", "type": "object" }, "own_key_set": { "description": "Whether the agency has saved its own DocuSign integration key, which Connect and every token refresh then run under. The key and its secret are never shown.", "type": "boolean" }, "own_key_set_at": { "description": "When the agency's own key was saved.", "format": "date-time", "nullable": true, "type": "string" }, "platform_price_microdollars": { "description": "What one envelope costs in prepaid credit, in millionths of a dollar, when sends go through HomeCareBilling's account.", "nullable": true, "type": "integer" }, "status": { "description": "The agency's own DocuSign connection: agency_connection.status, or none when it never connected.", "enum": [ "active", "needs_reconnect", "disconnected", "none" ], "type": "string" } }, "required": [ "status", "account_kind", "agency_connection", "own_key_set" ], "title": "DocuSignSettings", "type": "object" }, "ElectronicEvidenceCaregivers": { "properties": { "data": { "items": { "properties": { "client_days": { "description": "The caregiver's worked client-days in the month.", "nullable": true, "type": "integer" }, "electronic_days": { "description": "Of those, the days with electronic evidence.", "nullable": true, "type": "integer" }, "id": { "description": "The caregiver; null once the caregiver is removed.", "format": "uuid", "nullable": true, "type": "string" }, "name": { "description": "The caregiver's \"Last, First\".", "nullable": true, "type": "string", "x-untrusted": "text" }, "share": { "description": "electronic_days / client_days, 0 to 1; null with no worked day.", "nullable": true, "type": "number" } }, "required": [ "client_days", "electronic_days" ], "title": "ElectronicEvidenceCaregiversRow", "type": "object" }, "type": "array" }, "total": { "description": "How many rows the month has.", "nullable": true, "type": "integer" } }, "required": [ "data", "total" ], "title": "ElectronicEvidenceCaregivers", "type": "object" }, "ElectronicEvidenceCaregiversRow": { "properties": { "client_days": { "description": "The caregiver's worked client-days in the month.", "nullable": true, "type": "integer" }, "electronic_days": { "description": "Of those, the days with electronic evidence.", "nullable": true, "type": "integer" }, "id": { "description": "The caregiver; null once the caregiver is removed.", "format": "uuid", "nullable": true, "type": "string" }, "name": { "description": "The caregiver's \"Last, First\".", "nullable": true, "type": "string", "x-untrusted": "text" }, "share": { "description": "electronic_days / client_days, 0 to 1; null with no worked day.", "nullable": true, "type": "number" } }, "required": [ "client_days", "electronic_days" ], "title": "ElectronicEvidenceCaregiversRow", "type": "object" }, "ElectronicEvidenceClients": { "properties": { "data": { "items": { "properties": { "client_days": { "description": "The client's worked client-days in the month.", "nullable": true, "type": "integer" }, "electronic_days": { "description": "Of those, the days with electronic evidence.", "nullable": true, "type": "integer" }, "id": { "description": "The client; null once the client is removed.", "format": "uuid", "nullable": true, "type": "string" }, "name": { "description": "The client's \"Last, First\".", "nullable": true, "type": "string", "x-untrusted": "text" }, "share": { "description": "electronic_days / client_days, 0 to 1; null with no worked day.", "nullable": true, "type": "number" } }, "required": [ "client_days", "electronic_days" ], "title": "ElectronicEvidenceClientsRow", "type": "object" }, "type": "array" }, "total": { "description": "How many rows the month has.", "nullable": true, "type": "integer" } }, "required": [ "data", "total" ], "title": "ElectronicEvidenceClients", "type": "object" }, "ElectronicEvidenceClientsRow": { "properties": { "client_days": { "description": "The client's worked client-days in the month.", "nullable": true, "type": "integer" }, "electronic_days": { "description": "Of those, the days with electronic evidence.", "nullable": true, "type": "integer" }, "id": { "description": "The client; null once the client is removed.", "format": "uuid", "nullable": true, "type": "string" }, "name": { "description": "The client's \"Last, First\".", "nullable": true, "type": "string", "x-untrusted": "text" }, "share": { "description": "electronic_days / client_days, 0 to 1; null with no worked day.", "nullable": true, "type": "number" } }, "required": [ "client_days", "electronic_days" ], "title": "ElectronicEvidenceClientsRow", "type": "object" }, "ElectronicEvidenceReport": { "properties": { "caregivers": { "properties": { "data": { "items": { "properties": { "client_days": { "description": "The caregiver's worked client-days in the month.", "nullable": true, "type": "integer" }, "electronic_days": { "description": "Of those, the days with electronic evidence.", "nullable": true, "type": "integer" }, "id": { "description": "The caregiver; null once the caregiver is removed.", "format": "uuid", "nullable": true, "type": "string" }, "name": { "description": "The caregiver's \"Last, First\".", "nullable": true, "type": "string", "x-untrusted": "text" }, "share": { "description": "electronic_days / client_days, 0 to 1; null with no worked day.", "nullable": true, "type": "number" } }, "required": [ "client_days", "electronic_days" ], "title": "ElectronicEvidenceCaregiversRow", "type": "object" }, "type": "array" }, "total": { "description": "How many rows the month has.", "nullable": true, "type": "integer" } }, "required": [ "data", "total" ], "title": "ElectronicEvidenceCaregivers", "type": "object" }, "clients": { "properties": { "data": { "items": { "properties": { "client_days": { "description": "The client's worked client-days in the month.", "nullable": true, "type": "integer" }, "electronic_days": { "description": "Of those, the days with electronic evidence.", "nullable": true, "type": "integer" }, "id": { "description": "The client; null once the client is removed.", "format": "uuid", "nullable": true, "type": "string" }, "name": { "description": "The client's \"Last, First\".", "nullable": true, "type": "string", "x-untrusted": "text" }, "share": { "description": "electronic_days / client_days, 0 to 1; null with no worked day.", "nullable": true, "type": "number" } }, "required": [ "client_days", "electronic_days" ], "title": "ElectronicEvidenceClientsRow", "type": "object" }, "type": "array" }, "total": { "description": "How many rows the month has.", "nullable": true, "type": "integer" } }, "required": [ "data", "total" ], "title": "ElectronicEvidenceClients", "type": "object" }, "computed": { "description": "Whether the month has a snapshot.", "type": "boolean" }, "limit": { "description": "The page size of both tables.", "nullable": true, "type": "integer" }, "month": { "description": "YYYY-MM.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" }, "offset": { "description": "The rows skipped in both tables.", "nullable": true, "type": "integer" }, "trend": { "description": "The 12 months ending with month, newest first.", "items": { "properties": { "client_days": { "description": "Worked client-days; null when not computed.", "nullable": true, "type": "integer" }, "computed": { "description": "False when the month has no snapshot yet: not 0%.", "type": "boolean" }, "electronic_days": { "description": "Of those, the days with electronic evidence; null when not computed.", "nullable": true, "type": "integer" }, "month": { "description": "YYYY-MM.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" }, "share": { "description": "electronic_days / client_days, 0 to 1; null with no worked day.", "nullable": true, "type": "number" } }, "required": [ "month", "computed" ], "title": "ElectronicEvidenceTrendMonth", "type": "object" }, "type": "array" } }, "required": [ "month", "computed", "trend", "caregivers", "clients", "limit", "offset" ], "title": "ElectronicEvidenceReport", "type": "object" }, "ElectronicEvidenceTrendMonth": { "properties": { "client_days": { "description": "Worked client-days; null when not computed.", "nullable": true, "type": "integer" }, "computed": { "description": "False when the month has no snapshot yet: not 0%.", "type": "boolean" }, "electronic_days": { "description": "Of those, the days with electronic evidence; null when not computed.", "nullable": true, "type": "integer" }, "month": { "description": "YYYY-MM.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" }, "share": { "description": "electronic_days / client_days, 0 to 1; null with no worked day.", "nullable": true, "type": "number" } }, "required": [ "month", "computed" ], "title": "ElectronicEvidenceTrendMonth", "type": "object" }, "EligibilityCheck": { "description": "A Medicaid eligibility check the agency recorded for a client and one coverage month.", "properties": { "client_id": { "description": "The client checked.", "format": "uuid", "type": "string" }, "coverage_month": { "description": "The coverage month, 1 to 12.", "nullable": true, "type": "integer" }, "coverage_year": { "description": "The coverage year.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the check was recorded.", "format": "date-time", "type": "string" }, "method": { "enum": [ "hcpf_portal", "x12_271" ], "type": "string" }, "note": { "description": "Free text on the check.", "nullable": true, "type": "string" }, "status": { "enum": [ "eligible", "not_eligible", "unknown" ], "type": "string" }, "verified_on": { "format": "date", "nullable": true, "type": "string" } }, "required": [ "id", "client_id", "status" ], "title": "EligibilityCheck", "type": "object" }, "Error": { "description": "Every error on the API. The details field appears on a 422 and maps each invalid field to its messages.", "properties": { "error": { "properties": { "code": { "description": "Stable, machine-readable, for example not_found or idempotency_key_reused.", "type": "string" }, "details": { "description": "On a 422: each invalid field to a list of its messages. A nested record's field maps to an object of the same shape, and a list of nested records to a list of such objects. On a 409 whose code carries data (for example possible_match), that data, as the operation's 409 response describes it.", "type": "object" }, "message": { "description": "For a person to read.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "title": "Error", "type": "object" }, "EvidenceDismissal": { "properties": { "already_dismissed": { "description": "true when this request found the conflict dismissed already.", "type": "boolean" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "conflict_key": { "description": "The conflict dismissed.", "type": "string" }, "dismissed_at": { "description": "When it was dismissed.", "format": "date-time", "type": "string" }, "dismissed_by_user_id": { "description": "The member who dismissed it.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reason": { "description": "Why it was dismissed.", "type": "string" }, "service_date": { "description": "The day.", "format": "date", "type": "string" } }, "required": [ "id", "client_id", "caregiver_id", "service_date", "conflict_key", "reason", "dismissed_at", "already_dismissed" ], "title": "EvidenceDismissal", "type": "object" }, "EvvCollection": { "properties": { "enrolled_caregivers": { "description": "How many caregivers are enrolled in the EVV pilot.", "nullable": true, "type": "integer" }, "evv_collected_from": { "description": "The agency's calendar day HCB starts collecting EVV; null for no start day.", "format": "date", "nullable": true, "type": "string" }, "evv_rollout": { "description": "Who HCB collects EVV for: off (alerts start with the agency's first clock-in), pilot (enrolled caregivers only) or all.", "enum": [ "off", "pilot", "all" ], "type": "string" } }, "required": [ "evv_rollout", "evv_collected_from", "enrolled_caregivers" ], "title": "EvvCollection", "type": "object" }, "EvvCollectionUpdate": { "properties": { "evv_collected_from": { "description": "The agency's calendar day HCB starts collecting EVV; null for no start day.", "format": "date", "nullable": true, "type": "string" }, "evv_rollout": { "description": "Who HCB collects EVV for: off (alerts start with the agency's first clock-in), pilot (enrolled caregivers only) or all.", "enum": [ "off", "pilot", "all" ], "type": "string" } }, "title": "EvvCollectionUpdate", "type": "object" }, "EvvExceptionRule": { "properties": { "description": { "description": "What it means.", "nullable": true, "type": "string" }, "enabled": { "description": "Whether it raises exceptions.", "type": "boolean" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "rule_type": { "description": "What the rule checks.", "nullable": true, "type": "string" }, "severity": { "description": "How serious its exceptions are.", "enum": [ "warning", "error" ], "type": "string" }, "threshold_unit": { "description": "The threshold's unit.", "nullable": true, "type": "string" }, "threshold_value": { "description": "Its threshold.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "id", "rule_type", "enabled" ], "title": "EvvExceptionRule", "type": "object" }, "EvvExceptionRuleUpdate": { "properties": { "description": { "description": "What it means; null clears it.", "nullable": true, "type": "string" }, "enabled": { "description": "Whether it raises exceptions.", "type": "boolean" }, "severity": { "description": "How serious.", "enum": [ "warning", "error" ], "type": "string" }, "threshold_unit": { "description": "The threshold's unit; null clears it.", "maxLength": 50, "nullable": true, "type": "string" }, "threshold_value": { "description": "The threshold; null clears it.", "format": "decimal", "nullable": true, "type": "string" } }, "title": "EvvExceptionRuleUpdate", "type": "object" }, "EvvExceptionRules": { "items": { "properties": { "description": { "description": "What it means.", "nullable": true, "type": "string" }, "enabled": { "description": "Whether it raises exceptions.", "type": "boolean" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "rule_type": { "description": "What the rule checks.", "nullable": true, "type": "string" }, "severity": { "description": "How serious its exceptions are.", "enum": [ "warning", "error" ], "type": "string" }, "threshold_unit": { "description": "The threshold's unit.", "nullable": true, "type": "string" }, "threshold_value": { "description": "Its threshold.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "id", "rule_type", "enabled" ], "title": "EvvExceptionRule", "type": "object" }, "title": "EvvExceptionRules", "type": "array" }, "EvvExceptionRulesReset": { "items": { "properties": { "description": { "description": "What it means.", "nullable": true, "type": "string" }, "enabled": { "description": "Whether it raises exceptions.", "type": "boolean" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "rule_type": { "description": "What the rule checks.", "nullable": true, "type": "string" }, "severity": { "description": "How serious its exceptions are.", "enum": [ "warning", "error" ], "type": "string" }, "threshold_unit": { "description": "The threshold's unit.", "nullable": true, "type": "string" }, "threshold_value": { "description": "Its threshold.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "id", "rule_type", "enabled" ], "title": "EvvExceptionRule", "type": "object" }, "title": "EvvExceptionRulesReset", "type": "array" }, "FileCompleteness": { "description": "One client's or caregiver's file completeness: each item's status, what is wrong, and its expiry.", "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "items": { "additionalProperties": { "$ref": "#/components/schemas/FileCompletenessItem" }, "description": "Each file item by key.", "type": "object" }, "name": { "description": "The person's name.", "nullable": true, "type": "string" } }, "required": [ "id", "items" ], "title": "FileCompleteness", "type": "object" }, "FileCompletenessItem": { "description": "One item of a person's file: its status, what is wrong with it, and its expiry.", "properties": { "days": { "description": "Days until it expires, or since it expired.", "nullable": true, "type": "integer" }, "details": { "description": "What is wrong.", "nullable": true, "type": "string" }, "expiry_date": { "description": "When it expires.", "format": "date", "nullable": true, "type": "string" }, "status": { "description": "complete, missing, expiring_soon, and so on.", "nullable": true, "type": "string" } }, "required": [ "status" ], "title": "FileCompletenessItem", "type": "object" }, "FileGaps": { "description": "One person with a gap in their file: who, and only the items not complete.", "properties": { "gaps": { "additionalProperties": { "$ref": "#/components/schemas/FileCompletenessItem" }, "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "description": "The person's name.", "nullable": true, "type": "string" } }, "required": [ "id", "gaps" ], "title": "FileGaps", "type": "object" }, "FindingDismissal": { "properties": { "dismissed_at": { "description": "When it was dismissed.", "format": "date-time", "type": "string" }, "dismissed_by_user_id": { "description": "The member who dismissed it.", "format": "uuid", "nullable": true, "type": "string" }, "dismissed_via": { "description": "session (the web app) or token (an API key or connected app).", "enum": [ "session", "token" ], "type": "string" }, "fingerprint": { "description": "The figures dismissed.", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reason": { "description": "Why it was dismissed.", "nullable": true, "type": "string" }, "restored_at": { "description": "When it was shown again; null while it is dismissed.", "format": "date-time", "nullable": true, "type": "string" }, "rule_id": { "description": "The warning's rule, as the warning names it.", "type": "string" }, "subject_date": { "description": "The day, for a warning about one day of its subject.", "format": "date", "nullable": true, "type": "string" }, "subject_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "subject_type": { "description": "What the warning is about, e.g. claim.", "type": "string" } }, "required": [ "id", "rule_id", "subject_type", "subject_id", "fingerprint", "dismissed_via", "dismissed_at" ], "title": "FindingDismissal", "type": "object" }, "HalfMonthSummary": { "description": "One caregiver's half of a month for one client, as the evidence grid shows it, with where its signing stands. A draft's days are re-read from the grid each time it is answered; the first signature freezes them.", "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "client_skip_reason": { "description": "Why the client could not sign, as the caregiver gave it; null when none.", "nullable": true, "type": "string" }, "days": { "description": "The days of the half with care, oldest first.", "items": { "properties": { "date": { "description": "The day.", "format": "date", "nullable": false, "type": "string" }, "hours": { "description": "The day's hours.", "format": "decimal", "nullable": true, "type": "string" }, "shifts": { "description": "The day's shifts.", "items": { "properties": { "end": { "description": "When it ended (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "hours": { "description": "Its hours, to two places.", "format": "decimal", "nullable": true, "type": "string" }, "source": { "description": "Where the shift came from: a care log's source, else the visit's evidence source.", "enum": [ "hcb_app", "hcb_phone", "office", "paper_scan", "import", "sandata", "other_evv", "none" ], "type": "string" }, "start": { "description": "When it started (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "tasks": { "description": "The codes of the tasks done, from a care log; empty otherwise.", "items": { "type": "string" }, "type": "array" } }, "required": [ "source", "hours", "tasks" ], "title": "HalfMonthSummaryShift", "type": "object" }, "type": "array" } }, "required": [ "date", "hours", "shifts" ], "title": "HalfMonthSummaryDay", "type": "object" }, "type": "array" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "period_end": { "description": "The half's last day, the 15th or the month's last.", "format": "date", "nullable": false, "type": "string" }, "period_start": { "description": "The half's first day, the 1st or the 16th.", "format": "date", "nullable": false, "type": "string" }, "record_state": { "description": "draft until the first signature freezes it; then signed, amended or voided (corrected by a new draft).", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "replaces_id": { "description": "The voided summary this draft corrects; null when none.", "format": "uuid", "nullable": true, "type": "string" }, "service_type": { "description": "The service it attests: the client signs one summary per service. null for a shared summary from before that, which covers every service of the pair until it is voided.", "enum": [ "personal_care", "homemaker", "legacy" ], "nullable": true, "type": "string" }, "signatures": { "description": "The live signatures, oldest first, without their images.", "items": { "properties": { "channel": { "description": "Where it was captured.", "nullable": true, "type": "string" }, "id": { "description": "The signature.", "format": "uuid", "type": "string" }, "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin", "voice", "docusign_agency", "docusign_platform", "paper_on_file", "imported" ], "type": "string" }, "role": { "description": "The line signed: caregiver, client or representative.", "nullable": true, "type": "string" }, "signed_at": { "description": "When it was signed.", "format": "date-time", "type": "string" }, "signer_name": { "description": "The name the line is signed under.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "id", "role", "method", "signed_at" ], "title": "HalfMonthSummarySignature", "type": "object" }, "type": "array" }, "signed_at": { "description": "When it was first signed; null for a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing": { "properties": { "caregiver_signed": { "description": "Whether the caregiver's line is signed.", "type": "boolean" }, "client_signed": { "description": "Whether the client's line is signed, by them or a representative.", "type": "boolean" }, "complete": { "description": "Whether every line it needs is signed.", "type": "boolean" }, "hash": { "description": "The hash of the half as answered; send it as expected_content_hash with a signature, so a half that changed since is refused (409 content_changed) rather than signed.", "nullable": true, "type": "string" }, "open": { "description": "Whether that day has come.", "type": "boolean" }, "opens_on": { "description": "The first day the half may be signed: the 15th for a first half, the 20th for a second (Colorado's date).", "format": "date", "nullable": false, "type": "string" } }, "required": [ "opens_on", "open", "hash", "caregiver_signed", "client_signed", "complete" ], "title": "HalfMonthSummarySigning", "type": "object" }, "total_hours": { "description": "The half's hours.", "format": "decimal", "nullable": true, "type": "string" }, "voided_at": { "description": "When it was voided; null unless voided.", "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "id", "client_id", "caregiver_id", "period_start", "period_end", "record_state", "days", "signing", "signatures" ], "title": "HalfMonthSummary", "type": "object" }, "HalfMonthSummaryDay": { "properties": { "date": { "description": "The day.", "format": "date", "nullable": false, "type": "string" }, "hours": { "description": "The day's hours.", "format": "decimal", "nullable": true, "type": "string" }, "shifts": { "description": "The day's shifts.", "items": { "properties": { "end": { "description": "When it ended (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "hours": { "description": "Its hours, to two places.", "format": "decimal", "nullable": true, "type": "string" }, "source": { "description": "Where the shift came from: a care log's source, else the visit's evidence source.", "enum": [ "hcb_app", "hcb_phone", "office", "paper_scan", "import", "sandata", "other_evv", "none" ], "type": "string" }, "start": { "description": "When it started (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "tasks": { "description": "The codes of the tasks done, from a care log; empty otherwise.", "items": { "type": "string" }, "type": "array" } }, "required": [ "source", "hours", "tasks" ], "title": "HalfMonthSummaryShift", "type": "object" }, "type": "array" } }, "required": [ "date", "hours", "shifts" ], "title": "HalfMonthSummaryDay", "type": "object" }, "HalfMonthSummaryShift": { "properties": { "end": { "description": "When it ended (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "hours": { "description": "Its hours, to two places.", "format": "decimal", "nullable": true, "type": "string" }, "source": { "description": "Where the shift came from: a care log's source, else the visit's evidence source.", "enum": [ "hcb_app", "hcb_phone", "office", "paper_scan", "import", "sandata", "other_evv", "none" ], "type": "string" }, "start": { "description": "When it started (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "tasks": { "description": "The codes of the tasks done, from a care log; empty otherwise.", "items": { "type": "string" }, "type": "array" } }, "required": [ "source", "hours", "tasks" ], "title": "HalfMonthSummaryShift", "type": "object" }, "HalfMonthSummarySignature": { "properties": { "channel": { "description": "Where it was captured.", "nullable": true, "type": "string" }, "id": { "description": "The signature.", "format": "uuid", "type": "string" }, "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin", "voice", "docusign_agency", "docusign_platform", "paper_on_file", "imported" ], "type": "string" }, "role": { "description": "The line signed: caregiver, client or representative.", "nullable": true, "type": "string" }, "signed_at": { "description": "When it was signed.", "format": "date-time", "type": "string" }, "signer_name": { "description": "The name the line is signed under.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "id", "role", "method", "signed_at" ], "title": "HalfMonthSummarySignature", "type": "object" }, "HalfMonthSummarySigning": { "properties": { "caregiver_signed": { "description": "Whether the caregiver's line is signed.", "type": "boolean" }, "client_signed": { "description": "Whether the client's line is signed, by them or a representative.", "type": "boolean" }, "complete": { "description": "Whether every line it needs is signed.", "type": "boolean" }, "hash": { "description": "The hash of the half as answered; send it as expected_content_hash with a signature, so a half that changed since is refused (409 content_changed) rather than signed.", "nullable": true, "type": "string" }, "open": { "description": "Whether that day has come.", "type": "boolean" }, "opens_on": { "description": "The first day the half may be signed: the 15th for a first half, the 20th for a second (Colorado's date).", "format": "date", "nullable": false, "type": "string" } }, "required": [ "opens_on", "open", "hash", "caregiver_signed", "client_signed", "complete" ], "title": "HalfMonthSummarySigning", "type": "object" }, "IntakeWarningDismissal": { "properties": { "client_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "dismissed_at": { "description": "When it was dismissed.", "format": "date-time", "type": "string" }, "dismissed_by_id": { "description": "The user who dismissed it; the credential's user here.", "format": "uuid", "type": "string" }, "missing_forms": { "description": "The forms missing when it was dismissed; the warning shows again only when another form goes missing.", "items": { "enum": [ "agency_disclosure_notice", "client_rights_acknowledgement", "emergency_information" ], "type": "string" }, "type": "array" }, "reason": { "description": "The reason given, or null.", "nullable": true, "type": "string" } }, "required": [ "client_id", "missing_forms", "dismissed_at" ], "title": "IntakeWarningDismissal", "type": "object" }, "IntakeWarningDismissalInput": { "properties": { "reason": { "description": "Why the warning is dismissed, e.g. the intake packet was signed on paper and filed. Optional.", "maxLength": 500, "type": "string" } }, "title": "IntakeWarningDismissalInput", "type": "object" }, "Me": { "properties": { "agency_name": { "description": "The agency the caregiver works for.", "nullable": true, "type": "string" }, "email": { "description": "The caregiver's email.", "nullable": true, "type": "string" }, "employee_id": { "description": "The caregiver's employee id at the agency.", "nullable": true, "type": "string" }, "first_name": { "nullable": true, "type": "string" }, "id": { "description": "The caregiver's id.", "format": "uuid", "type": "string" }, "last_name": { "nullable": true, "type": "string" }, "phone": { "description": "The caregiver's cell phone, or home phone.", "nullable": true, "type": "string" }, "unread_notifications": { "description": "Notifications not yet read or dismissed (GET /api/v1/me/notifications).", "minimum": 0, "type": "integer" } }, "required": [ "id", "first_name", "last_name", "employee_id", "agency_name", "phone", "email", "unread_notifications" ], "title": "Me", "type": "object" }, "MeCareLog": { "description": "One of your care logs not finished yet: a draft with no finished_at, inside the app's reach.", "properties": { "attestation_skip_note": { "description": "The caregiver's note on that reason (required for other); null when none.", "nullable": true, "type": "string", "x-untrusted": "text" }, "attestation_skip_reason": { "description": "Why the client did not sign, as the caregiver gave it with Client can't sign (US-101.20); the day stays a draft for the office to collect a signature. null when none was given.", "enum": [ "client_asleep_or_unwell", "client_not_present", "client_declined_to_sign", "client_unable_to_sign", "other" ], "nullable": true, "type": "string" }, "attestation_skipped_at": { "description": "When the reason was given; null when none was.", "format": "date-time", "nullable": true, "type": "string" }, "attestation_skipped_by_caregiver_id": { "description": "The caregiver who gave the reason; null when none was.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "finished_at": { "description": "When it was marked finished; null while open.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was started.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "notes": { "description": "The day's notes.", "nullable": true, "type": "string", "x-untrusted": "text" }, "record_state": { "description": "draft until the client's signature (or a paper signature on file) locks it; then signed, amended (an addendum was signed) or voided (corrected by a new draft).", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "replaces_id": { "description": "The voided care log this draft corrects; null when none.", "format": "uuid", "nullable": true, "type": "string" }, "service_date": { "description": "The day.", "format": "date", "nullable": true, "type": "string" }, "service_type": { "description": "The service, as the Work Order's.", "enum": [ "personal_care", "homemaker", "legacy" ], "type": "string" }, "shift_number": { "description": "The shift, 1 to 4.", "maximum": 4, "minimum": 1, "type": "integer" }, "signed_at": { "description": "When it was first signed; null for a draft.", "format": "date-time", "nullable": true, "type": "string" }, "source": { "description": "Where it was captured: hcb_app, hcb_phone, office, paper_scan or import.", "enum": [ "hcb_app", "hcb_phone", "office", "paper_scan", "import" ], "type": "string" }, "time_in": { "description": "The entered start time, used only when no Visit is linked.", "format": "date-time", "nullable": true, "type": "string" }, "time_out": { "description": "The entered end time, used only when no Visit is linked.", "format": "date-time", "nullable": true, "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" }, "visit_id": { "description": "The Visit linked to the day, whose times are the care log's; null when none.", "format": "uuid", "nullable": true, "type": "string" }, "voided_at": { "description": "When it was voided; null unless voided.", "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "id", "client_id", "caregiver_id", "service_date", "record_state" ], "title": "MeCareLog", "type": "object" }, "MeCareLogAttestation": { "properties": { "capture_method": { "description": "drawn (the default) or initials.", "enum": [ "drawn", "initials" ], "type": "string" }, "expected_content_hash": { "description": "The signing_hash of the day the client read; a day changed since is refused with 409 content_changed.", "nullable": true, "type": "string" }, "image": { "description": "The signature as a base64 PNG, at most 51200 bytes.", "nullable": true, "type": "string" }, "role": { "description": "Who signs: the client (the default) or their representative in their place.", "enum": [ "client", "representative" ], "type": "string" }, "signer_name": { "description": "A representative's attestation by someone the office did not record: their name, signed with no relationship. With neither this nor signer_relation_id, the first listed representative signs, else \"Representative\". A client signs under their own name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "signer_relation_id": { "description": "A representative's attestation: the relation_id of one of the representatives the care log lists, whose name and relationship it is signed under (signer_name is then ignored). One the list does not hold is 422 validation_failed.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "image" ], "title": "MeCareLogAttestation", "type": "object" }, "MeCareLogAttestationSkip": { "properties": { "note": { "description": "The reason in words; required for other.", "nullable": true, "type": "string", "x-untrusted": "text" }, "reason": { "description": "Why the client could not sign.", "enum": [ "client_asleep_or_unwell", "client_not_present", "client_declined_to_sign", "client_unable_to_sign", "other" ], "type": "string" } }, "required": [ "reason" ], "title": "MeCareLogAttestationSkip", "type": "object" }, "MeCareLogDetail": { "description": "One of your care logs: the day, its tasks, its times, the differences from the plan to explain and its live signatures, with the hash to attest it under and the people who may sign in the client's place.", "properties": { "attestation_skip_note": { "description": "The caregiver's note on that reason (required for other); null when none.", "nullable": true, "type": "string", "x-untrusted": "text" }, "attestation_skip_reason": { "description": "Why the client did not sign, as the caregiver gave it with Client can't sign (US-101.20); the day stays a draft for the office to collect a signature. null when none was given.", "enum": [ "client_asleep_or_unwell", "client_not_present", "client_declined_to_sign", "client_unable_to_sign", "other" ], "nullable": true, "type": "string" }, "attestation_skipped_at": { "description": "When the reason was given; null when none was.", "format": "date-time", "nullable": true, "type": "string" }, "attestation_skipped_by_caregiver_id": { "description": "The caregiver who gave the reason; null when none was.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "finished_at": { "description": "When it was marked finished; null while open.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was started.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "notes": { "description": "The day's notes.", "nullable": true, "type": "string", "x-untrusted": "text" }, "record_state": { "description": "draft until the client's signature (or a paper signature on file) locks it; then signed, amended (an addendum was signed) or voided (corrected by a new draft).", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "replaced_by_id": { "description": "The draft that corrects this voided care log; null when none.", "format": "uuid", "nullable": true, "type": "string" }, "replaces_id": { "description": "The voided care log this draft corrects; null when none.", "format": "uuid", "nullable": true, "type": "string" }, "representatives": { "description": "The client's current representative, then its current responsible party, one entry per person; empty when the office recorded neither, or when the client is not one you are assigned to today. Send an entry's relation_id as signer_relation_id with a representative's attestation.", "items": { "$ref": "#/components/schemas/MeRepresentative" }, "type": "array" }, "service_date": { "description": "The day.", "format": "date", "nullable": true, "type": "string" }, "service_type": { "description": "The service, as the Work Order's.", "enum": [ "personal_care", "homemaker", "legacy" ], "type": "string" }, "shift_number": { "description": "The shift, 1 to 4.", "maximum": 4, "minimum": 1, "type": "integer" }, "signatures": { "description": "The live signatures, oldest first, without their images.", "items": { "properties": { "channel": { "description": "Where it was captured.", "nullable": true, "type": "string" }, "evidence_document_id": { "description": "The client's document holding the paper scan; null when none.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The signature.", "format": "uuid", "type": "string" }, "method": { "description": "How it was signed; paper_on_file for a paper signature the office marked as on file.", "enum": [ "drawn", "initials", "typed", "pin", "voice", "docusign_agency", "docusign_platform", "paper_on_file", "imported" ], "type": "string" }, "role": { "description": "The line signed (client, caregiver, ...).", "nullable": true, "type": "string" }, "signed_at": { "description": "When it was signed.", "format": "date-time", "type": "string" }, "signer_name": { "description": "The name the line is signed under.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "id", "role", "method", "signed_at" ], "title": "CareLogSignature", "type": "object" }, "type": "array" }, "signed_at": { "description": "When it was first signed; null for a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing_hash": { "description": "The hash of the day as answered; send it as expected_content_hash with the client's attestation, so a day changed since is refused (409 content_changed) rather than signed.", "nullable": true, "type": "string" }, "source": { "description": "Where it was captured: hcb_app, hcb_phone, office, paper_scan or import.", "enum": [ "hcb_app", "hcb_phone", "office", "paper_scan", "import" ], "type": "string" }, "tasks": { "description": "Planned tasks first, then those added off the plan.", "items": { "properties": { "code": { "description": "The task's code.", "nullable": true, "type": "string" }, "count": { "description": "How many times.", "minimum": 1, "type": "integer" }, "id": { "description": "The care log's task.", "format": "uuid", "type": "string" }, "name": { "description": "The task's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "planned": { "description": "Whether a Work Order in force planned it for the day; false for one added off the plan.", "type": "boolean" }, "reason_code": { "description": "Why it was refused, not needed or added.", "enum": [ "client_declined", "client_not_home", "client_asleep_or_unwell", "done_by_someone_else", "not_needed_today", "client_requested", "care_need_changed", "other" ], "nullable": true, "type": "string" }, "reason_note": { "description": "The reason in words.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "done, refused or not_needed; null when unmarked.", "enum": [ "done", "refused", "not_needed" ], "nullable": true, "type": "string" }, "task_definition_id": { "description": "The agency's task; the {task_id} a mark is sent to (POST /care-logs/{id}/tasks/{task_id}/mark).", "format": "uuid", "type": "string" } }, "required": [ "id", "task_definition_id", "planned", "count" ], "title": "CareLogTask", "type": "object" }, "type": "array" }, "time_in": { "description": "The entered start time, used only when no Visit is linked.", "format": "date-time", "nullable": true, "type": "string" }, "time_out": { "description": "The entered end time, used only when no Visit is linked.", "format": "date-time", "nullable": true, "type": "string" }, "times": { "properties": { "end": { "description": "When it ended.", "format": "date-time", "nullable": true, "type": "string" }, "source": { "description": "visit: the linked Visit's billable times (adjusted, else actual, else scheduled); entered: time_in and time_out, when no Visit is linked.", "enum": [ "visit", "entered" ], "type": "string" }, "start": { "description": "When the day's care started.", "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "source" ], "title": "CareLogTimes", "type": "object" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" }, "visit_id": { "description": "The Visit linked to the day, whose times are the care log's; null when none.", "format": "uuid", "nullable": true, "type": "string" }, "voided_at": { "description": "When it was voided; null unless voided.", "format": "date-time", "nullable": true, "type": "string" }, "warnings": { "description": "The differences from the plan the care log should explain.", "items": { "properties": { "code": { "description": "What differs from the plan. times_missing: no Visit is linked and the time in or time out is empty, so the day counts 0 hours. A care_logs.* code is a finding the save just answered raised: past the weekly or daily caregiver limit, past the Work Order's planned hours, entered times off the clocked Visit by more than 30 minutes, a day the Work Order withdrew, or time out equal to time in (0 hours). None refuses the save.", "enum": [ "times_missing", "planned_unmarked", "reason_missing", "unplanned_without_reason", "care_logs.over_weekly_limit", "care_logs.over_daily_limit", "care_logs.over_plan_ceiling", "care_logs.visit_disagrees", "care_logs.day_withdrawn", "care_logs.zero_length", "care_logs.delivered_after_submit", "care_logs.imported_for_billed_day", "care_logs.typed_times_set_aside", "care_logs.future_date" ], "type": "string" }, "message": { "description": "The warning in words.", "nullable": true, "type": "string" }, "task_definition_id": { "description": "The task it is about; null for a warning about the day (times_missing).", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "code", "message" ], "title": "CareLogWarning", "type": "object" }, "type": "array" } }, "required": [ "id", "client_id", "caregiver_id", "service_date", "record_state", "tasks", "times", "warnings", "signatures", "signing_hash", "representatives" ], "title": "MeCareLogDetail", "type": "object" }, "MeCareLogPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/MeCareLog" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "MeCareLogPage", "type": "object" }, "MeCareLogStart": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "service_date": { "description": "The day.", "format": "date", "nullable": false, "type": "string" }, "service_type": { "description": "The service, as the Work Order's.", "enum": [ "personal_care", "homemaker", "legacy" ], "type": "string" }, "shift_number": { "description": "The shift, 1 to 4 (default 1).", "maximum": 4, "minimum": 1, "type": "integer" }, "visit_id": { "description": "Your Visit to link, with the same client on the same day. Left out, the day's one such Visit is linked when exactly one exists.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "client_id", "service_date", "service_type" ], "title": "MeCareLogStart", "type": "object" }, "MeCareLogTaskAdd": { "properties": { "count": { "description": "How many times; 1 when left out.", "minimum": 1, "type": "integer" }, "reason_code": { "description": "Why it was done off the plan.", "enum": [ "client_declined", "client_not_home", "client_asleep_or_unwell", "done_by_someone_else", "not_needed_today", "client_requested", "care_need_changed", "other" ], "nullable": true, "type": "string" }, "reason_note": { "description": "The reason in words.", "nullable": true, "type": "string", "x-untrusted": "text" }, "task_definition_id": { "description": "The task to add: one of the agency's tasks or a system one.", "format": "uuid", "type": "string" } }, "required": [ "task_definition_id" ], "title": "MeCareLogTaskAdd", "type": "object" }, "MeCareLogTaskMark": { "properties": { "count": { "description": "How many times; unchanged when left out.", "minimum": 1, "type": "integer" }, "expect_status": { "description": "The status the app showed; sent (null included), the mark is refused with 409 stale_record when the task no longer has it, so a clear re-sent after the office changed the task changes nothing.", "enum": [ "done", "refused", "not_needed" ], "nullable": true, "type": "string" }, "reason_code": { "description": "Why a task was refused or not needed; left out or null clears it, as a mark on the screen does.", "enum": [ "client_declined", "client_not_home", "client_asleep_or_unwell", "done_by_someone_else", "not_needed_today", "client_requested", "care_need_changed", "other" ], "nullable": true, "type": "string" }, "reason_note": { "description": "The reason in words; left out or null clears it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "The status to SET: done, refused or not_needed; null clears it. Sending the status the task already has changes nothing.", "enum": [ "done", "refused", "not_needed" ], "nullable": true, "type": "string" } }, "required": [ "status" ], "title": "MeCareLogTaskMark", "type": "object" }, "MeClockEvent": { "properties": { "accuracy": { "description": "GPS accuracy in meters.", "nullable": true, "type": "number" }, "action": { "enum": [ "clock_in", "clock_out" ], "type": "string" }, "captured_at": { "description": "When the phone recorded the clock, in Unix milliseconds: the clock's time, read as clock-in reads it.", "nullable": true, "type": "number" }, "id": { "description": "The app's own id for the event, echoed in synced or failed; resend the same one to retry.", "type": "string" }, "latitude": { "nullable": true, "type": "number" }, "longitude": { "nullable": true, "type": "number" }, "manual": { "description": "true records a manual call.", "type": "boolean" }, "visit_id": { "description": "One of your visits.", "format": "uuid", "type": "string" } }, "required": [ "id", "visit_id", "action" ], "title": "MeClockEvent", "type": "object" }, "MeClockEventsInput": { "properties": { "events": { "description": "At most 100.", "items": { "properties": { "accuracy": { "description": "GPS accuracy in meters.", "nullable": true, "type": "number" }, "action": { "enum": [ "clock_in", "clock_out" ], "type": "string" }, "captured_at": { "description": "When the phone recorded the clock, in Unix milliseconds: the clock's time, read as clock-in reads it.", "nullable": true, "type": "number" }, "id": { "description": "The app's own id for the event, echoed in synced or failed; resend the same one to retry.", "type": "string" }, "latitude": { "nullable": true, "type": "number" }, "longitude": { "nullable": true, "type": "number" }, "manual": { "description": "true records a manual call.", "type": "boolean" }, "visit_id": { "description": "One of your visits.", "format": "uuid", "type": "string" } }, "required": [ "id", "visit_id", "action" ], "title": "MeClockEvent", "type": "object" }, "maxItems": 100, "type": "array" } }, "required": [ "events" ], "title": "MeClockEventsInput", "type": "object" }, "MeClockEventsResult": { "properties": { "failed": { "description": "Events not recorded, each with why; keep them and retry those that can succeed.", "items": { "properties": { "error": { "description": "visit_not_found (not one of your visits within reach), unknown_action, invalid_event (an id that is not a string; answered with a null id), clock_in_required, visit_not_clockable (the visit was closed and the server could not keep the clock: retry), sync_failed (retry), clock_in_failed or clock_out_failed.", "type": "string" }, "id": { "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "synced": { "description": "Ids of events recorded, already recorded, or kept for the office because the visit was closed: drop them.", "items": { "type": "string" }, "type": "array" } }, "required": [ "synced", "failed" ], "title": "MeClockEventsResult", "type": "object" }, "MeClockInput": { "properties": { "accuracy": { "description": "GPS accuracy in meters; a negative one, one over 10,000 km, or a non-number is left out, with unknown_accuracy.", "nullable": true, "type": "number" }, "captured_at": { "description": "When the device recorded the clock, in Unix milliseconds (a fraction is allowed); omit for now. One that is not a number, ahead of now, or before the visit existed (each by more than 5 minutes) is recorded at the server's time with a warning; one sent more than 5 minutes after the time it carries is recorded at that time, with late_sync.", "nullable": true, "type": "number" }, "latitude": { "description": "The device's latitude. With longitude, a pair that is not a location is left out, with invalid_coordinates; none at all records a manual call.", "nullable": true, "type": "number" }, "longitude": { "description": "The device's longitude.", "nullable": true, "type": "number" }, "manual": { "description": "true records a manual call, with no coordinates needed; false, null or left out does not.", "nullable": true, "type": "boolean" } }, "title": "MeClockInput", "type": "object" }, "MeClockResult": { "properties": { "call": { "description": "A clock-in or clock-out recorded on the visit.", "properties": { "call_datetime": { "description": "When the call was made (UTC).", "format": "date-time", "type": "string" }, "call_type": { "description": "How the call was made.", "enum": [ "mobile", "telephony", "fvv", "manual", "other" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "location_description": { "description": "GPS warnings recorded with the call, such as outside the geofence.", "nullable": true, "type": "string" } }, "title": "MeVisitCall", "type": "object" }, "gps_warnings": { "description": "What the clock was recorded with; it was recorded whatever they are.", "items": { "properties": { "message": { "type": "string" }, "type": { "description": "One of no_gps, low_accuracy, moderate_accuracy, suspicious_accuracy, outside_geofence, invalid_coordinates, unknown_accuracy, invalid_captured_at, captured_at_out_of_range, late_sync, manual, outside_schedule, before_clock_in; a later one may be added.", "type": "string" } }, "required": [ "type", "message" ], "type": "object" }, "type": "array" }, "visit": { "properties": { "actual_end_time": { "description": "When you clocked out (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "actual_start_time": { "description": "When you clocked in (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "status": { "enum": [ "scheduled", "in_progress", "completed", "verified", "submitted", "matched", "rejected", "cancelled" ], "type": "string" } }, "required": [ "id", "status" ], "type": "object" } }, "required": [ "call", "gps_warnings", "visit" ], "title": "MeClockResult", "type": "object" }, "MeDevice": { "properties": { "current": { "description": "Whether this is the device making the request.", "type": "boolean" }, "device_id": { "description": "The app's id for the device, sent at sign-in.", "nullable": true, "type": "string" }, "expires_at": { "description": "When the sign-in ends unless renewed.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the device signed in.", "format": "date-time", "type": "string" }, "last_seen_at": { "description": "When the device was last used.", "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "id", "device_id", "current", "inserted_at" ], "title": "MeDevice", "type": "object" }, "MeDevicePage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/MeDevice" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "MeDevicePage", "type": "object" }, "MeHalfMonthSummary": { "description": "Your half-month summary as the app opens it, with the people who may sign the client's line in their place.", "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "client_skip_reason": { "description": "Why the client could not sign, as the caregiver gave it; null when none.", "nullable": true, "type": "string" }, "days": { "description": "The days of the half with care, oldest first.", "items": { "properties": { "date": { "description": "The day.", "format": "date", "nullable": false, "type": "string" }, "hours": { "description": "The day's hours.", "format": "decimal", "nullable": true, "type": "string" }, "shifts": { "description": "The day's shifts.", "items": { "properties": { "end": { "description": "When it ended (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "hours": { "description": "Its hours, to two places.", "format": "decimal", "nullable": true, "type": "string" }, "source": { "description": "Where the shift came from: a care log's source, else the visit's evidence source.", "enum": [ "hcb_app", "hcb_phone", "office", "paper_scan", "import", "sandata", "other_evv", "none" ], "type": "string" }, "start": { "description": "When it started (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "tasks": { "description": "The codes of the tasks done, from a care log; empty otherwise.", "items": { "type": "string" }, "type": "array" } }, "required": [ "source", "hours", "tasks" ], "title": "HalfMonthSummaryShift", "type": "object" }, "type": "array" } }, "required": [ "date", "hours", "shifts" ], "title": "HalfMonthSummaryDay", "type": "object" }, "type": "array" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "period_end": { "description": "The half's last day, the 15th or the month's last.", "format": "date", "nullable": false, "type": "string" }, "period_start": { "description": "The half's first day, the 1st or the 16th.", "format": "date", "nullable": false, "type": "string" }, "record_state": { "description": "draft until the first signature freezes it; then signed, amended or voided (corrected by a new draft).", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "replaces_id": { "description": "The voided summary this draft corrects; null when none.", "format": "uuid", "nullable": true, "type": "string" }, "representatives": { "description": "The client's current representative, then its current responsible party, one entry per person; empty when the office recorded neither, or when the client is not one you are assigned to today.", "items": { "$ref": "#/components/schemas/MeRepresentative" }, "type": "array" }, "service_type": { "description": "The service it attests: the client signs one summary per service. null for a shared summary from before that, which covers every service of the pair until it is voided.", "enum": [ "personal_care", "homemaker", "legacy" ], "nullable": true, "type": "string" }, "signatures": { "description": "The live signatures, oldest first, without their images.", "items": { "properties": { "channel": { "description": "Where it was captured.", "nullable": true, "type": "string" }, "id": { "description": "The signature.", "format": "uuid", "type": "string" }, "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin", "voice", "docusign_agency", "docusign_platform", "paper_on_file", "imported" ], "type": "string" }, "role": { "description": "The line signed: caregiver, client or representative.", "nullable": true, "type": "string" }, "signed_at": { "description": "When it was signed.", "format": "date-time", "type": "string" }, "signer_name": { "description": "The name the line is signed under.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "id", "role", "method", "signed_at" ], "title": "HalfMonthSummarySignature", "type": "object" }, "type": "array" }, "signed_at": { "description": "When it was first signed; null for a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing": { "properties": { "caregiver_signed": { "description": "Whether the caregiver's line is signed.", "type": "boolean" }, "client_signed": { "description": "Whether the client's line is signed, by them or a representative.", "type": "boolean" }, "complete": { "description": "Whether every line it needs is signed.", "type": "boolean" }, "hash": { "description": "The hash of the half as answered; send it as expected_content_hash with a signature, so a half that changed since is refused (409 content_changed) rather than signed.", "nullable": true, "type": "string" }, "open": { "description": "Whether that day has come.", "type": "boolean" }, "opens_on": { "description": "The first day the half may be signed: the 15th for a first half, the 20th for a second (Colorado's date).", "format": "date", "nullable": false, "type": "string" } }, "required": [ "opens_on", "open", "hash", "caregiver_signed", "client_signed", "complete" ], "title": "HalfMonthSummarySigning", "type": "object" }, "total_hours": { "description": "The half's hours.", "format": "decimal", "nullable": true, "type": "string" }, "voided_at": { "description": "When it was voided; null unless voided.", "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "id", "client_id", "caregiver_id", "period_start", "period_end", "record_state", "days", "signing", "signatures", "representatives" ], "title": "MeHalfMonthSummary", "type": "object" }, "MeHalfMonthSummaryClientSkip": { "properties": { "reason": { "description": "Why the client could not sign.", "enum": [ "client_asleep_or_unwell", "client_not_present", "client_declined_to_sign", "client_unable_to_sign", "other" ], "type": "string" } }, "required": [ "reason" ], "title": "MeHalfMonthSummaryClientSkip", "type": "object" }, "MeHalfMonthSummaryDraft": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "period_start": { "description": "The half's first day, YYYY-MM-DD: the 1st or the 16th.", "format": "date", "nullable": false, "type": "string" }, "service_type": { "description": "The service the summary attests: the client signs one per service. Left out, the half's only service; a half with care for two services, or with none recorded and no summary yet, is 422 validation_failed.", "enum": [ "personal_care", "homemaker", "legacy" ], "nullable": true, "type": "string" } }, "required": [ "client_id", "period_start" ], "title": "MeHalfMonthSummaryDraft", "type": "object" }, "MeHalfMonthSummarySignature": { "properties": { "capture_method": { "description": "drawn (the default) or initials.", "enum": [ "drawn", "initials" ], "type": "string" }, "expected_content_hash": { "description": "The signing.hash of the half the signer read; a half changed since is refused with 409 content_changed.", "nullable": true, "type": "string" }, "image": { "description": "The signature as a base64 PNG, at most 51200 bytes.", "nullable": true, "type": "string" }, "role": { "description": "The line signed: yours first, then the client's or their representative's.", "enum": [ "caregiver", "client", "representative" ], "type": "string" }, "signer_name": { "description": "A representative's line signed by someone the office did not record: their name, signed with no relationship. With neither this nor signer_relation_id, the first listed representative signs, else \"Representative\".", "nullable": true, "type": "string", "x-untrusted": "text" }, "signer_relation_id": { "description": "A representative's line: the relation_id of one of the representatives the summary lists, whose name and relationship it is signed under (signer_name is then ignored). One the list does not hold is 422 validation_failed.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "role", "image" ], "title": "MeHalfMonthSummarySignature", "type": "object" }, "MeNotification": { "properties": { "body": { "nullable": true, "type": "string" }, "dismissed_at": { "description": "When it was dismissed.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was sent.", "format": "date-time", "type": "string" }, "read_at": { "description": "When it was read.", "format": "date-time", "nullable": true, "type": "string" }, "title": { "nullable": true, "type": "string" }, "type": { "enum": [ "schedule_change", "admin_message", "exception_alert", "assignment_update", "visit_reminder" ], "type": "string" } }, "required": [ "id", "type", "title" ], "title": "MeNotification", "type": "object" }, "MeNotificationPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/MeNotification" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "MeNotificationPage", "type": "object" }, "MeNotificationsMarked": { "properties": { "marked": { "minimum": 0, "type": "integer" } }, "required": [ "marked" ], "title": "MeNotificationsMarked", "type": "object" }, "MePinChange": { "description": "The caregiver's current PIN and the new one.", "properties": { "current_pin": { "description": "The PIN the caregiver signs in with now.", "type": "string" }, "new_pin": { "description": "Six digits, not repeated or sequential.", "pattern": "^[0-9]{6}$", "type": "string" } }, "required": [ "current_pin", "new_pin" ], "title": "MePinChange", "type": "object" }, "MePushToken": { "properties": { "platform": { "enum": [ "ios", "android" ], "type": "string" }, "registered_at": { "description": "When this device's token was last registered.", "format": "date-time", "type": "string" } }, "required": [ "platform", "registered_at" ], "title": "MePushToken", "type": "object" }, "MePushTokenInput": { "properties": { "platform": { "enum": [ "ios", "android" ], "type": "string" }, "token": { "maxLength": 4096, "minLength": 8, "type": "string" } }, "required": [ "platform", "token" ], "title": "MePushTokenInput", "type": "object" }, "MeRefusedClock": { "properties": { "assignment": { "description": "A clock-in or a clock-out.", "enum": [ "time_in", "time_out" ], "type": "string" }, "captured_at": { "description": "When you clocked (UTC).", "format": "date-time", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reviewed_at": { "description": "When the office handled it (UTC); null until then.", "format": "date-time", "nullable": true, "type": "string" }, "service_date": { "description": "The visit's day of service.", "format": "date", "nullable": true, "type": "string" }, "visit_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "visit_status": { "description": "The visit's status when it refused the clock.", "enum": [ "scheduled", "in_progress", "completed", "verified", "submitted", "matched", "rejected", "cancelled" ], "type": "string" } }, "required": [ "id", "visit_id", "service_date", "assignment", "captured_at", "visit_status" ], "title": "MeRefusedClock", "type": "object" }, "MeRefusedClockPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/MeRefusedClock" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "MeRefusedClockPage", "type": "object" }, "MeRepresentative": { "description": "A person the office recorded as the client's representative or responsible party. Send relation_id as signer_relation_id to sign a representative's line as them.", "properties": { "name": { "description": "The person's name, or the organization's when it has no name.", "nullable": false, "type": "string" }, "relation_id": { "description": "The relation the office recorded.", "format": "uuid", "type": "string" }, "relationship_label": { "description": "Their relationship to the client, as the office wrote it.", "nullable": true, "type": "string" } }, "required": [ "relation_id", "name", "relationship_label" ], "title": "MeRepresentative", "type": "object" }, "MeSignature": { "properties": { "captured_at": { "description": "When it was signed (UTC).", "format": "date-time", "type": "string" }, "captured_by_caregiver_id": { "description": "The record's id.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "signature_type": { "description": "A drawn signature or initials.", "enum": [ "drawn", "initials" ], "type": "string" }, "signer_name": { "description": "The signer's name as given.", "nullable": true, "type": "string" }, "signer_type": { "description": "Who signed.", "enum": [ "client", "caregiver" ], "type": "string" }, "updated_at": { "description": "When the server stored this capture (UTC), a replacement's included.", "format": "date-time", "type": "string" }, "visit_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "required": [ "id", "visit_id", "signer_type", "signature_type", "signer_name", "captured_at" ], "title": "MeSignature", "type": "object" }, "MeSignatureInput": { "properties": { "captured_at": { "description": "When it was signed, in Unix milliseconds; omit for now.", "nullable": true, "type": "number" }, "image": { "description": "The signature as a base64 PNG of at most 51200 bytes once decoded.", "format": "byte", "type": "string" }, "replace": { "description": "true replaces the visit's signature from this signer; otherwise a second one answers 200 with the one it holds.", "type": "boolean" }, "signature_type": { "enum": [ "drawn", "initials" ], "type": "string" }, "signer_name": { "description": "The signer's name.", "type": "string" }, "signer_type": { "enum": [ "client", "caregiver" ], "type": "string" } }, "required": [ "signer_type", "signature_type", "signer_name", "image" ], "title": "MeSignatureInput", "type": "object" }, "MeVisit": { "properties": { "actual_end_time": { "description": "When you clocked out (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "actual_start_time": { "description": "When you clocked in (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "client": { "description": "Who the visit serves and where, for the caregiver on the way there.", "properties": { "address": { "nullable": true, "type": "string" }, "address_line_2": { "nullable": true, "type": "string" }, "city": { "nullable": true, "type": "string" }, "first_name": { "nullable": true, "type": "string" }, "geofence_radius_meters": { "description": "How close to the home a clock-in counts as at the home.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "nullable": true, "type": "string" }, "latitude": { "description": "The home's latitude, for the geofence.", "format": "decimal", "nullable": true, "type": "string" }, "longitude": { "description": "The home's longitude, for the geofence.", "format": "decimal", "nullable": true, "type": "string" }, "state": { "nullable": true, "type": "string" }, "zip": { "nullable": true, "type": "string" } }, "title": "MeVisitClient", "type": "object" }, "deleted_at": { "description": "When the agency removed the visit (UTC); only read by id.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "procedure_code": { "description": "The service's HCPCS code.", "nullable": true, "type": "string" }, "scheduled_end_time": { "description": "Scheduled end (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "scheduled_start_time": { "description": "Scheduled start (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "service_date": { "description": "The day of service.", "format": "date", "nullable": true, "type": "string" }, "status": { "description": "Where the visit is in its lifecycle.", "enum": [ "scheduled", "in_progress", "completed", "verified", "submitted", "matched", "rejected", "cancelled" ], "type": "string" }, "visit_type": { "enum": [ "standard", "group", "live_in", "respite", "companion", "travel" ], "type": "string" } }, "required": [ "id", "service_date", "status", "client" ], "title": "MeVisit", "type": "object" }, "MeVisitCall": { "description": "A clock-in or clock-out recorded on the visit.", "properties": { "call_datetime": { "description": "When the call was made (UTC).", "format": "date-time", "type": "string" }, "call_type": { "description": "How the call was made.", "enum": [ "mobile", "telephony", "fvv", "manual", "other" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "location_description": { "description": "GPS warnings recorded with the call, such as outside the geofence.", "nullable": true, "type": "string" } }, "title": "MeVisitCall", "type": "object" }, "MeVisitClient": { "description": "Who the visit serves and where, for the caregiver on the way there.", "properties": { "address": { "nullable": true, "type": "string" }, "address_line_2": { "nullable": true, "type": "string" }, "city": { "nullable": true, "type": "string" }, "first_name": { "nullable": true, "type": "string" }, "geofence_radius_meters": { "description": "How close to the home a clock-in counts as at the home.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "nullable": true, "type": "string" }, "latitude": { "description": "The home's latitude, for the geofence.", "format": "decimal", "nullable": true, "type": "string" }, "longitude": { "description": "The home's longitude, for the geofence.", "format": "decimal", "nullable": true, "type": "string" }, "state": { "nullable": true, "type": "string" }, "zip": { "nullable": true, "type": "string" } }, "title": "MeVisitClient", "type": "object" }, "MeVisitDetail": { "properties": { "actual_end_time": { "description": "When you clocked out (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "actual_start_time": { "description": "When you clocked in (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "client": { "description": "Who the visit serves and where, for the caregiver on the way there.", "properties": { "address": { "nullable": true, "type": "string" }, "address_line_2": { "nullable": true, "type": "string" }, "city": { "nullable": true, "type": "string" }, "first_name": { "nullable": true, "type": "string" }, "geofence_radius_meters": { "description": "How close to the home a clock-in counts as at the home.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "nullable": true, "type": "string" }, "latitude": { "description": "The home's latitude, for the geofence.", "format": "decimal", "nullable": true, "type": "string" }, "longitude": { "description": "The home's longitude, for the geofence.", "format": "decimal", "nullable": true, "type": "string" }, "state": { "nullable": true, "type": "string" }, "zip": { "nullable": true, "type": "string" } }, "title": "MeVisitClient", "type": "object" }, "deleted_at": { "description": "When the agency removed the visit (UTC); only read by id.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "procedure_code": { "description": "The service's HCPCS code.", "nullable": true, "type": "string" }, "scheduled_end_time": { "description": "Scheduled end (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "scheduled_start_time": { "description": "Scheduled start (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "service_date": { "description": "The day of service.", "format": "date", "nullable": true, "type": "string" }, "status": { "description": "Where the visit is in its lifecycle.", "enum": [ "scheduled", "in_progress", "completed", "verified", "submitted", "matched", "rejected", "cancelled" ], "type": "string" }, "time_in": { "description": "The clock-in, once recorded.", "nullable": true, "properties": { "call_datetime": { "description": "When the call was made (UTC).", "format": "date-time", "type": "string" }, "call_type": { "description": "How the call was made.", "enum": [ "mobile", "telephony", "fvv", "manual", "other" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "location_description": { "description": "GPS warnings recorded with the call, such as outside the geofence.", "nullable": true, "type": "string" } }, "title": "MeVisitCall", "type": "object" }, "time_out": { "description": "The clock-out, once recorded.", "nullable": true, "properties": { "call_datetime": { "description": "When the call was made (UTC).", "format": "date-time", "type": "string" }, "call_type": { "description": "How the call was made.", "enum": [ "mobile", "telephony", "fvv", "manual", "other" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "location_description": { "description": "GPS warnings recorded with the call, such as outside the geofence.", "nullable": true, "type": "string" } }, "title": "MeVisitCall", "type": "object" }, "visit_type": { "enum": [ "standard", "group", "live_in", "respite", "companion", "travel" ], "type": "string" } }, "required": [ "id", "service_date", "status", "client", "time_in", "time_out" ], "title": "MeVisitDetail", "type": "object" }, "MeVisitPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/MeVisit" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "MeVisitPage", "type": "object" }, "Meeting minutesPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/MeetingMinutes" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Meeting minutesPage", "type": "object" }, "MeetingMinutes": { "description": "One meeting's minutes. A draft until finalized; finalized minutes are not changed.", "properties": { "adjourned_by": { "description": "Who adjourned it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "adjourned_time": { "description": "When it was adjourned, HH:MM:SS.", "format": "time", "nullable": true, "type": "string" }, "attendees": { "description": "Who was invited.", "items": { "properties": { "name": { "description": "Who attended.", "type": "string", "x-untrusted": "text" }, "present": { "description": "\"true\" when they were present.", "type": "string" }, "title": { "description": "Their title.", "type": "string", "x-untrusted": "text" } }, "type": "object" }, "type": "array" }, "called_by": { "description": "Who called it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "end_time": { "description": "When it ended, HH:MM:SS.", "format": "time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the minutes were created.", "format": "date-time", "type": "string" }, "location": { "description": "Where it was held.", "nullable": true, "type": "string", "x-untrusted": "text" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "meeting_date": { "description": "The day it was held.", "format": "date", "nullable": true, "type": "string" }, "meeting_type": { "description": "The kind of meeting.", "enum": [ "staff_meeting", "training", "in_service", "supervisory", "other" ], "type": "string" }, "new_business_topics": { "description": "New business, one entry a topic.", "items": { "properties": { "action_items": { "type": "string", "x-untrusted": "text" }, "deadline": { "type": "string", "x-untrusted": "text" }, "discussion": { "type": "string", "x-untrusted": "text" }, "responsible": { "type": "string", "x-untrusted": "text" }, "topic": { "type": "string", "x-untrusted": "text" } }, "type": "object" }, "type": "array" }, "next_meeting_date": { "description": "The next meeting's day.", "format": "date", "nullable": true, "type": "string" }, "next_meeting_location": { "description": "Where the next meeting is.", "nullable": true, "type": "string", "x-untrusted": "text" }, "next_meeting_time": { "description": "The next meeting's time, HH:MM:SS.", "format": "time", "nullable": true, "type": "string" }, "notes": { "description": "Anything else.", "nullable": true, "type": "string", "x-untrusted": "text" }, "old_business": { "description": "Old business.", "nullable": true, "type": "string", "x-untrusted": "text" }, "previous_minutes_approved": { "description": "Whether the previous meeting's minutes were approved.", "type": "boolean" }, "previous_minutes_notes": { "description": "Notes on the previous minutes.", "nullable": true, "type": "string", "x-untrusted": "text" }, "start_time": { "description": "When it started, HH:MM:SS.", "format": "time", "nullable": true, "type": "string" }, "status": { "description": "draft, or finalized.", "enum": [ "draft", "finalized" ], "type": "string" }, "updated_at": { "description": "When they last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "meeting_type", "meeting_date", "status", "lock_version" ], "title": "MeetingMinutes", "type": "object" }, "MeetingMinutesInput": { "description": "Meeting minutes' fields; meeting_type and meeting_date are required on a create. A PATCH carries lock_version.", "properties": { "adjourned_by": { "description": "Who adjourned it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "adjourned_time": { "description": "When it was adjourned, HH:MM:SS.", "format": "time", "nullable": true, "type": "string" }, "attendees": { "description": "Who was invited.", "items": { "properties": { "name": { "description": "Who attended.", "type": "string", "x-untrusted": "text" }, "present": { "description": "\"true\" when they were present.", "type": "string" }, "title": { "description": "Their title.", "type": "string", "x-untrusted": "text" } }, "type": "object" }, "type": "array" }, "called_by": { "description": "Who called it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "end_time": { "description": "When it ended, HH:MM:SS.", "format": "time", "nullable": true, "type": "string" }, "location": { "description": "Where it was held.", "nullable": true, "type": "string", "x-untrusted": "text" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "meeting_date": { "description": "The day it was held.", "format": "date", "nullable": false, "type": "string" }, "meeting_type": { "description": "The kind of meeting.", "enum": [ "staff_meeting", "training", "in_service", "supervisory", "other" ], "type": "string" }, "new_business_topics": { "description": "New business, one entry a topic.", "items": { "properties": { "action_items": { "type": "string", "x-untrusted": "text" }, "deadline": { "type": "string", "x-untrusted": "text" }, "discussion": { "type": "string", "x-untrusted": "text" }, "responsible": { "type": "string", "x-untrusted": "text" }, "topic": { "type": "string", "x-untrusted": "text" } }, "type": "object" }, "type": "array" }, "next_meeting_date": { "description": "The next meeting's day.", "format": "date", "nullable": true, "type": "string" }, "next_meeting_location": { "description": "Where the next meeting is.", "nullable": true, "type": "string", "x-untrusted": "text" }, "next_meeting_time": { "description": "The next meeting's time, HH:MM:SS.", "format": "time", "nullable": true, "type": "string" }, "notes": { "description": "Anything else.", "nullable": true, "type": "string", "x-untrusted": "text" }, "old_business": { "description": "Old business.", "nullable": true, "type": "string", "x-untrusted": "text" }, "previous_minutes_approved": { "description": "Whether the previous meeting's minutes were approved.", "type": "boolean" }, "previous_minutes_notes": { "description": "Notes on the previous minutes.", "nullable": true, "type": "string", "x-untrusted": "text" }, "start_time": { "description": "When it started, HH:MM:SS.", "format": "time", "nullable": true, "type": "string" } }, "title": "MeetingMinutesInput", "type": "object" }, "MissingSigner": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "MonthlyClientReport": { "description": "The monthly check-in with a client, one per Work Order month. Saved here with its answers, comments and how it was taken; the client signs in person.", "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "client_signed": { "description": "Whether the client's line is signed, on the device or on paper before.", "type": "boolean" }, "comments": { "description": "Comments; null or blank clears them.", "nullable": true, "type": "string" }, "conducted_via": { "description": "How the check-in was taken.", "enum": [ "phone", "in_person", "video_call" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the report was first saved.", "format": "date-time", "type": "string" }, "missing_signers": { "description": "Each required line no live signature fills yet, in order; empty when complete or voided.", "items": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "type": "array" }, "month": { "description": "The report's month, 1 to 12.", "nullable": true, "type": "integer" }, "questions": { "description": "The report's questions.", "items": { "$ref": "#/components/schemas/QuestionAnswer" }, "type": "array" }, "record_state": { "description": "Where the report stands as a signed record: draft (it changes here), signed or amended (locked: corrected with an addendum, or voided and started again as a new draft), voided. signing_complete says whether every required line is signed.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "signer_name", "method", "signed_at" ], "title": "RecordSignatureSummary", "type": "object" }, "type": "array" }, "signed_at": { "description": "When the first signature locked it; null on a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signed_on_paper": { "description": "Whether the signed paper sheet is on file. A yes is recorded as a paper-on-file signature on the report's signature line (the client's in person, the office's by phone or video), so it can sign the report; read-only.", "type": "boolean" }, "signing_complete": { "description": "True once the record is signed or amended and every required line holds a signature. A signed record can be false: signed by one line, with another still open. A voided record is always false, whatever it holds, and its missing_signers is empty: nothing can sign it, and its replacement is the record to complete.", "type": "boolean" }, "updated_at": { "description": "When the report last changed.", "format": "date-time", "type": "string" }, "work_order_id": { "description": "The Work Order month the report belongs to.", "format": "uuid", "type": "string" }, "year": { "description": "The report's year.", "nullable": true, "type": "integer" } }, "required": [ "id", "work_order_id", "client_id" ], "title": "MonthlyClientReport", "type": "object" }, "MonthlyClientReportInput": { "description": "What to save: answers maps a question key to yes or no (or true/false), a text or code, or a list of choices; comments; conducted_via. A save sends something to change. Saving again updates the same report.", "properties": { "answers": { "additionalProperties": true, "description": "Answers by question key, as the agency's monthly report lists its questions: yes or no (or true/false), a text or code, or a list of choices.", "type": "object" }, "comments": { "description": "Comments; null or blank clears them.", "nullable": true, "type": "string" }, "conducted_via": { "description": "How the check-in was taken.", "enum": [ "phone", "in_person", "video_call" ], "type": "string" } }, "title": "MonthlyClientReportInput", "type": "object" }, "MonthlyClientReportPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/MonthlyClientReport" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "MonthlyClientReportPage", "type": "object" }, "MonthlyClientReportSignature": { "properties": { "signer": { "description": "Whose line to sign: office, the staff member who conducted a phone or video check-in, signed as you. The client's line is drawn on the device in the app.", "enum": [ "office" ], "type": "string" } }, "required": [ "signer" ], "title": "MonthlyClientReportSignature", "type": "object" }, "MonthlyFollowUp": { "description": "A client's monthly follow-up: the contact the agency makes with each client once a month.", "properties": { "client_id": { "description": "The client it is for.", "format": "uuid", "type": "string" }, "completed": { "description": "Whether it has been logged.", "type": "boolean" }, "completed_at": { "description": "When it was logged.", "format": "date-time", "type": "string" }, "contact_date": { "description": "The day of the contact.", "format": "date", "nullable": true, "type": "string" }, "contact_type": { "description": "How the client was reached.", "enum": [ "phone", "in_person", "video", "email" ], "nullable": true, "type": "string" }, "due_date": { "description": "The day it is due.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "month": { "description": "The month it is filed under (1-12).", "nullable": true, "type": "integer" }, "notes": { "description": "What was discussed.", "nullable": true, "type": "string", "x-untrusted": "text" }, "year": { "description": "The year it is filed under.", "nullable": true, "type": "integer" } }, "required": [ "id", "client_id", "month", "year", "completed" ], "title": "MonthlyFollowUp", "type": "object" }, "MonthlyFollowUpLogInput": { "description": "The contact that completes the follow-up, as the Log form takes it. contact_type and contact_date are required; the date cannot be in the future.", "properties": { "contact_date": { "description": "The day of the contact (YYYY-MM-DD).", "format": "date", "nullable": false, "type": "string" }, "contact_type": { "description": "How the client was reached.", "enum": [ "phone", "in_person", "video", "email" ], "type": "string" }, "notes": { "description": "Optional: what was discussed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "contact_type", "contact_date" ], "title": "MonthlyFollowUpLogInput", "type": "object" }, "MoveDirection": { "properties": { "direction": { "description": "Which way to move it one place.", "enum": [ "up", "down" ], "type": "string" } }, "required": [ "direction" ], "title": "MoveDirection", "type": "object" }, "NextActionSnooze": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "snoozed_until": { "description": "When it comes back.", "format": "date-time", "type": "string" }, "suggestion_id": { "description": "The Next Actions suggestion.", "enum": [ "no_active_plan_of_care", "no_active_assignment", "missing_medicaid_id", "no_work_order_this_month", "expiring_certification", "overdue_supervisor_visit" ], "type": "string" } }, "required": [ "client_id", "suggestion_id", "snoozed_until" ], "title": "NextActionSnooze", "type": "object" }, "NextActionSnoozeCreate": { "properties": { "days": { "description": "Days to snooze it, 1 to 365. Leave it out for 7, as the page does.", "maximum": 365, "minimum": 1, "type": "integer" }, "suggestion_id": { "description": "The Next Actions suggestion.", "enum": [ "no_active_plan_of_care", "no_active_assignment", "missing_medicaid_id", "no_work_order_this_month", "expiring_certification", "overdue_supervisor_visit" ], "type": "string" } }, "required": [ "suggestion_id" ], "title": "NextActionSnoozeCreate", "type": "object" }, "NextActionUnsnoozed": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "suggestion_id": { "description": "The Next Actions suggestion.", "enum": [ "no_active_plan_of_care", "no_active_assignment", "missing_medicaid_id", "no_work_order_this_month", "expiring_certification", "overdue_supervisor_visit" ], "type": "string" } }, "required": [ "client_id", "suggestion_id" ], "title": "NextActionUnsnoozed", "type": "object" }, "NoteAttachment": { "properties": { "content_type": { "description": "Its type.", "nullable": true, "type": "string" }, "file_size": { "description": "Its size in bytes.", "nullable": true, "type": "integer" }, "filename": { "description": "The file's name.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was attached.", "format": "date-time", "type": "string" }, "note_id": { "description": "The note.", "format": "uuid", "type": "string" }, "note_kind": { "description": "The kind of note it is on.", "enum": [ "client", "caregiver" ], "type": "string" }, "scan_status": { "description": "The virus scan's verdict; only a clean file can be downloaded.", "enum": [ "pending", "clean", "infected", "error" ], "type": "string" }, "uploaded_by_id": { "description": "Who attached it.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "note_kind", "note_id", "filename", "content_type", "file_size", "scan_status" ], "title": "NoteAttachment", "type": "object" }, "NoteAttachmentList": { "properties": { "data": { "items": { "properties": { "content_type": { "description": "Its type.", "nullable": true, "type": "string" }, "file_size": { "description": "Its size in bytes.", "nullable": true, "type": "integer" }, "filename": { "description": "The file's name.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was attached.", "format": "date-time", "type": "string" }, "note_id": { "description": "The note.", "format": "uuid", "type": "string" }, "note_kind": { "description": "The kind of note it is on.", "enum": [ "client", "caregiver" ], "type": "string" }, "scan_status": { "description": "The virus scan's verdict; only a clean file can be downloaded.", "enum": [ "pending", "clean", "infected", "error" ], "type": "string" }, "uploaded_by_id": { "description": "Who attached it.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "note_kind", "note_id", "filename", "content_type", "file_size", "scan_status" ], "title": "NoteAttachment", "type": "object" }, "type": "array" } }, "required": [ "data" ], "title": "NoteAttachmentList", "type": "object" }, "Notification": { "properties": { "body": { "description": "Its text.", "nullable": true, "type": "string" }, "created_at": { "description": "When it was raised (UTC).", "format": "date-time", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "priority": { "description": "How urgent it is.", "enum": [ "low", "normal", "high", "urgent" ], "type": "string" }, "read_at": { "description": "When it was read (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "resolved_at": { "description": "When it was resolved (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "source_id": { "description": "The record it is about.", "format": "uuid", "nullable": true, "type": "string" }, "source_type": { "description": "The kind of record it is about.", "nullable": true, "type": "string" }, "title": { "description": "Its headline.", "nullable": true, "type": "string" }, "type": { "description": "The kind of notification.", "nullable": true, "type": "string" } }, "required": [ "id", "type", "title" ], "title": "Notification", "type": "object" }, "NotificationPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "body": { "description": "Its text.", "nullable": true, "type": "string" }, "created_at": { "description": "When it was raised (UTC).", "format": "date-time", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "priority": { "description": "How urgent it is.", "enum": [ "low", "normal", "high", "urgent" ], "type": "string" }, "read_at": { "description": "When it was read (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "resolved_at": { "description": "When it was resolved (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "source_id": { "description": "The record it is about.", "format": "uuid", "nullable": true, "type": "string" }, "source_type": { "description": "The kind of record it is about.", "nullable": true, "type": "string" }, "title": { "description": "Its headline.", "nullable": true, "type": "string" }, "type": { "description": "The kind of notification.", "nullable": true, "type": "string" } }, "required": [ "id", "type", "title" ], "title": "Notification", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "NotificationPage", "type": "object" }, "NotificationResolve": { "properties": { "notes": { "description": "Why it is resolved. Leave it out for none.", "type": "string" } }, "title": "NotificationResolve", "type": "object" }, "NotificationSettings": { "properties": { "notify_on_277ca": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_835": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_999": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_submission": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_ta1": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "remittance_review_email": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "text_caregivers_before_expiry": { "description": "Whether each caregiver is texted a month, and again a week, before a dated credential of theirs expires.", "type": "boolean" } }, "required": [ "notify_on_submission", "notify_on_ta1", "notify_on_999", "notify_on_277ca", "notify_on_835", "remittance_review_email", "text_caregivers_before_expiry" ], "title": "NotificationSettings", "type": "object" }, "NotificationSettingsUpdate": { "properties": { "notify_on_277ca": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_835": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_999": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_submission": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_ta1": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "remittance_review_email": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "text_caregivers_before_expiry": { "description": "Whether each caregiver is texted a month, and again a week, before a dated credential of theirs expires.", "type": "boolean" } }, "title": "NotificationSettingsUpdate", "type": "object" }, "NotificationsMarked": { "properties": { "marked": { "description": "Notifications marked read.", "type": "integer" } }, "required": [ "marked" ], "title": "NotificationsMarked", "type": "object" }, "OIG attestationPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/OigAttestation" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "OIG attestationPage", "type": "object" }, "OigAttestation": { "description": "One month's OIG exclusion attestation. It is never changed once recorded.", "properties": { "administrator_name": { "description": "Who attests.", "nullable": true, "type": "string", "x-untrusted": "text" }, "all_clear": { "description": "Whether nobody matched.", "type": "boolean" }, "company_document_id": { "description": "The attached report, a company document; null for none.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was recorded.", "format": "date-time", "type": "string" }, "leie_file_date": { "description": "The list file's date.", "format": "date", "nullable": true, "type": "string" }, "leie_source": { "description": "Where the exclusion list came from.", "nullable": true, "type": "string", "x-untrusted": "text" }, "recorded_by": { "description": "The user who recorded it.", "format": "uuid", "type": "string" }, "report_state": { "description": "The attached report's state: kept in Company Documents, virus scan pending, failed the virus scan, or removed after failing it; null for none.", "nullable": true, "type": "string" }, "review_month": { "description": "The month screened, as its first day.", "format": "date", "nullable": true, "type": "string" }, "review_names": { "description": "The names to review; required when all_clear is false.", "nullable": true, "type": "string", "x-untrusted": "text" }, "screen_date": { "description": "The day the screen was run; not in the future.", "format": "date", "nullable": true, "type": "string" }, "screened_count": { "description": "How many people were screened.", "minimum": 0, "type": "integer" }, "signed_on": { "description": "The day they signed; not in the future.", "format": "date", "nullable": true, "type": "string" } }, "required": [ "id", "review_month" ], "title": "OigAttestation", "type": "object" }, "OigAttestationInput": { "description": "An attestation's fields. attested must be true. Attach the report by uploading it as a company document first and sending its id.", "properties": { "administrator_name": { "description": "Who attests.", "nullable": true, "type": "string", "x-untrusted": "text" }, "all_clear": { "description": "Whether nobody matched.", "type": "boolean" }, "attested": { "description": "Must be true: the administrator attests the screen was run.", "type": "boolean" }, "company_document_id": { "description": "The report, a company document of this agency.", "format": "uuid", "nullable": true, "type": "string" }, "leie_file_date": { "description": "The list file's date.", "format": "date", "nullable": true, "type": "string" }, "leie_source": { "description": "Where the exclusion list came from.", "nullable": true, "type": "string", "x-untrusted": "text" }, "review_month": { "description": "The month screened, as its first day.", "format": "date", "nullable": true, "type": "string" }, "review_names": { "description": "The names to review; required when all_clear is false.", "nullable": true, "type": "string", "x-untrusted": "text" }, "screen_date": { "description": "The day the screen was run; not in the future.", "format": "date", "nullable": true, "type": "string" }, "screened_count": { "description": "How many people were screened.", "minimum": 0, "type": "integer" }, "signed_on": { "description": "The day they signed; not in the future.", "format": "date", "nullable": true, "type": "string" } }, "title": "OigAttestationInput", "type": "object" }, "OigCheck": { "description": "One caregiver's latest OIG exclusion check: whether the monthly screen covers them, when they were last checked, the result and status, and whether a person or the automatic screen recorded it.", "properties": { "employment_status": { "description": "The caregiver's status.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "in_screen": { "description": "Whether the monthly screen covers them.", "type": "boolean" }, "last_checked_on": { "description": "When last checked.", "format": "date", "nullable": true, "type": "string" }, "name": { "description": "The caregiver's name.", "nullable": true, "type": "string" }, "recorded_by": { "description": "automatic screen or a person.", "nullable": true, "type": "string" }, "result": { "description": "clear, review or excluded.", "nullable": true, "type": "string" }, "status": { "description": "current, overdue, missing, review, excluded or not_in_screen.", "nullable": true, "type": "string" } }, "required": [ "id" ], "title": "OigCheck", "type": "object" }, "OigCheckPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/OigCheck" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "OigCheckPage", "type": "object" }, "OigExclusionBulk": { "properties": { "checked_on": { "description": "The day the LEIE was checked, YYYY-MM-DD.", "format": "date", "type": "string" } }, "required": [ "checked_on" ], "title": "OigExclusionBulk", "type": "object" }, "OigExclusionCheck": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "checked_by": { "description": "Who recorded it.", "format": "uuid", "nullable": true, "type": "string" }, "checked_on": { "description": "The day the LEIE was checked.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was recorded.", "format": "date-time", "type": "string" }, "notes": { "description": "Notes.", "nullable": true, "type": "string" }, "result": { "enum": [ "clear", "excluded", "review" ], "type": "string" }, "source": { "description": "Recorded by a person or by a screen run.", "enum": [ "person", "screen" ], "type": "string" } }, "required": [ "id", "caregiver_id", "checked_on", "result" ], "title": "OigExclusionCheck", "type": "object" }, "OigExclusionCheckCreate": { "properties": { "checked_on": { "description": "The day the LEIE was checked, YYYY-MM-DD; not in the future, not over a year ago.", "format": "date", "type": "string" }, "notes": { "description": "Notes, e.g. how a match was reconciled.", "nullable": true, "type": "string" }, "result": { "description": "The result.", "enum": [ "clear", "excluded", "review" ], "type": "string" } }, "required": [ "checked_on", "result" ], "title": "OigExclusionCheckCreate", "type": "object" }, "OigExclusionCheckPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "checked_by": { "description": "Who recorded it.", "format": "uuid", "nullable": true, "type": "string" }, "checked_on": { "description": "The day the LEIE was checked.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was recorded.", "format": "date-time", "type": "string" }, "notes": { "description": "Notes.", "nullable": true, "type": "string" }, "result": { "enum": [ "clear", "excluded", "review" ], "type": "string" }, "source": { "description": "Recorded by a person or by a screen run.", "enum": [ "person", "screen" ], "type": "string" } }, "required": [ "id", "caregiver_id", "checked_on", "result" ], "title": "OigExclusionCheck", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "OigExclusionCheckPage", "type": "object" }, "OigScreen": { "description": "One OIG exclusion screen: screen date, LEIE file date, how many were screened, how many names it raised to review, how many of those are still open (each counted once, on the newest screen that raised it), and the printable record the Administrator signs.", "properties": { "all_clear": { "description": "Whether it raised nothing.", "type": "boolean" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "kind": { "description": "monthly, new_hire or single.", "nullable": true, "type": "string" }, "leie_file_date": { "description": "The LEIE file it screened against.", "format": "date", "nullable": true, "type": "string" }, "record_url": { "description": "The printable record.", "nullable": true, "type": "string" }, "screen_date": { "description": "When the screen ran.", "format": "date", "nullable": true, "type": "string" }, "screened": { "description": "How many were screened.", "nullable": true, "type": "integer" }, "still_to_review": { "description": "How many of its reviews are still open.", "nullable": true, "type": "integer" }, "to_review": { "description": "How many names it raised to review.", "nullable": true, "type": "integer" } }, "required": [ "id" ], "title": "OigScreen", "type": "object" }, "OigScreenPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/OigScreen" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "OigScreenPage", "type": "object" }, "OigScreenQueued": { "description": "A roster screen request: queued, or already_queued when a screen was already waiting, running or retrying. The screen's row exists once the worker starts; read it from GET /api/v1/oig-screens.", "properties": { "status": { "description": "What became of the request.", "enum": [ "queued", "already_queued" ], "type": "string" } }, "required": [ "status" ], "title": "OigScreenQueued", "type": "object" }, "OpenShift": { "properties": { "care_type": { "enum": [ "personal", "homemaking", "both" ], "type": "string" }, "client": { "description": "The client, by name only: never the address or point.", "properties": { "first_name": { "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "type": "string" } }, "type": "object" }, "client_gender": { "enum": [ "female", "male", "unspecified" ], "type": "string" }, "cross_streets": { "type": "string" }, "date_mode": { "enum": [ "exact", "this_week", "next_week", "within_2_weeks", "tbd" ], "type": "string" }, "end_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "hours": { "description": "A one-time shift's hours.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was posted.", "format": "date-time", "type": "string" }, "kind": { "enum": [ "one_time", "ongoing" ], "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "note": { "nullable": true, "type": "string" }, "ongoing_times": { "description": "An ongoing shift's Shift Plan times on starts_on, and the ISO weekdays (1 Monday .. 7 Sunday) its slot runs on; null for a one-time shift.", "nullable": true, "properties": { "end": { "description": "HH:MM.", "nullable": true, "type": "string" }, "ends_next_day": { "description": "The end is past midnight.", "type": "boolean" }, "hours": { "description": "The hours that day.", "format": "decimal", "nullable": true, "type": "string" }, "run_days": { "items": { "type": "integer" }, "type": "array" }, "start": { "description": "HH:MM.", "nullable": true, "type": "string" } }, "type": "object" }, "rate_cents": { "description": "The hourly rate, in cents.", "nullable": true, "type": "integer" }, "service_area": { "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "shift_id": { "description": "An ongoing shift's slot.", "nullable": true, "type": "string" }, "start_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "starts_on": { "description": "The date for exact; the window's last day for this_week, next_week and within_2_weeks; null for tbd.", "format": "date", "nullable": true, "type": "string" }, "status": { "enum": [ "open", "assigned", "completed", "cancelled" ], "type": "string" }, "time_mode": { "enum": [ "exact", "am", "midday", "pm", "flexible" ], "nullable": true, "type": "string" }, "zip": { "nullable": true, "type": "string" } }, "title": "OpenShift", "type": "object" }, "OpenShiftAssign": { "properties": { "caregiver_id": { "description": "The caregiver to assign.", "format": "uuid", "type": "string" } }, "required": [ "caregiver_id" ], "title": "OpenShiftAssign", "type": "object" }, "OpenShiftCreate": { "properties": { "acknowledged": { "description": "The fingerprints of client_info_found refusals the sender confirmed are not client information.", "items": { "type": "string" }, "type": "array" }, "care_type": { "description": "The care the shift gives.", "enum": [ "personal", "homemaking", "both" ], "type": "string" }, "client_gender": { "description": "The client's gender, shown to responders.", "enum": [ "female", "male", "unspecified" ], "type": "string" }, "client_id": { "description": "The client the shift is for.", "format": "uuid", "type": "string" }, "cross_streets": { "description": "Two nearby major streets, as 'S Chambers Rd & E Hampden Ave'; never a house number.", "maxLength": 200, "type": "string", "x-untrusted": "text" }, "date_mode": { "description": "exact needs starts_on; this_week, next_week and within_2_weeks are windows; tbd has no date yet.", "enum": [ "exact", "this_week", "next_week", "within_2_weeks", "tbd" ], "type": "string" }, "end_time": { "description": "HH:MM, one-time exact only; earlier than start_time for an overnight shift.", "format": "time", "nullable": true, "type": "string" }, "hours": { "description": "One-time only, when time_mode is not exact: 0.5 to 24, in halves.", "format": "decimal", "nullable": true, "type": "string" }, "kind": { "description": "one_time for a single shift; ongoing to fill a Shift Plan slot, whose days and times are the Shift Plan's.", "enum": [ "one_time", "ongoing" ], "type": "string" }, "note": { "description": "Up to 500 characters for responders. Checked for client information: a match is refused unless acknowledged names its fingerprint.", "maxLength": 500, "nullable": true, "type": "string", "x-untrusted": "text" }, "rate_cents": { "description": "The hourly rate shown to responders, in cents.", "maximum": 99999, "minimum": 1, "type": "integer" }, "service_area_id": { "description": "The agency area the shift is shown at.", "format": "uuid", "type": "string" }, "shift_id": { "description": "Ongoing only: the Shift Plan slot the shift fills.", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "nullable": true, "type": "string" }, "start_time": { "description": "HH:MM, one-time exact only.", "format": "time", "nullable": true, "type": "string" }, "starts_on": { "description": "The date, for date_mode exact; ignored for a window.", "format": "date", "nullable": true, "type": "string" }, "time_mode": { "description": "One-time only: exact needs start_time and end_time; am, midday, pm and flexible need hours.", "enum": [ "exact", "am", "midday", "pm", "flexible" ], "nullable": true, "type": "string" }, "zip": { "description": "The client's 5-digit ZIP code, shown to responders.", "nullable": true, "pattern": "^[0-9]{5}$", "type": "string" } }, "required": [ "client_id", "kind", "service_area_id", "cross_streets", "date_mode", "care_type", "client_gender", "rate_cents" ], "title": "OpenShiftCreate", "type": "object" }, "OpenShiftCrossStreets": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" } }, "required": [ "client_id" ], "title": "OpenShiftCrossStreets", "type": "object" }, "OpenShiftDashboard": { "properties": { "counts": { "description": "No section: the four counts.", "type": "object" }, "coverage": { "description": "No section: one row per area holding an open shift.", "items": { "type": "object" }, "type": "array" }, "rows": { "items": { "type": "object" }, "type": "array" }, "section": { "type": "string" }, "total": { "type": "integer" } }, "title": "OpenShiftDashboard", "type": "object" }, "OpenShiftPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "care_type": { "enum": [ "personal", "homemaking", "both" ], "type": "string" }, "client": { "description": "The client, by name only: never the address or point.", "properties": { "first_name": { "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "type": "string" } }, "type": "object" }, "client_gender": { "enum": [ "female", "male", "unspecified" ], "type": "string" }, "cross_streets": { "type": "string" }, "date_mode": { "enum": [ "exact", "this_week", "next_week", "within_2_weeks", "tbd" ], "type": "string" }, "end_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "hours": { "description": "A one-time shift's hours.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was posted.", "format": "date-time", "type": "string" }, "kind": { "enum": [ "one_time", "ongoing" ], "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "note": { "nullable": true, "type": "string" }, "ongoing_times": { "description": "An ongoing shift's Shift Plan times on starts_on, and the ISO weekdays (1 Monday .. 7 Sunday) its slot runs on; null for a one-time shift.", "nullable": true, "properties": { "end": { "description": "HH:MM.", "nullable": true, "type": "string" }, "ends_next_day": { "description": "The end is past midnight.", "type": "boolean" }, "hours": { "description": "The hours that day.", "format": "decimal", "nullable": true, "type": "string" }, "run_days": { "items": { "type": "integer" }, "type": "array" }, "start": { "description": "HH:MM.", "nullable": true, "type": "string" } }, "type": "object" }, "rate_cents": { "description": "The hourly rate, in cents.", "nullable": true, "type": "integer" }, "service_area": { "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "shift_id": { "description": "An ongoing shift's slot.", "nullable": true, "type": "string" }, "start_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "starts_on": { "description": "The date for exact; the window's last day for this_week, next_week and within_2_weeks; null for tbd.", "format": "date", "nullable": true, "type": "string" }, "status": { "enum": [ "open", "assigned", "completed", "cancelled" ], "type": "string" }, "time_mode": { "enum": [ "exact", "am", "midday", "pm", "flexible" ], "nullable": true, "type": "string" }, "zip": { "nullable": true, "type": "string" } }, "title": "OpenShift", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "OpenShiftPage", "type": "object" }, "OpenShiftResponse": { "description": "One live response to an open shift (a withdrawn one is not listed).", "properties": { "active": { "description": "The caregiver is active.", "type": "boolean" }, "caregiver_id": { "description": "The caregiver; null for a candidate.", "format": "uuid", "nullable": true, "type": "string" }, "completed": { "description": "Open shifts this caregiver has completed.", "nullable": true, "type": "integer" }, "home_area": { "description": "The caregiver's home service area. Present only for a holder of open_shifts.administer; null when none is set.", "nullable": true, "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "miles": { "description": "Whole miles from the caregiver's home area to the shift's service area; null when either has no known point.", "nullable": true, "type": "integer" }, "name": { "description": "Last, First.", "nullable": true, "type": "string" }, "open_shift_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "phone": { "nullable": true, "type": "string" }, "responded_at": { "description": "When they responded.", "format": "date-time", "type": "string" }, "role": { "enum": [ "Caregiver", "Candidate" ], "type": "string" } }, "title": "OpenShiftResponse", "type": "object" }, "OpenShiftResponsePage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "description": "One live response to an open shift (a withdrawn one is not listed).", "properties": { "active": { "description": "The caregiver is active.", "type": "boolean" }, "caregiver_id": { "description": "The caregiver; null for a candidate.", "format": "uuid", "nullable": true, "type": "string" }, "completed": { "description": "Open shifts this caregiver has completed.", "nullable": true, "type": "integer" }, "home_area": { "description": "The caregiver's home service area. Present only for a holder of open_shifts.administer; null when none is set.", "nullable": true, "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "miles": { "description": "Whole miles from the caregiver's home area to the shift's service area; null when either has no known point.", "nullable": true, "type": "integer" }, "name": { "description": "Last, First.", "nullable": true, "type": "string" }, "open_shift_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "phone": { "nullable": true, "type": "string" }, "responded_at": { "description": "When they responded.", "format": "date-time", "type": "string" }, "role": { "enum": [ "Caregiver", "Candidate" ], "type": "string" } }, "title": "OpenShiftResponse", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "OpenShiftResponsePage", "type": "object" }, "OpenShiftSettings": { "additionalProperties": false, "description": "The agency's open shifts rules. Sending the object sets only the keys sent; changing it needs agency_settings.manage, and a value out of range answers 422 validation_failed naming open_shifts..", "properties": { "alert_withdrawn_on_change": { "description": "A withdrawn responder is also told when a shift's details change.", "type": "boolean" }, "api_may_assign_non_responder": { "description": "REST and MCP may assign an active caregiver who did not respond.", "type": "boolean" }, "assignee_sees_client_details": { "description": "The assignee sees the client's name and address in the app.", "type": "boolean" }, "complete_before_start": { "description": "A shift may be marked completed before its start.", "type": "boolean" }, "cross_street_min_meters": { "description": "The least distance from the client's door for the cross streets (0-1000).", "type": "integer" }, "default_radius_miles": { "description": "The radius a new person starts with; one of radius_choices_miles.", "type": "integer" }, "enabled": { "description": "Open shifts are on for the agency; every open shifts job checks it.", "type": "boolean" }, "free_cancel_hours": { "description": "A caregiver may cancel free until this many hours before the start (0-168).", "type": "integer" }, "my_shifts_history_days": { "description": "How far back My shifts' history reaches, in days (7-365).", "type": "integer" }, "not_responding_alerts": { "description": "Alerts unanswered that mark a person as not responding (1-50).", "type": "integer" }, "not_responding_days": { "description": "The days those unanswered alerts are counted over (1-365).", "type": "integer" }, "pause_days": { "description": "How long a pause from open shifts lasts, in days (0-365).", "type": "integer" }, "pause_extends_running": { "description": "A new pause during a running one keeps the later end.", "type": "boolean" }, "post_lead_hours": { "description": "An exact-date shift starting sooner than this many hours warns when posted (0-168).", "type": "integer" }, "radius_choices_miles": { "description": "The radii a person may pick, in miles: 1-8 distinct values, 1-200.", "items": { "type": "integer" }, "type": "array" }, "reminder_offsets_hours": { "description": "Hours before the start the assignee is reminded: 1-3 distinct values, 1-168.", "items": { "type": "integer" }, "type": "array" }, "self_signup_enabled": { "description": "New people may sign up on the portal themselves.", "type": "boolean" }, "strike_window_days": { "description": "Only strikes this recent count, in days (1-365).", "type": "integer" }, "strikes_before_pause": { "description": "Strikes that pause a person (1-10).", "type": "integer" } }, "title": "OpenShiftSettings", "type": "object" }, "OpenShiftUpdate": { "properties": { "acknowledged": { "description": "The fingerprints of client_info_found refusals the sender confirmed are not client information.", "items": { "type": "string" }, "type": "array" }, "care_type": { "description": "The care the shift gives.", "enum": [ "personal", "homemaking", "both" ], "type": "string" }, "client_gender": { "description": "The client's gender, shown to responders.", "enum": [ "female", "male", "unspecified" ], "type": "string" }, "cross_streets": { "description": "Two nearby major streets, as 'S Chambers Rd & E Hampden Ave'; never a house number.", "maxLength": 200, "type": "string", "x-untrusted": "text" }, "date_mode": { "description": "exact needs starts_on; this_week, next_week and within_2_weeks are windows; tbd has no date yet.", "enum": [ "exact", "this_week", "next_week", "within_2_weeks", "tbd" ], "type": "string" }, "end_time": { "description": "HH:MM, one-time exact only; earlier than start_time for an overnight shift.", "format": "time", "nullable": true, "type": "string" }, "hours": { "description": "One-time only, when time_mode is not exact: 0.5 to 24, in halves.", "format": "decimal", "nullable": true, "type": "string" }, "kind": { "description": "one_time for a single shift; ongoing to fill a Shift Plan slot, whose days and times are the Shift Plan's.", "enum": [ "one_time", "ongoing" ], "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "note": { "description": "Up to 500 characters for responders. Checked for client information: a match is refused unless acknowledged names its fingerprint.", "maxLength": 500, "nullable": true, "type": "string", "x-untrusted": "text" }, "rate_cents": { "description": "The hourly rate shown to responders, in cents.", "maximum": 99999, "minimum": 1, "type": "integer" }, "service_area_id": { "description": "The agency area the shift is shown at.", "format": "uuid", "type": "string" }, "shift_id": { "description": "Ongoing only: the Shift Plan slot the shift fills.", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "nullable": true, "type": "string" }, "start_time": { "description": "HH:MM, one-time exact only.", "format": "time", "nullable": true, "type": "string" }, "starts_on": { "description": "The date, for date_mode exact; ignored for a window.", "format": "date", "nullable": true, "type": "string" }, "time_mode": { "description": "One-time only: exact needs start_time and end_time; am, midday, pm and flexible need hours.", "enum": [ "exact", "am", "midday", "pm", "flexible" ], "nullable": true, "type": "string" }, "zip": { "description": "The client's 5-digit ZIP code, shown to responders.", "nullable": true, "pattern": "^[0-9]{5}$", "type": "string" } }, "required": [ "lock_version" ], "title": "OpenShiftUpdate", "type": "object" }, "OverAuthorizationAdjustment": { "properties": { "caregiver_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "from": { "description": "Visits a week before the trim.", "nullable": true, "type": "integer" }, "task": { "description": "The task's key on the plan.", "nullable": true, "type": "string" }, "task_definition_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "task_label": { "description": "The task as the plan names it.", "nullable": true, "type": "string" }, "to": { "description": "Visits a week after it; 0 means the task was taken off.", "nullable": true, "type": "integer" }, "work_order_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "title": "OverAuthorizationAdjustment", "type": "object" }, "OverAuthorizationResolve": { "properties": { "month": { "description": "The month, 1 to 12.", "maximum": 12, "minimum": 1, "type": "integer" }, "target": { "additionalProperties": { "format": "uuid", "type": "string" }, "description": "Optional: task key or plan task id => the Work Order id to trim it from.", "type": "object" }, "year": { "description": "The year.", "maximum": 2100, "minimum": 2020, "type": "integer" } }, "required": [ "month", "year" ], "title": "OverAuthorizationResolve", "type": "object" }, "Page": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Page", "type": "object" }, "ParCheck": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "flags": { "description": "MI, BI, PLWA: the client's conditions the PAR carries.", "items": { "type": "string" }, "type": "array" }, "other_pars": { "description": "The client's other current PARs, each with only the services it has a plan for: separate Personal Care and Homemaker PARs are both current (RW1-N2). The top-level check then lists only its own services.", "items": { "properties": { "flags": { "description": "MI, BI, PLWA: the client's conditions the PAR carries.", "items": { "type": "string" }, "type": "array" }, "par_effective_date": { "description": "The PAR's first day.", "format": "date", "nullable": true, "type": "string" }, "par_expiry_date": { "description": "The PAR's last day.", "format": "date", "nullable": true, "type": "string" }, "par_number": { "description": "The PAR's number.", "nullable": true, "type": "string" }, "services": { "description": "One column per service, Personal Care, Homemaker, HMA.", "items": { "properties": { "base_units": { "description": "(hours_weekly + travel_hours) × weeks × 4, unrounded.", "format": "decimal", "nullable": true, "type": "string" }, "billing_code": { "description": "The billing code.", "nullable": true, "type": "string" }, "extra_hours": { "description": "Extra hours a week, for extra_weeks: a second segment.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours": { "description": "Travel hours a week, counted with extra_hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_units": { "description": "(extra_hours + extra_travel_hours) × extra_weeks × 4, unrounded.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks": { "description": "Weeks the extra hours run. None means the extra adds no units.", "format": "decimal", "nullable": true, "type": "string" }, "extra_without_weeks": { "description": "Extra hours are set with no extra_weeks, so add nothing.", "type": "boolean" }, "hours_weekly": { "description": "Authorized hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "mismatch": { "description": "total_units and units_on_par disagree.", "type": "boolean" }, "plan_of_care_id": { "description": "The plan it is read from; none when not authorized.", "format": "uuid", "nullable": true, "type": "string" }, "service": { "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "total_units": { "description": "base_units + extra_units, rounded half-up.", "nullable": true, "type": "integer" }, "travel_hours": { "description": "Travel hours a week, counted with the hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "units_on_par": { "description": "The units the case manager's letter carries.", "nullable": true, "type": "integer" }, "variance": { "description": "units_on_par less total_units.", "nullable": true, "type": "integer" } }, "required": [ "service", "mismatch" ], "title": "ParCheckService", "type": "object" }, "type": "array" }, "weeks": { "description": "The PAR's weeks, as the panel prints them.", "nullable": true, "type": "string" } }, "required": [ "services" ], "title": "ParCheckOther", "type": "object" }, "type": "array" }, "par_effective_date": { "description": "The PAR's first day.", "format": "date", "nullable": true, "type": "string" }, "par_expiry_date": { "description": "The PAR's last day.", "format": "date", "nullable": true, "type": "string" }, "par_number": { "description": "The PAR's number.", "nullable": true, "type": "string" }, "services": { "description": "One column per service, Personal Care, Homemaker, HMA.", "items": { "properties": { "base_units": { "description": "(hours_weekly + travel_hours) × weeks × 4, unrounded.", "format": "decimal", "nullable": true, "type": "string" }, "billing_code": { "description": "The billing code.", "nullable": true, "type": "string" }, "extra_hours": { "description": "Extra hours a week, for extra_weeks: a second segment.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours": { "description": "Travel hours a week, counted with extra_hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_units": { "description": "(extra_hours + extra_travel_hours) × extra_weeks × 4, unrounded.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks": { "description": "Weeks the extra hours run. None means the extra adds no units.", "format": "decimal", "nullable": true, "type": "string" }, "extra_without_weeks": { "description": "Extra hours are set with no extra_weeks, so add nothing.", "type": "boolean" }, "hours_weekly": { "description": "Authorized hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "mismatch": { "description": "total_units and units_on_par disagree.", "type": "boolean" }, "plan_of_care_id": { "description": "The plan it is read from; none when not authorized.", "format": "uuid", "nullable": true, "type": "string" }, "service": { "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "total_units": { "description": "base_units + extra_units, rounded half-up.", "nullable": true, "type": "integer" }, "travel_hours": { "description": "Travel hours a week, counted with the hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "units_on_par": { "description": "The units the case manager's letter carries.", "nullable": true, "type": "integer" }, "variance": { "description": "units_on_par less total_units.", "nullable": true, "type": "integer" } }, "required": [ "service", "mismatch" ], "title": "ParCheckService", "type": "object" }, "type": "array" }, "weeks": { "description": "The PAR's weeks, as the panel prints them.", "nullable": true, "type": "string" } }, "required": [ "client_id", "services", "other_pars" ], "title": "ParCheck", "type": "object" }, "ParCheckFigures": { "description": "This service's figures: travel_hours, extra_hours, extra_travel_hours, extra_weeks, units_on_par.", "properties": { "extra_hours": { "description": "Extra hours a week, for extra_weeks: a second segment.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours": { "description": "Travel hours a week, counted with extra_hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks": { "description": "Weeks the extra hours run. None means the extra adds no units.", "format": "decimal", "nullable": true, "type": "string" }, "travel_hours": { "description": "Travel hours a week, counted with the hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "units_on_par": { "description": "The units the case manager's letter carries.", "nullable": true, "type": "integer" } }, "title": "ParCheckFigures", "type": "object" }, "ParCheckOther": { "properties": { "flags": { "description": "MI, BI, PLWA: the client's conditions the PAR carries.", "items": { "type": "string" }, "type": "array" }, "par_effective_date": { "description": "The PAR's first day.", "format": "date", "nullable": true, "type": "string" }, "par_expiry_date": { "description": "The PAR's last day.", "format": "date", "nullable": true, "type": "string" }, "par_number": { "description": "The PAR's number.", "nullable": true, "type": "string" }, "services": { "description": "One column per service, Personal Care, Homemaker, HMA.", "items": { "properties": { "base_units": { "description": "(hours_weekly + travel_hours) × weeks × 4, unrounded.", "format": "decimal", "nullable": true, "type": "string" }, "billing_code": { "description": "The billing code.", "nullable": true, "type": "string" }, "extra_hours": { "description": "Extra hours a week, for extra_weeks: a second segment.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours": { "description": "Travel hours a week, counted with extra_hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_units": { "description": "(extra_hours + extra_travel_hours) × extra_weeks × 4, unrounded.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks": { "description": "Weeks the extra hours run. None means the extra adds no units.", "format": "decimal", "nullable": true, "type": "string" }, "extra_without_weeks": { "description": "Extra hours are set with no extra_weeks, so add nothing.", "type": "boolean" }, "hours_weekly": { "description": "Authorized hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "mismatch": { "description": "total_units and units_on_par disagree.", "type": "boolean" }, "plan_of_care_id": { "description": "The plan it is read from; none when not authorized.", "format": "uuid", "nullable": true, "type": "string" }, "service": { "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "total_units": { "description": "base_units + extra_units, rounded half-up.", "nullable": true, "type": "integer" }, "travel_hours": { "description": "Travel hours a week, counted with the hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "units_on_par": { "description": "The units the case manager's letter carries.", "nullable": true, "type": "integer" }, "variance": { "description": "units_on_par less total_units.", "nullable": true, "type": "integer" } }, "required": [ "service", "mismatch" ], "title": "ParCheckService", "type": "object" }, "type": "array" }, "weeks": { "description": "The PAR's weeks, as the panel prints them.", "nullable": true, "type": "string" } }, "required": [ "services" ], "title": "ParCheckOther", "type": "object" }, "ParCheckService": { "properties": { "base_units": { "description": "(hours_weekly + travel_hours) × weeks × 4, unrounded.", "format": "decimal", "nullable": true, "type": "string" }, "billing_code": { "description": "The billing code.", "nullable": true, "type": "string" }, "extra_hours": { "description": "Extra hours a week, for extra_weeks: a second segment.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours": { "description": "Travel hours a week, counted with extra_hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_units": { "description": "(extra_hours + extra_travel_hours) × extra_weeks × 4, unrounded.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks": { "description": "Weeks the extra hours run. None means the extra adds no units.", "format": "decimal", "nullable": true, "type": "string" }, "extra_without_weeks": { "description": "Extra hours are set with no extra_weeks, so add nothing.", "type": "boolean" }, "hours_weekly": { "description": "Authorized hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "mismatch": { "description": "total_units and units_on_par disagree.", "type": "boolean" }, "plan_of_care_id": { "description": "The plan it is read from; none when not authorized.", "format": "uuid", "nullable": true, "type": "string" }, "service": { "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "total_units": { "description": "base_units + extra_units, rounded half-up.", "nullable": true, "type": "integer" }, "travel_hours": { "description": "Travel hours a week, counted with the hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "units_on_par": { "description": "The units the case manager's letter carries.", "nullable": true, "type": "integer" }, "variance": { "description": "units_on_par less total_units.", "nullable": true, "type": "integer" } }, "required": [ "service", "mismatch" ], "title": "ParCheckService", "type": "object" }, "ParCheckUpdate": { "properties": { "hma": { "description": "This service's figures: travel_hours, extra_hours, extra_travel_hours, extra_weeks, units_on_par.", "properties": { "extra_hours": { "description": "Extra hours a week, for extra_weeks: a second segment.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours": { "description": "Travel hours a week, counted with extra_hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks": { "description": "Weeks the extra hours run. None means the extra adds no units.", "format": "decimal", "nullable": true, "type": "string" }, "travel_hours": { "description": "Travel hours a week, counted with the hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "units_on_par": { "description": "The units the case manager's letter carries.", "nullable": true, "type": "integer" } }, "title": "ParCheckFigures", "type": "object" }, "homemaker": { "description": "This service's figures: travel_hours, extra_hours, extra_travel_hours, extra_weeks, units_on_par.", "properties": { "extra_hours": { "description": "Extra hours a week, for extra_weeks: a second segment.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours": { "description": "Travel hours a week, counted with extra_hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks": { "description": "Weeks the extra hours run. None means the extra adds no units.", "format": "decimal", "nullable": true, "type": "string" }, "travel_hours": { "description": "Travel hours a week, counted with the hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "units_on_par": { "description": "The units the case manager's letter carries.", "nullable": true, "type": "integer" } }, "title": "ParCheckFigures", "type": "object" }, "personal_care": { "description": "This service's figures: travel_hours, extra_hours, extra_travel_hours, extra_weeks, units_on_par.", "properties": { "extra_hours": { "description": "Extra hours a week, for extra_weeks: a second segment.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours": { "description": "Travel hours a week, counted with extra_hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks": { "description": "Weeks the extra hours run. None means the extra adds no units.", "format": "decimal", "nullable": true, "type": "string" }, "travel_hours": { "description": "Travel hours a week, counted with the hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "units_on_par": { "description": "The units the case manager's letter carries.", "nullable": true, "type": "integer" } }, "title": "ParCheckFigures", "type": "object" } }, "title": "ParCheckUpdate", "type": "object" }, "PayrollCheckFinding": { "properties": { "caregiver_id": { "description": "The caregiver, or null for the export as a whole.", "format": "uuid", "nullable": true, "type": "string" }, "code": { "description": "Which rule found it.", "enum": [ "product_unknown", "no_company_code", "no_file_number", "hired_after_period", "hours_out_of_range", "rate_codes_assumed", "too_many_rates", "unmapped_kind", "basis_changed", "period_not_an_adp_pay_cycle", "pay_frequency_differs", "code_not_in_adp", "code_worker_type_mismatch", "adp_terminated", "adp_on_leave", "rate_differs" ], "type": "string" }, "fix_path": { "description": "The HomeCareBilling page where it is fixed.", "nullable": true, "type": "string" }, "message": { "description": "The sentence Payroll exports > Check shows.", "nullable": true, "type": "string" }, "severity": { "description": "unsendable (no line of the ADP file can be written), refusal (ADP refuses this line; the rest goes) or warning (sent as it is).", "enum": [ "unsendable", "refusal", "warning" ], "type": "string" } }, "required": [ "severity", "code", "caregiver_id", "message", "fix_path" ], "title": "PayrollCheckFinding", "type": "object" }, "PayrollConnectCode": { "properties": { "connect_code": { "description": "The single-use code to paste into the ADP Marketplace checkout form. Answered only here, never stored or shown again; a new code replaces the old.", "nullable": true, "type": "string" }, "expires_at": { "description": "When the code stops working, 7 days after it was made.", "format": "date-time", "type": "string" } }, "required": [ "connect_code", "expires_at" ], "title": "PayrollConnectCode", "type": "object" }, "PayrollConnection": { "properties": { "certificate_expires_at": { "description": "When the ADP API certificate expires; null when there is none (own_api only).", "format": "date-time", "nullable": true, "type": "string" }, "enabled": { "description": "Whether the ADP payroll integration is on for the agency (Settings > Payroll's switch).", "type": "boolean" }, "health": { "properties": { "certificate_expires_at": { "description": "When the ADP API certificate expires.", "format": "date-time", "nullable": true, "type": "string" }, "consecutive_failures": { "description": "Failures since the last success.", "nullable": true, "type": "integer" }, "last_failure_at": { "description": "The last failed one.", "format": "date-time", "nullable": true, "type": "string" }, "last_success_at": { "description": "The last successful token request or call to ADP.", "format": "date-time", "nullable": true, "type": "string" }, "message": { "description": "The sentence the reconnect banner shows while the connection needs attention; null otherwise.", "nullable": true, "type": "string" }, "paused_until": { "description": "While ADP is not answering and HomeCareBilling has paused calls to it, when it tries again; null otherwise.", "format": "date-time", "nullable": true, "type": "string" }, "status": { "description": "The connection's state.", "enum": [ "pending_subscription", "pending_consent", "active", "needs_attention", "disconnected" ], "type": "string" }, "status_reason": { "description": "Why the connection needs attention: token_refused, circuit_open, certificate_expired, method_paused, or the code Test connection recorded; null otherwise.", "nullable": true, "type": "string" } }, "required": [ "status", "last_success_at", "last_failure_at", "consecutive_failures", "certificate_expires_at", "status_reason", "message", "paused_until" ], "title": "PayrollConnectionHealth", "type": "object" }, "method": { "description": "How payroll reaches ADP.", "enum": [ "file", "sftp_drop", "own_api", "marketplace" ], "type": "string" }, "methods_offered": { "description": "The sending methods Settings > Payroll offers for this product: built, fitting the product and switched on.", "items": { "type": "string" }, "type": "array" }, "notice": { "description": "On a change, \"Sending switched to the file, because that method is not offered for this ADP.\" when the method was not offered for the product and the file was stored instead (or, when the marketplace is kept for an ADP product other than the one the agency's ADP Marketplace subscription is for, a sentence naming both products: the connection waits for that product's order); otherwise null.", "nullable": true, "type": "string" }, "product": { "description": "Which ADP the agency runs: run, wfn or unknown.", "enum": [ "run", "wfn", "wfn_next_gen", "unknown" ], "type": "string" }, "secrets_set": { "properties": { "certificate_pem": { "description": "Whether certificate_pem is set. The value is never answered.", "type": "boolean" }, "client_id": { "description": "Whether client_id is set. The value is never answered.", "type": "boolean" }, "client_secret": { "description": "Whether client_secret is set. The value is never answered.", "type": "boolean" }, "private_key_pem": { "description": "Whether private_key_pem is set. The value is never answered.", "type": "boolean" }, "sftp_private_key": { "description": "Whether sftp_private_key is set. The value is never answered.", "type": "boolean" } }, "required": [ "client_id", "client_secret", "certificate_pem", "private_key_pem", "sftp_private_key" ], "title": "PayrollConnectionSecretsSet", "type": "object" }, "settings": { "properties": { "allow_hire_push": { "description": "Whether a caregiver may be added to ADP from HomeCareBilling (RUN's Add to ADP).", "type": "boolean" }, "employee_id_template": { "description": "Which RUN Time Sheet Import template keys each caregiver: payroll_assigned (ADP's Employee ID) or time_clock (the Time Clock ID).", "enum": [ "payroll_assigned", "time_clock" ], "type": "string" }, "mark_exported_on": { "description": "When a sent export is marked exported.", "enum": [ "all_accepted", "manual" ], "type": "string" }, "rate_mode": { "description": "How API methods send a pay rate.", "enum": [ "rate_value", "rate_code" ], "type": "string" }, "rate_tolerance": { "description": "How far ADP's rate may differ from HomeCareBilling's before a warning.", "format": "decimal", "nullable": true, "type": "string" }, "run_company_code": { "description": "RUN's company code or IID, 1 to 10 letters and numbers; null when unset.", "nullable": true, "type": "string" }, "run_file_version": { "description": "The RUN Time Sheet Import file version.", "enum": [ "V1.0", "V2.0" ], "type": "string" }, "send_contractors": { "description": "Whether 1099 contractors' hours go to ADP too.", "type": "boolean" }, "sftp_folder": { "description": "The SFTP drop's folder; null when unset.", "nullable": true, "type": "string" }, "sftp_host": { "description": "The SFTP drop's host; null when unset.", "nullable": true, "type": "string" }, "sftp_host_key_fingerprint": { "description": "The SHA-256 host key fingerprint the SFTP server presented at the first successful Test connection, trusted from then on; null until then.", "nullable": true, "type": "string" }, "sftp_port": { "description": "The SFTP drop's port, 1 to 65535; null when unset, which connects on 22.", "nullable": true, "type": "integer" }, "sftp_user": { "description": "The SFTP drop's user; null when unset.", "nullable": true, "type": "string" } }, "required": [ "run_company_code", "employee_id_template", "run_file_version", "rate_mode", "mark_exported_on", "send_contractors", "allow_hire_push", "rate_tolerance", "sftp_host", "sftp_user", "sftp_folder", "sftp_host_key_fingerprint", "sftp_port" ], "title": "PayrollConnectionSettings", "type": "object" }, "sftp_key_fingerprint": { "description": "The SHA-256 fingerprint (SHA256:..., as ssh-keygen -lf prints it) of the SFTP drop key's public half; null when no key is set. The key is never answered.", "nullable": true, "type": "string" }, "status": { "description": "The connection's state.", "enum": [ "pending_subscription", "pending_consent", "active", "needs_attention", "disconnected" ], "type": "string" } }, "required": [ "enabled", "product", "method", "status", "methods_offered", "settings", "certificate_expires_at", "secrets_set", "sftp_key_fingerprint", "health", "notice" ], "title": "PayrollConnection", "type": "object" }, "PayrollConnectionHealth": { "properties": { "certificate_expires_at": { "description": "When the ADP API certificate expires.", "format": "date-time", "nullable": true, "type": "string" }, "consecutive_failures": { "description": "Failures since the last success.", "nullable": true, "type": "integer" }, "last_failure_at": { "description": "The last failed one.", "format": "date-time", "nullable": true, "type": "string" }, "last_success_at": { "description": "The last successful token request or call to ADP.", "format": "date-time", "nullable": true, "type": "string" }, "message": { "description": "The sentence the reconnect banner shows while the connection needs attention; null otherwise.", "nullable": true, "type": "string" }, "paused_until": { "description": "While ADP is not answering and HomeCareBilling has paused calls to it, when it tries again; null otherwise.", "format": "date-time", "nullable": true, "type": "string" }, "status": { "description": "The connection's state.", "enum": [ "pending_subscription", "pending_consent", "active", "needs_attention", "disconnected" ], "type": "string" }, "status_reason": { "description": "Why the connection needs attention: token_refused, circuit_open, certificate_expired, method_paused, or the code Test connection recorded; null otherwise.", "nullable": true, "type": "string" } }, "required": [ "status", "last_success_at", "last_failure_at", "consecutive_failures", "certificate_expires_at", "status_reason", "message", "paused_until" ], "title": "PayrollConnectionHealth", "type": "object" }, "PayrollConnectionSecretsSet": { "properties": { "certificate_pem": { "description": "Whether certificate_pem is set. The value is never answered.", "type": "boolean" }, "client_id": { "description": "Whether client_id is set. The value is never answered.", "type": "boolean" }, "client_secret": { "description": "Whether client_secret is set. The value is never answered.", "type": "boolean" }, "private_key_pem": { "description": "Whether private_key_pem is set. The value is never answered.", "type": "boolean" }, "sftp_private_key": { "description": "Whether sftp_private_key is set. The value is never answered.", "type": "boolean" } }, "required": [ "client_id", "client_secret", "certificate_pem", "private_key_pem", "sftp_private_key" ], "title": "PayrollConnectionSecretsSet", "type": "object" }, "PayrollConnectionSettings": { "properties": { "allow_hire_push": { "description": "Whether a caregiver may be added to ADP from HomeCareBilling (RUN's Add to ADP).", "type": "boolean" }, "employee_id_template": { "description": "Which RUN Time Sheet Import template keys each caregiver: payroll_assigned (ADP's Employee ID) or time_clock (the Time Clock ID).", "enum": [ "payroll_assigned", "time_clock" ], "type": "string" }, "mark_exported_on": { "description": "When a sent export is marked exported.", "enum": [ "all_accepted", "manual" ], "type": "string" }, "rate_mode": { "description": "How API methods send a pay rate.", "enum": [ "rate_value", "rate_code" ], "type": "string" }, "rate_tolerance": { "description": "How far ADP's rate may differ from HomeCareBilling's before a warning.", "format": "decimal", "nullable": true, "type": "string" }, "run_company_code": { "description": "RUN's company code or IID, 1 to 10 letters and numbers; null when unset.", "nullable": true, "type": "string" }, "run_file_version": { "description": "The RUN Time Sheet Import file version.", "enum": [ "V1.0", "V2.0" ], "type": "string" }, "send_contractors": { "description": "Whether 1099 contractors' hours go to ADP too.", "type": "boolean" }, "sftp_folder": { "description": "The SFTP drop's folder; null when unset.", "nullable": true, "type": "string" }, "sftp_host": { "description": "The SFTP drop's host; null when unset.", "nullable": true, "type": "string" }, "sftp_host_key_fingerprint": { "description": "The SHA-256 host key fingerprint the SFTP server presented at the first successful Test connection, trusted from then on; null until then.", "nullable": true, "type": "string" }, "sftp_port": { "description": "The SFTP drop's port, 1 to 65535; null when unset, which connects on 22.", "nullable": true, "type": "integer" }, "sftp_user": { "description": "The SFTP drop's user; null when unset.", "nullable": true, "type": "string" } }, "required": [ "run_company_code", "employee_id_template", "run_file_version", "rate_mode", "mark_exported_on", "send_contractors", "allow_hire_push", "rate_tolerance", "sftp_host", "sftp_user", "sftp_folder", "sftp_host_key_fingerprint", "sftp_port" ], "title": "PayrollConnectionSettings", "type": "object" }, "PayrollConnectionTest": { "properties": { "connected": { "description": "Whether ADP answered with the saved credentials, or the SFTP drop signed in and listed its folder.", "type": "boolean" }, "message": { "description": "The sentence Settings > Payroll's Test connection shows.", "nullable": true, "type": "string" } }, "required": [ "connected", "message" ], "title": "PayrollConnectionTest", "type": "object" }, "PayrollConnectionUpdate": { "properties": { "allow_hire_push": { "description": "RUN: let HomeCareBilling start new hires in RUN (Add to ADP on ADP workers), which sends the caregiver's SSN. Off by default.", "type": "boolean" }, "employee_id_template": { "description": "payroll_assigned (ADP's Employee ID, the default) or time_clock (the Time Clock ID).", "enum": [ "payroll_assigned", "time_clock" ], "type": "string" }, "enabled": { "description": "Turn the ADP payroll integration on or off for the agency. Off keeps the connection, its settings and earning codes.", "type": "boolean" }, "mark_exported_on": { "description": "API methods: all_accepted (the default) marks the export exported when ADP accepts every line; manual leaves it to Mark Downloaded.", "enum": [ "all_accepted", "manual" ], "type": "string" }, "method": { "description": "How payroll reaches ADP; one of methods_offered. Any other is stored as file, with notice saying so.", "enum": [ "file", "sftp_drop", "own_api", "marketplace" ], "type": "string" }, "product": { "description": "Which ADP the agency runs: run (signs in at runpayroll.adp.com), wfn (workforcenow.adp.com) or unknown.", "enum": [ "run", "wfn", "unknown" ], "type": "string" }, "run_company_code": { "description": "RUN's company code or IID, 1 to 10 letters and numbers; null or blank clears it.", "nullable": true, "type": "string" }, "run_file_version": { "description": "The RUN Time Sheet Import file version.", "enum": [ "V1.0", "V2.0" ], "type": "string" }, "send_contractors": { "description": "Send 1099 contractors' hours to ADP too.", "type": "boolean" } }, "title": "PayrollConnectionUpdate", "type": "object" }, "PayrollCredentialsUpdate": { "properties": { "certificate_pem": { "description": "The certificate API Central signed for the request from POST /payroll/connection/csr, PEM; absent or blank keeps the saved one.", "nullable": true, "type": "string" }, "client_id": { "description": "The API Central project's client ID; absent or blank keeps the saved one.", "nullable": true, "type": "string" }, "client_secret": { "description": "The API Central project's client secret; absent or blank keeps the saved one. Never answered.", "nullable": true, "type": "string" } }, "title": "PayrollCredentialsUpdate", "type": "object" }, "PayrollCsr": { "properties": { "csr_pem": { "description": "The certificate request to give API Central, PEM. HomeCareBilling keeps its private key; no answer carries it.", "nullable": true, "type": "string" } }, "required": [ "csr_pem" ], "title": "PayrollCsr", "type": "object" }, "PayrollEarningMapping": { "properties": { "earning_code": { "description": "The ADP earning code carrying these hours; null when the slot is unmapped.", "nullable": true, "type": "string" }, "file_column": { "description": "The Workforce Now file's \"Hours N\" pair, 3 to 50, or null for the file's own column.", "nullable": true, "type": "integer" }, "hour_kind": { "description": "The kind of hours.", "enum": [ "regular", "weekly_overtime", "daily_overtime", "travel", "attendant", "cash_advance" ], "type": "string" }, "rate_code": { "description": "The ADP rate code, or null.", "nullable": true, "type": "string" }, "saved": { "description": "true for a saved code; false for HomeCareBilling's proposal, used until one is saved.", "type": "boolean" }, "source": { "description": "admin when a member saved it, adp_default when read from ADP; null on a proposal.", "enum": [ "adp_default", "admin" ], "nullable": true, "type": "string" }, "worker_type": { "description": "Employees or contractors.", "enum": [ "employee", "contractor" ], "type": "string" } }, "required": [ "hour_kind", "worker_type", "earning_code", "rate_code", "file_column", "source", "saved" ], "title": "PayrollEarningMapping", "type": "object" }, "PayrollEarningMappingUpdate": { "properties": { "earning_code": { "description": "The ADP earning code, 1 to 10 letters or digits as on your ADP Earnings Codes report (upcased and trimmed); null or blank clears the slot back to its proposal.", "nullable": true, "type": "string" }, "file_column": { "description": "The Workforce Now \"Hours N\" pair, 3 to 50, not used by another slot. Left out keeps it; null clears it.", "nullable": true, "type": "integer" }, "hour_kind": { "description": "The kind of hours to map.", "enum": [ "regular", "weekly_overtime", "daily_overtime", "travel", "attendant", "cash_advance" ], "type": "string" }, "rate_code": { "description": "On RUN, BASE, RATE_2 to RATE_5 or HRLY4SLRY1; elsewhere up to 10 letters, digits or underscores. Left out keeps it; null clears it.", "nullable": true, "type": "string" }, "worker_type": { "description": "employee or contractor.", "enum": [ "employee", "contractor" ], "type": "string" } }, "required": [ "hour_kind", "worker_type", "earning_code" ], "title": "PayrollEarningMappingUpdate", "type": "object" }, "PayrollExport": { "properties": { "adp_co_code": { "nullable": true, "type": "string" }, "billing_period_end": { "format": "date", "nullable": true, "type": "string" }, "billing_period_start": { "format": "date", "nullable": true, "type": "string" }, "file_ready": { "description": "Whether GET .../file has a file to return.", "type": "boolean" }, "format": { "description": "adp (Workforce Now) or adp_run.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "status": { "description": "pending, generated or exported.", "nullable": true, "type": "string" } }, "title": "PayrollExport", "type": "object" }, "PayrollHireAttempt": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "message": { "description": "The sentence ADP workers shows on the caregiver's row; null where it offers Add to ADP again.", "nullable": true, "type": "string" }, "status": { "description": "Where the send stands: sent (ADP named the worker, now linked), pending_in_adp (an ADP user finishes it in RUN's New Hire Wizard), unconfirmed (ADP did not answer: check RUN's new hires before sending again), abandoned (cleared by \"I checked RUN: not there\").", "enum": [ "in_flight", "unconfirmed", "pending_in_adp", "sent", "refused", "abandoned" ], "type": "string" } }, "required": [ "caregiver_id", "status", "message" ], "title": "PayrollHireAttempt", "type": "object" }, "PayrollSftpUpdate": { "properties": { "folder": { "description": "The folder ADP picks paydata files up from; absent, blank or null keeps the saved one.", "nullable": true, "type": "string" }, "host": { "description": "The SFTP server ADP gave the agency, a host name; absent, blank or null keeps the saved one. A new host trusts the next Test connection's host key.", "nullable": true, "type": "string" }, "port": { "description": "The SFTP server's port, 1 to 65535; absent or null keeps the saved one, an empty string clears it, and none saved connects on 22. A new port trusts the next Test connection's host key.", "nullable": true, "oneOf": [ { "maximum": 65535, "minimum": 1, "type": "integer" }, { "maxLength": 0, "type": "string" } ] }, "private_key": { "description": "The private key file ADP gave the agency (OpenSSH or PEM, no passphrase), as text; absent, blank or null keeps the saved one. Never answered.", "nullable": true, "type": "string" }, "user": { "description": "The SFTP user ADP gave the agency; absent, blank or null keeps the saved one.", "nullable": true, "type": "string" } }, "title": "PayrollSftpUpdate", "type": "object" }, "PayrollSubmission": { "properties": { "attempt": { "description": "1 for the first send of the export, one more per resend.", "nullable": true, "type": "integer" }, "confirmed_at": { "description": "When every line was answered.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "line_count": { "description": "How many caregivers' lines the submission has.", "nullable": true, "type": "integer" }, "lines": { "items": { "properties": { "caregiver_id": { "description": "The caregiver the line pays.", "format": "uuid", "nullable": true, "type": "string" }, "error_code": { "description": "ADP's code, or HomeCareBilling's when it never reached ADP.", "nullable": true, "type": "string" }, "error_message": { "description": "Why the line was refused.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "label": { "description": "What Payroll exports shows for the line.", "nullable": true, "type": "string" }, "status": { "description": "pending and posting while it goes; accepted; refused by ADP, or before it was posted (error_code not_sent, not_linked or a check rule); unconfirmed while a post that may have been written is confirmed; sent when dropped as a file.", "enum": [ "pending", "posting", "accepted", "refused", "unconfirmed", "sent" ], "type": "string" } }, "required": [ "id", "status", "label" ], "title": "PayrollSubmissionLine", "type": "object" }, "type": "array" }, "message": { "description": "With unchanged: what Payroll exports shows.", "nullable": true, "type": "string" }, "payroll_export_id": { "description": "The payroll export sent.", "format": "uuid", "type": "string" }, "sent_at": { "description": "When posting began.", "format": "date-time", "nullable": true, "type": "string" }, "status": { "description": "queued and sending while it goes; sent when ADP accepted every line, partially_refused or refused when it refused some or all; unconfirmed when a post may have been written and is being confirmed; superseded once a resend replaced it.", "enum": [ "queued", "sending", "sent", "partially_refused", "refused", "unconfirmed", "superseded" ], "type": "string" }, "unchanged": { "description": "Present and true when ADP already had these hours: nothing was sent, and this is the last send that ADP accepted in full.", "type": "boolean" } }, "required": [ "id", "payroll_export_id", "status", "attempt", "line_count", "lines" ], "title": "PayrollSubmission", "type": "object" }, "PayrollSubmissionInput": { "properties": { "choices": { "additionalProperties": { "enum": [ "replace", "keep" ], "type": "string" }, "description": "Per caregiver id, replace (HomeCareBilling's hours) or keep (ADP's), for each line a 409 needs_choice listed.", "type": "object" }, "resend": { "description": "true for Fix and resend: lines ADP accepted before are replaced by their ADP item ids, new ones added.", "type": "boolean" } }, "title": "PayrollSubmissionInput", "type": "object" }, "PayrollSubmissionLine": { "properties": { "caregiver_id": { "description": "The caregiver the line pays.", "format": "uuid", "nullable": true, "type": "string" }, "error_code": { "description": "ADP's code, or HomeCareBilling's when it never reached ADP.", "nullable": true, "type": "string" }, "error_message": { "description": "Why the line was refused.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "label": { "description": "What Payroll exports shows for the line.", "nullable": true, "type": "string" }, "status": { "description": "pending and posting while it goes; accepted; refused by ADP, or before it was posted (error_code not_sent, not_linked or a check rule); unconfirmed while a post that may have been written is confirmed; sent when dropped as a file.", "enum": [ "pending", "posting", "accepted", "refused", "unconfirmed", "sent" ], "type": "string" } }, "required": [ "id", "status", "label" ], "title": "PayrollSubmissionLine", "type": "object" }, "PayrollSummaryPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "adp_left_out": { "description": "The 1099 contractors the ADP files leave out over every row of the period, and their hours.", "properties": { "count": { "description": "How many contractors.", "nullable": true, "type": "integer" }, "hours": { "description": "Their hours, all regular.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "data": { "items": { "$ref": "#/components/schemas/PayrollSummaryRow" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "pay_periods": { "description": "The month's pay periods, from the agency's pay period frequency.", "items": { "properties": { "index": { "description": "The period's index, the period parameter that reads it.", "nullable": true, "type": "integer" }, "period_end": { "format": "date", "nullable": true, "type": "string" }, "period_start": { "format": "date", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "period_end": { "description": "The last day read.", "format": "date", "nullable": true, "type": "string" }, "period_start": { "description": "The first day read.", "format": "date", "nullable": true, "type": "string" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" }, "totals": { "description": "Over every row of the period, not this page; a row with no pay counts 0 in total_pay.", "properties": { "attendant_hours": { "format": "decimal", "nullable": true, "type": "string" }, "cash_advance": { "format": "decimal", "nullable": true, "type": "string" }, "daily_overtime_hours": { "format": "decimal", "nullable": true, "type": "string" }, "overtime_hours": { "format": "decimal", "nullable": true, "type": "string" }, "regular_hours": { "format": "decimal", "nullable": true, "type": "string" }, "total_pay": { "format": "decimal", "nullable": true, "type": "string" }, "travel_hours": { "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "warnings": { "description": "The page's attendant classification warnings.", "items": { "nullable": true, "type": "string" }, "type": "array" } }, "required": [ "period_start", "period_end", "pay_periods", "totals", "warnings", "data", "limit", "offset", "total" ], "title": "PayrollSummaryPage", "type": "object" }, "PayrollSummaryRow": { "description": "One caregiver's pay for the period, as the Payroll Summary shows it.", "properties": { "adp_file_number": { "description": "The caregiver's ADP file number.", "nullable": true, "type": "string" }, "attendant_hours": { "description": "Hours, a decimal string.", "format": "decimal", "nullable": true, "type": "string" }, "attendant_rate": { "description": "The rate the period applied, a decimal string; \"multiple\" when it varied by day; null when none resolved.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "caregiver_name": { "description": "\"Last, First\", as the payroll pages show it.", "nullable": true, "type": "string" }, "cash_advance": { "description": "The cash advances this month's payroll deducts from the caregiver, the whole month's whichever pay period is shown.", "format": "decimal", "nullable": true, "type": "string" }, "cash_advance_held": { "items": { "description": "A cash advance another payroll file deducts and has not recorded the repayment of: not in cash_advance or the totals.", "properties": { "amount": { "description": "What that file deducts.", "format": "decimal", "nullable": true, "type": "string" }, "cash_advance_id": { "description": "The advance.", "format": "uuid", "type": "string" }, "description": { "description": "As the page's Cash Advance column shows it: \"$50.00 on the Oct 01 - Oct 15, 2026 file\".", "nullable": true, "type": "string" }, "payroll_export_id": { "description": "The payroll file that holds it.", "format": "uuid", "type": "string" }, "period_end": { "description": "That file's last day.", "format": "date", "nullable": true, "type": "string" }, "period_start": { "description": "That file's first day.", "format": "date", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "daily_overtime_hours": { "description": "Hours, a decimal string. Zero unless the agency pays daily overtime.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The caregiver (the row is the caregiver's).", "format": "uuid", "type": "string" }, "overtime_hours": { "description": "Hours, a decimal string.", "format": "decimal", "nullable": true, "type": "string" }, "regular_hours": { "description": "Hours, a decimal string.", "format": "decimal", "nullable": true, "type": "string" }, "timesheets": { "items": { "description": "A timesheet the row's hours came from; its hours, travel_hours and attendant_hours are the share of the row's that fell in the period.", "properties": { "attendant_hours": { "description": "Attendant hours in the period.", "format": "decimal", "nullable": true, "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "client_name": { "description": "\"Last, First\".", "nullable": true, "type": "string" }, "hours": { "description": "Worked hours in the period (regular, overtime and daily overtime).", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The timesheet.", "format": "uuid", "type": "string" }, "period_end": { "description": "The timesheet's last day.", "format": "date", "nullable": true, "type": "string" }, "period_start": { "description": "The timesheet's first day.", "format": "date", "nullable": true, "type": "string" }, "travel_hours": { "description": "Travel hours in the period.", "format": "decimal", "nullable": true, "type": "string" }, "wo_number": { "description": "The WO # of the work order it was made from, as the pages show it, or the number imported as text when it names no Work Order; null when it names none.", "nullable": true, "type": "string", "x-untrusted": "text" }, "work_order_id": { "description": "The work order it was made from; null when it names none in this agency.", "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "total_pay": { "description": "The period's pay; null when no work rate resolved.", "format": "decimal", "nullable": true, "type": "string" }, "travel_hours": { "description": "Hours, a decimal string.", "format": "decimal", "nullable": true, "type": "string" }, "travel_rate": { "description": "The rate the period applied, a decimal string; \"multiple\" when it varied by day; null when none resolved.", "nullable": true, "type": "string" }, "work_rate": { "description": "The rate the period applied, a decimal string; \"multiple\" when it varied by day; null when none resolved.", "nullable": true, "type": "string" }, "worker_classification": { "description": "w2 (W-2 employee) or 1099 (independent contractor): a contractor's hours are all regular, and the ADP file leaves them out.", "enum": [ "w2", "1099" ], "type": "string" } }, "required": [ "id", "caregiver_id" ], "title": "PayrollSummaryRow", "type": "object" }, "PayrollWorker": { "properties": { "adp_hire_date": { "description": "The hire date ADP holds.", "format": "date", "nullable": true, "type": "string" }, "adp_name": { "description": "The worker's name as ADP spells it.", "nullable": true, "type": "string" }, "adp_status": { "description": "The worker's status in ADP.", "enum": [ "active", "leave", "terminated" ], "nullable": true, "type": "string" }, "adp_status_date": { "description": "When that status began, in ADP.", "format": "date", "nullable": true, "type": "string" }, "adp_worker_id": { "description": "ADP's employee or file number for the worker.", "nullable": true, "type": "string" }, "associate_oid": { "description": "ADP's id for the worker.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The paired caregiver; null while the worker needs a person.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_name": { "description": "The paired caregiver's name.", "nullable": true, "type": "string" }, "id": { "description": "The worker link, the id POST /payroll/workers/{id}/link takes; null for a caregiver with no ADP worker.", "format": "uuid", "nullable": true, "type": "string" }, "linked_at": { "description": "When it was linked.", "format": "date-time", "nullable": true, "type": "string" }, "linked_by_name": { "description": "Who linked it, for a manual link.", "nullable": true, "type": "string" }, "match_method": { "description": "How the pairing was made: by ADP number, by name with birth or hire date, by a person (manual), or by HomeCareBilling adding the worker to ADP.", "enum": [ "file_number", "name_and_dob", "name_and_hire_date", "manual", "created_in_adp" ], "nullable": true, "type": "string" }, "missing_from_adp": { "description": "True when ADP's last complete worker list no longer held this worker; it then reads terminated.", "type": "boolean" }, "warning": { "description": "What /payroll/workers warns about the row: a different ADP number in HomeCareBilling, or another caregiver already holding this one.", "nullable": true, "type": "string" } }, "required": [ "id", "caregiver_id", "adp_status", "missing_from_adp" ], "title": "PayrollWorker", "type": "object" }, "PayrollWorkerLinkInput": { "properties": { "caregiver_id": { "description": "The caregiver this ADP worker is.", "format": "uuid", "type": "string" } }, "required": [ "caregiver_id" ], "title": "PayrollWorkerLinkInput", "type": "object" }, "PayrollWorkerPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "adp_hire_date": { "description": "The hire date ADP holds.", "format": "date", "nullable": true, "type": "string" }, "adp_name": { "description": "The worker's name as ADP spells it.", "nullable": true, "type": "string" }, "adp_status": { "description": "The worker's status in ADP.", "enum": [ "active", "leave", "terminated" ], "nullable": true, "type": "string" }, "adp_status_date": { "description": "When that status began, in ADP.", "format": "date", "nullable": true, "type": "string" }, "adp_worker_id": { "description": "ADP's employee or file number for the worker.", "nullable": true, "type": "string" }, "associate_oid": { "description": "ADP's id for the worker.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The paired caregiver; null while the worker needs a person.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_name": { "description": "The paired caregiver's name.", "nullable": true, "type": "string" }, "id": { "description": "The worker link, the id POST /payroll/workers/{id}/link takes; null for a caregiver with no ADP worker.", "format": "uuid", "nullable": true, "type": "string" }, "linked_at": { "description": "When it was linked.", "format": "date-time", "nullable": true, "type": "string" }, "linked_by_name": { "description": "Who linked it, for a manual link.", "nullable": true, "type": "string" }, "match_method": { "description": "How the pairing was made: by ADP number, by name with birth or hire date, by a person (manual), or by HomeCareBilling adding the worker to ADP.", "enum": [ "file_number", "name_and_dob", "name_and_hire_date", "manual", "created_in_adp" ], "nullable": true, "type": "string" }, "missing_from_adp": { "description": "True when ADP's last complete worker list no longer held this worker; it then reads terminated.", "type": "boolean" }, "warning": { "description": "What /payroll/workers warns about the row: a different ADP number in HomeCareBilling, or another caregiver already holding this one.", "nullable": true, "type": "string" } }, "required": [ "id", "caregiver_id", "adp_status", "missing_from_adp" ], "title": "PayrollWorker", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "PayrollWorkerPage", "type": "object" }, "PayrollWorkerSync": { "properties": { "queued": { "description": "True: the sync is queued, or already waiting to run.", "type": "boolean" } }, "required": [ "queued" ], "title": "PayrollWorkerSync", "type": "object" }, "PcspDocument": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "content_type": { "description": "Its type.", "nullable": true, "type": "string" }, "file_name": { "description": "Its name.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "uploaded_at": { "description": "When it was stored.", "format": "date-time", "type": "string" } }, "required": [ "id", "client_id" ], "title": "PcspDocument", "type": "object" }, "PcspReconciliationApply": { "properties": { "decisions": { "description": "excluded, choices and supersessions.", "properties": { "choices": { "description": "Row index => the authorization id it updates.", "type": "object" }, "excluded": { "description": "Row indexes to leave out.", "items": { "type": "integer" }, "type": "array" }, "supersessions": { "description": "Authorization id => end_date or leave.", "type": "object" } }, "title": "PcspReconciliationDecisions", "type": "object" }, "token": { "description": "The token the preview answered.", "format": "uuid", "type": "string" } }, "required": [ "token" ], "title": "PcspReconciliationApply", "type": "object" }, "PcspReconciliationDecisions": { "description": "excluded, choices and supersessions.", "properties": { "choices": { "description": "Row index => the authorization id it updates.", "type": "object" }, "excluded": { "description": "Row indexes to leave out.", "items": { "type": "integer" }, "type": "array" }, "supersessions": { "description": "Authorization id => end_date or leave.", "type": "object" } }, "title": "PcspReconciliationDecisions", "type": "object" }, "PcspReconciliationPreview": { "properties": { "candidates": { "description": "Each proposed authorisation, with its index.", "items": { "type": "object" }, "type": "array" }, "expires_in_seconds": { "description": "How long the token is good for.", "nullable": true, "type": "integer" }, "identity_mismatch": { "description": "Set when the PCSP names another member; nothing can be applied.", "items": { "type": "object" }, "type": "array" }, "service_plan_type": { "description": "initial, csr or revision.", "nullable": true, "type": "string" }, "supersessions": { "items": { "type": "object" }, "type": "array" }, "token": { "description": "The apply token, or null when nothing can be applied.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "candidates" ], "title": "PcspReconciliationPreview", "type": "object" }, "PcspReconciliationResult": { "properties": { "complete": { "description": "Whether nothing is left outstanding.", "type": "boolean" }, "results": { "items": { "type": "object" }, "type": "array" } }, "required": [ "results", "complete" ], "title": "PcspReconciliationResult", "type": "object" }, "PersonDocument": { "properties": { "content_type": { "description": "Its type.", "nullable": true, "type": "string" }, "document_type": { "description": "What the document is, as the Documents tab's Type.", "enum": [ "care_plan", "authorization", "signed_agreement", "training_certificate", "background_check", "medical_form", "incident_report", "pcsp", "cfc_calculator", "legacy_paper", "other", "paper_capture", "true_copy", "voice_attestation" ], "type": "string" }, "documentable_id": { "description": "The client or caregiver.", "format": "uuid", "type": "string" }, "documentable_type": { "description": "Whose file it is on.", "enum": [ "client", "caregiver" ], "type": "string" }, "expiry_date": { "description": "When it expires, if it does.", "format": "date", "nullable": true, "type": "string" }, "file_name": { "description": "The file's name.", "nullable": true, "type": "string" }, "file_size": { "description": "Its size in bytes.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was uploaded.", "format": "date-time", "type": "string" }, "notes": { "description": "The tab's notes.", "nullable": true, "type": "string" }, "paper_form_type": { "description": "A legacy_paper scan's form type, as the paper archive files it (US-101.7); other when not given. Ignored on any other document_type.", "enum": [ "work_order", "time_services_card", "plan_of_care", "monthly_client_report", "supervisory_visit", "cfc_calculator", "intake_consent", "complaint_incident", "other" ], "nullable": true, "type": "string" }, "record_date": { "description": "A legacy_paper scan's date on the paper; a monthly form's is its month's first day. Ignored on any other document_type.", "format": "date", "nullable": true, "type": "string" }, "scan_status": { "description": "The virus scan's verdict; only a clean file can be downloaded.", "enum": [ "pending", "clean", "infected", "error" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" }, "uploaded_by": { "description": "Who uploaded it.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "documentable_type", "documentable_id", "file_name", "scan_status" ], "title": "PersonDocument", "type": "object" }, "PersonDocumentList": { "properties": { "data": { "items": { "properties": { "content_type": { "description": "Its type.", "nullable": true, "type": "string" }, "document_type": { "description": "What the document is, as the Documents tab's Type.", "enum": [ "care_plan", "authorization", "signed_agreement", "training_certificate", "background_check", "medical_form", "incident_report", "pcsp", "cfc_calculator", "legacy_paper", "other", "paper_capture", "true_copy", "voice_attestation" ], "type": "string" }, "documentable_id": { "description": "The client or caregiver.", "format": "uuid", "type": "string" }, "documentable_type": { "description": "Whose file it is on.", "enum": [ "client", "caregiver" ], "type": "string" }, "expiry_date": { "description": "When it expires, if it does.", "format": "date", "nullable": true, "type": "string" }, "file_name": { "description": "The file's name.", "nullable": true, "type": "string" }, "file_size": { "description": "Its size in bytes.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was uploaded.", "format": "date-time", "type": "string" }, "notes": { "description": "The tab's notes.", "nullable": true, "type": "string" }, "paper_form_type": { "description": "A legacy_paper scan's form type, as the paper archive files it (US-101.7); other when not given. Ignored on any other document_type.", "enum": [ "work_order", "time_services_card", "plan_of_care", "monthly_client_report", "supervisory_visit", "cfc_calculator", "intake_consent", "complaint_incident", "other" ], "nullable": true, "type": "string" }, "record_date": { "description": "A legacy_paper scan's date on the paper; a monthly form's is its month's first day. Ignored on any other document_type.", "format": "date", "nullable": true, "type": "string" }, "scan_status": { "description": "The virus scan's verdict; only a clean file can be downloaded.", "enum": [ "pending", "clean", "infected", "error" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" }, "uploaded_by": { "description": "Who uploaded it.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "documentable_type", "documentable_id", "file_name", "scan_status" ], "title": "PersonDocument", "type": "object" }, "type": "array" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "PersonDocumentList", "type": "object" }, "PersonDocumentUpdate": { "properties": { "document_type": { "description": "What the document is, as the Documents tab's Type.", "enum": [ "care_plan", "authorization", "signed_agreement", "training_certificate", "background_check", "medical_form", "incident_report", "pcsp", "cfc_calculator", "legacy_paper", "other" ], "type": "string" }, "expiry_date": { "description": "When it expires.", "format": "date", "nullable": true, "type": "string" }, "notes": { "description": "Notes, as the tab's Notes.", "nullable": true, "type": "string" }, "paper_form_type": { "description": "A legacy_paper scan's form type, as the paper archive files it (US-101.7); other when not given. Ignored on any other document_type.", "enum": [ "work_order", "time_services_card", "plan_of_care", "monthly_client_report", "supervisory_visit", "cfc_calculator", "intake_consent", "complaint_incident", "other" ], "type": "string" }, "record_date": { "description": "A legacy_paper scan's date on the paper; a monthly form's is its month's first day. Ignored on any other document_type.", "format": "date", "nullable": true, "type": "string" } }, "title": "PersonDocumentUpdate", "type": "object" }, "PersonDocumentUpload": { "properties": { "content_type": { "description": "Its type; null or left out reads the extension's.", "nullable": true, "type": "string" }, "document_type": { "description": "What the document is, as the Documents tab's Type.", "enum": [ "care_plan", "authorization", "signed_agreement", "training_certificate", "background_check", "medical_form", "incident_report", "pcsp", "cfc_calculator", "legacy_paper", "other" ], "type": "string" }, "expiry_date": { "description": "When it expires.", "format": "date", "nullable": true, "type": "string" }, "file_base64": { "description": "The file's bytes, base64.", "type": "string" }, "file_name": { "description": "Its name, with its extension.", "type": "string" }, "notes": { "description": "Notes, as the tab's Notes.", "nullable": true, "type": "string" }, "paper_form_type": { "description": "A legacy_paper scan's form type, as the paper archive files it (US-101.7); other when not given. Ignored on any other document_type.", "enum": [ "work_order", "time_services_card", "plan_of_care", "monthly_client_report", "supervisory_visit", "cfc_calculator", "intake_consent", "complaint_incident", "other" ], "type": "string" }, "record_date": { "description": "A legacy_paper scan's date on the paper; a monthly form's is its month's first day. Ignored on any other document_type.", "format": "date", "nullable": true, "type": "string" } }, "required": [ "file_base64", "file_name" ], "title": "PersonDocumentUpload", "type": "object" }, "PhoneCareLogDismiss": { "properties": { "reason": { "description": "Why it can be dismissed, 3 to 500 characters, as the screen asks.", "type": "string" } }, "title": "PhoneCareLogDismiss", "type": "object" }, "PhoneCareLogException": { "properties": { "attestation_skip_reason": { "description": "Why the phone attestation did not become a signature, if it did not.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "finished_at": { "description": "When the call finished the day.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reasons": { "description": "Why it is listed: no_tasks (No tasks entered); call_ended_early (Call ended before finishing); attestation_missing (No client confirmation); attestation_interrupted (Attestation interrupted); attestation_empty (Client recording silent); attestation_unverified (Recording not linked to this log); attestation_not_saved (Client recording could not be saved)", "items": { "enum": [ "no_tasks", "call_ended_early", "attestation_missing", "attestation_interrupted", "attestation_empty", "attestation_unverified", "attestation_not_saved" ], "type": "string" }, "type": "array" }, "record_state": { "description": "The care log's record state; a voided one is never listed.", "enum": [ "draft", "signed", "amended" ], "type": "string" }, "recording_document_id": { "description": "The client's kept recording, a voice_attestation document, if any.", "format": "uuid", "nullable": true, "type": "string" }, "service_date": { "description": "The day.", "format": "date", "type": "string" }, "service_type": { "description": "The service.", "enum": [ "personal_care", "homemaker", "legacy" ], "type": "string" }, "shift_number": { "description": "The shift.", "type": "integer" }, "visit_id": { "description": "The Visit the call clocked.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "client_id", "caregiver_id", "service_date", "service_type", "shift_number", "record_state", "reasons" ], "title": "PhoneCareLogException", "type": "object" }, "PhoneCareLogExceptionPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/PhoneCareLogException" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "PhoneCareLogExceptionPage", "type": "object" }, "Plan of carePage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/PlanOfCare" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Plan of carePage", "type": "object" }, "PlanOfCare": { "description": "A client's Plan of Care for one service, with its tasks. Creating one makes the client's current plan for that billing line past, as on the web (an LRP Homemaker plan is its own line).", "properties": { "authorization_id": { "description": "The service authorization (PAR) the plan works under: one of this client's, not deleted. Null or blank unlinks it; another id answers 422 naming authorization_id.", "format": "uuid", "nullable": true, "type": "string" }, "billing_code_hmkr": { "description": "The homemaker billing code.", "nullable": true, "type": "string" }, "billing_code_ihss": { "description": "The IHSS billing code.", "nullable": true, "type": "string" }, "billing_code_pcp": { "description": "The personal care billing code.", "nullable": true, "type": "string" }, "case_manager_name": { "description": "The client's case manager.", "nullable": true, "type": "string", "x-untrusted": "text" }, "client_id": { "description": "The client the plan is for.", "format": "uuid", "type": "string" }, "cm_authorized_hma_hours_weekly": { "description": "Health maintenance hours a week the case manager authorized.", "format": "decimal", "nullable": true, "type": "string" }, "effective_date": { "format": "date", "nullable": true, "type": "string" }, "end_date": { "format": "date", "nullable": true, "type": "string" }, "extra_hours_weekly_hma": { "description": "Extra health maintenance hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "extra_hours_weekly_homemaker": { "description": "Extra homemaker hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "extra_hours_weekly_personal_care": { "description": "Extra personal care hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours_weekly_hma": { "description": "Travel hours a week with the extra health maintenance hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours_weekly_homemaker": { "description": "Travel hours a week with the extra homemaker hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours_weekly_personal_care": { "description": "Travel hours a week with the extra personal care hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks_hma": { "description": "Weeks the extra health maintenance hours run.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks_homemaker": { "description": "Weeks the extra homemaker hours run.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks_personal_care": { "description": "Weeks the extra personal care hours run.", "format": "decimal", "nullable": true, "type": "string" }, "flag_bi": { "description": "Brain injury flag.", "type": "boolean" }, "flag_mi": { "description": "Mental illness flag.", "type": "boolean" }, "flag_plwa": { "description": "PLWA flag.", "type": "boolean" }, "hma_hours_weekly": { "description": "Health maintenance hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "homemaker_hours_weekly": { "description": "Homemaker hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the plan was created.", "format": "date-time", "type": "string" }, "lrp": { "description": "A legally responsible person provides this Homemaker plan's care (US-83.6): it is its own billing line, billed with HA, and stays current beside the client's regular Homemaker plan. False when left out of a create; only a Homemaker plan may set it, and only on create: a PATCH that changes it answers 422 naming lrp.", "type": "boolean" }, "lrp_hours_weekly": { "description": "Hours a week a legally responsible person provides.", "format": "decimal", "nullable": true, "type": "string" }, "missing_signers": { "description": "Each required line no live signature fills yet, in order; empty when complete or voided.", "items": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "type": "array" }, "modifiers_hmkr": { "description": "Homemaker modifiers.", "items": { "type": "string" }, "type": "array" }, "modifiers_ihss": { "description": "IHSS modifiers.", "items": { "type": "string" }, "type": "array" }, "modifiers_pcp": { "description": "Personal care modifiers.", "items": { "type": "string" }, "type": "array" }, "notes": { "description": "Free text on the plan.", "nullable": true, "type": "string", "x-untrusted": "text" }, "par_effective_date": { "format": "date", "nullable": true, "type": "string" }, "par_expiry_date": { "format": "date", "nullable": true, "type": "string" }, "par_number": { "description": "The PAR the plan works under.", "nullable": true, "type": "string" }, "par_units_hma": { "description": "PAR units authorized for health maintenance.", "nullable": true, "type": "integer" }, "par_units_homemaker": { "description": "PAR units authorized for homemaker.", "nullable": true, "type": "integer" }, "par_units_personal_care": { "description": "PAR units authorized for personal care.", "nullable": true, "type": "integer" }, "personal_care_hours_weekly": { "description": "Personal care hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "record_state": { "description": "The signed record's state: draft until the first signature, then signed (locked: changed only by revising it), amended (an addendum was signed) or voided (revised into a new draft). signing_complete says whether every required line is signed: the client or representative, and the supervisor.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "replaces_id": { "description": "The voided plan this draft was revised from, if any.", "format": "uuid", "nullable": true, "type": "string" }, "service_type": { "description": "The plan's one service.", "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "signatures": { "description": "The live signatures, oldest first, without their images. Drawing is done on a device, on the plan page.", "items": { "properties": { "method": { "description": "How it was signed: drawn, initials, typed and so on.", "enum": [ "drawn", "initials", "typed", "pin", "voice", "docusign_agency", "docusign_platform", "paper_on_file", "imported" ], "type": "string" }, "role": { "description": "The line signed: client, or representative in the client's place, and supervisor.", "enum": [ "client", "representative", "supervisor" ], "type": "string" }, "signed_at": { "description": "When the line was signed.", "format": "date-time", "type": "string" }, "signer_name": { "description": "The name the line is signed under.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "method", "signed_at" ], "title": "PlanOfCareSignature", "type": "object" }, "type": "array" }, "signed_at": { "description": "When the first signature locked it; null on a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing_complete": { "description": "True once the record is signed or amended and every required line holds a signature. A signed record can be false: signed by one line, with another still open. A voided record is always false, whatever it holds, and its missing_signers is empty: nothing can sign it, and its replacement is the record to complete.", "type": "boolean" }, "status": { "enum": [ "current", "past" ], "type": "string" }, "tasks": { "description": "The plan's tasks.", "items": { "$ref": "#/components/schemas/PlanOfCareTask" }, "type": "array" }, "travel_hours_weekly_hma": { "description": "Health maintenance travel hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "travel_hours_weekly_homemaker": { "description": "Homemaker travel hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "travel_hours_weekly_personal_care": { "description": "Personal care travel hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "updated_at": { "description": "When the plan last changed.", "format": "date-time", "type": "string" }, "warnings": { "description": "What a save saved anyway, in this order: over_authorized when an update lowers a task below what the client's Work Orders still schedule; then care_planning.task_hours_over_authorization, one per service whose tasks add up to more hours a week than the plan authorizes, on a create or an update. Empty otherwise, and on a read.", "items": { "properties": { "code": { "description": "The warning.", "nullable": true, "type": "string" }, "message": { "description": "What it means.", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "id", "client_id", "status" ], "title": "PlanOfCare", "type": "object" }, "PlanOfCareCreate": { "description": "A new Plan of Care for one of the agency's clients, with its tasks, all of one service. The client's current plan for that billing line becomes past (lrp true makes a Homemaker plan its own line, beside the regular one). A client_id that is not the agency's answers 422 client_not_found.", "properties": { "authorization_id": { "description": "The service authorization (PAR) the plan works under: one of this client's, not deleted. Null or blank unlinks it; another id answers 422 naming authorization_id.", "format": "uuid", "nullable": true, "type": "string" }, "billing_code_hmkr": { "description": "The homemaker billing code.", "nullable": true, "type": "string" }, "billing_code_ihss": { "description": "The IHSS billing code.", "nullable": true, "type": "string" }, "billing_code_pcp": { "description": "The personal care billing code.", "nullable": true, "type": "string" }, "case_manager_name": { "description": "The client's case manager.", "nullable": true, "type": "string", "x-untrusted": "text" }, "client_id": { "description": "The client the plan is for.", "format": "uuid", "type": "string" }, "cm_authorized_hma_hours_weekly": { "description": "Health maintenance hours a week the case manager authorized.", "format": "decimal", "nullable": true, "type": "string" }, "effective_date": { "format": "date", "nullable": false, "type": "string" }, "end_date": { "format": "date", "nullable": true, "type": "string" }, "extra_hours_weekly_hma": { "description": "Extra health maintenance hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "extra_hours_weekly_homemaker": { "description": "Extra homemaker hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "extra_hours_weekly_personal_care": { "description": "Extra personal care hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours_weekly_hma": { "description": "Travel hours a week with the extra health maintenance hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours_weekly_homemaker": { "description": "Travel hours a week with the extra homemaker hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours_weekly_personal_care": { "description": "Travel hours a week with the extra personal care hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks_hma": { "description": "Weeks the extra health maintenance hours run.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks_homemaker": { "description": "Weeks the extra homemaker hours run.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks_personal_care": { "description": "Weeks the extra personal care hours run.", "format": "decimal", "nullable": true, "type": "string" }, "flag_bi": { "description": "Brain injury flag.", "type": "boolean" }, "flag_mi": { "description": "Mental illness flag.", "type": "boolean" }, "flag_plwa": { "description": "PLWA flag.", "type": "boolean" }, "hma_hours_weekly": { "description": "Health maintenance hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "homemaker_hours_weekly": { "description": "Homemaker hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "lrp": { "description": "A legally responsible person provides this Homemaker plan's care (US-83.6): it is its own billing line, billed with HA, and stays current beside the client's regular Homemaker plan. False when left out of a create; only a Homemaker plan may set it, and only on create: a PATCH that changes it answers 422 naming lrp.", "type": "boolean" }, "lrp_hours_weekly": { "description": "Hours a week a legally responsible person provides.", "format": "decimal", "nullable": true, "type": "string" }, "modifiers_hmkr": { "description": "Homemaker modifiers.", "items": { "type": "string" }, "type": "array" }, "modifiers_ihss": { "description": "IHSS modifiers.", "items": { "type": "string" }, "type": "array" }, "modifiers_pcp": { "description": "Personal care modifiers.", "items": { "type": "string" }, "type": "array" }, "notes": { "description": "Free text on the plan.", "nullable": true, "type": "string", "x-untrusted": "text" }, "par_effective_date": { "format": "date", "nullable": true, "type": "string" }, "par_expiry_date": { "format": "date", "nullable": true, "type": "string" }, "par_number": { "description": "The PAR the plan works under.", "nullable": true, "type": "string" }, "par_units_hma": { "description": "PAR units authorized for health maintenance.", "nullable": true, "type": "integer" }, "par_units_homemaker": { "description": "PAR units authorized for homemaker.", "nullable": true, "type": "integer" }, "par_units_personal_care": { "description": "PAR units authorized for personal care.", "nullable": true, "type": "integer" }, "personal_care_hours_weekly": { "description": "Personal care hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "service_type": { "description": "The plan's service; derived from the tasks when they share one.", "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "tasks": { "description": "The plan's tasks. A create or update replaces them with the list sent.", "items": { "description": "A task on a Plan of Care, as a create or update takes it.", "properties": { "ame_flag": { "description": "Whether the task is AME.", "type": "boolean" }, "justification": { "description": "Why the task needs the time it takes.", "nullable": true, "type": "string", "x-untrusted": "text" }, "minutes_fri": { "description": "Minutes on that weekday (minutes_fri).", "nullable": true, "type": "integer" }, "minutes_mon": { "description": "Minutes on that weekday (minutes_mon).", "nullable": true, "type": "integer" }, "minutes_per_task": { "description": "Minutes each time.", "nullable": true, "type": "number" }, "minutes_sat": { "description": "Minutes on that weekday (minutes_sat).", "nullable": true, "type": "integer" }, "minutes_sun": { "description": "Minutes on that weekday (minutes_sun).", "nullable": true, "type": "integer" }, "minutes_thu": { "description": "Minutes on that weekday (minutes_thu).", "nullable": true, "type": "integer" }, "minutes_tue": { "description": "Minutes on that weekday (minutes_tue).", "nullable": true, "type": "integer" }, "minutes_wed": { "description": "Minutes on that weekday (minutes_wed).", "nullable": true, "type": "integer" }, "norms": { "description": "The norms that apply to the task.", "nullable": true, "type": "string", "x-untrusted": "text" }, "shift_number": { "description": "The shift, 1 to 4.", "nullable": true, "type": "integer" }, "sort_order": { "description": "Where the task sits in the plan.", "nullable": true, "type": "integer" }, "task_category": { "description": "The service the task belongs to.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" }, "task_name": { "description": "What the caregiver does; free text, as on the web.", "nullable": true, "type": "string", "x-untrusted": "text" }, "times_per_week": { "description": "Times a week.", "nullable": true, "type": "integer" } }, "title": "PlanOfCareTaskInput", "type": "object" }, "type": "array" }, "travel_hours_weekly_hma": { "description": "Health maintenance travel hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "travel_hours_weekly_homemaker": { "description": "Homemaker travel hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "travel_hours_weekly_personal_care": { "description": "Personal care travel hours a week.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "client_id", "effective_date", "tasks" ], "title": "PlanOfCareCreate", "type": "object" }, "PlanOfCareRevision": { "properties": { "reason": { "description": "Why the signed plan is revised, 3 to 1000 characters. It is kept with the voided original.", "nullable": true, "type": "string" } }, "required": [ "reason" ], "title": "PlanOfCareRevision", "type": "object" }, "PlanOfCareSignature": { "properties": { "method": { "description": "How it was signed: drawn, initials, typed and so on.", "enum": [ "drawn", "initials", "typed", "pin", "voice", "docusign_agency", "docusign_platform", "paper_on_file", "imported" ], "type": "string" }, "role": { "description": "The line signed: client, or representative in the client's place, and supervisor.", "enum": [ "client", "representative", "supervisor" ], "type": "string" }, "signed_at": { "description": "When the line was signed.", "format": "date-time", "type": "string" }, "signer_name": { "description": "The name the line is signed under.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "method", "signed_at" ], "title": "PlanOfCareSignature", "type": "object" }, "PlanOfCareSupervisorSignature": { "properties": { "signer_name": { "description": "The supervisor's name as the signature records it; the credential's user is the signer.", "nullable": true, "type": "string" } }, "required": [ "signer_name" ], "title": "PlanOfCareSupervisorSignature", "type": "object" }, "PlanOfCareTask": { "description": "A task on a Plan of Care.", "properties": { "ame_flag": { "description": "Whether the task is AME.", "type": "boolean" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "justification": { "description": "Why the task needs the time it takes.", "nullable": true, "type": "string", "x-untrusted": "text" }, "minutes_fri": { "description": "Minutes on that weekday (minutes_fri).", "nullable": true, "type": "integer" }, "minutes_mon": { "description": "Minutes on that weekday (minutes_mon).", "nullable": true, "type": "integer" }, "minutes_per_task": { "description": "Minutes each time.", "format": "decimal", "nullable": true, "type": "string" }, "minutes_per_week": { "description": "Minutes a week, computed by the plan.", "format": "decimal", "nullable": true, "type": "string" }, "minutes_sat": { "description": "Minutes on that weekday (minutes_sat).", "nullable": true, "type": "integer" }, "minutes_sun": { "description": "Minutes on that weekday (minutes_sun).", "nullable": true, "type": "integer" }, "minutes_thu": { "description": "Minutes on that weekday (minutes_thu).", "nullable": true, "type": "integer" }, "minutes_tue": { "description": "Minutes on that weekday (minutes_tue).", "nullable": true, "type": "integer" }, "minutes_wed": { "description": "Minutes on that weekday (minutes_wed).", "nullable": true, "type": "integer" }, "norms": { "description": "The norms that apply to the task.", "nullable": true, "type": "string", "x-untrusted": "text" }, "shift_number": { "description": "The shift, 1 to 4.", "nullable": true, "type": "integer" }, "sort_order": { "description": "Where the task sits in the plan.", "nullable": true, "type": "integer" }, "task_category": { "description": "The service the task belongs to.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" }, "task_name": { "description": "What the caregiver does; free text, as on the web.", "nullable": true, "type": "string", "x-untrusted": "text" }, "times_per_week": { "description": "Times a week.", "nullable": true, "type": "integer" } }, "title": "PlanOfCareTask", "type": "object" }, "PlanOfCareTaskInput": { "description": "A task on a Plan of Care, as a create or update takes it.", "properties": { "ame_flag": { "description": "Whether the task is AME.", "type": "boolean" }, "justification": { "description": "Why the task needs the time it takes.", "nullable": true, "type": "string", "x-untrusted": "text" }, "minutes_fri": { "description": "Minutes on that weekday (minutes_fri).", "nullable": true, "type": "integer" }, "minutes_mon": { "description": "Minutes on that weekday (minutes_mon).", "nullable": true, "type": "integer" }, "minutes_per_task": { "description": "Minutes each time.", "nullable": true, "type": "number" }, "minutes_sat": { "description": "Minutes on that weekday (minutes_sat).", "nullable": true, "type": "integer" }, "minutes_sun": { "description": "Minutes on that weekday (minutes_sun).", "nullable": true, "type": "integer" }, "minutes_thu": { "description": "Minutes on that weekday (minutes_thu).", "nullable": true, "type": "integer" }, "minutes_tue": { "description": "Minutes on that weekday (minutes_tue).", "nullable": true, "type": "integer" }, "minutes_wed": { "description": "Minutes on that weekday (minutes_wed).", "nullable": true, "type": "integer" }, "norms": { "description": "The norms that apply to the task.", "nullable": true, "type": "string", "x-untrusted": "text" }, "shift_number": { "description": "The shift, 1 to 4.", "nullable": true, "type": "integer" }, "sort_order": { "description": "Where the task sits in the plan.", "nullable": true, "type": "integer" }, "task_category": { "description": "The service the task belongs to.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" }, "task_name": { "description": "What the caregiver does; free text, as on the web.", "nullable": true, "type": "string", "x-untrusted": "text" }, "times_per_week": { "description": "Times a week.", "nullable": true, "type": "integer" } }, "title": "PlanOfCareTaskInput", "type": "object" }, "PlanOfCareUpdate": { "description": "The plan fields to change, and its tasks. A task list sent replaces the plan's tasks; leave it out to keep them. Lowering a task below what the client's Work Orders still schedule is saved with an over_authorized warning.", "properties": { "authorization_id": { "description": "The service authorization (PAR) the plan works under: one of this client's, not deleted. Null or blank unlinks it; another id answers 422 naming authorization_id.", "format": "uuid", "nullable": true, "type": "string" }, "billing_code_hmkr": { "description": "The homemaker billing code.", "nullable": true, "type": "string" }, "billing_code_ihss": { "description": "The IHSS billing code.", "nullable": true, "type": "string" }, "billing_code_pcp": { "description": "The personal care billing code.", "nullable": true, "type": "string" }, "case_manager_name": { "description": "The client's case manager.", "nullable": true, "type": "string", "x-untrusted": "text" }, "cm_authorized_hma_hours_weekly": { "description": "Health maintenance hours a week the case manager authorized.", "format": "decimal", "nullable": true, "type": "string" }, "effective_date": { "format": "date", "nullable": false, "type": "string" }, "end_date": { "format": "date", "nullable": true, "type": "string" }, "extra_hours_weekly_hma": { "description": "Extra health maintenance hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "extra_hours_weekly_homemaker": { "description": "Extra homemaker hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "extra_hours_weekly_personal_care": { "description": "Extra personal care hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours_weekly_hma": { "description": "Travel hours a week with the extra health maintenance hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours_weekly_homemaker": { "description": "Travel hours a week with the extra homemaker hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours_weekly_personal_care": { "description": "Travel hours a week with the extra personal care hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks_hma": { "description": "Weeks the extra health maintenance hours run.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks_homemaker": { "description": "Weeks the extra homemaker hours run.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks_personal_care": { "description": "Weeks the extra personal care hours run.", "format": "decimal", "nullable": true, "type": "string" }, "flag_bi": { "description": "Brain injury flag.", "type": "boolean" }, "flag_mi": { "description": "Mental illness flag.", "type": "boolean" }, "flag_plwa": { "description": "PLWA flag.", "type": "boolean" }, "hma_hours_weekly": { "description": "Health maintenance hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "homemaker_hours_weekly": { "description": "Homemaker hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "lrp": { "description": "A legally responsible person provides this Homemaker plan's care (US-83.6): it is its own billing line, billed with HA, and stays current beside the client's regular Homemaker plan. False when left out of a create; only a Homemaker plan may set it, and only on create: a PATCH that changes it answers 422 naming lrp.", "type": "boolean" }, "lrp_hours_weekly": { "description": "Hours a week a legally responsible person provides.", "format": "decimal", "nullable": true, "type": "string" }, "modifiers_hmkr": { "description": "Homemaker modifiers.", "items": { "type": "string" }, "type": "array" }, "modifiers_ihss": { "description": "IHSS modifiers.", "items": { "type": "string" }, "type": "array" }, "modifiers_pcp": { "description": "Personal care modifiers.", "items": { "type": "string" }, "type": "array" }, "notes": { "description": "Free text on the plan.", "nullable": true, "type": "string", "x-untrusted": "text" }, "par_effective_date": { "format": "date", "nullable": true, "type": "string" }, "par_expiry_date": { "format": "date", "nullable": true, "type": "string" }, "par_number": { "description": "The PAR the plan works under.", "nullable": true, "type": "string" }, "par_units_hma": { "description": "PAR units authorized for health maintenance.", "nullable": true, "type": "integer" }, "par_units_homemaker": { "description": "PAR units authorized for homemaker.", "nullable": true, "type": "integer" }, "par_units_personal_care": { "description": "PAR units authorized for personal care.", "nullable": true, "type": "integer" }, "personal_care_hours_weekly": { "description": "Personal care hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "tasks": { "description": "The plan's tasks. A create or update replaces them with the list sent.", "items": { "description": "A task on a Plan of Care, as a create or update takes it.", "properties": { "ame_flag": { "description": "Whether the task is AME.", "type": "boolean" }, "justification": { "description": "Why the task needs the time it takes.", "nullable": true, "type": "string", "x-untrusted": "text" }, "minutes_fri": { "description": "Minutes on that weekday (minutes_fri).", "nullable": true, "type": "integer" }, "minutes_mon": { "description": "Minutes on that weekday (minutes_mon).", "nullable": true, "type": "integer" }, "minutes_per_task": { "description": "Minutes each time.", "nullable": true, "type": "number" }, "minutes_sat": { "description": "Minutes on that weekday (minutes_sat).", "nullable": true, "type": "integer" }, "minutes_sun": { "description": "Minutes on that weekday (minutes_sun).", "nullable": true, "type": "integer" }, "minutes_thu": { "description": "Minutes on that weekday (minutes_thu).", "nullable": true, "type": "integer" }, "minutes_tue": { "description": "Minutes on that weekday (minutes_tue).", "nullable": true, "type": "integer" }, "minutes_wed": { "description": "Minutes on that weekday (minutes_wed).", "nullable": true, "type": "integer" }, "norms": { "description": "The norms that apply to the task.", "nullable": true, "type": "string", "x-untrusted": "text" }, "shift_number": { "description": "The shift, 1 to 4.", "nullable": true, "type": "integer" }, "sort_order": { "description": "Where the task sits in the plan.", "nullable": true, "type": "integer" }, "task_category": { "description": "The service the task belongs to.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" }, "task_name": { "description": "What the caregiver does; free text, as on the web.", "nullable": true, "type": "string", "x-untrusted": "text" }, "times_per_week": { "description": "Times a week.", "nullable": true, "type": "integer" } }, "title": "PlanOfCareTaskInput", "type": "object" }, "type": "array" }, "travel_hours_weekly_hma": { "description": "Health maintenance travel hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "travel_hours_weekly_homemaker": { "description": "Homemaker travel hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "travel_hours_weekly_personal_care": { "description": "Personal care travel hours a week.", "format": "decimal", "nullable": true, "type": "string" } }, "title": "PlanOfCareUpdate", "type": "object" }, "PlanServiceMinutes": { "properties": { "authorized_minutes": { "type": "integer" }, "rounding": { "enum": [ "quarter_hour", "under" ], "nullable": true, "type": "string" }, "service": { "type": "string" }, "task_minutes": { "type": "integer" } }, "required": [ "service", "authorized_minutes", "task_minutes", "rounding" ], "title": "PlanServiceMinutes", "type": "object" }, "Prospect": { "description": "Someone in the agency's pipeline: a potential client or a potential employee. Converting one at onboarding makes the client or caregiver and links it here.", "properties": { "address": { "description": "Their address on one line, \"street, city, ST 12345\". Carried to the client or caregiver on conversion.", "nullable": true, "type": "string", "x-untrusted": "text" }, "availability": { "description": "Employee: when they can work.", "nullable": true, "type": "string", "x-untrusted": "text" }, "contact_name": { "description": "Client: the person to reach about them (family, a case manager). Becomes the client's emergency contact on conversion.", "nullable": true, "type": "string", "x-untrusted": "text" }, "contact_notes": { "description": "Notes from contacting them.", "nullable": true, "type": "string", "x-untrusted": "text" }, "contact_phone": { "description": "Client: the contact person's 10-digit phone.", "nullable": true, "type": "string", "x-untrusted": "text" }, "converted_at": { "description": "When it was converted (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "converted_to_id": { "description": "The client or caregiver it was converted to.", "format": "uuid", "nullable": true, "type": "string" }, "converted_to_type": { "description": "What it was converted to.", "enum": [ "client", "caregiver" ], "nullable": true, "type": "string" }, "email": { "description": "Email address.", "nullable": true, "type": "string" }, "employee_comments": { "description": "Employee: comments.", "nullable": true, "type": "string", "x-untrusted": "text" }, "first_name": { "description": "First name.", "type": "string" }, "has_experience": { "description": "Employee: whether they have care experience.", "type": "boolean" }, "has_vehicle": { "description": "Employee: whether they have a vehicle.", "type": "boolean" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was added.", "format": "date-time", "type": "string" }, "insurance_type": { "description": "Client: their coverage.", "enum": [ "medicaid", "private", "other" ], "nullable": true, "type": "string" }, "languages": { "description": "Languages spoken, for either kind of lead (at most 5). A potential client's become the client's language preference on conversion.", "items": { "type": "string", "x-untrusted": "text" }, "type": "array" }, "last_name": { "description": "Last name.", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "medicaid_id": { "description": "Client: their Colorado Medicaid ID, one letter and six digits. Carried to the client on conversion.", "nullable": true, "type": "string", "x-untrusted": "text" }, "next_follow_up_date": { "description": "When to follow up next.", "format": "date", "nullable": true, "type": "string" }, "phone": { "description": "Phone number.", "type": "string" }, "physical_restrictions": { "description": "Employee: physical restrictions.", "nullable": true, "type": "string", "x-untrusted": "text" }, "prospect_type": { "description": "A potential client or a potential employee.", "enum": [ "potential_client", "potential_employee" ], "type": "string" }, "referral_source": { "description": "Client: who referred them.", "nullable": true, "type": "string", "x-untrusted": "text" }, "service_needs": { "description": "Client: what services they need.", "nullable": true, "type": "string", "x-untrusted": "text" }, "source": { "description": "How they found the agency.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "Where they are in the pipeline.", "enum": [ "new", "contacted", "interested", "interviewing", "onboarding", "converted", "declined", "archived" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" }, "working_area": { "description": "Employee: where they can work.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "id", "prospect_type", "first_name", "last_name", "status", "lock_version" ], "title": "Prospect", "type": "object" }, "ProspectConversion": { "properties": { "converted_to_id": { "description": "The client or caregiver the prospect became: a new record, or the client already on file it was linked to.", "format": "uuid", "type": "string" }, "converted_to_type": { "description": "What was made.", "enum": [ "client", "caregiver" ], "type": "string" }, "prospect": { "$ref": "#/components/schemas/Prospect" }, "warnings": { "description": "What the conversion did not do as asked: a Medicaid ID left off, an existing client linked, namesakes on file. Usually empty.", "items": { "type": "string" }, "type": "array" } }, "required": [ "prospect", "converted_to_type", "converted_to_id", "warnings" ], "title": "ProspectConversion", "type": "object" }, "ProspectConversionInput": { "properties": { "as": { "description": "Start onboarding (US-122.23), as the Pipeline page's Start onboarding does: an open caregiver lead at any stage (new to onboarding) is moved to onboarding and becomes a caregiver with status potential, its open-shift responses, alerts and portal devices moving with it; a former employee's re-hire lead sets that caregiver card back to potential instead of making one. A closed lead answers 422 lead_not_open, a client lead 422 not_employee_lead. Send it again with the possible-match answer. Absent: convert at onboarding into an active caregiver or a client.", "enum": [ "potential" ], "type": "string" }, "create_new": { "description": "The answer to a 409 possible_match when the prospect is someone else: a new record is made, and warnings counts the namesakes passed over. A list of record ids names the namesakes the caller was shown, and makes the record only if it names every namesake on file now that the caller can open, and, with hidden_seen, no more than that many on cards it cannot; one filed since (or one the 409 counted in more and did not list) answers 409 possible_match again. true is an explicit \"create regardless\": the record is made, passing over every namesake on file, including any the caller never saw. false or absent makes nothing.", "oneOf": [ { "type": "boolean" }, { "items": { "format": "uuid", "type": "string" }, "type": "array" } ] }, "hidden_seen": { "description": "With a create_new list: the hidden count of the 409 possible_match it answers, the namesakes on cards the caller cannot open, which are never named. The list then also passes over up to that many of them, as the Pipeline page's \"Someone else\" does; one more than that (filed since) answers 409 possible_match again. Absent or 0 passes over none.", "minimum": 0, "type": "integer" }, "same_person_id": { "description": "The answer to a 409 possible_match: the id of one of its matches, which is the same person. The prospect is linked to that record and nothing is made. An id that is no longer one of the prospect's namesakes answers 409 possible_match again.", "format": "uuid", "type": "string" } }, "title": "ProspectConversionInput", "type": "object" }, "ProspectCreate": { "description": "Adds a prospect, as the Pipeline page's New does. first_name, last_name, phone and prospect_type are required.", "properties": { "address": { "description": "Their address on one line, \"street, city, ST 12345\". Carried to the client or caregiver on conversion.", "nullable": true, "type": "string", "x-untrusted": "text" }, "availability": { "description": "Employee: when they can work.", "nullable": true, "type": "string", "x-untrusted": "text" }, "contact_name": { "description": "Client: the person to reach about them (family, a case manager). Becomes the client's emergency contact on conversion.", "nullable": true, "type": "string", "x-untrusted": "text" }, "contact_notes": { "description": "Notes from contacting them.", "nullable": true, "type": "string", "x-untrusted": "text" }, "contact_phone": { "description": "Client: the contact person's 10-digit phone.", "nullable": true, "type": "string", "x-untrusted": "text" }, "email": { "description": "Email address.", "nullable": true, "type": "string" }, "employee_comments": { "description": "Employee: comments.", "nullable": true, "type": "string", "x-untrusted": "text" }, "first_name": { "description": "First name.", "type": "string" }, "has_experience": { "description": "Employee: whether they have care experience.", "type": "boolean" }, "has_vehicle": { "description": "Employee: whether they have a vehicle.", "type": "boolean" }, "insurance_type": { "description": "Client: their coverage.", "enum": [ "medicaid", "private", "other" ], "nullable": true, "type": "string" }, "languages": { "description": "Languages spoken, for either kind of lead (at most 5). A potential client's become the client's language preference on conversion.", "items": { "type": "string", "x-untrusted": "text" }, "type": "array" }, "last_name": { "description": "Last name.", "type": "string" }, "medicaid_id": { "description": "Client: their Colorado Medicaid ID, one letter and six digits. Carried to the client on conversion.", "nullable": true, "type": "string", "x-untrusted": "text" }, "next_follow_up_date": { "description": "When to follow up next.", "format": "date", "nullable": true, "type": "string" }, "phone": { "description": "Phone number.", "type": "string" }, "physical_restrictions": { "description": "Employee: physical restrictions.", "nullable": true, "type": "string", "x-untrusted": "text" }, "prospect_type": { "description": "A potential client or a potential employee.", "enum": [ "potential_client", "potential_employee" ], "type": "string" }, "referral_source": { "description": "Client: who referred them.", "nullable": true, "type": "string", "x-untrusted": "text" }, "service_needs": { "description": "Client: what services they need.", "nullable": true, "type": "string", "x-untrusted": "text" }, "source": { "description": "How they found the agency.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "Where they are in the pipeline. Not converted: only POST /api/v1/prospects/{id}/convert converts a prospect, with the client or caregiver it makes.", "enum": [ "new", "contacted", "interested", "interviewing", "onboarding", "declined", "archived" ], "type": "string" }, "working_area": { "description": "Employee: where they can work.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "prospect_type", "first_name", "last_name", "phone" ], "title": "ProspectCreate", "type": "object" }, "ProspectInput": { "description": "Send only the fields to change, with the lock_version read. A status moves only along the pipeline (new → contacted → interested → interviewing → onboarding; declined or archived back to new); converted is reached only by POST /api/v1/prospects/{id}/convert, never sent as a status (a create or update sending it answers 422).", "properties": { "address": { "description": "Their address on one line, \"street, city, ST 12345\". Carried to the client or caregiver on conversion.", "nullable": true, "type": "string", "x-untrusted": "text" }, "availability": { "description": "Employee: when they can work.", "nullable": true, "type": "string", "x-untrusted": "text" }, "contact_name": { "description": "Client: the person to reach about them (family, a case manager). Becomes the client's emergency contact on conversion.", "nullable": true, "type": "string", "x-untrusted": "text" }, "contact_notes": { "description": "Notes from contacting them.", "nullable": true, "type": "string", "x-untrusted": "text" }, "contact_phone": { "description": "Client: the contact person's 10-digit phone.", "nullable": true, "type": "string", "x-untrusted": "text" }, "email": { "description": "Email address.", "nullable": true, "type": "string" }, "employee_comments": { "description": "Employee: comments.", "nullable": true, "type": "string", "x-untrusted": "text" }, "first_name": { "description": "First name.", "type": "string" }, "has_experience": { "description": "Employee: whether they have care experience.", "type": "boolean" }, "has_vehicle": { "description": "Employee: whether they have a vehicle.", "type": "boolean" }, "insurance_type": { "description": "Client: their coverage.", "enum": [ "medicaid", "private", "other" ], "nullable": true, "type": "string" }, "languages": { "description": "Languages spoken, for either kind of lead (at most 5). A potential client's become the client's language preference on conversion.", "items": { "type": "string", "x-untrusted": "text" }, "type": "array" }, "last_name": { "description": "Last name.", "type": "string" }, "medicaid_id": { "description": "Client: their Colorado Medicaid ID, one letter and six digits. Carried to the client on conversion.", "nullable": true, "type": "string", "x-untrusted": "text" }, "next_follow_up_date": { "description": "When to follow up next.", "format": "date", "nullable": true, "type": "string" }, "phone": { "description": "Phone number.", "type": "string" }, "physical_restrictions": { "description": "Employee: physical restrictions.", "nullable": true, "type": "string", "x-untrusted": "text" }, "referral_source": { "description": "Client: who referred them.", "nullable": true, "type": "string", "x-untrusted": "text" }, "service_needs": { "description": "Client: what services they need.", "nullable": true, "type": "string", "x-untrusted": "text" }, "source": { "description": "How they found the agency.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "Where they are in the pipeline. Not converted: only POST /api/v1/prospects/{id}/convert converts a prospect, with the client or caregiver it makes.", "enum": [ "new", "contacted", "interested", "interviewing", "onboarding", "declined", "archived" ], "type": "string" }, "working_area": { "description": "Employee: where they can work.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "title": "ProspectInput", "type": "object" }, "ProspectPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Prospect" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ProspectPage", "type": "object" }, "Provider revalidationPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ProviderRevalidation" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Provider revalidationPage", "type": "object" }, "ProviderCarePlan": { "properties": { "authorizations_reconciled_at": { "description": "When its authorisations were last fully reconciled.", "format": "date-time", "nullable": true, "type": "string" }, "certification_end_date": { "description": "The certification period's end.", "format": "date", "nullable": true, "type": "string" }, "certification_start_date": { "description": "The certification period's start.", "format": "date", "nullable": true, "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "created_at": { "description": "When it was created.", "format": "date-time", "type": "string" }, "current_revision_id": { "description": "Its current revision.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "source_document_id": { "description": "The PCSP it was imported from.", "format": "uuid", "nullable": true, "type": "string" }, "status": { "description": "Whether it is the client's current plan.", "enum": [ "current", "past" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "client_id", "status" ], "title": "ProviderCarePlan", "type": "object" }, "ProviderCarePlanDetail": { "properties": { "authorizations_reconciled_at": { "description": "When its authorisations were last fully reconciled.", "format": "date-time", "nullable": true, "type": "string" }, "certification_end_date": { "description": "The certification period's end.", "format": "date", "nullable": true, "type": "string" }, "certification_start_date": { "description": "The certification period's start.", "format": "date", "nullable": true, "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "content": { "description": "The current revision's fields, by key.", "type": "object" }, "created_at": { "description": "When it was created.", "format": "date-time", "type": "string" }, "current_revision_id": { "description": "Its current revision.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reconciliation_outcome": { "description": "The last reconciliation's rows.", "nullable": true, "type": "object" }, "source_document_id": { "description": "The PCSP it was imported from.", "format": "uuid", "nullable": true, "type": "string" }, "status": { "description": "Whether it is the client's current plan.", "enum": [ "current", "past" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "client_id", "status", "content" ], "title": "ProviderCarePlanDetail", "type": "object" }, "ProviderCarePlanPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "authorizations_reconciled_at": { "description": "When its authorisations were last fully reconciled.", "format": "date-time", "nullable": true, "type": "string" }, "certification_end_date": { "description": "The certification period's end.", "format": "date", "nullable": true, "type": "string" }, "certification_start_date": { "description": "The certification period's start.", "format": "date", "nullable": true, "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "created_at": { "description": "When it was created.", "format": "date-time", "type": "string" }, "current_revision_id": { "description": "Its current revision.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "source_document_id": { "description": "The PCSP it was imported from.", "format": "uuid", "nullable": true, "type": "string" }, "status": { "description": "Whether it is the client's current plan.", "enum": [ "current", "past" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "client_id", "status" ], "title": "ProviderCarePlan", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ProviderCarePlanPage", "type": "object" }, "ProviderCarePlanReconciliation": { "properties": { "complete": { "description": "Whether nothing is left outstanding.", "type": "boolean" }, "rows": { "description": "One per service row.", "items": { "type": "object" }, "type": "array" } }, "title": "ProviderCarePlanReconciliation", "type": "object" }, "ProviderCarePlanSave": { "properties": { "certification_choice": { "description": "Which period wins when the PCSP's and the client's certification disagree.", "enum": [ "document", "client_certification" ], "type": "string" }, "certification_end_date": { "description": "The PCSP's certification end, YYYY-MM-DD.", "format": "date", "nullable": true, "type": "string" }, "certification_start_date": { "description": "The PCSP's certification start, YYYY-MM-DD.", "format": "date", "nullable": true, "type": "string" }, "change_note": { "description": "Why this revision.", "nullable": true, "type": "string" }, "client_id": { "description": "For a new plan: the client.", "format": "uuid", "type": "string" }, "content": { "description": "The plan's fields, by key, as get_provider_care_plan shows them.", "type": "object" }, "source_document_id": { "description": "The PCSP stored for the client, with store_pcsp; a new plan only, where null means none.", "format": "uuid", "nullable": true, "type": "string" } }, "title": "ProviderCarePlanSave", "type": "object" }, "ProviderRevalidation": { "description": "A Medicaid revalidation due date for one NPI. The bell reminds every member holding compliance.view at 90, 60 and 30 days.", "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the date was entered.", "format": "date-time", "type": "string" }, "last_alerted_threshold": { "description": "The notice last sent, 90, 60 or 30 days; null when none has been. A changed date clears it.", "nullable": true, "type": "integer" }, "location_name": { "description": "Which location the NPI is enrolled for, when it has several.", "maxLength": 120, "nullable": true, "type": "string", "x-untrusted": "text" }, "notes": { "description": "Anything the agency wants to remember about it.", "maxLength": 500, "nullable": true, "type": "string", "x-untrusted": "text" }, "npi": { "description": "The NPI, exactly 10 digits.", "pattern": "^[0-9]{10}$", "type": "string" }, "revalidation_due_on": { "description": "The revalidation due date the Provider Web Portal shows (YYYY-MM-DD).", "format": "date", "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "npi", "revalidation_due_on" ], "title": "ProviderRevalidation", "type": "object" }, "ProviderRevalidationInput": { "description": "A revalidation date's fields. A POST needs npi and revalidation_due_on; a PATCH sets only the fields sent, and a changed date is reminded again at 90, 60 and 30 days.", "properties": { "location_name": { "description": "Which location the NPI is enrolled for, when it has several.", "maxLength": 120, "nullable": true, "type": "string", "x-untrusted": "text" }, "notes": { "description": "Anything the agency wants to remember about it.", "maxLength": 500, "nullable": true, "type": "string", "x-untrusted": "text" }, "npi": { "description": "The NPI, exactly 10 digits.", "pattern": "^[0-9]{10}$", "type": "string" }, "revalidation_due_on": { "description": "The revalidation due date the Provider Web Portal shows (YYYY-MM-DD).", "format": "date", "type": "string" } }, "title": "ProviderRevalidationInput", "type": "object" }, "ProviderTypeCertification": { "properties": { "certification_text": { "nullable": true, "type": "string" }, "certification_translations": { "additionalProperties": { "type": "string" }, "type": "object" }, "certification_version": { "nullable": true, "type": "string" }, "code": { "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "title": "ProviderTypeCertification", "type": "object" }, "ProviderTypeCertificationUpdate": { "properties": { "certification_text": { "description": "English; empty for the standard wording.", "nullable": true, "type": "string" }, "certification_version": { "description": "As GET /api/v1/provider-type-modifiers (find_provider_type_modifiers) returned it.", "type": "string" }, "translation": { "description": "Optional: into the agency's card language.", "nullable": true, "type": "string" } }, "required": [ "certification_version" ], "title": "ProviderTypeCertificationUpdate", "type": "object" }, "ProviderTypeModifierWarning": { "properties": { "message": { "description": "What the admin is warned of.", "type": "string" }, "rule_id": { "description": "The rule that raised it.", "type": "string" } }, "required": [ "rule_id", "message" ], "title": "ProviderTypeModifierWarning", "type": "object" }, "ProviderTypeModifiers": { "properties": { "agency_owned": { "description": "Whether the agency has its own copy of the template. Its first certification save on a system template makes that copy; modifier changes write the agency's offering and make no copy.", "type": "boolean" }, "billing_code": { "description": "The HCPCS code it bills.", "nullable": true, "type": "string" }, "certification_text": { "description": "The certification its cards print, in English.", "nullable": true, "type": "string" }, "certification_translations": { "additionalProperties": { "type": "string" }, "description": "Its translations, by language code.", "type": "object" }, "certification_version": { "description": "What a certification save sends back, to refuse one saved since.", "nullable": true, "type": "string" }, "code": { "description": "The provider type's code, as the path takes it.", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "modifiers": { "description": "The modifiers it bills, and the batch validation expects.", "items": { "type": "string" }, "type": "array" }, "name": { "description": "The provider type's name.", "nullable": true, "type": "string" } }, "required": [ "code", "modifiers" ], "title": "ProviderTypeModifiers", "type": "object" }, "QuestionAnswer": { "description": "A question the agency asks, keyed by its question key, with its wording, type, the options a choice offers, and the answer on record. Send an answer back under the same key.", "properties": { "answer": { "description": "The answer on record: text, a code, or a list of choices.", "nullable": true, "oneOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" } ] }, "comment": { "description": "A visit answer's comment; a monthly report keeps none.", "nullable": true, "type": "string" }, "key": { "description": "The question's key; answers are sent under it.", "nullable": true, "type": "string" }, "options": { "description": "The answers a yes/no or choice takes; none for free text.", "items": { "type": "string" }, "nullable": true, "type": "array" }, "question": { "description": "The question's wording.", "nullable": true, "type": "string" }, "type": { "description": "yes_no, text, choice, multi_choice, date and the like.", "nullable": true, "type": "string" } }, "required": [ "key", "type" ], "title": "QuestionAnswer", "type": "object" }, "Recertification": { "description": "The renewal of a service authorization (PAR).", "properties": { "authorization_id": { "description": "The authorization being renewed.", "format": "uuid", "type": "string" }, "case_manager": { "description": "The case manager handling the renewal.", "nullable": true, "type": "string", "x-untrusted": "text" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the recertification was started.", "format": "date-time", "type": "string" }, "notes": { "description": "Free text on the renewal.", "nullable": true, "type": "string", "x-untrusted": "text" }, "renewed_authorization_id": { "description": "The authorization that renewed it, once renewed.", "format": "uuid", "nullable": true, "type": "string" }, "renewed_on": { "format": "date", "nullable": true, "type": "string" }, "requested_on": { "format": "date", "nullable": true, "type": "string" }, "state": { "enum": [ "requested", "in_progress", "renewed" ], "type": "string" }, "target_date": { "format": "date", "nullable": true, "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "authorization_id", "state" ], "title": "Recertification", "type": "object" }, "RecertificationPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Recertification" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "RecertificationPage", "type": "object" }, "Reconciliation": { "description": "The payment against its claims: bpr_total should equal claims_total minus plb_net, and balanced is false when it does not. In the remittances list these are the figures stored when the 835 was recorded: null for one recorded before they were stored, and an amount they do not hold readably is null, and then so is balanced. On a single remittance they are computed from its parse, and null only when it has none.", "nullable": true, "properties": { "balanced": { "nullable": true, "type": "boolean" }, "bpr_total": { "description": "What HCPF paid, the BPR amount.", "format": "decimal", "nullable": true, "type": "string" }, "claims_total": { "description": "The claims' paid amounts added up.", "format": "decimal", "nullable": true, "type": "string" }, "plb_net": { "description": "Provider-level adjustments (PLB), net.", "format": "decimal", "nullable": true, "type": "string" } }, "title": "Reconciliation", "type": "object" }, "RecordAddendum": { "description": "Text added to a signed record after signing, signed by its author. The record it amends is never changed.", "properties": { "author_user_id": { "description": "The member who wrote and signed it.", "format": "uuid", "type": "string" }, "body": { "description": "What was added.", "nullable": true, "type": "string", "x-untrusted": "text" }, "id": { "description": "The addendum.", "format": "uuid", "type": "string" }, "reason": { "description": "Why it was added.", "nullable": true, "type": "string", "x-untrusted": "text" }, "record_id": { "description": "The record it amends.", "format": "uuid", "type": "string" }, "record_state": { "description": "signed once its author's signature is recorded.", "enum": [ "draft", "signed" ], "type": "string" }, "record_type": { "description": "The type of the record it amends: supervisor_visit, plan_of_care, monthly_client_report, complaint, critical_incident, client_consent_form, client_emergency_info or care_log.", "nullable": true, "type": "string" }, "signed_at": { "description": "When it was signed.", "format": "date-time", "nullable": true, "type": "string" }, "signer_name": { "description": "The name it is signed under.", "nullable": true, "type": "string", "x-untrusted": "text" }, "true_copy_document_id": { "description": "Its true copy (PDF): the record's print as it stood when the addendum was signed; null until stored.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "record_type", "record_id", "body", "reason", "record_state" ], "title": "RecordAddendum", "type": "object" }, "RecordAddendumInput": { "properties": { "body": { "description": "What to add, up to 5000 characters. The signed record itself never changes.", "nullable": true, "type": "string" }, "reason": { "description": "Why it is added, 3 to 1000 characters.", "nullable": true, "type": "string" }, "signer_name": { "description": "The name the addendum is signed under, a typed signature by the credential's user; the user's own name when left out.", "nullable": true, "type": "string" } }, "required": [ "body", "reason" ], "title": "RecordAddendumInput", "type": "object" }, "RecordImportResult": { "properties": { "dry_run": { "description": "true: nothing was written; the counts are what the import would do.", "type": "boolean" }, "failed": { "description": "Rows refused, by row number (the first row after the header is 1), with the errors by field.", "items": { "properties": { "errors": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "description": "Field name to its error messages.", "type": "object" }, "row": { "type": "integer" } }, "required": [ "row", "errors" ], "type": "object" }, "type": "array" }, "format": { "description": "How the file was read: HCB's own columns, or an InMyTeam export recognised by its headers.", "enum": [ "hcb", "inmyteam_patients", "inmyteam_caregivers", "inmyteam_authorizations" ], "type": "string" }, "imported": { "description": "Rows written as new records.", "type": "integer" }, "pay_withheld": { "description": "Caregivers only: the rows whose pay rates, W-4 and ADP fields were left out because the key's member lacks payroll.manage, and the words for it; null when none were.", "nullable": true, "properties": { "message": { "type": "string" }, "rows": { "type": "integer" } }, "type": "object" }, "reasons": { "additionalProperties": { "items": { "properties": { "detail": { "nullable": true, "type": "string" }, "row": { "type": "integer" } }, "type": "object" }, "type": "array" }, "description": "Rows imported, updated or skipped in a way to check, by code (already_on_file, pay_rates_skipped, office_staff...): each {row, detail}, the detail naming no person.", "type": "object" }, "skipped": { "description": "Rows not written; reasons says why (already_on_file, empty_row, office_staff...).", "type": "integer" }, "updated": { "description": "Rows matching a record on file that filled in what that record left blank.", "type": "integer" } }, "required": [ "dry_run", "format", "imported", "updated", "skipped", "failed", "reasons" ], "title": "RecordImportResult", "type": "object" }, "RecordSignatureSummary": { "properties": { "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "signer_name", "method", "signed_at" ], "title": "RecordSignatureSummary", "type": "object" }, "RecurringLineCreate": { "properties": { "charge_amount": { "description": "Amount billed each period.", "format": "decimal", "type": "string" }, "diagnosis_code_1": { "description": "A diagnosis code.", "type": "string" }, "diagnosis_code_2": { "description": "A diagnosis code.", "type": "string" }, "diagnosis_code_3": { "description": "A diagnosis code.", "type": "string" }, "diagnosis_code_4": { "description": "A diagnosis code.", "type": "string" }, "member_id": { "description": "The Medicaid member id.", "type": "string" }, "modifier_1": { "description": "A modifier.", "type": "string" }, "modifier_2": { "description": "A modifier.", "type": "string" }, "modifier_3": { "description": "A modifier.", "type": "string" }, "modifier_4": { "description": "A modifier.", "type": "string" }, "par_number": { "description": "The prior authorization request number.", "type": "string" }, "patient_dob": { "description": "The member's date of birth, YYYY-MM-DD. Written only; never answered.", "format": "date", "type": "string" }, "patient_first_name": { "description": "The member's first name.", "type": "string" }, "patient_last_name": { "description": "The member's last name.", "type": "string" }, "place_of_service": { "description": "The place of service code, e.g. 99.", "type": "string" }, "procedure_code": { "description": "The procedure code, e.g. T1019.", "type": "string" }, "rendering_npi": { "description": "The rendering provider's NPI.", "type": "string" }, "units": { "description": "Units billed each period.", "format": "decimal", "type": "string" } }, "required": [ "member_id", "procedure_code", "units", "charge_amount" ], "title": "RecurringLineCreate", "type": "object" }, "RecurringLineUpdate": { "properties": { "charge_amount": { "description": "Amount billed each period.", "format": "decimal", "type": "string" }, "diagnosis_code_1": { "description": "A diagnosis code. Null clears it.", "nullable": true, "type": "string" }, "diagnosis_code_2": { "description": "A diagnosis code. Null clears it.", "nullable": true, "type": "string" }, "diagnosis_code_3": { "description": "A diagnosis code. Null clears it.", "nullable": true, "type": "string" }, "diagnosis_code_4": { "description": "A diagnosis code. Null clears it.", "nullable": true, "type": "string" }, "member_id": { "description": "The Medicaid member id.", "type": "string" }, "modifier_1": { "description": "A modifier. Null clears it.", "nullable": true, "type": "string" }, "modifier_2": { "description": "A modifier. Null clears it.", "nullable": true, "type": "string" }, "modifier_3": { "description": "A modifier. Null clears it.", "nullable": true, "type": "string" }, "modifier_4": { "description": "A modifier. Null clears it.", "nullable": true, "type": "string" }, "par_number": { "description": "The prior authorization request number. Null clears it.", "nullable": true, "type": "string" }, "patient_dob": { "description": "The member's date of birth, YYYY-MM-DD. Written only; never answered. Null clears it.", "format": "date", "nullable": true, "type": "string" }, "patient_first_name": { "description": "The member's first name. Null clears it.", "nullable": true, "type": "string" }, "patient_last_name": { "description": "The member's last name. Null clears it.", "nullable": true, "type": "string" }, "place_of_service": { "description": "The place of service code, e.g. 99.", "type": "string" }, "procedure_code": { "description": "The procedure code, e.g. T1019.", "type": "string" }, "rendering_npi": { "description": "The rendering provider's NPI. Null clears it.", "nullable": true, "type": "string" }, "status": { "description": "paused leaves the line out of runs until it is set active again, whatever paused it.", "enum": [ "active", "paused" ], "type": "string" }, "units": { "description": "Units billed each period.", "format": "decimal", "type": "string" } }, "title": "RecurringLineUpdate", "type": "object" }, "RecurringLineWarning": { "properties": { "authorization_id": { "description": "The PAR an over_weekly_allowance warning was judged against; null for every other code.", "format": "uuid", "nullable": true, "type": "string" }, "code": { "description": "What to check.", "enum": [ "not_paid", "recouped", "evv", "par_ends", "over_weekly_allowance" ], "type": "string" }, "line_id": { "description": "The line it is about.", "format": "uuid", "type": "string" }, "message": { "description": "The words the schedule page shows.", "type": "string" } }, "required": [ "code", "message" ], "title": "RecurringLineWarning", "type": "object" }, "RecurringPeriod": { "description": "The period the schedule bills next, the one Skip acts on; null once it has none.", "nullable": true, "properties": { "period_end": { "description": "The last day billed.", "format": "date", "nullable": true, "type": "string" }, "period_start": { "description": "The first day billed.", "format": "date", "nullable": true, "type": "string" } }, "required": [ "period_start", "period_end" ], "title": "RecurringPeriod", "type": "object" }, "RecurringProposal": { "properties": { "anchor_date": { "description": "Period 0's first day.", "format": "date", "nullable": true, "type": "string" }, "batch_id": { "description": "The batch.", "format": "uuid", "type": "string" }, "cadence": { "enum": [ "weekly", "biweekly", "monthly" ], "type": "string" }, "limit": { "type": "integer" }, "lines": { "items": { "type": "object" }, "type": "array" }, "lines_total": { "type": "integer" }, "name": { "type": "string" }, "offset": { "type": "integer" }, "period": { "nullable": true, "properties": { "period_end": { "description": "The last day billed.", "format": "date", "nullable": true, "type": "string" }, "period_start": { "description": "The first day billed.", "format": "date", "nullable": true, "type": "string" } }, "required": [ "period_start", "period_end" ], "title": "RecurringPeriod", "type": "object" }, "submit_mode": { "enum": [ "auto", "approval" ], "type": "string" }, "submit_time": { "format": "time", "type": "string" }, "submit_weekday": { "type": "integer" } }, "title": "RecurringProposal", "type": "object" }, "RecurringRun": { "description": "One billed period of a recurring schedule. status records the scheduling decision only: submitted means handed to delivery, and whether HCPF got the file is the batch's own status.", "properties": { "batch_id": { "description": "The batch it made; null for a period skipped before a batch was made.", "format": "uuid", "nullable": true, "type": "string" }, "fail_reason": { "description": "Why it was not sent.", "enum": [ "batch_failed", "batch_stuck", "invalid_claims", "enqueue_failed" ], "nullable": true, "type": "string" }, "held_at": { "description": "When it was held.", "format": "date-time", "nullable": true, "type": "string" }, "hold_reason": { "description": "Why it is held.", "enum": [ "tenant", "duplicates_flagged", "duplicate_check_not_run", "tenant_blocked", "schedule_paused", "schedule_ended" ], "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the record was created.", "format": "date-time", "type": "string" }, "notice_sent_at": { "description": "When the notice announcing it was queued.", "format": "date-time", "nullable": true, "type": "string" }, "period_end": { "description": "The last day billed.", "format": "date", "nullable": true, "type": "string" }, "period_start": { "description": "The first day billed.", "format": "date", "nullable": true, "type": "string" }, "schedule_id": { "description": "The schedule it belongs to.", "format": "uuid", "type": "string" }, "scheduled_submit_at": { "description": "When it goes out unless held; null under approval or once left.", "format": "date-time", "nullable": true, "type": "string" }, "skip_reason": { "description": "Why it was skipped.", "enum": [ "skipped_by_tenant", "no_submission_access", "no_billing_submit", "patient_limit_exceeded", "too_many_claims" ], "nullable": true, "type": "string" }, "skipped_lines": { "description": "Each line left out of the run: its line_id, the reason, and the claim and batch it would have duplicated.", "items": { "properties": { "conflicting_batch_id": { "description": "That claim's batch.", "format": "uuid", "nullable": true, "type": "string" }, "conflicting_claim_id": { "description": "The claim it overlapped.", "format": "uuid", "nullable": true, "type": "string" }, "line_id": { "description": "The schedule line.", "format": "uuid", "type": "string" }, "reason": { "description": "Why it was left out.", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "status": { "enum": [ "created", "held", "submitted", "cancelled", "skipped", "failed" ], "type": "string" }, "updated_at": { "description": "When the record last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "schedule_id", "status", "period_start", "period_end" ], "title": "RecurringRun", "type": "object" }, "RecurringSchedule": { "description": "A standing instruction to bill an uploaded batch's lines again every week, two weeks or month. Each period's run makes a batch of the schedule's active lines with that period's dates.", "properties": { "anchor_date": { "description": "The first day of the source batch's period, period 0.", "format": "date", "nullable": true, "type": "string" }, "cadence": { "description": "How often it bills: weekly, biweekly (every two weeks) or monthly.", "enum": [ "weekly", "biweekly", "monthly" ], "type": "string" }, "end_date": { "description": "No run is made for a period starting after it.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the record was created.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "name": { "description": "The schedule's name, as the schedule page shows it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "paused_at": { "description": "When it was last paused.", "format": "date-time", "nullable": true, "type": "string" }, "resumed_at": { "description": "When it was last resumed.", "format": "date-time", "nullable": true, "type": "string" }, "source_batch_id": { "description": "The uploaded batch it was made from.", "format": "uuid", "type": "string" }, "status": { "description": "active, paused (no runs until resumed) or ended (final).", "enum": [ "active", "paused", "ended" ], "type": "string" }, "submit_mode": { "description": "auto sends each run at its send time unless held; approval waits for a Submit.", "enum": [ "auto", "approval" ], "type": "string" }, "submit_time": { "description": "The time a run is sent, HH:MM:SS, Mountain time.", "format": "time", "nullable": true, "type": "string" }, "submit_weekday": { "description": "The day a run is sent, Monday 1 to Sunday 7, in Mountain time.", "nullable": true, "type": "integer" }, "updated_at": { "description": "When the record last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "status", "cadence", "submit_mode" ], "title": "RecurringSchedule", "type": "object" }, "RecurringScheduleCreate": { "properties": { "batch_id": { "description": "The uploaded batch to make recurring.", "format": "uuid", "type": "string" }, "end_date": { "description": "No run is made for a period starting after it, YYYY-MM-DD.", "format": "date", "type": "string" }, "name": { "description": "The schedule's name.", "maxLength": 120, "type": "string" }, "submit_mode": { "description": "auto sends each run at its send time unless held; approval waits for a Submit.", "enum": [ "auto", "approval" ], "type": "string" }, "submit_time": { "description": "The time a run is sent, HH:MM or HH:MM:SS, Mountain time.", "format": "time", "type": "string" }, "submit_weekday": { "description": "The day a run is sent, Monday 1 to Sunday 7, in Mountain time.", "maximum": 7, "minimum": 1, "type": "integer" } }, "required": [ "batch_id" ], "title": "RecurringScheduleCreate", "type": "object" }, "RecurringScheduleLine": { "description": "One claim line a recurring schedule bills every period, copied from a claim of the source batch or added by hand.", "properties": { "charge_amount": { "description": "Amount billed each period.", "format": "decimal", "nullable": true, "type": "string" }, "diagnosis_code_1": { "nullable": true, "type": "string" }, "diagnosis_code_2": { "nullable": true, "type": "string" }, "diagnosis_code_3": { "nullable": true, "type": "string" }, "diagnosis_code_4": { "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the record was created.", "format": "date-time", "type": "string" }, "member_id": { "description": "The Medicaid member id.", "nullable": true, "type": "string" }, "modifier_1": { "nullable": true, "type": "string" }, "modifier_2": { "nullable": true, "type": "string" }, "modifier_3": { "nullable": true, "type": "string" }, "modifier_4": { "nullable": true, "type": "string" }, "ordering_npi": { "nullable": true, "type": "string" }, "par_number": { "description": "The prior authorization request number.", "nullable": true, "type": "string" }, "patient_first_name": { "nullable": true, "type": "string" }, "patient_last_name": { "nullable": true, "type": "string" }, "pause_reason": { "description": "tenant when paused by hand; denied when HCPF denied its claim (paused_by_claim_id).", "enum": [ "tenant", "denied" ], "nullable": true, "type": "string" }, "paused_by_claim_id": { "description": "The denied claim that paused it, when one did.", "format": "uuid", "nullable": true, "type": "string" }, "place_of_service": { "description": "The place of service code.", "nullable": true, "type": "string" }, "position": { "description": "Its order on the schedule.", "nullable": true, "type": "integer" }, "procedure_code": { "description": "The procedure code, e.g. T1019.", "nullable": true, "type": "string" }, "rendering_npi": { "nullable": true, "type": "string" }, "schedule_id": { "description": "The schedule it belongs to.", "format": "uuid", "type": "string" }, "source_claim_id": { "description": "The claim it was copied from; null when added by hand.", "format": "uuid", "nullable": true, "type": "string" }, "status": { "description": "active, or paused: left out of runs until resumed.", "enum": [ "active", "paused" ], "type": "string" }, "unit_type": { "description": "The unit type, UN unless the source claim said otherwise.", "nullable": true, "type": "string" }, "units": { "description": "Units billed each period.", "format": "decimal", "nullable": true, "type": "string" }, "updated_at": { "description": "When the record last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "schedule_id", "status" ], "title": "RecurringScheduleLine", "type": "object" }, "RecurringSchedulePage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "allOf": [ { "$ref": "#/components/schemas/RecurringSchedule" }, { "properties": { "next_period": { "description": "The period the schedule bills next, the one Skip acts on; null once it has none.", "nullable": true, "properties": { "period_end": { "description": "The last day billed.", "format": "date", "nullable": true, "type": "string" }, "period_start": { "description": "The first day billed.", "format": "date", "nullable": true, "type": "string" } }, "required": [ "period_start", "period_end" ], "title": "RecurringPeriod", "type": "object" } }, "type": "object" } ] }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "RecurringSchedulePage", "type": "object" }, "RecurringScheduleUpdate": { "properties": { "end_date": { "description": "YYYY-MM-DD; null clears it.", "format": "date", "nullable": true, "type": "string" }, "lock_version": { "description": "The lock_version the schedule was read with; required when a setting (name, submit_mode, submit_weekday, submit_time, end_date) is sent. A schedule changed since answers 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "name": { "description": "The schedule's name.", "maxLength": 120, "type": "string" }, "status": { "description": "Pause (paused), resume (active) or end (ended, final) the schedule.", "enum": [ "active", "paused", "ended" ], "type": "string" }, "submit_mode": { "description": "auto sends each run at its send time unless held; approval waits for a Submit.", "enum": [ "auto", "approval" ], "type": "string" }, "submit_time": { "description": "The time a run is sent, HH:MM or HH:MM:SS, Mountain time.", "format": "time", "type": "string" }, "submit_weekday": { "description": "The day a run is sent, Monday 1 to Sunday 7, in Mountain time.", "maximum": 7, "minimum": 1, "type": "integer" } }, "title": "RecurringScheduleUpdate", "type": "object" }, "RecurringSkip": { "properties": { "period_start": { "description": "The next_period.period_start this schedule was read with. Any other answers 409 period_moved, so a repeated skip never skips a second period.", "format": "date", "type": "string" } }, "required": [ "period_start" ], "title": "RecurringSkip", "type": "object" }, "RefusedClock": { "properties": { "assignment": { "description": "A clock-in or a clock-out.", "enum": [ "time_in", "time_out" ], "type": "string" }, "captured_at": { "description": "When the caregiver clocked (UTC), the device's time when it sent one.", "format": "date-time", "type": "string" }, "caregiver_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "device_id": { "description": "The device that sent the clock.", "nullable": true, "type": "string" }, "gps_accuracy_meters": { "description": "How accurate the location was, in meters.", "nullable": true, "type": "number" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the server kept it (UTC).", "format": "date-time", "type": "string" }, "latitude": { "description": "Where the device was.", "format": "decimal", "nullable": true, "type": "string" }, "longitude": { "description": "Where the device was.", "format": "decimal", "nullable": true, "type": "string" }, "reviewed_at": { "description": "When the office marked it reviewed (UTC); null while open.", "format": "date-time", "nullable": true, "type": "string" }, "visit_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "visit_status": { "description": "The visit's status when it refused the clock.", "enum": [ "scheduled", "in_progress", "completed", "verified", "submitted", "matched", "rejected", "cancelled" ], "type": "string" } }, "required": [ "id", "visit_id", "caregiver_id", "assignment", "captured_at", "visit_status" ], "title": "RefusedClock", "type": "object" }, "RefusedClockPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/RefusedClock" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "RefusedClockPage", "type": "object" }, "Reminder": { "description": "A reminder on the Today page: a supervisory visit, a recertification, a follow-up or one the agency wrote. Agency-wide reminders name no client.", "properties": { "client_first_name": { "description": "The client's first name.", "nullable": true, "type": "string" }, "client_id": { "description": "The client it is about.", "format": "uuid", "nullable": true, "type": "string" }, "client_last_name": { "description": "The client's last name.", "nullable": true, "type": "string" }, "due_date": { "description": "The day it is due.", "format": "date", "nullable": true, "type": "string" }, "due_time": { "description": "The time of day it is due, HH:MM:SS (Mountain time), when it has one.", "nullable": true, "type": "string" }, "event_type": { "enum": [ "supervisory_visit", "recertification", "follow_up", "custom" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "status": { "description": "upcoming or overdue on the agenda.", "enum": [ "upcoming", "overdue", "completed", "dismissed" ], "type": "string" }, "title": { "description": "What is due.", "nullable": true, "type": "string" } }, "required": [ "id", "title", "event_type", "status", "due_date" ], "title": "Reminder", "type": "object" }, "ReminderClosed": { "description": "The reminder's status after the call. changed is false when it was already where it was asked to go (a retry): nothing was changed, and any next occurrence the first call scheduled is not repeated here.", "properties": { "already": { "description": "It was already completed or dismissed, as asked, before this call.", "type": "boolean" }, "changed": { "description": "Whether this call changed it.", "type": "boolean" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "next": { "description": "The next occurrence completing a recurring reminder scheduled.", "nullable": true, "properties": { "due_date": { "description": "The day it is due.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "type": "object" }, "recurrence_stopped": { "description": "A recurring reminder has no next one: dismissing ends the series, and completing one whose next date is past or too far out schedules none.", "type": "boolean" }, "status": { "description": "completed or dismissed.", "enum": [ "upcoming", "overdue", "completed", "dismissed" ], "type": "string" } }, "required": [ "id", "status", "changed", "already", "recurrence_stopped" ], "title": "ReminderClosed", "type": "object" }, "ReminderPreferences": { "properties": { "birthday_lead_days": { "description": "Days of notice before a birthday, 0 to 30.", "type": "integer" }, "default_reminder_time": { "description": "The time of day reminders are due, as HH:MM:SS in the agency's timezone.", "type": "string" }, "email_digest_enabled": { "description": "Whether reminders are emailed as a digest.", "type": "boolean" }, "paused_until": { "description": "Reminder email paused until then, an ISO 8601 time in the future; null resumes it.", "format": "date-time", "nullable": true, "type": "string" }, "recert_lead_days": { "description": "Days of notice before a recert, 0 to 180.", "type": "integer" }, "supervisor_visit_cadence_mode": { "description": "How the next supervisory visit is counted.", "enum": [ "exact_days", "calendar_months", "approx_days_same_dow" ], "type": "string" }, "supervisor_visit_cadence_value": { "description": "Days or months between supervisory visits, 0 to 365.", "type": "integer" } }, "required": [ "birthday_lead_days", "default_reminder_time", "email_digest_enabled", "paused_until", "recert_lead_days", "supervisor_visit_cadence_mode", "supervisor_visit_cadence_value" ], "title": "ReminderPreferences", "type": "object" }, "ReminderPreferencesUpdate": { "properties": { "birthday_lead_days": { "description": "Days of notice before a birthday, 0 to 30.", "type": "integer" }, "default_reminder_time": { "description": "The time of day reminders are due, as HH:MM:SS in the agency's timezone.", "type": "string" }, "email_digest_enabled": { "description": "Whether reminders are emailed as a digest.", "type": "boolean" }, "paused_until": { "description": "Reminder email paused until then, an ISO 8601 time in the future; null resumes it.", "format": "date-time", "nullable": true, "type": "string" }, "recert_lead_days": { "description": "Days of notice before a recert, 0 to 180.", "type": "integer" }, "supervisor_visit_cadence_mode": { "description": "How the next supervisory visit is counted.", "enum": [ "exact_days", "calendar_months", "approx_days_same_dow" ], "type": "string" }, "supervisor_visit_cadence_value": { "description": "Days or months between supervisory visits, 0 to 365.", "type": "integer" } }, "title": "ReminderPreferencesUpdate", "type": "object" }, "Remittance": { "description": "An 835 remittance, with its totals. GET its id for the claim lines.", "properties": { "file_name": { "description": "The file's name as HCPF named it.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the record was created.", "format": "date-time", "type": "string" }, "parsed_at": { "format": "date-time", "nullable": true, "type": "string" }, "received_at": { "description": "When it was downloaded.", "format": "date-time", "type": "string" }, "reconciliation": { "$ref": "#/components/schemas/Reconciliation" }, "updated_at": { "description": "When the record last changed.", "format": "date-time", "type": "string" } }, "required": [ "id" ], "title": "Remittance", "type": "object" }, "RemittanceDetail": { "description": "What HCPF paid, denied and reversed, and why. A carc is GROUP-REASON (e.g. CO-45); each code has its plain-English description beside it. The id is the 835 Response's. The MCP remittance tools return one record per batch a remittance touched, each carrying this id as response_id. reconciliation is null for a remittance with no parse.", "properties": { "batch_ids": { "description": "The agency's batches whose claims it pays or denies.", "items": { "format": "uuid", "type": "string" }, "type": "array" }, "complete": { "description": "False only when the remittance has no parse, and then reconciliation is null and lines is empty. Otherwise true: every line was matched against all of the agency's claims, so a null claim_id means the line matched none of them.", "type": "boolean" }, "denial_groups": { "description": "Denied claims grouped by their reason.", "items": { "properties": { "billed_total": { "description": "Billed on those claims.", "format": "decimal", "nullable": true, "type": "string" }, "carc": { "description": "GROUP-REASON.", "nullable": true, "type": "string" }, "carc_description": { "nullable": true, "type": "string" }, "claim_count": { "type": "integer" }, "rarc": { "description": "Remark code.", "nullable": true, "type": "string" }, "rarc_description": { "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "limit": { "description": "Lines per page.", "type": "integer" }, "lines": { "description": "One per claim (CLP) on the remittance, a page at a time: lines_total counts them all, and limit and offset say which page this is.", "items": { "properties": { "billed_amount": { "description": "Billed.", "format": "decimal", "nullable": true, "type": "string" }, "carc": { "description": "Claim adjustment reason, GROUP-REASON.", "nullable": true, "type": "string" }, "carc_description": { "nullable": true, "type": "string" }, "claim_id": { "description": "The agency's claim it matched. Null when it matched none: a claim the agency did not submit through HCB.", "format": "uuid", "type": "string" }, "icn": { "description": "HCPF's internal control number.", "nullable": true, "type": "string" }, "paid_amount": { "description": "Paid; negative on a reversal.", "format": "decimal", "nullable": true, "type": "string" }, "rarc": { "description": "Remark code.", "nullable": true, "type": "string" }, "rarc_description": { "nullable": true, "type": "string" }, "status_code": { "description": "CLP02: 1 paid, 4 denied, 22 reversed, ...", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "lines_total": { "description": "Every line on the remittance.", "type": "integer" }, "offset": { "description": "Lines skipped.", "type": "integer" }, "outcomes": { "additionalProperties": true, "description": "Counts and amounts by outcome: claims_count, paid_count/paid_amount, denied_count/denied_amount, reversed_count/reversed_amount, other_count/other_amount, billed_total. Amounts are decimal strings.", "type": "object" }, "received_at": { "description": "When it was downloaded.", "format": "date-time", "type": "string" }, "reconciliation": { "$ref": "#/components/schemas/Reconciliation" } }, "required": [ "id", "outcomes", "reconciliation", "lines", "lines_total", "limit", "offset", "denial_groups" ], "title": "RemittanceDetail", "type": "object" }, "RemittancePage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Remittance" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "RemittancePage", "type": "object" }, "ReportPresetApply": { "properties": { "confirm": { "description": "Confirm a change the page would ask about first.", "type": "boolean" }, "preset": { "description": "The preset's name.", "type": "string" } }, "required": [ "preset" ], "title": "ReportPresetApply", "type": "object" }, "ReportQuestion": { "properties": { "active": { "description": "Whether new reports ask it.", "type": "boolean" }, "advisory": { "description": "Whether a statute or the agency's paper asks for it.", "type": "boolean" }, "config": { "description": "Its type's settings.", "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_type": { "description": "What kind of question it is.", "nullable": true, "type": "string" }, "labels": { "description": "Its text by language code (en, and the print language).", "type": "object" }, "position": { "description": "Its place on the form.", "type": "integer" }, "printed": { "description": "Whether it prints.", "type": "boolean" }, "question_key": { "description": "Its frozen key; answers are kept under it.", "nullable": true, "type": "string" }, "report_type": { "description": "Its report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "required_to_sign": { "description": "Whether it must be answered before signing.", "type": "boolean" }, "seeded": { "description": "Whether it ships with the form.", "type": "boolean" }, "translated": { "description": "Whether it prints in the second language.", "type": "boolean" } }, "required": [ "id", "report_type", "question_key", "labels" ], "title": "ReportQuestion", "type": "object" }, "ReportQuestionCreate": { "properties": { "describes": { "description": "text: the key of the question it explains; null or an empty string clears it.", "nullable": true, "type": "string" }, "heading": { "description": "consent_text: its heading.", "type": "string" }, "item_type": { "description": "What kind of question it is; the report type's first kind when omitted.", "enum": [ "yes_no", "consent_text", "text", "phone", "choice", "multi_choice", "date", "section" ], "type": "string" }, "label_en": { "description": "The English text.", "type": "string" }, "label_secondary": { "description": "The text in the agency's print language; null or an empty string removes it.", "nullable": true, "type": "string" }, "multiline": { "description": "text: whether the answer is a paragraph.", "type": "boolean" }, "option_labels": { "additionalProperties": { "type": "string" }, "description": "choice and multi_choice: a caption for each code, keyed by code. It replaces the stored captions. A code it names must be in the options, or be one this same write removes from them, whose caption is dropped with it. Sent without it, an options change keeps the captions of the codes still listed.", "type": "object" }, "options": { "description": "choice and multi_choice: the option codes, in print order.", "items": { "type": "string" }, "type": "array" }, "print_region": { "description": "yes_no on the supervisory sheet: where it prints. A new one prints in the table unless told otherwise. The sheet's own band questions print below both tables and take none.", "enum": [ "top_list", "table" ], "type": "string" } }, "required": [ "label_en" ], "title": "ReportQuestionCreate", "type": "object" }, "ReportQuestionFlag": { "properties": { "flag": { "description": "The flag to set.", "enum": [ "printed", "required_to_sign", "translated" ], "type": "string" }, "value": { "description": "What to set it to.", "type": "boolean" } }, "required": [ "flag", "value" ], "title": "ReportQuestionFlag", "type": "object" }, "ReportQuestionHide": { "properties": { "confirm": { "description": "Confirm a change the page would ask about first.", "type": "boolean" } }, "title": "ReportQuestionHide", "type": "object" }, "ReportQuestionMove": { "properties": { "direction": { "description": "Which way.", "enum": [ "up", "down" ], "type": "string" } }, "required": [ "direction" ], "title": "ReportQuestionMove", "type": "object" }, "ReportQuestionUpdate": { "properties": { "confirm": { "description": "Confirm a change the page would ask about.", "type": "boolean" }, "describes": { "description": "text: the key of the question it explains; null or an empty string clears it.", "nullable": true, "type": "string" }, "heading": { "description": "consent_text: its heading.", "type": "string" }, "item_type": { "description": "Its kind, which never changes: the type it has is accepted, any other is refused.", "enum": [ "yes_no", "consent_text", "text", "phone", "choice", "multi_choice", "date", "section" ], "type": "string" }, "label_en": { "description": "The English text.", "type": "string" }, "label_secondary": { "description": "The text in the agency's print language; null or an empty string removes it.", "nullable": true, "type": "string" }, "multiline": { "description": "text: whether the answer is a paragraph.", "type": "boolean" }, "option_labels": { "additionalProperties": { "type": "string" }, "description": "choice and multi_choice: a caption for each code, keyed by code. It replaces the stored captions. A code it names must be in the options, or be one this same write removes from them, whose caption is dropped with it. Sent without it, an options change keeps the captions of the codes still listed.", "type": "object" }, "options": { "description": "choice and multi_choice: the option codes, in print order.", "items": { "type": "string" }, "type": "array" }, "print_region": { "description": "yes_no on the supervisory sheet: where it prints. A new one prints in the table unless told otherwise. The sheet's own band questions print below both tables and take none.", "enum": [ "top_list", "table" ], "type": "string" } }, "required": [ "label_en" ], "title": "ReportQuestionUpdate", "type": "object" }, "ReportQuestionsMoved": { "items": { "properties": { "active": { "description": "Whether new reports ask it.", "type": "boolean" }, "advisory": { "description": "Whether a statute or the agency's paper asks for it.", "type": "boolean" }, "config": { "description": "Its type's settings.", "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_type": { "description": "What kind of question it is.", "nullable": true, "type": "string" }, "labels": { "description": "Its text by language code (en, and the print language).", "type": "object" }, "position": { "description": "Its place on the form.", "type": "integer" }, "printed": { "description": "Whether it prints.", "type": "boolean" }, "question_key": { "description": "Its frozen key; answers are kept under it.", "nullable": true, "type": "string" }, "report_type": { "description": "Its report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "required_to_sign": { "description": "Whether it must be answered before signing.", "type": "boolean" }, "seeded": { "description": "Whether it ships with the form.", "type": "boolean" }, "translated": { "description": "Whether it prints in the second language.", "type": "boolean" } }, "required": [ "id", "report_type", "question_key", "labels" ], "title": "ReportQuestion", "type": "object" }, "title": "ReportQuestionsMoved", "type": "array" }, "ReportQuestionsPreset": { "items": { "properties": { "active": { "description": "Whether new reports ask it.", "type": "boolean" }, "advisory": { "description": "Whether a statute or the agency's paper asks for it.", "type": "boolean" }, "config": { "description": "Its type's settings.", "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_type": { "description": "What kind of question it is.", "nullable": true, "type": "string" }, "labels": { "description": "Its text by language code (en, and the print language).", "type": "object" }, "position": { "description": "Its place on the form.", "type": "integer" }, "printed": { "description": "Whether it prints.", "type": "boolean" }, "question_key": { "description": "Its frozen key; answers are kept under it.", "nullable": true, "type": "string" }, "report_type": { "description": "Its report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "required_to_sign": { "description": "Whether it must be answered before signing.", "type": "boolean" }, "seeded": { "description": "Whether it ships with the form.", "type": "boolean" }, "translated": { "description": "Whether it prints in the second language.", "type": "boolean" } }, "required": [ "id", "report_type", "question_key", "labels" ], "title": "ReportQuestion", "type": "object" }, "title": "ReportQuestionsPreset", "type": "array" }, "ReportTemplate": { "properties": { "form": { "properties": { "orientation": { "description": "How it prints.", "enum": [ "portrait", "landscape" ], "type": "string" }, "report_type": { "description": "The report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "title": { "description": "The printed title; null prints the default.", "nullable": true, "type": "string" }, "version": { "description": "How many times it has been saved.", "type": "integer" } }, "required": [ "report_type", "orientation" ], "title": "ReportTemplateForm", "type": "object" }, "questions": { "items": { "properties": { "active": { "description": "Whether new reports ask it.", "type": "boolean" }, "advisory": { "description": "Whether a statute or the agency's paper asks for it.", "type": "boolean" }, "config": { "description": "Its type's settings.", "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_type": { "description": "What kind of question it is.", "nullable": true, "type": "string" }, "labels": { "description": "Its text by language code (en, and the print language).", "type": "object" }, "position": { "description": "Its place on the form.", "type": "integer" }, "printed": { "description": "Whether it prints.", "type": "boolean" }, "question_key": { "description": "Its frozen key; answers are kept under it.", "nullable": true, "type": "string" }, "report_type": { "description": "Its report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "required_to_sign": { "description": "Whether it must be answered before signing.", "type": "boolean" }, "seeded": { "description": "Whether it ships with the form.", "type": "boolean" }, "translated": { "description": "Whether it prints in the second language.", "type": "boolean" } }, "required": [ "id", "report_type", "question_key", "labels" ], "title": "ReportQuestion", "type": "object" }, "type": "array" } }, "required": [ "form", "questions" ], "title": "ReportTemplate", "type": "object" }, "ReportTemplateForm": { "properties": { "orientation": { "description": "How it prints.", "enum": [ "portrait", "landscape" ], "type": "string" }, "report_type": { "description": "The report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "title": { "description": "The printed title; null prints the default.", "nullable": true, "type": "string" }, "version": { "description": "How many times it has been saved.", "type": "integer" } }, "required": [ "report_type", "orientation" ], "title": "ReportTemplateForm", "type": "object" }, "ReportTemplateFormUpdate": { "properties": { "orientation": { "description": "How it prints.", "enum": [ "portrait", "landscape" ], "type": "string" }, "title": { "description": "The printed title; null, blank or left out prints the default.", "nullable": true, "type": "string" } }, "required": [ "orientation" ], "title": "ReportTemplateFormUpdate", "type": "object" }, "Response": { "description": "A file HCPF sent back: an acknowledgment of a submission (response_type says which kind), or era835, a remittance, whose amounts are at /api/v1/remittances/{id}.", "properties": { "acknowledged": { "description": "For an acknowledgment: whether HCPF accepted the submission.", "nullable": true, "type": "boolean" }, "batch_id": { "description": "The batch whose submission it answers; null for a remittance, which can pay several (see its batch_ids).", "format": "uuid", "type": "string" }, "error_code": { "description": "For a refusal, HCPF's code.", "nullable": true, "type": "string" }, "error_message": { "description": "For a refusal, what HCPF said.", "nullable": true, "type": "string" }, "file_name": { "description": "The file's name as HCPF named it.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the record was created.", "format": "date-time", "type": "string" }, "parsed_at": { "format": "date-time", "nullable": true, "type": "string" }, "processed_at": { "description": "When claims were updated from it.", "format": "date-time", "nullable": true, "type": "string" }, "received_at": { "description": "When it was downloaded.", "format": "date-time", "type": "string" }, "response_type": { "enum": [ "ta1", "x999", "x277ca", "era835" ], "type": "string" }, "updated_at": { "description": "When the record last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "response_type" ], "title": "Response", "type": "object" }, "ResponsePage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Response" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ResponsePage", "type": "object" }, "RestoreBody": { "properties": { "lock_version": { "description": "The lock_version the deleted record has: the one its DELETE answered, or read it by listing with include_deleted=true.", "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": [ "lock_version" ], "title": "RestoreBody", "type": "object" }, "ResubmissionDeadline": { "description": "A denied or unpaid claim and the last day Colorado Medicaid accepts it: 365 days from its first date of service, or 60 days from the answer to its latest ICN when that is later. Dismiss one with POST /api/v1/revenue-warnings/dismissals, sending kind resubmission_deadline, its claim_id as subject_id and its fingerprint; a newer ICN that moves the date lists it again. It blocks nothing.", "properties": { "basis": { "description": "What the date counts from: 365 days from the date of service, or 60 days from the latest ICN's answer.", "enum": [ "date_of_service", "latest_icn" ], "type": "string" }, "batch_id": { "description": "The claim file the claim is in.", "format": "uuid", "nullable": true, "type": "string" }, "claim_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client the claim bills for.", "format": "uuid", "nullable": true, "type": "string" }, "days_left": { "description": "Days from today to resubmit_by; negative once it has passed.", "type": "integer" }, "dismissed": { "description": "Whether a member dismissed this line at this date.", "type": "boolean" }, "fingerprint": { "description": "The resubmit_by date, which a dismissal names.", "type": "string" }, "icn": { "description": "The newest claim's ICN, when HCPF gave it one.", "nullable": true, "type": "string" }, "id": { "description": "The claim's id, as claim_id.", "format": "uuid", "type": "string" }, "kind": { "description": "The dismissal kind: resubmission_deadline.", "type": "string" }, "procedure_code": { "description": "The HCPCS procedure code.", "type": "string" }, "resubmit_by": { "description": "The last day the line can be resubmitted.", "format": "date", "nullable": true, "type": "string" }, "service_date_from": { "description": "The claim's first date of service.", "format": "date", "nullable": true, "type": "string" }, "service_date_to": { "description": "The claim's last date of service.", "format": "date", "nullable": true, "type": "string" }, "status": { "description": "The newest claim's status.", "type": "string" } }, "required": [ "id", "claim_id", "service_date_from", "service_date_to", "procedure_code", "status", "resubmit_by", "basis", "days_left", "kind", "fingerprint", "dismissed" ], "title": "ResubmissionDeadline", "type": "object" }, "ResubmissionDeadlinePage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ResubmissionDeadline" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ResubmissionDeadlinePage", "type": "object" }, "RevenueAtRisk": { "description": "A PAR ending inside the window with authorized care unused and no renewal on file (source unused_authorization: bill the care or renew the PAR), or a scheduled visit inside the window that no active or pending PAR of its client and code covers (source uncovered_visit: enter the renewal PAR or move the visit). Nothing here blocks a claim.", "properties": { "client_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "client_name": { "description": "The client, last name first.", "nullable": true, "type": "string" }, "date": { "description": "The PAR's end date, or the visit's date of service.", "format": "date", "nullable": true, "type": "string" }, "service_code": { "description": "The HCPCS code.", "type": "string" }, "source": { "description": "What is at risk.", "enum": [ "unused_authorization", "uncovered_visit" ], "type": "string" }, "subject_id": { "description": "The service authorization (unused_authorization) or the visit (uncovered_visit).", "format": "uuid", "type": "string" }, "units": { "description": "15-minute units for an hourly code, visits for a per-visit code: the PAR's unused units, or the visit's scheduled time. Null when the code's unit cannot be told.", "format": "decimal", "nullable": true, "type": "string" }, "value": { "description": "Whole dollars at HCPF's published rate. Null when no published rate prices it; such a row adds nothing to the total.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "source", "subject_id", "client_id", "client_name", "service_code", "date", "units", "value" ], "title": "RevenueAtRisk", "type": "object" }, "RevenueAtRiskPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/RevenueAtRisk" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "summary": { "properties": { "total": { "description": "unused.value plus uncovered.value, in whole dollars.", "format": "decimal", "nullable": true, "type": "string" }, "truncated": { "description": "True when the window held more PARs or visits than one read values; the total is then a floor.", "type": "boolean" }, "uncovered": { "description": "Scheduled care with no PAR.", "properties": { "count": { "description": "Rows, priced or not.", "minimum": 0, "type": "integer" }, "value": { "description": "Whole dollars, the priced rows only.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "value", "count" ], "title": "RevenueAtRiskPart", "type": "object" }, "unpriced_count": { "description": "Rows with no published rate, left out of the total.", "minimum": 0, "type": "integer" }, "unused": { "description": "Authorized care ending unused.", "properties": { "count": { "description": "Rows, priced or not.", "minimum": 0, "type": "integer" }, "value": { "description": "Whole dollars, the priced rows only.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "value", "count" ], "title": "RevenueAtRiskPart", "type": "object" }, "within_days": { "description": "The window read.", "enum": [ 14, 30 ], "type": "integer" } }, "required": [ "within_days", "total", "unused", "uncovered", "unpriced_count", "truncated" ], "title": "RevenueAtRiskSummary", "type": "object" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total", "summary" ], "title": "RevenueAtRiskPage", "type": "object" }, "RevenueAtRiskPart": { "description": "Scheduled care with no PAR.", "properties": { "count": { "description": "Rows, priced or not.", "minimum": 0, "type": "integer" }, "value": { "description": "Whole dollars, the priced rows only.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "value", "count" ], "title": "RevenueAtRiskPart", "type": "object" }, "RevenueAtRiskSummary": { "properties": { "total": { "description": "unused.value plus uncovered.value, in whole dollars.", "format": "decimal", "nullable": true, "type": "string" }, "truncated": { "description": "True when the window held more PARs or visits than one read values; the total is then a floor.", "type": "boolean" }, "uncovered": { "description": "Scheduled care with no PAR.", "properties": { "count": { "description": "Rows, priced or not.", "minimum": 0, "type": "integer" }, "value": { "description": "Whole dollars, the priced rows only.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "value", "count" ], "title": "RevenueAtRiskPart", "type": "object" }, "unpriced_count": { "description": "Rows with no published rate, left out of the total.", "minimum": 0, "type": "integer" }, "unused": { "description": "Authorized care ending unused.", "properties": { "count": { "description": "Rows, priced or not.", "minimum": 0, "type": "integer" }, "value": { "description": "Whole dollars, the priced rows only.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "value", "count" ], "title": "RevenueAtRiskPart", "type": "object" }, "within_days": { "description": "The window read.", "enum": [ 14, 30 ], "type": "integer" } }, "required": [ "within_days", "total", "unused", "uncovered", "unpriced_count", "truncated" ], "title": "RevenueAtRiskSummary", "type": "object" }, "RevenueWarning": { "description": "A warning about money a claim may lose. It blocks nothing. Dismiss it with POST /api/v1/revenue-warnings/dismissals, sending its kind, its claim_id as subject_id, and its fingerprint; a dismissed warning whose figures change gets a new fingerprint and warns again.", "properties": { "claim_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "dismissed": { "description": "Whether a member dismissed this warning at these figures.", "type": "boolean" }, "fingerprint": { "description": "The figures the warning states, joined with a colon.", "type": "string" }, "kind": { "description": "What the warning is about.", "type": "string" }, "link": { "description": "The web app path where the agency checks the warning (a care log changed after the claim was sent opens the client's evidence grid); null when the warning has none.", "nullable": true, "type": "string" }, "message": { "description": "The warning, in plain English.", "type": "string" }, "row_number": { "description": "The claim's row in the uploaded file.", "nullable": true, "type": "integer" } }, "required": [ "claim_id", "row_number", "kind", "fingerprint", "message", "dismissed" ], "title": "RevenueWarning", "type": "object" }, "RevenueWarningDismissal": { "properties": { "dismissed_at": { "description": "When it was dismissed.", "format": "date-time", "type": "string" }, "dismissed_by_id": { "description": "The member who dismissed it.", "format": "uuid", "nullable": true, "type": "string" }, "fingerprint": { "description": "The figures dismissed.", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "kind": { "description": "The warning's kind.", "type": "string" }, "subject_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "required": [ "id", "kind", "subject_id", "fingerprint", "dismissed_at" ], "title": "RevenueWarningDismissal", "type": "object" }, "RevenueWarningPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/RevenueWarning" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "RevenueWarningPage", "type": "object" }, "SampleRecordCounts": { "properties": { "clients": { "description": "Sample clients.", "type": "integer" }, "employees": { "description": "Sample employees.", "type": "integer" }, "visits": { "description": "Sample visits.", "type": "integer" } }, "required": [ "clients", "employees", "visits" ], "title": "SampleRecordCounts", "type": "object" }, "SampleRecordsQueued": { "properties": { "cases": { "description": "Each case's result.", "items": { "properties": { "case": { "description": "The case's id.", "nullable": true, "type": "string" }, "dry_run": { "description": "True: written to the server log, nothing sent to Sandata and nothing changed.", "type": "boolean" }, "records": { "description": "How many records the case holds.", "type": "integer" }, "refused": { "description": "POST /settings/sandata/certification/send only: present when this case was refused while the other went; it changed nothing.", "properties": { "code": { "description": "The refusal's code, as an error carries it.", "nullable": true, "type": "string" }, "message": { "description": "Why the case was not sent.", "nullable": true, "type": "string" } }, "required": [ "code", "message" ], "title": "CertificationCaseRefusal", "type": "object" }, "sending": { "description": "Live: how many of them were queued, those Sandata does not hold as they are now, a record it refused included until it is parked. Dry run: how many were written to the server log.", "type": "integer" } }, "required": [ "case", "records", "sending", "dry_run" ], "title": "CertificationCaseResult", "type": "object" }, "type": "array" }, "dry_run": { "description": "Whether this was a dry run.", "type": "boolean" }, "queued": { "description": "True when they were queued for Sandata; false in a dry run.", "type": "boolean" } }, "required": [ "queued" ], "title": "SampleRecordsQueued", "type": "object" }, "SampleVisitsQueued": { "properties": { "case": { "description": "The test case sent.", "nullable": true, "type": "string" }, "queued_visits": { "description": "Sample visits queued.", "type": "integer" } }, "required": [ "queued_visits" ], "title": "SampleVisitsQueued", "type": "object" }, "SandataCertification": { "properties": { "cases": { "description": "Sandata's certification test cases, in order, each sent on its own.", "items": { "properties": { "applied": { "description": "Round 2: whether the case's change was made. Null in round 1.", "nullable": true, "type": "boolean" }, "blocked": { "description": "Why a send is refused now; null when it is not.", "nullable": true, "type": "string" }, "id": { "description": "The case's id, as POST /settings/sandata/certification/cases/{id} takes it.", "nullable": true, "type": "string" }, "records": { "description": "How many records it sends.", "type": "integer" }, "round": { "description": "1: the sample records as created. 2: changes to records Sandata accepted.", "type": "integer" }, "scenario": { "description": "The Sandata scenario it covers.", "nullable": true, "type": "string" }, "state": { "additionalProperties": { "type": "integer" }, "description": "Of those records, how many Sandata holds as they are now (accepted), are waiting for Sandata's answer (waiting), were refused as they are now and go again on a send (refused), were refused too often to go again until they change (parked), cannot be sent as they are (held_back), and are left to send (to_send); each record is in exactly one. Null while Sandata is paused or not set up.", "nullable": true, "type": "object" }, "title": { "description": "What the page calls it.", "nullable": true, "type": "string" } }, "required": [ "id", "round", "title", "scenario", "records" ], "title": "CertificationCase", "type": "object" }, "type": "array" }, "cleanup_refusal": { "description": "Why sample records cannot be removed; null when they can.", "nullable": true, "type": "string" }, "completed_count": { "description": "Steps done.", "type": "integer" }, "dry_run": { "description": "Whether sends are a dry run: written to the server log, nothing sent to Sandata. Only the certification tenant has one.", "type": "boolean" }, "environment": { "description": "The Sandata environment the sends reach.", "nullable": true, "type": "string" }, "generate_refusal": { "description": "Why sample records cannot be created; null when they can.", "nullable": true, "type": "string" }, "globally_enabled": { "description": "The platform switch: whether Sandata is turned on for agencies. It never pauses the certification tenant; see sandata_open.", "type": "boolean" }, "parties": { "description": "Each sample client and employee, and where it stands with Sandata.", "items": { "properties": { "batch": { "description": "Its latest batch's status; null when never sent.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "kind": { "description": "Client or employee.", "enum": [ "client", "employee" ], "type": "string" }, "name": { "description": "Its name.", "nullable": true, "type": "string" }, "state": { "description": "Where it stands with Sandata.", "enum": [ "accepted", "refused", "waiting", "unanswered", "not_sent" ], "type": "string" } }, "required": [ "kind", "id", "name", "state" ], "title": "CertificationParty", "type": "object" }, "type": "array" }, "percentage": { "description": "Steps done, in percent.", "type": "number" }, "sandata_open": { "description": "False while Sandata is paused for this agency: the platform switch is off and this is not the certification tenant.", "type": "boolean" }, "send_refusal": { "description": "Why sample records cannot be sent; null when they can.", "nullable": true, "type": "string" }, "steps": { "description": "The checklist, in order.", "items": { "properties": { "category": { "description": "Its section on the page.", "nullable": true, "type": "string" }, "completed": { "description": "Whether it is done.", "type": "boolean" }, "date": { "description": "The day it was marked done; null when not done.", "format": "date", "nullable": true, "type": "string" }, "key": { "description": "The step's key.", "nullable": true, "type": "string" }, "notes": { "description": "Its notes; null when none.", "nullable": true, "type": "string" }, "text": { "description": "What the page calls it.", "nullable": true, "type": "string" } }, "required": [ "key", "text", "category", "completed" ], "title": "CertificationStep", "type": "object" }, "type": "array" }, "test_data_exists": { "description": "Whether sample records exist.", "type": "boolean" }, "total_count": { "description": "Steps in all.", "type": "integer" } }, "required": [ "steps", "completed_count", "total_count", "percentage", "parties" ], "title": "SandataCertification", "type": "object" }, "SandataConnected": { "properties": { "connected": { "description": "Always true.", "type": "boolean" } }, "required": [ "connected" ], "title": "SandataConnected", "type": "object" }, "SandataConnectionTest": { "properties": { "sandata_agency_id": { "description": "The Sandata Account.", "nullable": true, "type": "string" }, "sandata_api_url": { "description": "The Sandata API URL (https).", "nullable": true, "type": "string" }, "sandata_entity_guid": { "description": "The EntityGuid header, sent when set.", "nullable": true, "type": "string" }, "sandata_password": { "description": "The password; null or blank tests the saved one.", "nullable": true, "type": "string" }, "sandata_username": { "description": "The username; null or blank tests the saved one.", "nullable": true, "type": "string" } }, "title": "SandataConnectionTest", "type": "object" }, "SandataSettings": { "properties": { "sandata_agency_id": { "description": "The Sandata Account.", "nullable": true, "type": "string" }, "sandata_api_url": { "description": "The Sandata API URL (https).", "nullable": true, "type": "string" }, "sandata_batch_size": { "description": "Visits per send, 1 to 5000.", "nullable": true, "type": "integer" }, "sandata_custom_cron": { "description": "A five-field cron expression, for a custom schedule.", "nullable": true, "type": "string" }, "sandata_default_timezone": { "description": "The timezone visits are sent in.", "nullable": true, "type": "string" }, "sandata_enabled": { "description": "Whether visits are sent to Sandata.", "enum": [ "true", "false" ], "nullable": true, "type": "string" }, "sandata_entity_guid": { "description": "The EntityGuid header, sent when set.", "nullable": true, "type": "string" }, "sandata_password": { "properties": { "set": { "description": "Whether a value is saved; read it with the secrets operation.", "type": "boolean" } }, "required": [ "set" ], "title": "SecretSet", "type": "object" }, "sandata_provider_id": { "description": "The agency's Medicaid provider id (8 to 10 digits).", "nullable": true, "type": "string" }, "sandata_send_visit_memo": { "description": "Whether the visit memo is sent.", "enum": [ "true", "false" ], "nullable": true, "type": "string" }, "sandata_submission_schedule": { "description": "When visits are sent: a preset or custom.", "nullable": true, "type": "string" }, "sandata_username": { "properties": { "set": { "description": "Whether a value is saved; read it with the secrets operation.", "type": "boolean" } }, "required": [ "set" ], "title": "SecretSet", "type": "object" } }, "required": [ "sandata_username", "sandata_password" ], "title": "SandataSettings", "type": "object" }, "SandataSettingsUpdate": { "properties": { "sandata_agency_id": { "description": "The Sandata Account.", "nullable": false, "type": "string" }, "sandata_api_url": { "description": "The Sandata API URL (https).", "nullable": true, "type": "string" }, "sandata_batch_size": { "description": "Visits per send, 1 to 5000.", "type": "integer" }, "sandata_custom_cron": { "description": "A five-field cron expression, for a custom schedule.", "nullable": true, "type": "string" }, "sandata_default_timezone": { "description": "The timezone visits are sent in.", "nullable": true, "type": "string" }, "sandata_enabled": { "description": "Whether visits are sent to Sandata.", "enum": [ "true", "false" ], "type": "string" }, "sandata_entity_guid": { "description": "The EntityGuid header, sent when set.", "nullable": true, "type": "string" }, "sandata_password": { "description": "The password; null or blank keeps the saved one.", "nullable": true, "type": "string" }, "sandata_provider_id": { "description": "The agency's Medicaid provider id (8 to 10 digits).", "nullable": false, "type": "string" }, "sandata_send_visit_memo": { "description": "Whether the visit memo is sent.", "enum": [ "true", "false" ], "type": "string" }, "sandata_submission_schedule": { "description": "When visits are sent: a preset or custom.", "nullable": true, "type": "string" }, "sandata_username": { "description": "The username; null or blank keeps the saved one.", "nullable": true, "type": "string" } }, "title": "SandataSettingsUpdate", "type": "object" }, "SatisfactionSurvey": { "description": "One satisfaction survey of a client: a draft until it is completed.", "properties": { "client_id": { "description": "The client surveyed.", "format": "uuid", "type": "string" }, "comments": { "description": "Comments.", "nullable": true, "type": "string", "x-untrusted": "text" }, "conducted_by_id": { "description": "Who conducted it.", "format": "uuid", "nullable": true, "type": "string" }, "conducted_via": { "description": "How it was conducted.", "enum": [ "phone", "in_person", "video_call" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was recorded.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "responses": { "description": "The answers, by question key.", "type": "object" }, "status": { "description": "A draft, or completed.", "enum": [ "draft", "completed" ], "type": "string" }, "survey_date": { "description": "The day of the survey.", "format": "date", "nullable": true, "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "client_id", "survey_date", "status", "lock_version" ], "title": "SatisfactionSurvey", "type": "object" }, "SatisfactionSurveyInput": { "description": "Send only the fields to change, with the lock_version read.", "properties": { "comments": { "description": "Comments.", "nullable": true, "type": "string" }, "conducted_via": { "description": "How it was conducted.", "enum": [ "phone", "in_person", "video_call" ], "type": "string" }, "responses": { "description": "The answers, by question key; the answers sent replace those stored. A yes/no question takes yes, no or na, a rating poor, fair, good or excellent.", "properties": { "q1": { "description": "Were you given a copy of the Consumer/Employee Handbook?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q10": { "description": "Is the employee courteous and respectful?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q11": { "description": "Does the employee report changes in your condition to the supervisor?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q12": { "description": "Does the employee maintain confidentiality?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q13": { "description": "Does the employee follow infection control/universal precaution practices?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q14": { "description": "If applicable, does the employee properly handle your medications?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q15": { "description": "Has the agency sent a substitute when the regular employee is absent?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q16a": { "description": "Bathing", "enum": [ "yes", "no", "na" ], "type": "string" }, "q16b": { "description": "Dressing", "enum": [ "yes", "no", "na" ], "type": "string" }, "q16c": { "description": "Grooming", "enum": [ "yes", "no", "na" ], "type": "string" }, "q16d": { "description": "Toileting", "enum": [ "yes", "no", "na" ], "type": "string" }, "q16e": { "description": "Eating/Feeding", "enum": [ "yes", "no", "na" ], "type": "string" }, "q16f": { "description": "Transferring/Mobility", "enum": [ "yes", "no", "na" ], "type": "string" }, "q16g": { "description": "Meal Preparation", "enum": [ "yes", "no", "na" ], "type": "string" }, "q16h": { "description": "Housekeeping", "enum": [ "yes", "no", "na" ], "type": "string" }, "q16i": { "description": "Laundry", "enum": [ "yes", "no", "na" ], "type": "string" }, "q16j": { "description": "Shopping/Errands", "enum": [ "yes", "no", "na" ], "type": "string" }, "q17": { "description": "Has the employee ever asked you to sign a blank timesheet?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q18": { "description": "Has the employee ever asked you to sign a timesheet without reviewing it?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q19": { "description": "Has the employee ever asked you for money or gifts?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q2": { "description": "Were you informed about the complaint/grievance procedures?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q20": { "description": "Has anyone from the agency asked you to pay for services?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q21": { "description": "Has the agency supervisor visited you at least once every 6 months?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q22": { "description": "What do you like best about the services you receive?", "type": "string" }, "q23": { "description": "What changes would you suggest to improve services?", "type": "string" }, "q24": { "description": "Would you recommend this agency to others?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q25": { "description": "Do you feel safe with the employee in your home?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q26": { "description": "How would you rate the overall quality of services?", "enum": [ "poor", "fair", "good", "excellent" ], "type": "string" }, "q27": { "description": "Additional comments:", "type": "string" }, "q3a": { "description": "Name of the agency", "enum": [ "yes", "no", "na" ], "type": "string" }, "q3b": { "description": "Name of the supervisor", "enum": [ "yes", "no", "na" ], "type": "string" }, "q3c": { "description": "How to contact the agency", "enum": [ "yes", "no", "na" ], "type": "string" }, "q3d": { "description": "What to do in case of an emergency", "enum": [ "yes", "no", "na" ], "type": "string" }, "q3e": { "description": "How to report complaints", "enum": [ "yes", "no", "na" ], "type": "string" }, "q3f": { "description": "Services to be provided", "enum": [ "yes", "no", "na" ], "type": "string" }, "q4": { "description": "Were you asked to sign a document verifying the above information?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q5": { "description": "Are you receiving the services as outlined in the service plan?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q6": { "description": "Were you involved in the development of the service plan?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q7": { "description": "Has the service plan been reviewed at least annually?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q8": { "description": "Does the employee arrive and leave on time?", "enum": [ "yes", "no", "na" ], "type": "string" }, "q9": { "description": "Does the employee perform the tasks listed in the service plan?", "enum": [ "yes", "no", "na" ], "type": "string" } }, "type": "object" }, "survey_date": { "description": "The day of the survey, YYYY-MM-DD.", "format": "date", "nullable": false, "type": "string" } }, "title": "SatisfactionSurveyInput", "type": "object" }, "SatisfactionSurveyPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/SatisfactionSurvey" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "SatisfactionSurveyPage", "type": "object" }, "SavedProviderTypeModifiers": { "properties": { "agency_owned": { "description": "Whether the agency has its own copy of the template. Its first certification save on a system template makes that copy; modifier changes write the agency's offering and make no copy.", "type": "boolean" }, "billing_code": { "description": "The HCPCS code it bills.", "nullable": true, "type": "string" }, "certification_text": { "description": "The certification its cards print, in English.", "nullable": true, "type": "string" }, "certification_translations": { "additionalProperties": { "type": "string" }, "description": "Its translations, by language code.", "type": "object" }, "certification_version": { "description": "What a certification save sends back, to refuse one saved since.", "nullable": true, "type": "string" }, "code": { "description": "The provider type's code, as the path takes it.", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "modifiers": { "description": "The modifiers it bills, and the batch validation expects.", "items": { "type": "string" }, "type": "array" }, "name": { "description": "The provider type's name.", "nullable": true, "type": "string" }, "warnings": { "description": "What the saved set warns of; usually empty. Never a refusal: the set is saved. Each names its rule (catalog.unpriced_modifier: a modifier no fee schedule in force today or later prices on the billing code; it bills as entered) and the message.", "items": { "properties": { "message": { "description": "What the admin is warned of.", "type": "string" }, "rule_id": { "description": "The rule that raised it.", "type": "string" } }, "required": [ "rule_id", "message" ], "title": "ProviderTypeModifierWarning", "type": "object" }, "type": "array" } }, "required": [ "code", "modifiers", "warnings" ], "title": "SavedProviderTypeModifiers", "type": "object" }, "ScheduleImportResult": { "properties": { "dry_run": { "description": "true: nothing was written; items are what the import would do.", "type": "boolean" }, "failed": { "description": "Real run only: items refused, by row, with the errors by field.", "items": { "properties": { "errors": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object" }, "row": { "type": "integer" } }, "required": [ "row", "errors" ], "type": "object" }, "type": "array" }, "imported": { "description": "Real run only: new assignments written.", "type": "integer" }, "items": { "items": { "properties": { "assignment_id": { "nullable": true, "type": "string" }, "caregiver": { "description": "\"Last, First\" from the agency's records, or the PDF's name when none matched.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "Null when not matched.", "nullable": true, "type": "string" }, "client": { "description": "\"Last, First\" from the agency's records, or the PDF's name when none matched.", "nullable": true, "type": "string" }, "client_id": { "description": "Null when not matched.", "nullable": true, "type": "string" }, "days_after": { "description": "The days the file gives.", "items": { "properties": { "day_of_week": { "enum": [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" ], "type": "string" }, "end_time": { "description": "HH:MM:SS", "format": "time", "type": "string" }, "ends_next_day": { "description": "true: the visit ends after midnight, on the next day.", "type": "boolean" }, "shift_number": { "description": "1 to 4: the visit's place on its day.", "type": "integer" }, "start_time": { "description": "HH:MM:SS", "format": "time", "type": "string" } }, "required": [ "shift_number", "day_of_week", "start_time", "end_time", "ends_next_day" ], "type": "object" }, "type": "array" }, "days_before": { "description": "The days HCB holds now.", "items": { "properties": { "day_of_week": { "enum": [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" ], "type": "string" }, "end_time": { "description": "HH:MM:SS", "format": "time", "type": "string" }, "ends_next_day": { "description": "true: the visit ends after midnight, on the next day.", "type": "boolean" }, "shift_number": { "description": "1 to 4: the visit's place on its day.", "type": "integer" }, "start_time": { "description": "HH:MM:SS", "format": "time", "type": "string" } }, "required": [ "shift_number", "day_of_week", "start_time", "end_time", "ends_next_day" ], "type": "object" }, "type": "array" }, "outcome": { "description": "new: a pair HCB has no active or open temporary assignment for; changed: its days differ; unchanged: they match; not_imported: a name or service that did not resolve (reason says which); not_on_schedule: an active assignment, or a temporary one with no end date, that the file does not name, left as it is.", "enum": [ "new", "changed", "unchanged", "not_imported", "not_on_schedule" ], "type": "string" }, "reason": { "nullable": true, "type": "string" }, "row": { "description": "The item's number, which failed, reasons and warnings name.", "type": "integer" }, "service": { "description": "InMyTeam's service label (PCA, HMKRrel...), or for not_on_schedule the assignment's provider type.", "nullable": true, "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "row", "client", "caregiver", "service", "outcome", "days_before", "days_after", "reason", "warnings" ], "type": "object" }, "type": "array" }, "reasons": { "additionalProperties": { "items": { "properties": { "detail": { "nullable": true, "type": "string" }, "row": { "type": "integer" } }, "type": "object" }, "type": "array" }, "description": "Real run only: rows by code, each {row, detail}.", "type": "object" }, "skipped": { "description": "Real run only: items not written; reasons says why (unchanged, not_imported, not_on_schedule, already_on_file, changed_since_preview).", "type": "integer" }, "updated": { "description": "Real run only: assignments whose days were replaced.", "type": "integer" }, "warnings": { "description": "Real run only: rows written with something to check (no PAR or billing code...), each {row, detail}.", "items": { "properties": { "detail": { "nullable": true, "type": "string" }, "row": { "type": "integer" } }, "type": "object" }, "type": "array" }, "week_start": { "description": "The Sunday the schedule's week starts on.", "format": "date", "type": "string" } }, "required": [ "dry_run", "week_start", "items" ], "title": "ScheduleImportResult", "type": "object" }, "SecretSet": { "properties": { "set": { "description": "Whether a value is saved; read it with the secrets operation.", "type": "boolean" } }, "required": [ "set" ], "title": "SecretSet", "type": "object" }, "SecuritySettings": { "properties": { "require_two_factor": { "description": "Whether every member must sign in with two-factor.", "type": "boolean" }, "session_timeout_minutes": { "description": "Minutes idle before sign-out.", "enum": [ 5, 15, 30, 60 ], "type": "integer" } }, "required": [ "require_two_factor", "session_timeout_minutes" ], "title": "SecuritySettings", "type": "object" }, "SecuritySettingsUpdate": { "properties": { "code": { "deprecated": true, "description": "Deprecated: send otp_code. Read when otp_code is absent, until April 30, 2027.", "type": "string" }, "otp_code": { "description": "A current 6-digit code from your authenticator app; needed to turn the requirement off.", "type": "string" }, "require_two_factor": { "description": "Require two-factor sign-in of every member (true), or stop (false). Requiring it needs your own two-factor on first.", "type": "boolean" }, "session_timeout_minutes": { "description": "Minutes idle before sign-out: 5, 15, 30 or 60.", "type": "integer" } }, "title": "SecuritySettingsUpdate", "type": "object" }, "Service authorizationPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ServiceAuthorization" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Service authorizationPage", "type": "object" }, "Service ratePage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ServiceRate" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Service ratePage", "type": "object" }, "ServiceArea": { "properties": { "archived": { "description": "Archived: kept for the shifts that name it, offered for none.", "type": "boolean" }, "county": { "description": "A Colorado county.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "latitude": { "description": "The latitude of the area's centre.", "format": "decimal", "nullable": true, "type": "string" }, "longitude": { "description": "The longitude of the area's centre.", "format": "decimal", "nullable": true, "type": "string" }, "name": { "description": "The area's name.", "type": "string" }, "position": { "description": "Its place in the agency's list, 1 first; an archived area keeps its last.", "nullable": true, "type": "integer" } }, "required": [ "id", "name", "latitude", "longitude", "position", "archived" ], "title": "ServiceArea", "type": "object" }, "ServiceAreaCreate": { "properties": { "county": { "description": "A Colorado county (Douglas), or null for none.", "nullable": true, "type": "string" }, "latitude": { "description": "The latitude of the area's centre.", "maximum": 90, "minimum": -90, "type": "number" }, "longitude": { "description": "The longitude of the area's centre.", "maximum": 180, "minimum": -180, "type": "number" }, "name": { "description": "The area's name, as the agency writes it (Denver — Downtown, Parker).", "maxLength": 80, "minLength": 1, "type": "string", "x-untrusted": "text" }, "position": { "description": "Optional; last when left out. Its place in the agency's list, 1 first; the other areas move to make room, and a place past the end puts it last.", "minimum": 1, "type": "integer" } }, "required": [ "name", "latitude", "longitude" ], "title": "ServiceAreaCreate", "type": "object" }, "ServiceAreaPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "archived": { "description": "Archived: kept for the shifts that name it, offered for none.", "type": "boolean" }, "county": { "description": "A Colorado county.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "latitude": { "description": "The latitude of the area's centre.", "format": "decimal", "nullable": true, "type": "string" }, "longitude": { "description": "The longitude of the area's centre.", "format": "decimal", "nullable": true, "type": "string" }, "name": { "description": "The area's name.", "type": "string" }, "position": { "description": "Its place in the agency's list, 1 first; an archived area keeps its last.", "nullable": true, "type": "integer" } }, "required": [ "id", "name", "latitude", "longitude", "position", "archived" ], "title": "ServiceArea", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ServiceAreaPage", "type": "object" }, "ServiceAreaUpdate": { "properties": { "archived": { "description": "true archives the area: it keeps its id and stays on what names it, and is offered for nothing new; false restores it, last in the list unless a position is sent.", "type": "boolean" }, "county": { "description": "A Colorado county (Douglas), or null for none.", "nullable": true, "type": "string" }, "latitude": { "description": "The latitude of the area's centre.", "maximum": 90, "minimum": -90, "type": "number" }, "longitude": { "description": "The longitude of the area's centre.", "maximum": 180, "minimum": -180, "type": "number" }, "name": { "description": "The area's name, as the agency writes it (Denver — Downtown, Parker).", "maxLength": 80, "minLength": 1, "type": "string", "x-untrusted": "text" }, "position": { "description": "Its place in the agency's list, 1 first; the other areas move to make room, and a place past the end puts it last.", "minimum": 1, "type": "integer" } }, "title": "ServiceAreaUpdate", "type": "object" }, "ServiceAuthorization": { "description": "A service authorization (a PAR): the units of a service HCPF authorized for a client, and what is left of them. Not an HTTP authorization. The four usage figures are live: they move as time is billed WITHOUT changing updated_at or lock_version, so a sync that skips records it already holds must re-read an authorization (GET) for current figures.", "properties": { "authorized_units": { "description": "Units authorized.", "format": "decimal", "nullable": true, "type": "string" }, "client_id": { "description": "The client the service is authorized for.", "format": "uuid", "type": "string" }, "cm_authorization_reference": { "description": "The case manager's approval reference.", "nullable": true, "type": "string" }, "cm_authorized_on": { "description": "The day the case manager approved (YYYY-MM-DD).", "format": "date", "nullable": true, "type": "string" }, "committed_units": { "description": "Units scheduled or entered but not yet billed. Null unless the authorization is active.", "format": "decimal", "nullable": true, "type": "string" }, "deleted_at": { "description": "Set when the agency deleted the record. Only a list with include_deleted=true returns deleted records.", "format": "date-time", "nullable": true, "type": "string" }, "effective_date": { "description": "Effective date (YYYY-MM-DD).", "format": "date", "nullable": true, "type": "string" }, "end_date": { "description": "End date (YYYY-MM-DD).", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the record was created.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "modifiers": { "description": "Billing code modifiers, like U1.", "items": { "type": "string" }, "type": "array" }, "par_number": { "description": "The prior authorization request (PAR) number.", "nullable": true, "type": "string" }, "payer": { "description": "Who pays for the service.", "enum": [ "medicaid", "private" ], "type": "string" }, "remaining_units": { "description": "Authorized minus used, never below zero. Null unless the authorization is active.", "format": "decimal", "nullable": true, "type": "string" }, "service_code": { "description": "The HCPCS code authorized, five letters and digits like T1019.", "nullable": true, "type": "string" }, "shown_status": { "description": "The status the agency's screens show, and the one the status filter matches: expired once the end date has passed, even before the nightly job stores it in status.", "enum": [ "pending", "active", "expired", "suspended" ], "type": "string" }, "status": { "enum": [ "pending", "active", "expired", "suspended" ], "type": "string" }, "unit_type": { "description": "What one authorized unit is.", "enum": [ "hours", "visits" ], "type": "string" }, "unused_value": { "description": "Roughly what the authorized units not yet billed on claims are worth, in whole US dollars, at HCPF's published rate on the end date (\"2496\"). Null unless the authorization is active, or when no published rate prices its code and modifiers.", "nullable": true, "type": "string" }, "updated_at": { "description": "When the record last changed.", "format": "date-time", "type": "string" }, "used_units": { "description": "Units used by this authorization's own billed time. Null unless the authorization is active.", "format": "decimal", "nullable": true, "type": "string" }, "utilization_percentage": { "description": "Used as a percentage of authorized, to one decimal place. Null unless the authorization is active.", "format": "decimal", "nullable": true, "type": "string" }, "weekly_hours": { "description": "Hours a week the authorization allows: its total spread evenly over its dates (inclusive days / 7), to two places. Null for a visits authorization, or when the units or dates are missing.", "format": "decimal", "nullable": true, "type": "string" }, "weekly_units": { "description": "Billing units a week the authorization allows (15-minute units for an hours authorization, visits for a visits one), to two places. Null when the units, unit type or dates are missing.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "id", "client_id", "status", "lock_version" ], "title": "ServiceAuthorization", "type": "object" }, "ServiceAuthorizationCreate": { "description": "A new service authorization for one of the agency's clients. A client_id that is not the agency's answers 422 client_not_found. It is created pending: billing and utilization alerts ignore it until it is activated, in the app or with POST /api/v1/authorizations/{id}/transition.", "properties": { "authorized_units": { "description": "Units authorized.", "format": "decimal", "nullable": true, "type": "string" }, "client_id": { "description": "The client the service is authorized for.", "format": "uuid", "type": "string" }, "cm_authorization_reference": { "description": "The case manager's approval reference.", "nullable": true, "type": "string" }, "cm_authorized_on": { "description": "The day the case manager approved (YYYY-MM-DD).", "format": "date", "nullable": true, "type": "string" }, "effective_date": { "description": "Effective date (YYYY-MM-DD).", "format": "date", "nullable": false, "type": "string" }, "end_date": { "description": "End date (YYYY-MM-DD).", "format": "date", "nullable": false, "type": "string" }, "modifiers": { "description": "Billing code modifiers, like U1.", "items": { "type": "string" }, "type": "array" }, "notes": { "description": "Free text; written, never returned.", "nullable": true, "type": "string" }, "par_number": { "description": "The prior authorization request (PAR) number.", "nullable": true, "type": "string" }, "payer": { "description": "Who pays for the service.", "enum": [ "medicaid", "private" ], "type": "string" }, "service_code": { "description": "The HCPCS code authorized, five letters and digits like T1019.", "nullable": false, "type": "string" }, "unit_type": { "description": "What one authorized unit is.", "enum": [ "hours", "visits" ], "type": "string" } }, "required": [ "client_id", "payer", "service_code", "authorized_units", "unit_type", "effective_date", "end_date" ], "title": "ServiceAuthorizationCreate", "type": "object" }, "ServiceAuthorizationRenewal": { "description": "The new PAR's fields; its client is the renewed PAR's.", "properties": { "authorized_units": { "description": "Units authorized.", "format": "decimal", "nullable": true, "type": "string" }, "cm_authorization_reference": { "description": "The case manager's approval reference.", "nullable": true, "type": "string" }, "cm_authorized_on": { "description": "The day the case manager approved (YYYY-MM-DD).", "format": "date", "nullable": true, "type": "string" }, "effective_date": { "description": "Effective date (YYYY-MM-DD).", "format": "date", "nullable": false, "type": "string" }, "end_date": { "description": "End date (YYYY-MM-DD).", "format": "date", "nullable": false, "type": "string" }, "modifiers": { "description": "Billing code modifiers, like U1.", "items": { "type": "string" }, "type": "array" }, "notes": { "description": "Free text; written, never returned.", "nullable": true, "type": "string" }, "par_number": { "description": "The prior authorization request (PAR) number.", "nullable": true, "type": "string" }, "payer": { "description": "Who pays for the service.", "enum": [ "medicaid", "private" ], "type": "string" }, "service_code": { "description": "The HCPCS code authorized, five letters and digits like T1019.", "nullable": false, "type": "string" }, "unit_type": { "description": "What one authorized unit is.", "enum": [ "hours", "visits" ], "type": "string" } }, "required": [ "payer", "service_code", "authorized_units", "unit_type", "effective_date", "end_date" ], "title": "ServiceAuthorizationRenewal", "type": "object" }, "ServiceAuthorizationUpdate": { "description": "Fields to change, plus the lock_version you read (required). Raising authorized_units needs the case manager's approval, sent with it: cm_authorization_reference and cm_authorized_on. Those two are recorded only with an increase: a changed value sent without one answers 422 validation_failed, and the stored value sent back unchanged is accepted.", "properties": { "authorized_units": { "description": "Units authorized. Raising it needs the case manager's approval, sent with it: cm_authorization_reference and cm_authorized_on.", "format": "decimal", "nullable": false, "type": "string" }, "cm_authorization_reference": { "description": "The case manager's approval reference; recorded only with a units increase, so a changed value (null included) is accepted only with one.", "nullable": true, "type": "string" }, "cm_authorized_on": { "description": "The day the case manager approved (YYYY-MM-DD); recorded only with a units increase, so a changed value (null included) is accepted only with one.", "format": "date", "nullable": true, "type": "string" }, "effective_date": { "description": "Effective date (YYYY-MM-DD).", "format": "date", "nullable": false, "type": "string" }, "end_date": { "description": "End date (YYYY-MM-DD).", "format": "date", "nullable": false, "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "modifiers": { "description": "Billing code modifiers, like U1.", "items": { "type": "string" }, "type": "array" }, "notes": { "description": "Free text; written, never returned.", "nullable": true, "type": "string" }, "par_number": { "description": "The prior authorization request (PAR) number.", "nullable": true, "type": "string" }, "payer": { "description": "Who pays for the service.", "enum": [ "medicaid", "private" ], "type": "string" }, "service_code": { "description": "The HCPCS code authorized, five letters and digits like T1019.", "nullable": false, "type": "string" }, "unit_type": { "description": "What one authorized unit is.", "enum": [ "hours", "visits" ], "type": "string" } }, "title": "ServiceAuthorizationUpdate", "type": "object" }, "ServiceRate": { "description": "What a billing code and modifiers pay per 15-minute unit, from effective_date to end_date. A rate the agency deletes is removed outright, and no list or sync reports it: a client keeping rates re-reads the whole list, which is short. The status filter reads end_date against today's date in Colorado: active is no end_date or one today or later, which includes a rate whose effective_date is still ahead; expired is an end_date before today. A rate expiring does not move its updated_at: sync without status and judge end_date yourself.", "properties": { "description": { "nullable": true, "type": "string", "x-untrusted": "text" }, "effective_date": { "format": "date", "nullable": true, "type": "string" }, "end_date": { "description": "The last day it applies; none while it is current.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the record was created.", "format": "date-time", "type": "string" }, "modifiers": { "description": "Billing code modifiers.", "items": { "type": "string" }, "type": "array" }, "procedure_code": { "description": "The HCPCS code.", "nullable": true, "type": "string" }, "rate_per_unit": { "description": "Dollars per 15-minute unit.", "format": "decimal", "nullable": true, "type": "string" }, "updated_at": { "description": "When the record last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "procedure_code", "rate_per_unit" ], "title": "ServiceRate", "type": "object" }, "ServiceRateCreate": { "description": "A new rate for one of the agency's billing codes and its modifiers, from effective_date. A rate with the same code, modifiers and effective_date as one the agency already has is refused, as is a rate_per_unit not greater than 0.", "properties": { "description": { "nullable": true, "type": "string", "x-untrusted": "text" }, "effective_date": { "format": "date", "nullable": false, "type": "string" }, "modifiers": { "description": "Billing code modifiers.", "items": { "type": "string" }, "type": "array" }, "procedure_code": { "description": "The HCPCS code.", "nullable": false, "type": "string" }, "rate_per_unit": { "description": "Dollars per 15-minute unit.", "format": "decimal", "nullable": false, "type": "string" } }, "required": [ "procedure_code", "modifiers", "rate_per_unit", "effective_date" ], "title": "ServiceRateCreate", "type": "object" }, "ServiceRateUpdate": { "description": "The rate fields to change. A service rate carries no lock_version: the change is applied to the rate as it is when the request arrives.", "properties": { "description": { "nullable": true, "type": "string", "x-untrusted": "text" }, "effective_date": { "format": "date", "nullable": false, "type": "string" }, "rate_per_unit": { "description": "Dollars per 15-minute unit.", "format": "decimal", "nullable": false, "type": "string" } }, "title": "ServiceRateUpdate", "type": "object" }, "SettingSecret": { "properties": { "key": { "description": "The credential's key.", "nullable": true, "type": "string" }, "value": { "description": "Its value; null when none is saved.", "nullable": true, "type": "string" } }, "required": [ "key", "value" ], "title": "SettingSecret", "type": "object" }, "ShiftPlan": { "properties": { "addable": { "description": "Per service, the state form's tasks the table does not hold: what Add task offers.", "properties": { "hm": { "items": { "type": "string" }, "type": "array" }, "pc": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "cards": { "items": { "description": "One shift and its Work Order.", "properties": { "after": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "nullable": true, "type": "string" }, "care_instructions": { "description": "The shift's Care Instructions.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "Its Work Order's caregiver.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_week": { "description": "The shift's caregiver's week across the agency's clients: this client's shifts as the screen times them, the others from their Work Orders.", "nullable": true, "properties": { "by_client": { "items": { "properties": { "client": { "type": "string" }, "minutes": { "description": "A week.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "caregiver": { "description": "Last, First.", "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "minutes": { "description": "Her minutes a week.", "nullable": true, "type": "integer" }, "visits": { "items": { "properties": { "client": { "description": "Last, First.", "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" }, "here": { "description": "A shift of this client's plan.", "type": "boolean" }, "minutes": { "description": "The visit's minutes.", "nullable": true, "type": "integer" }, "service": { "type": "string" }, "start": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "days": { "description": "Its columns in the agency's week order.", "items": { "properties": { "by_day": { "description": "It starts at a time of its own that day (shift_settings by_day).", "type": "boolean" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight it ends; past 1440 runs past midnight.", "nullable": true, "type": "integer" }, "label": { "type": "string" }, "minutes": { "description": "The minutes it holds that day.", "nullable": true, "type": "integer" }, "overlap": { "description": "It overlaps another shift that day.", "type": "boolean" }, "start": { "description": "Minutes after midnight the shift starts, null when off.", "nullable": true, "type": "integer" }, "working": { "description": "A day the service works.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "effective_date": { "description": "Its Work Order's Effective Date.", "format": "date", "nullable": true, "type": "string" }, "empty": { "description": "No visits fall on this shift.", "type": "boolean" }, "label": { "type": "string" }, "lock_version": { "description": "Its Work Order's lock_version, null before Generate.", "nullable": true, "type": "integer" }, "rows": { "items": { "properties": { "cells": { "items": { "properties": { "count": { "description": "The marks that day.", "nullable": true, "type": "integer" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "edited": { "description": "Differs from the layout; Undo puts it back.", "type": "boolean" }, "minutes": { "description": "The minutes they hold.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "in_plan": { "description": "One of the plan's tasks, so its cells can be changed.", "type": "boolean" }, "min_task": { "description": "Min / Task on this shift, as the printed Work Order writes it: the row's week over its visits, at most 2 places (40 + 35 is 37.5). Null with no marks.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "One visit's minutes.", "nullable": true, "type": "integer" }, "name": { "description": "What a cell change names as row.", "type": "string" }, "slug": { "type": "string" }, "times": { "description": "Times / Week: the row's marks on this shift. Null with no marks.", "nullable": true, "type": "integer" }, "week": { "description": "Week: the row's day minutes added on this shift. Null with no marks.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "shift_id": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "shift_number": { "description": "k of the service's shifts.", "nullable": true, "type": "integer" }, "work_order_id": { "description": "Its generated Work Order, null before Generate.", "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "caregivers": { "additionalProperties": { "description": "The caregiver's id.", "format": "uuid", "type": "string" }, "description": "Shift id => the caregiver picked for it, which Generate reads. A shift left out has none yet: it is planned and printable, and Generate makes it no Work Order.", "type": "object" }, "client_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "edited": { "description": "Some cell differs from the layout.", "type": "boolean" }, "hma": { "description": "The client's HMA calculator week, which the Shift Plan does not lay out: HMA stays on its Plan of Care. Null when the client has no current HMA plan with tasks.", "nullable": true, "properties": { "plan_id": { "description": "The HMA Plan of Care's id.", "format": "uuid", "type": "string" }, "weekly_minutes": { "description": "Its tasks' minutes a week.", "type": "integer" } }, "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "other_work_orders": { "description": "The client's live Work Orders made outside the Shift Plan, in force this month or later, by Effective Date (at most 50): the screen names them so the month is not made twice.", "items": { "properties": { "caregiver": { "description": "The Work Order's caregiver; null when it has none.", "nullable": true, "properties": { "first_name": { "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "nullable": true, "type": "string" } }, "type": "object" }, "closing_date": { "description": "Its Closing Date; null while it stays open.", "format": "date", "nullable": true, "type": "string" }, "effective_date": { "description": "Its Effective Date.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "number": { "description": "The Work Order's WO #.", "nullable": true, "type": "integer" }, "service": { "description": "The Work Order's service.", "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "shift_id": { "description": "The Shift Plan's shift that made it; only on a Work Order the plan made.", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } }, "required": [ "id", "number", "service", "caregiver", "effective_date", "closing_date" ], "title": "ShiftPlanWorkOrderLine", "type": "object" }, "type": "array" }, "overlaps": { "items": { "properties": { "a": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "b": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" } }, "type": "object" }, "type": "array" }, "print_problems": { "description": "What the screen asks to check before a print or Download Excel.", "items": { "type": "string" }, "type": "array" }, "services": { "properties": { "hm": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "settings": { "description": "days, shifts_per_day, shift_settings, gap_minutes, split_long_tasks, marks_mode, as PATCH takes them, task_overrides, the task table's edits, and care_instructions, shift id => text.", "type": "object" }, "task_table": { "items": { "properties": { "edited": { "description": "A figure differs from the Plan of Care's.", "type": "boolean" }, "fractional": { "description": "Min / task is not whole.", "type": "boolean" }, "max": { "description": "The state's weekly maximum, in minutes; null for a task it does not list.", "nullable": true, "type": "integer" }, "min_task": { "description": "Min / task.", "format": "decimal", "nullable": true, "type": "string" }, "min_week": { "description": "Min / week.", "format": "decimal", "nullable": true, "type": "string" }, "name": { "description": "What a task change names as task.", "type": "string" }, "norm": { "description": "The state's norm and weekly maximum, as the screen shows it under the task.", "nullable": true, "type": "string" }, "over_max": { "description": "Min / week is above the state's weekly maximum: needs justification and supervisor approval. Never a refusal.", "type": "boolean" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "split": { "description": "A split task: its visits and the minutes of each.", "nullable": true, "properties": { "minutes": { "description": "Each.", "nullable": true, "type": "integer" }, "visits": { "description": "Visits.", "nullable": true, "type": "integer" } }, "type": "object" }, "times": { "description": "Times / week.", "nullable": true, "type": "integer" }, "uneven": { "description": "Times / week was rounded.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "task_totals": { "properties": { "hm": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "warnings": { "description": "What the screen warns of; never a refusal.", "items": { "type": "string" }, "type": "array" } }, "title": "ShiftPlan", "type": "object" }, "ShiftPlanCareInstructions": { "properties": { "text": { "description": "The shift's Care Instructions, as the card's box takes them; blank or null removes them. At most the characters a Work Order's notes hold, else 422 too_long.", "nullable": true, "type": "string" } }, "required": [ "text" ], "title": "ShiftPlanCareInstructions", "type": "object" }, "ShiftPlanCaregiverSet": { "properties": { "caregiver_id": { "description": "The caregiver picked for the shift, any of the agency's on file, or null to let go of the pick.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "caregiver_id" ], "title": "ShiftPlanCaregiverSet", "type": "object" }, "ShiftPlanCellSet": { "properties": { "count": { "description": "The marks that day; the screen offers 0 to 8. The count the automatic layout gives that cell lets go of the change.", "minimum": 0, "type": "integer" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "row": { "description": "The row's name, as the card's rows name it (Bathing, Toileting).", "type": "string" }, "shift_id": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } }, "required": [ "shift_id", "day", "row", "count" ], "title": "ShiftPlanCellSet", "type": "object" }, "ShiftPlanGenerate": { "properties": { "caregivers": { "additionalProperties": { "description": "The caregiver's id.", "format": "uuid", "nullable": true, "type": "string" }, "description": "Optional: shift id => the caregiver for its Work Order, or null for none, each saved as the shift's pick as PUT /clients/{id}/shift-plan/caregivers/{shift_id} saves it. A shift left out takes its saved pick (the plan's caregivers); a shift with no caregiver gets no Work Order and keeps the one it has.", "type": "object" } }, "title": "ShiftPlanGenerate", "type": "object" }, "ShiftPlanSettingsUpdate": { "properties": { "days": { "description": "Optional: pc and/or hm => the service's working days; a service left out keeps its days.", "properties": { "hm": { "description": "The service's working days.", "items": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "type": "array" }, "pc": { "description": "The service's working days.", "items": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "type": "array" } }, "type": "object" }, "gap_minutes": { "description": "Optional: minutes between a shift and the one it starts after.", "minimum": 0, "type": "integer" }, "marks_mode": { "description": "Optional: the day cells as marks (x) or minutes.", "enum": [ "x", "minutes" ], "type": "string" }, "shift_settings": { "additionalProperties": { "properties": { "after": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "nullable": true, "type": "string" }, "by_day": { "additionalProperties": { "type": "string" }, "type": "object" }, "time": { "description": "HH:MM.", "type": "string" } }, "type": "object" }, "description": "Optional: shift id => the keys that change: time (HH:MM, its start), after (the shift it starts after, null for none), by_day (day => HH:MM, a start of its own that day). A key left out is kept.", "type": "object" }, "shifts_per_day": { "description": "Optional: pc and/or hm => shifts a day; a service left out keeps its count.", "properties": { "hm": { "description": "Shifts a day, 0 to 4.", "maximum": 4, "minimum": 0, "type": "integer" }, "pc": { "description": "Shifts a day, 0 to 4.", "maximum": 4, "minimum": 0, "type": "integer" } }, "type": "object" }, "split_long_tasks": { "description": "Optional: whether a long, rare task is split.", "type": "boolean" } }, "title": "ShiftPlanSettingsUpdate", "type": "object" }, "ShiftPlanTaskAdd": { "properties": { "service": { "description": "The task's service.", "enum": [ "homemaker", "personal_care" ], "type": "string" }, "task": { "description": "A task on the state form for that service, by its name (Dusting, Meal Prep/Menu Planning); the screen's Add task lists the ones the table does not hold.", "type": "string" } }, "required": [ "service", "task" ], "title": "ShiftPlanTaskAdd", "type": "object" }, "ShiftPlanTaskUpdate": { "properties": { "field": { "description": "The figure: times (Times / week), min_task (Min / task) or min_week (Min / week).", "enum": [ "min_task", "min_week", "times" ], "type": "string" }, "service": { "description": "The task's service.", "enum": [ "homemaker", "personal_care" ], "type": "string" }, "task": { "description": "The task, as the task table names it (Bathing).", "type": "string" }, "value": { "description": "Above 0; a whole number for times. Past a week answers 422 too_large.", "type": "number" } }, "required": [ "service", "task", "field", "value" ], "title": "ShiftPlanTaskUpdate", "type": "object" }, "ShiftPlanWorkOrderLine": { "properties": { "caregiver": { "description": "The Work Order's caregiver; null when it has none.", "nullable": true, "properties": { "first_name": { "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "nullable": true, "type": "string" } }, "type": "object" }, "closing_date": { "description": "Its Closing Date; null while it stays open.", "format": "date", "nullable": true, "type": "string" }, "effective_date": { "description": "Its Effective Date.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "number": { "description": "The Work Order's WO #.", "nullable": true, "type": "integer" }, "service": { "description": "The Work Order's service.", "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "shift_id": { "description": "The Shift Plan's shift that made it; only on a Work Order the plan made.", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } }, "required": [ "id", "number", "service", "caregiver", "effective_date", "closing_date" ], "title": "ShiftPlanWorkOrderLine", "type": "object" }, "SignWarning": { "properties": { "id": { "description": "The warning's stable id.", "type": "string" }, "question_key": { "description": "The record's question that fixes it, when one does.", "type": "string" }, "text": { "description": "What the signer is warned of.", "type": "string" } }, "required": [ "id", "text" ], "title": "SignWarning", "type": "object" }, "SignedRecordEvent": { "description": "One event of a signed record's history, oldest first: a signature, a signature voided, the true copy stored, an addendum, the record voided, or the record it replaces or that replaced it.", "properties": { "actor_name": { "description": "Who: the signer's name, the addendum's author, or the member who voided; null for a true copy or a replacement.", "nullable": true, "type": "string", "x-untrusted": "text" }, "at": { "description": "When it happened.", "format": "date-time", "type": "string" }, "body": { "description": "An addendum's text, in full.", "nullable": true, "type": "string", "x-untrusted": "text" }, "kind": { "description": "What happened.", "enum": [ "signed", "signature_voided", "true_copy_stored", "addendum", "voided", "replaces", "replaced_by" ], "type": "string" }, "link": { "description": "The path that opens what the event names: a true copy's PDF, an addendum's true copy, or the other record's page.", "nullable": true, "type": "string" }, "method": { "description": "How a signature was made, for signed: drawn, typed, pin and so on.", "nullable": true, "type": "string" }, "reason": { "description": "The reason given, for an addendum, a voided signature or a voided record.", "nullable": true, "type": "string", "x-untrusted": "text" }, "record_id": { "description": "For replaces and replaced_by: the other record.", "format": "uuid", "nullable": true, "type": "string" }, "role": { "description": "The signature's role, for signed and signature_voided: client, supervisor and so on.", "nullable": true, "type": "string" }, "signed_at": { "description": "When an addendum was signed.", "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "at", "kind" ], "title": "SignedRecordEvent", "type": "object" }, "SignedRecordEventPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/SignedRecordEvent" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "SignedRecordEventPage", "type": "object" }, "SignedRecordState": { "description": "Where a signed record stands: signed, amended (it has an addendum) or voided.", "properties": { "id": { "description": "The record.", "format": "uuid", "type": "string" }, "record_state": { "description": "The record's state.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "record_type": { "description": "supervisor_visit, plan_of_care, monthly_client_report, complaint, critical_incident, client_consent_form, client_emergency_info, care_log or half_month_summary.", "nullable": true, "type": "string" }, "signed_at": { "description": "When its first signature was made.", "format": "date-time", "nullable": true, "type": "string" }, "void_reason": { "description": "Why it was voided; null unless voided.", "nullable": true, "type": "string", "x-untrusted": "text" }, "voided_at": { "description": "When it was voided; null unless voided.", "format": "date-time", "nullable": true, "type": "string" }, "voided_by_user_id": { "description": "Who voided it; null unless voided.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "record_type", "record_state" ], "title": "SignedRecordState", "type": "object" }, "SignedRecordVoid": { "properties": { "reason": { "description": "Why the record is voided, 3 to 1000 characters. It is kept with the voided record.", "nullable": true, "type": "string" } }, "required": [ "reason" ], "title": "SignedRecordVoid", "type": "object" }, "Supervisory visitPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/SupervisoryVisit" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Supervisory visitPage", "type": "object" }, "SupervisoryVisit": { "description": "A supervisor's visit to a client's home to check on the caregiver's work. Recorded and edited here as a draft only; completing, signing and reopening happen on the visit page, where signatures are captured in person.", "properties": { "caregiver_id": { "description": "The caregiver observed.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_name": { "description": "The caregiver's name.", "nullable": true, "type": "string" }, "client_id": { "description": "The client visited.", "format": "uuid", "type": "string" }, "client_name": { "description": "The client's name.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the visit was recorded.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "missing_signers": { "description": "Each required line no live signature fills yet, in order; empty when complete or voided.", "items": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "type": "array" }, "questions": { "description": "The checklist.", "items": { "$ref": "#/components/schemas/QuestionAnswer" }, "type": "array" }, "record_state": { "description": "The signed record's state: draft until the first signature, then signed (locked), amended (an addendum was signed) or voided (replaced by a new draft). signing_complete says whether every required line is signed: the supervisor, the client, and the caregiver or PCP; a telehealth visit needs the supervisor alone.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "signatures": { "description": "The live signatures, oldest first, without their images.", "items": { "properties": { "method": { "description": "How it was signed: typed, drawn, initials, pin and so on.", "enum": [ "drawn", "initials", "typed", "pin", "voice", "docusign_agency", "docusign_platform", "paper_on_file", "imported" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "supervisor", "client", "caregiver", "pcp" ], "type": "string" }, "signed_at": { "description": "When the line was signed.", "format": "date-time", "type": "string" }, "signer_name": { "description": "The name the line is signed under.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "method", "signed_at" ], "title": "SupervisoryVisitSignature", "type": "object" }, "type": "array" }, "signed_at": { "description": "When the first signature locked it; null on a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signed_on_paper": { "description": "Whether the signed paper sheet is on file. A yes is recorded as a paper-on-file signature in each role the visit still needs, so it can sign the visit; read-only.", "type": "boolean" }, "signing_complete": { "description": "True once the record is signed or amended and every required line holds a signature. A signed record can be false: signed by one line, with another still open. A voided record is always false, whatever it holds, and its missing_signers is empty: nothing can sign it, and its replacement is the record to complete.", "type": "boolean" }, "status": { "description": "draft, completed or signed.", "enum": [ "draft", "completed", "signed" ], "type": "string" }, "supervisor_name": { "description": "Who conducted the visit; null or blank clears it.", "nullable": true, "type": "string" }, "updated_at": { "description": "When the visit last changed.", "format": "date-time", "type": "string" }, "visit_date": { "description": "The day of the visit; null or blank clears it.", "format": "date", "nullable": true, "type": "string" }, "visit_type": { "description": "In person (the default), or telehealth.", "enum": [ "in_person", "telehealth" ], "type": "string" } }, "required": [ "id", "client_id", "status" ], "title": "SupervisoryVisit", "type": "object" }, "SupervisoryVisitCreate": { "description": "Records a draft visit, conducted by the API key's user. client_id and caregiver_id are required. A telehealth visit needs agency_settings.manage and the agency's telehealth acknowledgment.", "properties": { "answers": { "additionalProperties": true, "description": "Checklist answers by question key, as the visit's own read lists its questions: a text or code (yes, no, na for a yes/no), a list of choices, or {value, comment}.", "type": "object" }, "caregiver_id": { "description": "The caregiver observed (their id).", "format": "uuid", "type": "string" }, "client_id": { "description": "The client visited (their id).", "format": "uuid", "type": "string" }, "supervisor_name": { "description": "Who conducted the visit; null or blank clears it.", "nullable": true, "type": "string" }, "visit_date": { "description": "The day of the visit; null or blank clears it.", "format": "date", "nullable": true, "type": "string" }, "visit_type": { "description": "In person (the default), or telehealth.", "enum": [ "in_person", "telehealth" ], "type": "string" } }, "required": [ "client_id", "caregiver_id" ], "title": "SupervisoryVisitCreate", "type": "object" }, "SupervisoryVisitDate": { "properties": { "date": { "description": "The visit's date, YYYY-MM-DD, or null to clear it; empty clears it too.", "format": "date", "nullable": true, "type": "string" } }, "title": "SupervisoryVisitDate", "type": "object" }, "SupervisoryVisitDue": { "description": "A client and when their last supervisory visit was, most urgent first.", "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "client_name": { "description": "The client's name.", "nullable": true, "type": "string" }, "due_status": { "description": "How urgent the next visit is.", "nullable": true, "type": "string" }, "last_visit_date": { "description": "The last visit; none if never visited.", "format": "date", "nullable": true, "type": "string" }, "planned_day": { "description": "The client's planned day of the month for the visit, null when none is planned; with planned_for, capped to that month's last day.", "nullable": true, "type": "integer" } }, "required": [ "client_id", "due_status" ], "title": "SupervisoryVisitDue", "type": "object" }, "SupervisoryVisitDuePage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/SupervisoryVisitDue" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "SupervisoryVisitDuePage", "type": "object" }, "SupervisoryVisitInput": { "description": "Fields to change on a draft visit, plus the lock_version read (required). answers maps a question key to a text or code (yes, no, na for a yes/no), a list of choices, or {value, comment}; a half not sent is kept, a half sent blank is cleared.", "properties": { "answers": { "additionalProperties": true, "description": "Checklist answers by question key, as the visit's own read lists its questions: a text or code (yes, no, na for a yes/no), a list of choices, or {value, comment}.", "type": "object" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "supervisor_name": { "description": "Who conducted the visit; null or blank clears it.", "nullable": true, "type": "string" }, "visit_date": { "description": "The day of the visit; null or blank clears it.", "format": "date", "nullable": true, "type": "string" }, "visit_type": { "description": "In person (the default), or telehealth.", "enum": [ "in_person", "telehealth" ], "type": "string" } }, "title": "SupervisoryVisitInput", "type": "object" }, "SupervisoryVisitReopen": { "properties": { "reason": { "description": "Why the visit is being corrected, 3 to 1000 characters; required once any line is signed, when the visit is voided and copied into a new draft.", "nullable": true, "type": "string" } }, "title": "SupervisoryVisitReopen", "type": "object" }, "SupervisoryVisitSignature": { "properties": { "method": { "description": "How it was signed: typed, drawn, initials, pin and so on.", "enum": [ "drawn", "initials", "typed", "pin", "voice", "docusign_agency", "docusign_platform", "paper_on_file", "imported" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "supervisor", "client", "caregiver", "pcp" ], "type": "string" }, "signed_at": { "description": "When the line was signed.", "format": "date-time", "type": "string" }, "signer_name": { "description": "The name the line is signed under.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "method", "signed_at" ], "title": "SupervisoryVisitSignature", "type": "object" }, "SupportTicket": { "description": "A request to the HomeCareBilling support team that the API key's user raised, and where it has got to. Support replies by email, quoting the reference.", "properties": { "category": { "enum": [ "general", "bug_report", "feature_request", "question" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the ticket was filed.", "format": "date-time", "type": "string" }, "priority": { "enum": [ "low", "normal", "high", "urgent" ], "type": "string" }, "reference": { "description": "The ticket's reference, e.g. #HCB-a1b2c3d4, as support's emails quote it.", "nullable": true, "type": "string" }, "resolution_notes": { "description": "What support did, once resolved.", "nullable": true, "type": "string" }, "resolved_at": { "description": "When the ticket was resolved.", "format": "date-time", "nullable": true, "type": "string" }, "sla_status": { "description": "Whether support is answering within its target.", "enum": [ "on_track", "at_risk", "breached", "met", "missed" ], "nullable": true, "type": "string" }, "status": { "description": "Where the ticket has got to.", "enum": [ "open", "in_progress", "waiting_on_user", "resolved", "closed" ], "type": "string" }, "subject": { "description": "The request's short summary.", "nullable": true, "type": "string" }, "updated_at": { "description": "When the ticket last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "reference", "subject", "status", "priority", "category" ], "title": "SupportTicket", "type": "object" }, "SupportTicketInput": { "description": "The request. subject, description, category and priority are required. For a bug report, fill screen, record_ids, steps_to_reproduce, expected and actual from what the user told you; a bug report missing what the server cannot work out from the user's recent activity is answered 422 needs_more_info, with the questions to ask and a follow_up_id to send back with the answers. A screenshot or any other field is not accepted and is ignored.", "properties": { "actual": { "description": "Bug reports: what happened instead, the error message shown or \"nothing\". \"don't know\" when they do not know.", "maxLength": 1000, "nullable": true, "type": "string" }, "category": { "description": "bug_report for something broken, feature_request for an idea, question for how to do something, general for anything else.", "enum": [ "general", "bug_report", "feature_request", "question" ], "type": "string" }, "description": { "description": "What happened, where in the app, and what was expected. Leave out client names and Medicaid IDs; support will ask if they need them.", "maxLength": 5000, "minLength": 20, "type": "string" }, "expected": { "description": "Bug reports: what the user expected to happen.", "maxLength": 1000, "nullable": true, "type": "string" }, "follow_up_id": { "description": "Only when answering a needs_more_info reply: the follow_up_id it gave. That call files the request whatever is still missing, and repeating it files no second one.", "format": "uuid", "nullable": true, "type": "string" }, "priority": { "description": "urgent only when it stops claims from being sent or paid, high when it gets in the way of daily work, normal for questions, low for ideas.", "enum": [ "low", "normal", "high", "urgent" ], "type": "string" }, "record_ids": { "description": "Bug reports: the ids of the records it happens on (from the page address), or [\"any\"] when it happens on any record, or [\"don't know\"]; a single string is read as a one-item list. Ids only, never names.", "items": { "type": "string" }, "maxItems": 10, "nullable": true, "type": "array" }, "screen": { "description": "Bug reports: the screen or feature the problem is on, e.g. Today, Needs attention, a client's page. \"don't know\" when the user does not know.", "maxLength": 200, "nullable": true, "type": "string" }, "steps_to_reproduce": { "description": "Bug reports: what the user clicked or tried, step by step. \"don't know\" when they do not know.", "maxLength": 2000, "nullable": true, "type": "string" }, "subject": { "description": "A short summary of the request.", "maxLength": 200, "type": "string" } }, "required": [ "subject", "description", "category", "priority" ], "title": "SupportTicketInput", "type": "object" }, "SupportTicketPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/SupportTicket" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "SupportTicketPage", "type": "object" }, "Task set templatePage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/TaskSetTemplate" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Task set templatePage", "type": "object" }, "TaskSetTemplate": { "description": "A reusable set of tasks with default minutes and visits a week. Editing one never changes a Work Order made from it.", "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the template was created.", "format": "date-time", "type": "string" }, "is_default": { "description": "Whether it is the agency's default template.", "type": "boolean" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "name": { "description": "The template's name, unique in the agency.", "nullable": true, "type": "string", "x-untrusted": "text" }, "service_type": { "description": "The service it is for.", "enum": [ "personal_care", "homemaker", "legacy" ], "type": "string" }, "tasks": { "description": "The tasks, each name once.", "items": { "properties": { "minutes_per_task": { "description": "Minutes each time.", "minimum": 0, "type": "integer" }, "task_category": { "description": "The service the task belongs to.", "enum": [ "personal_care", "homemaker" ], "type": "string" }, "task_name": { "description": "The task, as the Work Order names it.", "type": "string", "x-untrusted": "text" }, "times_per_week": { "description": "Visits a week.", "minimum": 0, "type": "integer" } }, "required": [ "task_name", "task_category", "minutes_per_task", "times_per_week" ], "type": "object" }, "type": "array" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "name", "service_type", "tasks", "lock_version" ], "title": "TaskSetTemplate", "type": "object" }, "TaskSetTemplateInput": { "description": "A task set template's fields. A tasks list sent replaces the template's tasks. A PATCH carries lock_version.", "properties": { "is_default": { "description": "Whether it is the agency's default template.", "type": "boolean" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "name": { "description": "The template's name, unique in the agency.", "nullable": false, "type": "string", "x-untrusted": "text" }, "service_type": { "description": "The service it is for.", "enum": [ "personal_care", "homemaker", "legacy" ], "type": "string" }, "tasks": { "description": "The tasks, each name once.", "items": { "properties": { "minutes_per_task": { "description": "Minutes each time.", "minimum": 0, "type": "integer" }, "task_category": { "description": "The service the task belongs to.", "enum": [ "personal_care", "homemaker" ], "type": "string" }, "task_name": { "description": "The task, as the Work Order names it.", "type": "string", "x-untrusted": "text" }, "times_per_week": { "description": "Visits a week.", "minimum": 0, "type": "integer" } }, "required": [ "task_name", "task_category", "minutes_per_task", "times_per_week" ], "type": "object" }, "type": "array" } }, "title": "TaskSetTemplateInput", "type": "object" }, "TelephonyCleared": { "properties": { "settings": { "properties": { "telephony_match_window_minutes": { "description": "Minutes a call may be from its visit, 1 to 480.", "nullable": true, "type": "string" }, "telephony_send_sms_confirmation": { "description": "SMS confirmation; unavailable for now.", "nullable": true, "type": "string" }, "twilio_account_sid": { "properties": { "masked": { "description": "Its last four characters, as ****1234; empty when none.", "nullable": true, "type": "string" }, "set": { "description": "Whether an Account SID is saved.", "type": "boolean" } }, "required": [ "set", "masked" ], "title": "AccountSidSet", "type": "object" }, "twilio_auth_token": { "properties": { "set": { "description": "Whether a value is saved; read it with the secrets operation.", "type": "boolean" } }, "required": [ "set" ], "title": "SecretSet", "type": "object" }, "twilio_phone_number": { "description": "The agency's own Twilio number, 10 digits.", "nullable": true, "type": "string" }, "twilio_record_calls": { "description": "Whether calls are recorded.", "enum": [ "true", "false" ], "nullable": true, "type": "string" } }, "required": [ "twilio_account_sid", "twilio_auth_token" ], "title": "TelephonySettings", "type": "object" }, "warnings": { "description": "Set when the old number's webhook could not be reset.", "items": { "type": "string" }, "type": "array" } }, "required": [ "settings", "warnings" ], "title": "TelephonyCleared", "type": "object" }, "TelephonyPinsAssigned": { "properties": { "assigned": { "description": "Caregivers given a PIN.", "nullable": true, "type": "integer" }, "incomplete": { "description": "Whether it stopped part way.", "type": "boolean" }, "reason": { "description": "Why it stopped: no free PIN left (exhausted), a refused audit row rolled back the next assignment (audit_log_failed; the ones before it were kept), or a caregiver changed during the run (stale).", "enum": [ "exhausted", "audit_log_failed", "stale" ], "nullable": true, "type": "string" } }, "required": [ "assigned" ], "title": "TelephonyPinsAssigned", "type": "object" }, "TelephonySave": { "properties": { "cleared": { "description": "True when every credential was blank, so it was cleared.", "type": "boolean" }, "settings": { "properties": { "telephony_match_window_minutes": { "description": "Minutes a call may be from its visit, 1 to 480.", "nullable": true, "type": "string" }, "telephony_send_sms_confirmation": { "description": "SMS confirmation; unavailable for now.", "nullable": true, "type": "string" }, "twilio_account_sid": { "properties": { "masked": { "description": "Its last four characters, as ****1234; empty when none.", "nullable": true, "type": "string" }, "set": { "description": "Whether an Account SID is saved.", "type": "boolean" } }, "required": [ "set", "masked" ], "title": "AccountSidSet", "type": "object" }, "twilio_auth_token": { "properties": { "set": { "description": "Whether a value is saved; read it with the secrets operation.", "type": "boolean" } }, "required": [ "set" ], "title": "SecretSet", "type": "object" }, "twilio_phone_number": { "description": "The agency's own Twilio number, 10 digits.", "nullable": true, "type": "string" }, "twilio_record_calls": { "description": "Whether calls are recorded.", "enum": [ "true", "false" ], "nullable": true, "type": "string" } }, "required": [ "twilio_account_sid", "twilio_auth_token" ], "title": "TelephonySettings", "type": "object" }, "warnings": { "description": "What went through but needs attention.", "items": { "type": "string" }, "type": "array" } }, "required": [ "settings", "warnings" ], "title": "TelephonySave", "type": "object" }, "TelephonySettings": { "properties": { "telephony_match_window_minutes": { "description": "Minutes a call may be from its visit, 1 to 480.", "nullable": true, "type": "string" }, "telephony_send_sms_confirmation": { "description": "SMS confirmation; unavailable for now.", "nullable": true, "type": "string" }, "twilio_account_sid": { "properties": { "masked": { "description": "Its last four characters, as ****1234; empty when none.", "nullable": true, "type": "string" }, "set": { "description": "Whether an Account SID is saved.", "type": "boolean" } }, "required": [ "set", "masked" ], "title": "AccountSidSet", "type": "object" }, "twilio_auth_token": { "properties": { "set": { "description": "Whether a value is saved; read it with the secrets operation.", "type": "boolean" } }, "required": [ "set" ], "title": "SecretSet", "type": "object" }, "twilio_phone_number": { "description": "The agency's own Twilio number, 10 digits.", "nullable": true, "type": "string" }, "twilio_record_calls": { "description": "Whether calls are recorded.", "enum": [ "true", "false" ], "nullable": true, "type": "string" } }, "required": [ "twilio_account_sid", "twilio_auth_token" ], "title": "TelephonySettings", "type": "object" }, "TelephonySettingsUpdate": { "properties": { "telephony_match_window_minutes": { "description": "Minutes, 1 to 480.", "nullable": true, "type": "string" }, "twilio_account_sid": { "description": "The Account SID; null or blank keeps the saved one.", "nullable": true, "type": "string" }, "twilio_auth_token": { "description": "The Auth Token; null or blank keeps the saved one.", "nullable": true, "type": "string" }, "twilio_phone_number": { "description": "The agency's Twilio number.", "nullable": true, "type": "string" }, "twilio_record_calls": { "description": "Whether calls are recorded.", "enum": [ "true", "false" ], "type": "string" } }, "title": "TelephonySettingsUpdate", "type": "object" }, "TelephonyTest": { "properties": { "twilio_account_sid": { "description": "The Account SID; null or blank keeps the saved one.", "nullable": true, "type": "string" }, "twilio_auth_token": { "description": "The Auth Token; null or blank keeps the saved one.", "nullable": true, "type": "string" }, "twilio_phone_number": { "description": "The agency's Twilio number.", "nullable": true, "type": "string" } }, "title": "TelephonyTest", "type": "object" }, "TelephonyTested": { "properties": { "owns_number": { "description": "Always true.", "type": "boolean" } }, "required": [ "owns_number" ], "title": "TelephonyTested", "type": "object" }, "Timesheet": { "description": "The hours worked for one client and caregiver in one billing period.", "properties": { "assignment_id": { "description": "The assignment it bills under.", "format": "uuid", "type": "string" }, "billing_period_end": { "format": "date", "nullable": true, "type": "string" }, "billing_period_start": { "format": "date", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver who worked.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client served.", "format": "uuid", "type": "string" }, "deleted_at": { "description": "Set when the agency deleted the record. Only a list with include_deleted=true returns deleted records.", "format": "date-time", "nullable": true, "type": "string" }, "entries": { "description": "The dated hours, one per visit, as they are now. An entry can change without moving this record's updated_at; re-read the record by id to have them current.", "items": { "properties": { "date": { "format": "date", "nullable": true, "type": "string" }, "hours_worked": { "description": "Hours worked that day.", "format": "decimal", "nullable": true, "type": "string" }, "time_in": { "description": "HH:MM:SS, local time.", "nullable": true, "type": "string" }, "time_out": { "description": "HH:MM:SS, local time.", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "first_half_hours": { "description": "Hours, days 1 to 15.", "format": "decimal", "nullable": true, "type": "string" }, "half_signature_sources": { "description": "Where each half's signatures come from (US-101.25, US-119.10, US-119.14): a signed half-month summary whose attested hours agree with what the Timesheets bill (summary, its id), one whose hours differ by a quarter hour or more on the days listed (hours_differ, its id and the days; not counted as signed), the same summary signed by this Timesheet's own Work Order's paper card (paper, its id), one signed by the paper card of another Work Order of the client and caregiver (paper_elsewhere, its id and that Work Order's number; not counted as signed), another card's rows written when this Timesheet was returned for correction, counted as signed until its submit refreshes them from the corrected entries (paper_refresh, its id; US-119.16), or neither (missing). Not who signed or when.", "properties": { "first": { "description": "Days 1 to 15.", "enum": [ "summary", "hours_differ", "paper", "paper_elsewhere", "paper_refresh", "missing" ], "type": "string" }, "first_hours_differ_days": { "description": "For hours_differ: the dates of days 1 to 15 whose billed hours differ from the summary's by a quarter hour or more; null otherwise.", "items": { "format": "date", "type": "string" }, "nullable": true, "type": "array" }, "first_paper_work_order_number": { "description": "For paper_elsewhere: the number of the Work Order whose paper card signs days 1 to 15; null otherwise.", "nullable": true, "type": "string" }, "first_summary_id": { "description": "The half-month summary that signs days 1 to 15.", "format": "uuid", "nullable": true, "type": "string" }, "second": { "description": "Day 16 on.", "enum": [ "summary", "hours_differ", "paper", "paper_elsewhere", "paper_refresh", "missing" ], "type": "string" }, "second_hours_differ_days": { "description": "For hours_differ: the dates of day 16 on whose billed hours differ from the summary's by a quarter hour or more; null otherwise.", "items": { "format": "date", "type": "string" }, "nullable": true, "type": "array" }, "second_paper_work_order_number": { "description": "For paper_elsewhere: the number of the Work Order whose paper card signs day 16 on; null otherwise.", "nullable": true, "type": "string" }, "second_summary_id": { "description": "The half-month summary that signs day 16 on.", "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the record was created.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "second_half_hours": { "description": "Hours, day 16 on.", "format": "decimal", "nullable": true, "type": "string" }, "status": { "enum": [ "draft", "submitted", "approved", "rejected", "exported" ], "type": "string" }, "total_hours": { "description": "Hours in the billing period.", "format": "decimal", "nullable": true, "type": "string" }, "updated_at": { "description": "When the record last changed, its hours included.", "format": "date-time", "type": "string" }, "wo_number": { "description": "The WO # of the work order it was made from, as the pages show it, or the number imported as text when it names no Work Order; null when it names none.", "nullable": true, "type": "string", "x-untrusted": "text" }, "work_order_id": { "description": "The work order it was made from; null when it names none in this agency.", "format": "uuid", "nullable": true, "type": "string" }, "work_order_number": { "description": "The stored link to the work order it was made from: the Work Order's id, or a number imported as text. Read wo_number and work_order_id instead.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "id", "client_id", "caregiver_id", "status", "lock_version" ], "title": "Timesheet", "type": "object" }, "TimesheetCreate": { "properties": { "month": { "description": "The month, 1 to 12.", "maximum": 12, "minimum": 1, "type": "integer" }, "year": { "description": "The year.", "maximum": 2100, "minimum": 2020, "type": "integer" } }, "required": [ "year", "month" ], "title": "TimesheetCreate", "type": "object" }, "TimesheetEntry": { "properties": { "date": { "format": "date", "nullable": true, "type": "string" }, "day_of_week": { "nullable": true, "type": "string" }, "deviation_explanation": { "nullable": true, "type": "string" }, "evv_clock_in": { "description": "The EVV clock-in pulled from the matched visit.", "format": "date-time", "type": "string" }, "evv_clock_out": { "description": "The EVV clock-out pulled from the matched visit.", "format": "date-time", "type": "string" }, "evv_source": { "nullable": true, "type": "string" }, "hours_worked": { "description": "Hours that day.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "time_in": { "description": "HH:MM:SS.", "nullable": true, "type": "string" }, "time_out": { "description": "HH:MM:SS.", "nullable": true, "type": "string" }, "timesheet_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "travel_time": { "type": "boolean" }, "visit_id": { "description": "The EVV visit the times were pulled from.", "format": "uuid", "type": "string" } }, "title": "TimesheetEntry", "type": "object" }, "TimesheetEntryCreate": { "properties": { "date": { "description": "The date, YYYY-MM-DD.", "format": "date", "type": "string" }, "deviation_explanation": { "description": "Why the times deviate from the plan; null or blank clears it.", "nullable": true, "type": "string" }, "time_in": { "description": "HH:MM:SS; null or blank clears it.", "nullable": true, "type": "string" }, "time_out": { "description": "HH:MM:SS; null or blank clears it.", "nullable": true, "type": "string" }, "travel_time": { "description": "Whether the entry is travel time.", "type": "boolean" } }, "required": [ "date" ], "title": "TimesheetEntryCreate", "type": "object" }, "TimesheetEntryUpdate": { "properties": { "date": { "description": "The date, YYYY-MM-DD.", "format": "date", "type": "string" }, "deviation_explanation": { "description": "Why the times deviate from the plan; null or blank clears it.", "nullable": true, "type": "string" }, "time_in": { "description": "HH:MM:SS; null or blank clears it.", "nullable": true, "type": "string" }, "time_out": { "description": "HH:MM:SS; null or blank clears it.", "nullable": true, "type": "string" }, "travel_time": { "description": "Whether the entry is travel time.", "type": "boolean" } }, "title": "TimesheetEntryUpdate", "type": "object" }, "TimesheetPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Timesheet" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "TimesheetPage", "type": "object" }, "TimesheetReject": { "properties": { "reason": { "description": "Why it is rejected.", "type": "string" } }, "required": [ "reason" ], "title": "TimesheetReject", "type": "object" }, "TimesheetSign": { "properties": { "client_name": { "description": "The client's name, for a client slot.", "nullable": true, "type": "string" }, "resign": { "description": "Re-sign a signed slot (needs signed_records.void).", "type": "boolean" }, "signature_type": { "description": "The slot to sign.", "enum": [ "caregiver_first_half", "client_first_half", "caregiver_second_half", "client_second_half" ], "type": "string" } }, "required": [ "signature_type" ], "title": "TimesheetSign", "type": "object" }, "TimesheetSubmit": { "properties": { "acknowledge_missing_signatures": { "description": "Submit with signatures missing.", "type": "boolean" } }, "title": "TimesheetSubmit", "type": "object" }, "TimesheetTask": { "properties": { "completed": { "type": "boolean" }, "frequency": { "description": "Times done.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "notes": { "nullable": true, "type": "string" }, "task_category": { "nullable": true, "type": "string" }, "task_name": { "nullable": true, "type": "string" }, "time_minutes": { "description": "Minutes spent.", "nullable": true, "type": "integer" }, "timesheet_entry_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "title": "TimesheetTask", "type": "object" }, "TimesheetTaskCreate": { "properties": { "completed": { "description": "Whether the task was done.", "type": "boolean" }, "frequency": { "description": "Times done.", "nullable": true, "type": "integer" }, "notes": { "description": "Notes on the task; null or blank clears them.", "nullable": true, "type": "string" }, "task_name": { "description": "HCPF's task name.", "type": "string" }, "time_minutes": { "description": "Minutes spent.", "nullable": true, "type": "integer" }, "timesheet_entry_id": { "description": "The entry the task was done on.", "format": "uuid", "type": "string" } }, "required": [ "timesheet_entry_id", "task_name" ], "title": "TimesheetTaskCreate", "type": "object" }, "TimesheetTaskUpdate": { "properties": { "completed": { "description": "Whether the task was done.", "type": "boolean" }, "frequency": { "description": "Times done.", "nullable": true, "type": "integer" }, "notes": { "description": "Notes on the task; null or blank clears them.", "nullable": true, "type": "string" }, "time_minutes": { "description": "Minutes spent.", "nullable": true, "type": "integer" } }, "title": "TimesheetTaskUpdate", "type": "object" }, "TpidAuthorization": { "properties": { "tpid_authorized": { "description": "Whether the agency confirmed its Trading Partner authorization.", "type": "boolean" } }, "required": [ "tpid_authorized" ], "title": "TpidAuthorization", "type": "object" }, "TpidAuthorizationUpdate": { "properties": { "authorized": { "description": "Whether the agency authorized HomeCareBilling as its Trading Partner: confirmed (true) or not (false).", "type": "boolean" } }, "required": [ "authorized" ], "title": "TpidAuthorizationUpdate", "type": "object" }, "TrainingBulkCompletion": { "properties": { "completed_date": { "description": "The completion date, YYYY-MM-DD; its year is the training year.", "format": "date", "type": "string" }, "replace": { "description": "Also move dates already recorded.", "type": "boolean" } }, "required": [ "completed_date" ], "title": "TrainingBulkCompletion", "type": "object" }, "TwoFactorReset": { "properties": { "two_factor_enabled": { "description": "Always false once reset.", "type": "boolean" }, "user_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "required": [ "user_id", "two_factor_enabled" ], "title": "TwoFactorReset", "type": "object" }, "Underpayment": { "description": "A paid claim HCPF paid less than its published rate says, after the adjustments that lawfully explain short pay (deductible, coinsurance, copay, prior payer, patient liability). It blocks nothing. Dismiss it with POST /api/v1/revenue-warnings/dismissals, sending kind underpayment, its claim_id as subject_id, and its fingerprint; a dismissed row whose paid amount changes is listed again.", "properties": { "carcs": { "items": { "properties": { "amount": { "description": "The amount the remittance adjusted for this reason.", "format": "decimal", "nullable": true, "type": "string" }, "description": { "description": "What the code means, in plain English.", "type": "string" }, "group_code": { "description": "The CARC group: CO, PR, OA or PI.", "nullable": true, "type": "string" }, "reason_code": { "description": "The CARC reason code.", "type": "string" } }, "required": [ "group_code", "reason_code", "amount", "description" ], "title": "UnderpaymentAdjustment", "type": "object" }, "type": "array" }, "claim_id": { "description": "The underpaid claim.", "format": "uuid", "type": "string" }, "client_id": { "description": "The record's id.", "format": "uuid", "nullable": true, "type": "string" }, "dismissed": { "description": "Whether a member dismissed it at these amounts.", "type": "boolean" }, "expected": { "description": "The lesser of the charge and the published rate times the units.", "format": "decimal", "nullable": true, "type": "string" }, "fingerprint": { "description": "The expected and paid amounts, joined with a colon.", "type": "string" }, "gap": { "description": "How much less HCPF paid than expected, after explained adjustments.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The claim's id, as claim_id.", "format": "uuid", "type": "string" }, "kind": { "description": "Always underpayment: the kind to dismiss it as.", "type": "string" }, "modifiers": { "items": { "type": "string" }, "type": "array" }, "paid": { "description": "What HCPF paid.", "format": "decimal", "nullable": true, "type": "string" }, "paid_date": { "description": "When the remittance paid it.", "format": "date", "nullable": true, "type": "string" }, "procedure_code": { "description": "The HCPCS code billed.", "type": "string" }, "published_rate": { "description": "HCPF's published rate per unit on the dates of service.", "format": "decimal", "nullable": true, "type": "string" }, "service_date_from": { "description": "The first date of service.", "format": "date", "nullable": true, "type": "string" }, "service_date_to": { "description": "The last date of service.", "format": "date", "nullable": true, "type": "string" }, "tenant_rate": { "description": "The agency's own rate per unit the claim was billed at; null for a claim from a spreadsheet upload. Shown only: the expected amount never uses it.", "format": "decimal", "nullable": true, "type": "string" }, "units": { "description": "Units billed.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "id", "claim_id", "client_id", "service_date_from", "service_date_to", "paid_date", "procedure_code", "modifiers", "units", "published_rate", "tenant_rate", "expected", "paid", "gap", "carcs", "kind", "fingerprint", "dismissed" ], "title": "Underpayment", "type": "object" }, "UnderpaymentAdjustment": { "properties": { "amount": { "description": "The amount the remittance adjusted for this reason.", "format": "decimal", "nullable": true, "type": "string" }, "description": { "description": "What the code means, in plain English.", "type": "string" }, "group_code": { "description": "The CARC group: CO, PR, OA or PI.", "nullable": true, "type": "string" }, "reason_code": { "description": "The CARC reason code.", "type": "string" } }, "required": [ "group_code", "reason_code", "amount", "description" ], "title": "UnderpaymentAdjustment", "type": "object" }, "UnderpaymentPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Underpayment" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "paid_from": { "description": "The first paid date read.", "format": "date", "nullable": true, "type": "string" }, "paid_to": { "description": "The last paid date read.", "format": "date", "nullable": true, "type": "string" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" }, "total_gap": { "description": "The sum of every listed row's gap, not just this page's.", "format": "decimal", "nullable": true, "type": "string" }, "truncated": { "description": "True when the period held more paid claims than one read judges (5000): only the newest-paid were judged. Narrow the dates to see the rest.", "type": "boolean" } }, "required": [ "data", "limit", "offset", "total", "total_gap", "truncated", "paid_from", "paid_to" ], "title": "UnderpaymentPage", "type": "object" }, "UniversityVideo": { "description": "A narrated HCB University video of a job in the app, recorded on the demo agency, so it holds no agency's data.", "properties": { "duration_ms": { "description": "The English render's length in milliseconds.", "type": "integer" }, "locales": { "description": "The languages the video has a render in, e.g. [\"en\"].", "items": { "type": "string" }, "type": "array" }, "section": { "description": "The catalog section, e.g. billing or clients.", "type": "string" }, "slug": { "description": "The video's id, as GET /university/videos/{slug} takes it.", "type": "string" }, "summary": { "description": "One or two sentences on what the video shows.", "nullable": true, "type": "string" }, "title": { "description": "The video's title.", "type": "string" }, "url": { "description": "The video's player page in HomeCareBilling; it asks the viewer to sign in.", "format": "uri", "type": "string" } }, "required": [ "slug", "section", "title", "summary", "duration_ms", "locales", "url" ], "title": "UniversityVideo", "type": "object" }, "UniversityVideoDetail": { "description": "An HCB University video with its chapters, and the video, captions and poster of each rendered language as signed URLs to play or show directly.", "properties": { "chapters": { "description": "The English render's chapters, in order.", "items": { "properties": { "start_ms": { "description": "Where it starts, in milliseconds.", "type": "integer" }, "title": { "description": "The chapter's title.", "type": "string" } }, "required": [ "title", "start_ms" ], "type": "object" }, "type": "array" }, "duration_ms": { "description": "The English render's length in milliseconds.", "type": "integer" }, "locales": { "description": "The languages the video has a render in, e.g. [\"en\"].", "items": { "type": "string" }, "type": "array" }, "pages": { "description": "The app pages the video shows, e.g. [\"/batches\"].", "items": { "type": "string" }, "type": "array" }, "renders": { "description": "One per rendered language, in language order.", "items": { "properties": { "captions_url": { "description": "The WebVTT captions. A signed storage URL that works for 6 hours; null when it could not be signed.", "nullable": true, "type": "string" }, "locale": { "description": "The language, e.g. en.", "type": "string" }, "poster_url": { "description": "The poster image (JPEG). A signed storage URL that works for 6 hours; null when it could not be signed.", "nullable": true, "type": "string" }, "render_id": { "description": "The render's id.", "type": "string" }, "video_url": { "description": "The MP4. A signed storage URL that works for 6 hours; null when it could not be signed.", "nullable": true, "type": "string" } }, "required": [ "locale", "render_id", "video_url", "captions_url", "poster_url" ], "type": "object" }, "type": "array" }, "section": { "description": "The catalog section, e.g. billing or clients.", "type": "string" }, "slug": { "description": "The video's id, as GET /university/videos/{slug} takes it.", "type": "string" }, "summary": { "description": "One or two sentences on what the video shows.", "nullable": true, "type": "string" }, "title": { "description": "The video's title.", "type": "string" }, "url": { "description": "The video's player page in HomeCareBilling; it asks the viewer to sign in.", "format": "uri", "type": "string" } }, "required": [ "slug", "section", "title", "summary", "duration_ms", "locales", "url", "pages", "chapters", "renders" ], "title": "UniversityVideoDetail", "type": "object" }, "UniversityVideoPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/UniversityVideo" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "UniversityVideoPage", "type": "object" }, "UnmatchedCall": { "properties": { "call_assignment": { "description": "A clock-in or clock-out.", "enum": [ "time_in", "time_out" ], "nullable": true, "type": "string" }, "call_datetime": { "description": "When the call came in (UTC).", "format": "date-time", "type": "string" }, "caregiver_id": { "description": "The record's id.", "format": "uuid", "nullable": true, "type": "string" }, "chosen_visit_id": { "description": "The record's id.", "format": "uuid", "nullable": true, "type": "string" }, "dismiss_reason": { "description": "Why the office dismissed it.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the server kept it (UTC).", "format": "date-time", "type": "string" }, "matched_visit_id": { "description": "The record's id.", "format": "uuid", "nullable": true, "type": "string" }, "originating_phone_last4": { "description": "The calling number's last four digits; the rest is masked.", "nullable": true, "type": "string" }, "reason": { "description": "Why it was kept: no_matching_visit or outside_window (no visit to clock), or, when the visit the caregiver chose refused it once locked (chosen_visit_id), visit_closed, visit_reassigned, visit_already_clocked, no_clock_in or not_recorded.", "nullable": true, "type": "string" }, "reviewed_at": { "description": "When the office matched or dismissed it (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "status": { "description": "pending, matched or dismissed.", "enum": [ "pending", "matched", "dismissed" ], "type": "string" } }, "required": [ "id", "call_datetime", "status" ], "title": "UnmatchedCall", "type": "object" }, "UnmatchedCallDismiss": { "properties": { "reason": { "description": "Why it is dismissed: 10 to 500 characters, as on the screen.", "maxLength": 500, "minLength": 10, "type": "string" } }, "required": [ "reason" ], "title": "UnmatchedCallDismiss", "type": "object" }, "UnmatchedCallMatch": { "properties": { "visit_id": { "description": "The visit the call clocked.", "format": "uuid", "type": "string" } }, "required": [ "visit_id" ], "title": "UnmatchedCallMatch", "type": "object" }, "UnmatchedCallPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/UnmatchedCall" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "UnmatchedCallPage", "type": "object" }, "VaccinationBulkEntry": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "notes": { "description": "Notes.", "nullable": true, "type": "string" }, "status": { "enum": [ "vaccinated", "declined_medical", "declined_other", "unknown" ], "type": "string" }, "vaccination_date": { "description": "When vaccinated.", "format": "date", "nullable": true, "type": "string" } }, "required": [ "caregiver_id", "status" ], "title": "VaccinationBulkEntry", "type": "object" }, "VaccinationBulkResult": { "properties": { "updated": { "description": "Vaccination records written.", "nullable": true, "type": "integer" } }, "required": [ "updated" ], "title": "VaccinationBulkResult", "type": "object" }, "VaccinationBulkUpdate": { "properties": { "updates": { "description": "One per caregiver: {caregiver_id, status, vaccination_date, notes}.", "items": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "notes": { "description": "Notes.", "nullable": true, "type": "string" }, "status": { "enum": [ "vaccinated", "declined_medical", "declined_other", "unknown" ], "type": "string" }, "vaccination_date": { "description": "When vaccinated.", "format": "date", "nullable": true, "type": "string" } }, "required": [ "caregiver_id", "status" ], "title": "VaccinationBulkEntry", "type": "object" }, "type": "array" }, "year": { "description": "The flu season's year.", "type": "integer" } }, "required": [ "year", "updates" ], "title": "VaccinationBulkUpdate", "type": "object" }, "Visit": { "properties": { "actual_end_time": { "description": "When the caregiver clocked out (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "actual_start_time": { "description": "When the caregiver clocked in (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "adjusted_end_time": { "description": "The agency's corrected end, when it changed the clocked one (UTC); written with its UTC offset, refused without one (422 time_offset_required).", "format": "date-time", "nullable": true, "type": "string" }, "adjusted_start_time": { "description": "The agency's corrected start, when it changed the clocked one (UTC); written with its UTC offset, refused without one (422 time_offset_required).", "format": "date-time", "nullable": true, "type": "string" }, "alternate_location": { "description": "Whether the service was given away from the client's home address.", "type": "boolean" }, "assignment_id": { "description": "The assignment the visit came from, if any.", "format": "uuid", "nullable": true, "type": "string" }, "billable_hours": { "description": "Hours the visit bills.", "format": "decimal", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver who served.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client served.", "format": "uuid", "type": "string" }, "client_signature_captured": { "description": "Whether the client signed for the visit.", "type": "boolean" }, "deleted_at": { "description": "Set when the agency deleted the record. Only a list with include_deleted=true returns deleted records.", "format": "date-time", "nullable": true, "type": "string" }, "group_identifier": { "description": "For a group visit, the caregiver's name for the group session.", "nullable": true, "type": "string", "x-untrusted": "text" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "import_external_id": { "description": "For an imported visit, that system's id for it (Sandata's Visit ID); else null.", "nullable": true, "type": "string", "x-untrusted": "text" }, "import_system": { "description": "For an imported visit, the system it was imported from; else null.", "enum": [ "sandata" ], "nullable": true, "type": "string" }, "inserted_at": { "description": "When the visit was created.", "format": "date-time", "type": "string" }, "location_verified": { "description": "Whether the clock-in was inside the client's geofence.", "type": "boolean" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "memo": { "description": "The agency's note on the visit.", "nullable": true, "type": "string", "x-untrusted": "text" }, "modifiers": { "description": "The procedure modifiers.", "items": { "type": "string" }, "type": "array" }, "payable_hours": { "description": "Hours the visit pays the caregiver.", "format": "decimal", "nullable": true, "type": "string" }, "procedure_code": { "description": "The HCPCS code.", "nullable": true, "type": "string" }, "sandata_sent_at": { "description": "When Sandata first took the visit.", "format": "date-time", "nullable": true, "type": "string" }, "sandata_submission_status": { "description": "Where the visit is in the Sandata queue.", "enum": [ "pending", "submitted", "accepted", "rejected", "resubmitted" ], "nullable": true, "type": "string" }, "sandata_visit_id": { "description": "Sandata's id for the visit, once Sandata has it.", "nullable": true, "type": "string" }, "scheduled_end_time": { "description": "Scheduled end (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "scheduled_start_time": { "description": "Scheduled start (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "service_date": { "description": "The day of service.", "format": "date", "nullable": true, "type": "string" }, "source": { "description": "How the visit was created; import is an EVV vendor's record of a shift, read-only, beside the agency's own visit for it.", "enum": [ "schedule", "manual", "api", "import" ], "type": "string" }, "status": { "description": "Where the visit is in its lifecycle.", "enum": [ "scheduled", "in_progress", "completed", "verified", "submitted", "matched", "rejected", "cancelled" ], "type": "string" }, "updated_at": { "description": "When the visit last changed.", "format": "date-time", "type": "string" }, "visit_type": { "enum": [ "standard", "group", "live_in", "respite", "companion", "travel" ], "type": "string" } }, "required": [ "id", "client_id", "caregiver_id", "service_date", "status", "lock_version" ], "title": "Visit", "type": "object" }, "Visit exceptionPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/VisitException" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Visit exceptionPage", "type": "object" }, "VisitBulkTransition": { "properties": { "cancellation_note": { "description": "A note on the cancellation (a cancel only, up to 1000 characters); needs a cancellation_reason.", "maxLength": 1000, "type": "string" }, "cancellation_reason": { "description": "Why the visit is cancelled (a cancel only), from the web's pick list: caregiver_call_off (Caregiver called off), client_cancelled (Client cancelled (don't come)), client_hospitalized (Client in hospital or facility), client_unavailable (Client not home or unavailable), schedule_change (Schedule changed), weather_emergency (Weather or emergency), entered_in_error (Entered in error or duplicate), other (Other). Optional; a cancel without one records no reason.", "enum": [ "caregiver_call_off", "client_cancelled", "client_hospitalized", "client_unavailable", "schedule_change", "weather_emergency", "entered_in_error", "other" ], "type": "string" }, "ids": { "description": "The visits to move, at most 100.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "ids" ], "title": "VisitBulkTransition", "type": "object" }, "VisitBulkTransitionResult": { "properties": { "failed": { "description": "Not moved: not_found (not this agency's visit), invalid_transition (its status cannot move there), exception_not_dismissed (a cancel whose open exception could not be dismissed), imported_visit (a visit imported from another EVV system, US-101.9, which is read-only here) or error (the write failed; retrying is safe).", "items": { "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reason": { "description": "Why.", "enum": [ "not_found", "invalid_transition", "exception_not_dismissed", "imported_visit", "error" ], "type": "string" } }, "required": [ "id", "reason" ], "type": "object" }, "type": "array" }, "succeeded_ids": { "description": "Moved now.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "type": "array" } }, "required": [ "succeeded_ids", "failed" ], "title": "VisitBulkTransitionResult", "type": "object" }, "VisitCall": { "description": "A clock event: the caregiver's app, a phone call (IVR) or a manual entry. Calls are never edited; a correction is a change.", "properties": { "call_assignment": { "description": "What the call recorded.", "enum": [ "time_in", "time_out", "other" ], "type": "string" }, "call_datetime": { "description": "When the call was made (UTC).", "format": "date-time", "type": "string" }, "call_type": { "description": "How the call was made.", "enum": [ "mobile", "telephony", "fvv", "manual", "other" ], "type": "string" }, "device_id": { "description": "The device that made the call.", "nullable": true, "type": "string", "x-untrusted": "text" }, "gps_accuracy_meters": { "nullable": true, "type": "number" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "latitude": { "description": "Where the device was.", "format": "decimal", "nullable": true, "type": "string" }, "location_description": { "description": "GPS warnings recorded with the call, such as outside the geofence.", "nullable": true, "type": "string" }, "longitude": { "description": "Where the device was.", "format": "decimal", "nullable": true, "type": "string" }, "superseded_at": { "description": "Set when the visit was reassigned away from the caregiver who made the call: the call stays as history and no longer counts as the visit's clock.", "format": "date-time", "nullable": true, "type": "string" } }, "title": "VisitCall", "type": "object" }, "VisitChange": { "description": "A correction the agency made to the visit, with Colorado's reason code.", "properties": { "change_datetime": { "description": "When it changed (UTC).", "format": "date-time", "type": "string" }, "change_source": { "description": "Where the change was made.", "enum": [ "agency_portal", "api", "system", "bulk_action" ], "type": "string" }, "changed_by_id": { "description": "The user who made it.", "format": "uuid", "nullable": true, "type": "string" }, "field_changed": { "description": "The field that changed.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "new_value": { "nullable": true, "type": "object" }, "old_value": { "nullable": true, "type": "object" }, "reason_code": { "description": "Why it changed: Colorado's reason code, such as CLKIN, CLKOUT, SCHED or OTHER.", "nullable": true, "type": "string" }, "reason_memo": { "nullable": true, "type": "string", "x-untrusted": "text" }, "resolution_code": { "nullable": true, "type": "string" } }, "title": "VisitChange", "type": "object" }, "VisitCreate": { "description": "A new scheduled visit. Its service date is the scheduled start's day in Mountain time. The client, caregiver and assignment must be this agency's, the assignment for that client and caregiver. A visit overlapping the caregiver's others, on an assignment no longer open, or with a window over 24 hours is created with a warning; a window over 31 days is refused.", "properties": { "alternate_location": { "description": "Whether the service was given away from the client's home address.", "type": "boolean" }, "assignment_id": { "description": "The assignment the visit comes from, if any.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver serving.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client served.", "format": "uuid", "type": "string" }, "group_identifier": { "description": "For a group visit, the caregiver's name for the group session.", "nullable": true, "type": "string", "x-untrusted": "text" }, "memo": { "description": "The agency's note on the visit.", "nullable": true, "type": "string", "x-untrusted": "text" }, "modifiers": { "description": "The procedure modifiers.", "items": { "type": "string" }, "type": "array" }, "procedure_code": { "description": "The HCPCS code.", "nullable": true, "type": "string" }, "scheduled_end_time": { "description": "Scheduled end, with its UTC offset; refused without one, as the start.", "format": "date-time", "type": "string" }, "scheduled_start_time": { "description": "Scheduled start, with its UTC offset (Z or -06:00); one without is refused (422 time_offset_required), as is a value that is not a time (422 invalid_time).", "format": "date-time", "type": "string" }, "visit_type": { "enum": [ "standard", "group", "live_in", "respite", "companion", "travel" ], "type": "string" } }, "required": [ "client_id", "caregiver_id", "scheduled_start_time", "scheduled_end_time" ], "title": "VisitCreate", "type": "object" }, "VisitDeleteLinks": { "properties": { "timesheet_entries": { "description": "Timesheet entries whose EVV times were pulled from it, the first 50 by date.", "items": { "properties": { "date": { "format": "date", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "timesheet_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "work_order_number": { "description": "The number of the Work Order its timesheet names; null when it names none this agency has.", "nullable": true, "type": "string" } }, "required": [ "id", "timesheet_id", "date", "work_order_number" ], "type": "object" }, "type": "array" }, "timesheet_entries_total": { "description": "How many such entries there are.", "minimum": 0, "type": "integer" }, "unfrozen_months": { "description": "Work Order months its signature alone froze, open to edits again.", "items": { "properties": { "month": { "maximum": 12, "minimum": 1, "type": "integer" }, "work_order_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "work_order_number": { "description": "The Work Order's number.", "nullable": true, "type": "string" }, "year": { "type": "integer" } }, "required": [ "work_order_id", "work_order_number", "year", "month" ], "type": "object" }, "type": "array" } }, "required": [ "timesheet_entries", "timesheet_entries_total", "unfrozen_months" ], "title": "VisitDeleteLinks", "type": "object" }, "VisitDetail": { "properties": { "actual_end_time": { "description": "When the caregiver clocked out (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "actual_start_time": { "description": "When the caregiver clocked in (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "adjusted_end_time": { "description": "The agency's corrected end, when it changed the clocked one (UTC); written with its UTC offset, refused without one (422 time_offset_required).", "format": "date-time", "nullable": true, "type": "string" }, "adjusted_start_time": { "description": "The agency's corrected start, when it changed the clocked one (UTC); written with its UTC offset, refused without one (422 time_offset_required).", "format": "date-time", "nullable": true, "type": "string" }, "alternate_location": { "description": "Whether the service was given away from the client's home address.", "type": "boolean" }, "assignment_id": { "description": "The assignment the visit came from, if any.", "format": "uuid", "nullable": true, "type": "string" }, "billable_hours": { "description": "Hours the visit bills.", "format": "decimal", "nullable": true, "type": "string" }, "calls": { "description": "The newest 200 at most, oldest first.", "items": { "description": "A clock event: the caregiver's app, a phone call (IVR) or a manual entry. Calls are never edited; a correction is a change.", "properties": { "call_assignment": { "description": "What the call recorded.", "enum": [ "time_in", "time_out", "other" ], "type": "string" }, "call_datetime": { "description": "When the call was made (UTC).", "format": "date-time", "type": "string" }, "call_type": { "description": "How the call was made.", "enum": [ "mobile", "telephony", "fvv", "manual", "other" ], "type": "string" }, "device_id": { "description": "The device that made the call.", "nullable": true, "type": "string", "x-untrusted": "text" }, "gps_accuracy_meters": { "nullable": true, "type": "number" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "latitude": { "description": "Where the device was.", "format": "decimal", "nullable": true, "type": "string" }, "location_description": { "description": "GPS warnings recorded with the call, such as outside the geofence.", "nullable": true, "type": "string" }, "longitude": { "description": "Where the device was.", "format": "decimal", "nullable": true, "type": "string" }, "superseded_at": { "description": "Set when the visit was reassigned away from the caregiver who made the call: the call stays as history and no longer counts as the visit's clock.", "format": "date-time", "nullable": true, "type": "string" } }, "title": "VisitCall", "type": "object" }, "type": "array" }, "caregiver_id": { "description": "The caregiver who served.", "format": "uuid", "type": "string" }, "changes": { "description": "The newest 200 at most, oldest first.", "items": { "description": "A correction the agency made to the visit, with Colorado's reason code.", "properties": { "change_datetime": { "description": "When it changed (UTC).", "format": "date-time", "type": "string" }, "change_source": { "description": "Where the change was made.", "enum": [ "agency_portal", "api", "system", "bulk_action" ], "type": "string" }, "changed_by_id": { "description": "The user who made it.", "format": "uuid", "nullable": true, "type": "string" }, "field_changed": { "description": "The field that changed.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "new_value": { "nullable": true, "type": "object" }, "old_value": { "nullable": true, "type": "object" }, "reason_code": { "description": "Why it changed: Colorado's reason code, such as CLKIN, CLKOUT, SCHED or OTHER.", "nullable": true, "type": "string" }, "reason_memo": { "nullable": true, "type": "string", "x-untrusted": "text" }, "resolution_code": { "nullable": true, "type": "string" } }, "title": "VisitChange", "type": "object" }, "type": "array" }, "client_id": { "description": "The client served.", "format": "uuid", "type": "string" }, "client_signature_captured": { "description": "Whether the client signed for the visit.", "type": "boolean" }, "deleted_at": { "description": "Set when the agency deleted the record. Only a list with include_deleted=true returns deleted records.", "format": "date-time", "nullable": true, "type": "string" }, "group_identifier": { "description": "For a group visit, the caregiver's name for the group session.", "nullable": true, "type": "string", "x-untrusted": "text" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "import_external_id": { "description": "For an imported visit, that system's id for it (Sandata's Visit ID); else null.", "nullable": true, "type": "string", "x-untrusted": "text" }, "import_system": { "description": "For an imported visit, the system it was imported from; else null.", "enum": [ "sandata" ], "nullable": true, "type": "string" }, "inserted_at": { "description": "When the visit was created.", "format": "date-time", "type": "string" }, "location_verified": { "description": "Whether the clock-in was inside the client's geofence.", "type": "boolean" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "memo": { "description": "The agency's note on the visit.", "nullable": true, "type": "string", "x-untrusted": "text" }, "modifiers": { "description": "The procedure modifiers.", "items": { "type": "string" }, "type": "array" }, "payable_hours": { "description": "Hours the visit pays the caregiver.", "format": "decimal", "nullable": true, "type": "string" }, "procedure_code": { "description": "The HCPCS code.", "nullable": true, "type": "string" }, "sandata_sent_at": { "description": "When Sandata first took the visit.", "format": "date-time", "nullable": true, "type": "string" }, "sandata_submission_status": { "description": "Where the visit is in the Sandata queue.", "enum": [ "pending", "submitted", "accepted", "rejected", "resubmitted" ], "nullable": true, "type": "string" }, "sandata_visit_id": { "description": "Sandata's id for the visit, once Sandata has it.", "nullable": true, "type": "string" }, "scheduled_end_time": { "description": "Scheduled end (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "scheduled_start_time": { "description": "Scheduled start (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "service_date": { "description": "The day of service.", "format": "date", "nullable": true, "type": "string" }, "signatures": { "description": "The newest 200 at most, oldest first.", "items": { "description": "Who signed for the visit and how. The image is not returned here.", "properties": { "captured_at": { "description": "When it was signed (UTC).", "format": "date-time", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "signature_type": { "enum": [ "drawn", "initials" ], "type": "string" }, "signer_name": { "nullable": true, "type": "string", "x-untrusted": "text" }, "signer_type": { "enum": [ "client", "caregiver" ], "type": "string" } }, "title": "VisitSignatureSummary", "type": "object" }, "type": "array" }, "source": { "description": "How the visit was created; import is an EVV vendor's record of a shift, read-only, beside the agency's own visit for it.", "enum": [ "schedule", "manual", "api", "import" ], "type": "string" }, "status": { "description": "Where the visit is in its lifecycle.", "enum": [ "scheduled", "in_progress", "completed", "verified", "submitted", "matched", "rejected", "cancelled" ], "type": "string" }, "updated_at": { "description": "When the visit last changed.", "format": "date-time", "type": "string" }, "visit_type": { "enum": [ "standard", "group", "live_in", "respite", "companion", "travel" ], "type": "string" } }, "required": [ "id", "client_id", "caregiver_id", "service_date", "status", "lock_version", "calls", "changes", "signatures" ], "title": "VisitDetail", "type": "object" }, "VisitException": { "properties": { "assigned_to_id": { "description": "The member it is assigned to; set by the assignment operation.", "format": "uuid", "nullable": true, "type": "string" }, "auto_detected": { "description": "Whether a rule detected it, rather than a person.", "type": "boolean" }, "detected_at": { "description": "When it was detected (UTC).", "format": "date-time", "type": "string" }, "detection_details": { "additionalProperties": true, "description": "What the rule measured, such as the distance from the geofence.", "type": "object" }, "exception_type": { "description": "The rule the visit broke.", "enum": [ "late_clock_in", "location_mismatch", "time_discrepancy", "missing_clock_in", "missing_clock_out", "overlapping_visits", "manual_entry", "suspicious_regularity", "phone_mismatch", "sandata_raised" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the exception was recorded.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "resolution_code": { "description": "Why it was resolved as it was.", "enum": [ "valid_reason", "scheduling_change", "traffic", "gps_inaccuracy", "approved_overtime", "false_positive", "client_request", "caregiver_error", "system_error", "other" ], "nullable": true, "type": "string" }, "resolution_notes": { "description": "The office's note on the resolution.", "nullable": true, "type": "string", "x-untrusted": "text" }, "resolved_at": { "description": "When it was resolved (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "resolved_by_id": { "description": "The member who resolved it.", "format": "uuid", "nullable": true, "type": "string" }, "sandata_ack_status": { "description": "Where the acknowledgement to Sandata is; null until the reconciler first looks at it, held means it can never be sent.", "enum": [ "pending", "submitted", "accepted", "failed", "held" ], "nullable": true, "type": "string" }, "sandata_exception_id": { "description": "The Addendum exception code Sandata reported for the visit (for example \"15\"), when it did; only an ACK code (15, 21) is acknowledged.", "nullable": true, "type": "string" }, "sandata_reason_code": { "description": "The Colorado Appendix 3 reason code that describes the exception type, as reference data; null when the type has none. Sandata receives no reason code from an exception: an acknowledgement carries the Addendum exception code, and a visit change carries the reason its own edit records (GET /api/v1/visit-exceptions/reason-codes lists them).", "nullable": true, "type": "integer" }, "severity": { "enum": [ "warning", "error" ], "type": "string" }, "status": { "description": "open until resolved.", "enum": [ "open", "acknowledged", "corrected", "dismissed", "withdrawn" ], "type": "string" }, "updated_at": { "description": "When the exception last changed.", "format": "date-time", "type": "string" }, "visit_id": { "description": "The visit the exception is on.", "format": "uuid", "type": "string" } }, "required": [ "id", "visit_id", "exception_type", "severity", "status", "detected_at", "lock_version" ], "title": "VisitException", "type": "object" }, "VisitExceptionAssignment": { "properties": { "assigned_to_id": { "description": "A user of this agency, or null to unassign. A user of another agency answers 422 assignee_not_found.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "assigned_to_id" ], "title": "VisitExceptionAssignment", "type": "object" }, "VisitExceptionBulkResolve": { "properties": { "action": { "description": "What to do with them; dismiss needs resolution_notes.", "enum": [ "acknowledge", "dismiss" ], "type": "string" }, "ids": { "description": "The exceptions to resolve, at most 100.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array" }, "resolution_code": { "description": "Why they are resolved.", "enum": [ "valid_reason", "scheduling_change", "traffic", "gps_inaccuracy", "approved_overtime", "false_positive", "client_request", "caregiver_error", "system_error", "other" ], "type": "string" }, "resolution_notes": { "description": "Required to dismiss. At most 2000 characters.", "nullable": true, "type": "string" } }, "required": [ "ids", "action", "resolution_code" ], "title": "VisitExceptionBulkResolve", "type": "object" }, "VisitExceptionBulkResult": { "properties": { "failed_ids": { "description": "Not resolved because the write failed; retrying them is safe.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "type": "array" }, "resolved_ids": { "description": "Resolved now.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "type": "array" }, "skipped_ids": { "description": "Not open, or not this agency's: nothing was done to them.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "type": "array" } }, "required": [ "resolved_ids", "failed_ids", "skipped_ids" ], "title": "VisitExceptionBulkResult", "type": "object" }, "VisitExceptionReasonCodes": { "properties": { "resolution_codes": { "description": "What resolution_code takes.", "items": { "enum": [ "valid_reason", "scheduling_change", "traffic", "gps_inaccuracy", "approved_overtime", "false_positive", "client_request", "caregiver_error", "system_error", "other" ], "type": "string" }, "type": "array" }, "sandata_reason_codes": { "description": "The Colorado Appendix 3 reason codes that describe each exception type (an exception's sandata_reason_code), as reference data.", "items": { "properties": { "code": { "type": "integer" }, "description": { "type": "string" }, "location_required": { "description": "The note must give the client's location.", "type": "boolean" }, "note_required": { "description": "Sandata needs a note with this code; it is built from the client's address, not from resolution_notes.", "type": "boolean" } }, "required": [ "code", "description", "note_required", "location_required" ], "type": "object" }, "type": "array" } }, "required": [ "resolution_codes", "sandata_reason_codes" ], "title": "VisitExceptionReasonCodes", "type": "object" }, "VisitExceptionResolve": { "properties": { "action": { "description": "What to do with it: acknowledge marks it reviewed; correct also sets the visit's adjusted times; dismiss flags it as not applicable and needs resolution_notes.", "enum": [ "acknowledge", "correct", "dismiss" ], "type": "string" }, "adjusted_end_time": { "description": "Required for correct: the visit's corrected end (ISO 8601, with an offset).", "format": "date-time", "type": "string" }, "adjusted_start_time": { "description": "Required for correct: the visit's corrected start (ISO 8601, with an offset).", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "resolution_code": { "description": "Why it is resolved (GET /api/v1/visit-exceptions/reason-codes).", "enum": [ "valid_reason", "scheduling_change", "traffic", "gps_inaccuracy", "approved_overtime", "false_positive", "client_request", "caregiver_error", "system_error", "other" ], "type": "string" }, "resolution_notes": { "description": "Required to dismiss. At most 2000 characters.", "nullable": true, "type": "string" } }, "required": [ "action", "resolution_code", "lock_version" ], "title": "VisitExceptionResolve", "type": "object" }, "VisitImport": { "properties": { "completed_at": { "format": "date-time", "nullable": true, "type": "string" }, "counts": { "allOf": [ { "$ref": "#/components/schemas/VisitImportCounts" } ], "description": "How its rows were taken, once it has ended.", "nullable": true }, "error": { "description": "A failed import's reason: missing_columns, csv_parse_error, empty_file, too_many_rows, file_too_large, unreadable_file, internal_error, abandoned (stopped and not resumed within 2 hours).", "nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "file_name": { "description": "The file's name as sent.", "nullable": true, "type": "string", "x-untrusted": "text" }, "findings": { "description": "Warnings about rows that were written, once it has ended: a visit on a day a submitted Returned Timesheet holds, left unlinked to that day's care log.", "items": { "$ref": "#/components/schemas/VisitImportFinding" }, "nullable": true, "type": "array" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was started.", "format": "date-time", "type": "string" }, "status": { "enum": [ "pending", "processing", "completed", "partial", "failed" ], "type": "string" }, "total_rows": { "description": "The file's visit rows.", "nullable": true, "type": "integer" }, "unresolved": { "description": "The rows not written, by number and reason.", "items": { "$ref": "#/components/schemas/VisitImportUnresolved" }, "nullable": true, "type": "array" } }, "required": [ "id", "status" ], "title": "VisitImport", "type": "object" }, "VisitImportCounts": { "properties": { "already_ours": { "description": "HCB's own visits, as HCB sent them to Sandata; never imported.", "type": "integer" }, "changed": { "description": "Visits imported before whose times, code or people Sandata changed.", "type": "integer" }, "new": { "description": "Sandata visits not imported before.", "type": "integer" }, "unchanged": { "description": "Visits imported before, as they were.", "type": "integer" }, "unresolved": { "description": "Rows not written; see unresolved.", "type": "integer" } }, "required": [ "new", "changed", "unchanged", "already_ours", "unresolved" ], "title": "VisitImportCounts", "type": "object" }, "VisitImportFinding": { "properties": { "care_log_id": { "format": "uuid", "nullable": true, "type": "string" }, "message": { "description": "The warning in words.", "type": "string" }, "period": { "description": "The Returned Timesheet's billing period.", "nullable": true, "properties": { "end": { "format": "date", "nullable": true, "type": "string" }, "start": { "format": "date", "type": "string" } }, "type": "object" }, "row": { "description": "The row's number, the heading row being 1.", "type": "integer" }, "rule_id": { "enum": [ "care_logs.imported_for_billed_day" ], "type": "string" }, "service_date": { "format": "date", "nullable": true, "type": "string" }, "status": { "description": "The Returned Timesheet's status: submitted, approved or exported.", "nullable": true, "type": "string" }, "timesheet_id": { "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "row", "rule_id", "message" ], "title": "VisitImportFinding", "type": "object" }, "VisitImportPreview": { "properties": { "counts": { "$ref": "#/components/schemas/VisitImportCounts" }, "dry_run": { "description": "Always true: nothing was written.", "type": "boolean" }, "total_rows": { "description": "The file's visit rows.", "type": "integer" }, "unresolved": { "items": { "$ref": "#/components/schemas/VisitImportUnresolved" }, "type": "array" } }, "required": [ "dry_run", "total_rows", "counts", "unresolved" ], "title": "VisitImportPreview", "type": "object" }, "VisitImportUnresolved": { "properties": { "message": { "description": "The reason in words.", "type": "string" }, "reason": { "enum": [ "client_not_found", "client_ambiguous", "caregiver_not_found", "caregiver_ambiguous", "duplicate_visit_id", "no_calls", "no_visit_id", "no_service", "invalid_time", "times_out_of_order", "write_failed", "no_work_order_for_code", "delivery_failed" ], "type": "string" }, "row": { "description": "The row's number, the heading row being 1.", "type": "integer" } }, "required": [ "row", "reason", "message" ], "title": "VisitImportUnresolved", "type": "object" }, "VisitPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Visit" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "VisitPage", "type": "object" }, "VisitReassign": { "description": "The caregiver to hand the visit to, and the lock_version you read.", "properties": { "caregiver_id": { "description": "One of this agency's caregivers.", "format": "uuid", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": [ "caregiver_id", "lock_version" ], "title": "VisitReassign", "type": "object" }, "VisitSandataException": { "properties": { "code": { "description": "The ACK exception Sandata raised on the visit, as its Aggregator shows it: 15 Unmatched Client ID / Phone, 21 No Show Exception.", "enum": [ "15", "21" ], "type": "string" } }, "required": [ "code" ], "title": "VisitSandataException", "type": "object" }, "VisitSignatureSummary": { "description": "Who signed for the visit and how. The image is not returned here.", "properties": { "captured_at": { "description": "When it was signed (UTC).", "format": "date-time", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "signature_type": { "enum": [ "drawn", "initials" ], "type": "string" }, "signer_name": { "nullable": true, "type": "string", "x-untrusted": "text" }, "signer_type": { "enum": [ "client", "caregiver" ], "type": "string" } }, "title": "VisitSignatureSummary", "type": "object" }, "VisitTransition": { "description": "The status to move the visit to, and the lock_version you read.", "properties": { "cancellation_note": { "description": "A note on the cancellation (a cancel only, up to 1000 characters); needs a cancellation_reason.", "maxLength": 1000, "type": "string" }, "cancellation_reason": { "description": "Why the visit is cancelled (a cancel only), from the web's pick list: caregiver_call_off (Caregiver called off), client_cancelled (Client cancelled (don't come)), client_hospitalized (Client in hospital or facility), client_unavailable (Client not home or unavailable), schedule_change (Schedule changed), weather_emergency (Weather or emergency), entered_in_error (Entered in error or duplicate), other (Other). Optional; a cancel without one records no reason.", "enum": [ "caregiver_call_off", "client_cancelled", "client_hospitalized", "client_unavailable", "schedule_change", "weather_emergency", "entered_in_error", "other" ], "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "status": { "description": "The status to move the visit to.", "enum": [ "scheduled", "in_progress", "completed", "verified", "submitted", "matched", "rejected", "cancelled" ], "type": "string" } }, "required": [ "status", "lock_version" ], "title": "VisitTransition", "type": "object" }, "VisitUpdate": { "description": "Fields to change, plus the lock_version you read (required). Moving the scheduled start moves the service date to the start's Mountain day (warned as service_date_moved); a window over 24 hours is saved with a long_window warning, one over 31 days is refused. visit_type changes only while the visit is not queued for or sent to Sandata; a visit that is not a group visit carries no group_identifier.", "properties": { "adjusted_end_time": { "description": "The agency's corrected end, when it changed the clocked one (UTC); written with its UTC offset, refused without one (422 time_offset_required).", "format": "date-time", "nullable": true, "type": "string" }, "adjusted_start_time": { "description": "The agency's corrected start, when it changed the clocked one (UTC); written with its UTC offset, refused without one (422 time_offset_required).", "format": "date-time", "nullable": true, "type": "string" }, "alternate_location": { "description": "Whether the service was given away from the client's home address.", "type": "boolean" }, "group_identifier": { "description": "For a group visit, the caregiver's name for the group session.", "nullable": true, "type": "string", "x-untrusted": "text" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "memo": { "description": "The agency's note on the visit.", "nullable": true, "type": "string", "x-untrusted": "text" }, "modifiers": { "description": "The procedure modifiers.", "items": { "type": "string" }, "type": "array" }, "procedure_code": { "description": "The HCPCS code.", "nullable": true, "type": "string" }, "reason_code": { "description": "Colorado's reason for a change to adjusted_start_time or adjusted_end_time. Left out, null or blank, the change is saved with OTHER and the answer warns.", "enum": [ "CLKIN", "CLKOUT", "SCHED", "OTHER" ], "nullable": true, "type": "string" }, "reason_memo": { "description": "A note on the reason, kept with the change.", "nullable": true, "type": "string" }, "scheduled_end_time": { "description": "Scheduled end, with its UTC offset; refused without one, as the start.", "format": "date-time", "type": "string" }, "scheduled_start_time": { "description": "Scheduled start, with its UTC offset (Z or -06:00); one without is refused (422 time_offset_required), as is a value that is not a time (422 invalid_time).", "format": "date-time", "type": "string" }, "visit_type": { "enum": [ "standard", "group", "live_in", "respite", "companion", "travel" ], "type": "string" } }, "title": "VisitUpdate", "type": "object" }, "VisitWriteResult": { "properties": { "data": { "$ref": "#/components/schemas/Visit" }, "warnings": { "description": "What the write was saved despite: reason_code_missing (an adjusted time changed with no reason_code; recorded as OTHER), overlapping_visit (the caregiver has another visit at that time), group_identifier_dropped (a group name sent for a visit that is not a group visit, which keeps none), assignment_not_open, long_window (over 24 hours) service_date_moved (a moved start re-dated the visit), and on a reassignment calls_superseded (the earlier caregiver's clock calls stay as history and no longer count) caregiver_not_active or months_unfrozen (the visit's signature alone froze the earlier caregiver's Work Order month, which can be edited again).", "items": { "properties": { "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "title": "VisitWriteResult", "type": "object" }, "W4Change": { "description": "A caregiver whose W-4 changed since payroll was last told.", "properties": { "adp_file_number": { "description": "The caregiver's ADP file number.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "caregiver_name": { "description": "\"Last, First\", as the payroll pages show it.", "nullable": true, "type": "string" }, "id": { "description": "The caregiver (the row is the caregiver).", "format": "uuid", "type": "string" }, "w4_changed_at": { "description": "When the W-4 changed; POST /caregivers/{id}/w4-sent-to-payroll takes it back to clear it.", "format": "date-time", "type": "string" }, "w4_dependents": { "description": "The dependents now on file.", "nullable": true, "type": "integer" }, "w4_filing_status": { "description": "The filing status now on file.", "nullable": true, "type": "string" } }, "required": [ "id", "caregiver_id", "w4_changed_at" ], "title": "W4Change", "type": "object" }, "W4ChangePage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/W4Change" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "W4ChangePage", "type": "object" }, "Warning": { "properties": { "fix": { "description": "Where it is fixed, when a page fixes it.", "nullable": true, "properties": { "label": { "description": "What the link says.", "type": "string" }, "path": { "description": "The app route that fixes it.", "type": "string" } }, "required": [ "path", "label" ], "type": "object" }, "id": { "description": "The rule that raised it, stable, e.g. client_care.medicaid_id_pending.", "type": "string" }, "message": { "description": "For a person to read.", "type": "string" } }, "required": [ "id", "message" ], "title": "Warning", "type": "object" }, "WebhookDelivery": { "properties": { "attempts": { "description": "Attempts so far.", "type": "integer" }, "created_at": { "description": "When the event was queued (UTC).", "format": "date-time", "type": "string" }, "delivered_at": { "description": "When it was delivered (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "endpoint_id": { "description": "The endpoint it went to.", "format": "uuid", "type": "string" }, "event_id": { "description": "The event's id, the same on every attempt.", "format": "uuid", "type": "string" }, "event_type": { "description": "The event type.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_error": { "description": "The last failure.", "nullable": true, "type": "string" }, "last_status_code": { "description": "The last HTTP status the endpoint answered.", "nullable": true, "type": "integer" }, "status": { "description": "Where it stands.", "enum": [ "pending", "delivered", "failed" ], "type": "string" } }, "required": [ "id", "endpoint_id", "event_type", "status" ], "title": "WebhookDelivery", "type": "object" }, "WebhookDeliveryPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "attempts": { "description": "Attempts so far.", "type": "integer" }, "created_at": { "description": "When the event was queued (UTC).", "format": "date-time", "type": "string" }, "delivered_at": { "description": "When it was delivered (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "endpoint_id": { "description": "The endpoint it went to.", "format": "uuid", "type": "string" }, "event_id": { "description": "The event's id, the same on every attempt.", "format": "uuid", "type": "string" }, "event_type": { "description": "The event type.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_error": { "description": "The last failure.", "nullable": true, "type": "string" }, "last_status_code": { "description": "The last HTTP status the endpoint answered.", "nullable": true, "type": "integer" }, "status": { "description": "Where it stands.", "enum": [ "pending", "delivered", "failed" ], "type": "string" } }, "required": [ "id", "endpoint_id", "event_type", "status" ], "title": "WebhookDelivery", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "WebhookDeliveryPage", "type": "object" }, "WebhookEndpoint": { "properties": { "active": { "description": "Whether events are sent.", "type": "boolean" }, "created_at": { "description": "When it was registered (UTC).", "format": "date-time", "type": "string" }, "events": { "description": "Event types sent.", "items": { "type": "string" }, "type": "array" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "url": { "description": "Where events are posted.", "nullable": true, "type": "string" } }, "required": [ "id", "url", "events", "active" ], "title": "WebhookEndpoint", "type": "object" }, "WebhookEndpointCreate": { "properties": { "events": { "description": "Event types to send.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "An https URL.", "type": "string" } }, "required": [ "url", "events" ], "title": "WebhookEndpointCreate", "type": "object" }, "WebhookEndpointCreated": { "properties": { "data": { "properties": { "active": { "description": "Whether events are sent.", "type": "boolean" }, "created_at": { "description": "When it was registered (UTC).", "format": "date-time", "type": "string" }, "events": { "description": "Event types sent.", "items": { "type": "string" }, "type": "array" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "url": { "description": "Where events are posted.", "nullable": true, "type": "string" } }, "required": [ "id", "url", "events", "active" ], "title": "WebhookEndpoint", "type": "object" }, "secret": { "description": "The signing secret, shown this once.", "nullable": true, "type": "string" } }, "required": [ "data", "secret" ], "title": "WebhookEndpointCreated", "type": "object" }, "WebhookEndpointPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "active": { "description": "Whether events are sent.", "type": "boolean" }, "created_at": { "description": "When it was registered (UTC).", "format": "date-time", "type": "string" }, "events": { "description": "Event types sent.", "items": { "type": "string" }, "type": "array" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "url": { "description": "Where events are posted.", "nullable": true, "type": "string" } }, "required": [ "id", "url", "events", "active" ], "title": "WebhookEndpoint", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "WebhookEndpointPage", "type": "object" }, "WebhookEndpointUpdate": { "properties": { "active": { "description": "Whether events are sent.", "type": "boolean" }, "events": { "description": "Event types to send.", "items": { "type": "string" }, "type": "array" } }, "title": "WebhookEndpointUpdate", "type": "object" }, "Work orderPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/WorkOrder" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Work orderPage", "type": "object" }, "WorkOrder": { "description": "What was ordered for one client, caregiver and month. An archived work order leaves the plain list; a list with updated_since (a sync) includes archived ones, archived_at set, so a sync learns of an archive.", "properties": { "archived_at": { "description": "Set when the agency archived it.", "format": "date-time", "nullable": true, "type": "string" }, "authorization_id": { "description": "The service authorization (PAR) it bills against, one of this client's and not deleted; see /api/v1/authorizations. Null or blank unlinks it; another id answers 422 naming authorization_id.", "format": "uuid", "nullable": true, "type": "string" }, "billing_code": { "description": "The HCPCS code billed for the service.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver serving.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client served.", "format": "uuid", "type": "string" }, "client_signature_date": { "description": "When the client signed; null while unsigned.", "format": "date", "nullable": true, "type": "string" }, "closing_date": { "format": "date", "nullable": true, "type": "string" }, "effective_date": { "format": "date", "nullable": true, "type": "string" }, "entries": { "description": "The delivered days: one per Care Log of this Work Order's client, caregiver, service and shift in its month, as they are now; a combined (legacy) Work Order's are every day recorded on it, since no Care Log carries a combined service. A day can change without moving this record's updated_at; re-read the record by id to have it current.", "items": { "properties": { "date": { "format": "date", "nullable": true, "type": "string" }, "hours_worked": { "description": "Hours worked that day.", "format": "decimal", "nullable": true, "type": "string" }, "time_in": { "description": "HH:MM:SS, local time.", "nullable": true, "type": "string" }, "time_out": { "description": "HH:MM:SS, local time.", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "expires_on": { "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the record was created.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "modifiers": { "description": "Billing code modifiers.", "items": { "type": "string" }, "type": "array" }, "month": { "description": "1 to 12.", "nullable": true, "type": "integer" }, "office_hours_total": { "description": "Hours the office recorded for the month.", "format": "decimal", "nullable": true, "type": "string" }, "paper_signatures_collected": { "description": "Whether the signed paper Time & Services card is collected.", "type": "boolean" }, "paper_signatures_collected_at": { "description": "When the paper card was marked collected.", "format": "date-time", "nullable": true, "type": "string" }, "provider_signature_date": { "description": "When the provider signed; null while unsigned.", "format": "date", "nullable": true, "type": "string" }, "seen_by_date": { "additionalProperties": { "type": "string" }, "description": "Each date of the month (YYYY-MM-DD) to an opaque value: send it as seen to PUT /api/v1/work-orders/{id}/days/{date}, and a date changed since this read is refused with 409 stale_record and nothing written. Its format is not a contract.", "type": "object" }, "service_type": { "enum": [ "personal_care", "homemaker", "legacy" ], "type": "string" }, "shift_number": { "description": "The shift, 1 to 4 (default 1).", "maximum": 4, "minimum": 1, "type": "integer" }, "status": { "enum": [ "in_progress", "completed" ], "type": "string" }, "supervisor_designee_signature_date": { "description": "When the supervisor's designee signed; null while unsigned.", "format": "date", "nullable": true, "type": "string" }, "supervisor_signature_date": { "description": "When the supervisor signed; null while unsigned.", "format": "date", "nullable": true, "type": "string" }, "updated_at": { "description": "When the record last changed.", "format": "date-time", "type": "string" }, "verified_hours_first_half": { "description": "Verified hours, days 1 to 15.", "format": "decimal", "nullable": true, "type": "string" }, "verified_hours_second_half": { "description": "Verified hours, day 16 on.", "format": "decimal", "nullable": true, "type": "string" }, "warnings": { "description": "What the catalog warns of; usually empty. Never a refusal: the work order is saved and bills as entered. Each names its rule (catalog.unknown_code: no HCPF fee schedule prices the billing code) and the message. Recomputed on every read, so it clears once the code changes to a priced one or a fee schedule prices it.", "items": { "properties": { "message": { "description": "What the agency is warned of.", "type": "string" }, "rule_id": { "description": "The rule that raised it.", "type": "string" } }, "required": [ "rule_id", "message" ], "title": "WorkOrderWarning", "type": "object" }, "type": "array" }, "wo_number": { "description": "The agency's work order number.", "nullable": true, "type": "integer" }, "wo_type": { "enum": [ "standard", "temporary", "extra" ], "type": "string" }, "year": { "maximum": 2100, "minimum": 2020, "type": "integer" } }, "required": [ "id", "client_id", "caregiver_id", "month", "year", "status", "lock_version" ], "title": "WorkOrder", "type": "object" }, "WorkOrderCareLogFill": { "properties": { "differences": { "description": "Always empty: the fill writes nothing (US-118.17).", "items": { "properties": { "date": { "format": "date", "type": "string" }, "reason": { "type": "string" } }, "type": "object" }, "type": "array" }, "filled": { "description": "Always empty: the fill writes nothing (US-118.17).", "items": { "format": "date", "type": "string" }, "type": "array" }, "flagged": { "description": "Always empty: the fill writes nothing (US-118.17).", "items": { "properties": { "date": { "format": "date", "type": "string" }, "reason": { "type": "string" } }, "type": "object" }, "type": "array" }, "unchanged": { "description": "Every date of the month with a delivery (a live care log the Work Order holds), each once, in order.", "items": { "format": "date", "type": "string" }, "type": "array" }, "updated": { "description": "Always empty: the fill writes nothing (US-118.17).", "items": { "format": "date", "type": "string" }, "type": "array" } }, "required": [ "filled", "updated", "unchanged", "differences", "flagged" ], "title": "WorkOrderCareLogFill", "type": "object" }, "WorkOrderChangeCaregiver": { "properties": { "caregiver_id": { "description": "The caregiver who takes over.", "format": "uuid", "type": "string" }, "from": { "description": "The first day the new caregiver works it, YYYY-MM-DD. On or before the Effective Date the whole Work Order moves and this one is archived; later, this one closes the day before.", "format": "date", "nullable": true, "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": [ "caregiver_id", "from", "lock_version" ], "title": "WorkOrderChangeCaregiver", "type": "object" }, "WorkOrderCreate": { "description": "A new work order. The client and caregiver must be members of the agency that are not deleted; a pair already holding a work order for the month, service, shift and type is refused.", "properties": { "billing_code": { "description": "The HCPCS code billed for the service.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver serving.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client served.", "format": "uuid", "type": "string" }, "effective_date": { "format": "date", "nullable": true, "type": "string" }, "expires_on": { "format": "date", "nullable": true, "type": "string" }, "extra_reason": { "description": "Why an extra work order is needed (wo_type extra).", "nullable": true, "type": "string" }, "modifiers": { "description": "Billing code modifiers.", "items": { "type": "string" }, "type": "array" }, "month": { "description": "1 to 12.", "nullable": true, "type": "integer" }, "notes": { "description": "Free text; written, never returned.", "nullable": true, "type": "string" }, "service_type": { "enum": [ "personal_care", "homemaker", "legacy" ], "type": "string" }, "shift_number": { "description": "The shift, 1 to 4 (default 1).", "maximum": 4, "minimum": 1, "type": "integer" }, "wo_type": { "enum": [ "standard", "temporary", "extra" ], "type": "string" }, "year": { "maximum": 2100, "minimum": 2020, "type": "integer" } }, "required": [ "client_id", "caregiver_id", "month", "year", "service_type" ], "title": "WorkOrderCreate", "type": "object" }, "WorkOrderDayChange": { "properties": { "confirm": { "description": "Optional: mark a date with recorded work not worked.", "type": "boolean" }, "seen": { "description": "The date's value from seen_by_date on GET /api/v1/work-orders/{id} (the get_work_order tool answers it too), to refuse a date changed since that read.", "nullable": true, "type": "string" }, "shaded": { "description": "true worked, false not worked.", "type": "boolean" } }, "required": [ "shaded" ], "title": "WorkOrderDayChange", "type": "object" }, "WorkOrderDistribute": { "properties": { "month": { "description": "The month, 1 to 12.", "maximum": 12, "minimum": 1, "type": "integer" }, "selections": { "description": "One per service and shift being generated.", "items": { "properties": { "frequencies": { "additionalProperties": { "additionalProperties": { "minimum": 0, "type": "integer" }, "type": "object" }, "description": "caregiver id => plan task id => visits a week. A caregiver whose counts are all 0 gets no Work Order.", "type": "object" }, "service_type": { "description": "The service.", "enum": [ "homemaker", "personal_care" ], "type": "string" }, "shift_number": { "description": "Optional: the shift, 1 to 4; default 1.", "maximum": 4, "minimum": 1, "type": "integer" } }, "required": [ "service_type", "frequencies" ], "type": "object" }, "type": "array" }, "year": { "description": "The year.", "maximum": 2100, "minimum": 2020, "type": "integer" } }, "required": [ "month", "year", "selections" ], "title": "WorkOrderDistribute", "type": "object" }, "WorkOrderDuplicate": { "properties": { "caregiver_id": { "description": "With mode: the copy's caregiver, this agency's; this Work Order's when not sent.", "format": "uuid", "type": "string" }, "client_id": { "description": "With mode: the copy's client, this agency's; this Work Order's when not sent.", "format": "uuid", "type": "string" }, "closing_date": { "description": "close_previous: this Work Order's Closing Date; the day before effective_date when not sent, as the page's dialog fills it in. Refused before this Work Order's own Effective Date.", "format": "date", "type": "string" }, "effective_date": { "description": "keep_both and close_previous, which need it: the copy's Effective Date.", "format": "date", "type": "string" }, "lock_version": { "description": "With mode: the lock_version this Work Order was read with. close_previous needs it, since it closes this Work Order: one changed since answers 409 stale_record, as a second close from the page is refused. Checked when sent with the other modes.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "mode": { "description": "Makes a new standing Work Order as the page's Duplicate does: keep_both keeps this one as it is; close_previous closes it at closing_date; temporary makes a copy that runs temporary_from to temporary_to. Not with month or year.", "enum": [ "keep_both", "close_previous", "temporary" ], "type": "string" }, "month": { "description": "Target month; send with year.", "maximum": 12, "minimum": 1, "type": "integer" }, "temporary_from": { "description": "temporary, which needs it: the copy's first day.", "format": "date", "type": "string" }, "temporary_to": { "description": "temporary, which needs it: the copy's last day.", "format": "date", "type": "string" }, "year": { "description": "Target year; send with month.", "maximum": 2100, "minimum": 2020, "type": "integer" } }, "title": "WorkOrderDuplicate", "type": "object" }, "WorkOrderEvvFill": { "properties": { "differences": { "description": "Always empty: the fill writes nothing (US-118.17).", "items": { "properties": { "date": { "format": "date", "type": "string" }, "entry_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "entry_time_in": { "description": "HH:MM:SS, Mountain.", "nullable": true, "type": "string" }, "entry_time_out": { "description": "HH:MM:SS, Mountain.", "nullable": true, "type": "string" }, "visit_clock_in": { "description": "The visit's clock-in (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "visit_clock_out": { "description": "The visit's clock-out (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "visit_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "type": "object" }, "type": "array" }, "filled": { "description": "Always empty: the fill writes nothing (US-118.17).", "items": { "format": "date", "type": "string" }, "type": "array" }, "flagged": { "description": "Always empty: the fill writes nothing (US-118.17).", "items": { "properties": { "date": { "format": "date", "type": "string" }, "reason": { "type": "string" } }, "type": "object" }, "type": "array" }, "unchanged": { "description": "Every date of the month with a delivery (a live care log the Work Order holds), each once, in order.", "items": { "format": "date", "type": "string" }, "type": "array" }, "updated": { "description": "Always empty: the fill writes nothing (US-118.17).", "items": { "format": "date", "type": "string" }, "type": "array" } }, "required": [ "filled", "updated", "unchanged", "differences", "flagged" ], "title": "WorkOrderEvvFill", "type": "object" }, "WorkOrderGenerate": { "properties": { "lrp": { "description": "Optional: generate the Homemaker Work Order from the client's LRP (legally responsible person) Homemaker plan instead of the regular one, as that plan's page does. Default false.", "type": "boolean" }, "month": { "description": "The month, 1 to 12.", "maximum": 12, "minimum": 1, "type": "integer" }, "overwrite": { "description": "Optional: replace the days of a Work Order already in the slot. Default false.", "type": "boolean" }, "schedule_pattern": { "description": "Optional: the weekdays the Work Order runs on, as the Work Order takes them.", "items": { "type": "integer" }, "type": "array" }, "service_type_override": { "description": "Optional: generate this service instead of the assignment's own; legacy is one Work Order carrying both.", "enum": [ "homemaker", "legacy", "personal_care" ], "type": "string" }, "shift_number": { "description": "Optional: the shift, 1 to 4; default 1.", "maximum": 4, "minimum": 1, "type": "integer" }, "year": { "description": "The year.", "maximum": 2100, "minimum": 2020, "type": "integer" } }, "required": [ "month", "year" ], "title": "WorkOrderGenerate", "type": "object" }, "WorkOrderPlan": { "properties": { "lines": { "items": { "properties": { "minutes": { "description": "Minutes each time (the line's Min/Task).", "nullable": true, "type": "integer" }, "notes": { "description": "The line's notes.", "nullable": true, "type": "string" }, "task_definition_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "weekday_counts": { "description": "Times on each weekday, Monday first.", "items": { "maximum": 24, "minimum": 0, "type": "integer" }, "maxItems": 7, "minItems": 7, "type": "array" } }, "required": [ "task_definition_id" ], "type": "object" }, "type": "array" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "slot_days": { "additionalProperties": { "items": { "properties": { "time_in": { "description": "HH:MM:SS, Mountain.", "nullable": true, "type": "string" }, "time_out": { "description": "HH:MM:SS, Mountain.", "nullable": true, "type": "string" }, "time_out_computed": { "description": "Whether its Time Out was worked out from the day's tasks.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "description": "Weekday, 1 (Monday) to 7, to its visits in order.", "type": "object" }, "work_order_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "required": [ "work_order_id", "lock_version", "slot_days", "lines" ], "title": "WorkOrderPlan", "type": "object" }, "WorkOrderPlanUpdate": { "properties": { "drop_lines": { "description": "Task definition ids whose lines to remove.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "type": "array" }, "lines": { "description": "Task lines: task_definition_id, minutes, weekday_counts (seven, Monday first), notes.", "items": { "properties": { "minutes": { "description": "Minutes each time (the line's Min/Task).", "nullable": true, "type": "integer" }, "notes": { "description": "The line's notes.", "nullable": true, "type": "string" }, "task_definition_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "weekday_counts": { "description": "Times on each weekday, Monday first.", "items": { "maximum": 24, "minimum": 0, "type": "integer" }, "maxItems": 7, "minItems": 7, "type": "array" } }, "required": [ "task_definition_id" ], "type": "object" }, "type": "array" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "slot_days": { "additionalProperties": { "items": { "properties": { "time_in": { "description": "HH:MM:SS, Mountain.", "nullable": true, "type": "string" }, "time_out": { "description": "HH:MM:SS, Mountain.", "nullable": true, "type": "string" }, "time_out_computed": { "description": "Whether its Time Out was worked out from the day's tasks.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "description": "Weekday 1 (Monday) to 7 => its visits, each time_in and time_out (HH:MM:SS); [] clears the day.", "type": "object" } }, "required": [ "lock_version" ], "title": "WorkOrderPlanUpdate", "type": "object" }, "WorkOrderSign": { "properties": { "date": { "description": "The signature date, YYYY-MM-DD: today when left out or null.", "format": "date", "nullable": true, "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "signature": { "description": "The signature as the pad saves it: a base64 PNG of at most 50 KB, with or without a data:image/png;base64, prefix.", "type": "string" }, "signature_type": { "description": "Whose signature.", "enum": [ "client", "provider", "supervisor", "supervisor_designee" ], "type": "string" } }, "required": [ "signature_type", "signature", "lock_version" ], "title": "WorkOrderSign", "type": "object" }, "WorkOrderTaskMark": { "properties": { "completed": { "nullable": true, "type": "boolean" }, "count": { "description": "Times that day.", "nullable": true, "type": "integer" }, "date": { "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "notes": { "nullable": true, "type": "string" }, "task_definition_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "warnings": { "description": "Dismissible warnings the day's care log raised on this write (a weekly or daily limit, a day a submitted Returned Timesheet missed), each with code and message. Absent for a combined Work Order.", "items": { "properties": { "code": { "nullable": true, "type": "string" }, "message": { "nullable": true, "type": "string" }, "task_definition_id": { "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "work_order_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "title": "WorkOrderTaskMark", "type": "object" }, "WorkOrderTaskToggle": { "properties": { "completed": { "description": "true done, false not done, null untouched.", "nullable": true, "type": "boolean" } }, "required": [ "completed" ], "title": "WorkOrderTaskToggle", "type": "object" }, "WorkOrderTransition": { "properties": { "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "status": { "description": "The new status.", "enum": [ "in_progress", "completed" ], "type": "string" } }, "required": [ "status", "lock_version" ], "title": "WorkOrderTransition", "type": "object" }, "WorkOrderUnplannedTask": { "properties": { "date": { "description": "The date, YYYY-MM-DD.", "format": "date", "type": "string" }, "notes": { "description": "Optional notes.", "nullable": true, "type": "string" }, "task_definition_id": { "description": "The task's definition id.", "format": "uuid", "type": "string" } }, "required": [ "task_definition_id", "date" ], "title": "WorkOrderUnplannedTask", "type": "object" }, "WorkOrderUpdate": { "description": "Fields to change, plus the lock_version you read (required).", "properties": { "billing_code": { "description": "The HCPCS code billed for the service.", "nullable": true, "type": "string" }, "effective_date": { "format": "date", "nullable": true, "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "modifiers": { "description": "Billing code modifiers.", "items": { "type": "string" }, "type": "array" } }, "title": "WorkOrderUpdate", "type": "object" }, "WorkOrderWarning": { "properties": { "message": { "description": "What the agency is warned of.", "type": "string" }, "rule_id": { "description": "The rule that raised it.", "type": "string" } }, "required": [ "rule_id", "message" ], "title": "WorkOrderWarning", "type": "object" }, "WorkforceReportPage": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/WorkforceReportRow" }, "type": "array" }, "from": { "description": "The period's first day.", "format": "date", "nullable": true, "type": "string" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "to": { "description": "The period's last day.", "format": "date", "nullable": true, "type": "string" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "from", "to", "data", "limit", "offset", "total" ], "title": "WorkforceReportPage", "type": "object" }, "WorkforceReportRow": { "description": "One worker's hours, wage and members served in one primary service.", "properties": { "average_weekly_hours": { "description": "The hours of the period's last four weeks, over four.", "format": "decimal", "nullable": true, "type": "string" }, "below_base_wage": { "description": "Whether wage_rate is under the 17.00 statewide base wage.", "type": "boolean" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "caregiver_name": { "description": "\"Last, First\". The CSV never carries it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "counties": { "description": "The clients' counties.", "items": { "nullable": true, "type": "string" }, "type": "array" }, "employee_id": { "description": "The caregiver's employee ID, the file's Unique Worker ID.", "nullable": true, "type": "string", "x-untrusted": "text" }, "employment_type": { "description": "\"Employee\" for every caregiver.", "nullable": true, "type": "string" }, "end_date": { "description": "The end of employment, only when it falls in the period.", "format": "date", "nullable": true, "type": "string" }, "hours": { "description": "The worked visits' payable hours in the period.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The row: the caregiver and the service.", "nullable": true, "type": "string" }, "members_served": { "description": "The distinct clients served.", "nullable": true, "type": "integer" }, "missing": { "description": "The cells the report could not fill; the row is kept with them blank.", "items": { "enum": [ "employee_id", "wage_rate", "primary_service", "county" ], "type": "string" }, "type": "array" }, "modifiers": { "description": "The visits' modifiers.", "items": { "nullable": true, "type": "string" }, "type": "array" }, "npi": { "description": "The agency's NPI.", "nullable": true, "type": "string" }, "primary_service": { "description": "The procedure code and modifiers, \"T1019 U1\"; null with no code.", "nullable": true, "type": "string" }, "procedure_code": { "description": "The visits' procedure code.", "nullable": true, "type": "string" }, "start_date": { "description": "The hire date, only when it falls in the period.", "format": "date", "nullable": true, "type": "string" }, "wage_missing_dates": { "description": "Days worked with no pay rate in force.", "items": { "format": "date", "nullable": true, "type": "string" }, "type": "array" }, "wage_rate": { "description": "The lowest work rate in force on a day worked (the client's own rate where one is set); null when none was.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "id", "caregiver_id" ], "title": "WorkforceReportRow", "type": "object" } }, "securitySchemes": { "bearer": { "description": "An agency API key, created on the agency's Settings page.", "scheme": "bearer", "type": "http" }, "caregiverBearer": { "description": "A caregiver app's device token, from POST /api/v1/caregiver-sessions. Accepted only on /api/v1/me, /api/v1/me/* and caregiver-sessions/current; an agency API key is refused there.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Read and write an agency's billing records. Authenticate with an agency API key as a bearer token. Every POST made with an API key needs an Idempotency-Key header, except one that only reads (validating a claims file); each operation that needs it lists it. Rate limits, per API key unless stated: 600 requests a minute; 1200 a minute across all of one agency's keys and AI app connections; 300 writes a minute and 20000 a day, and 50000 writes a day across all of one agency's keys and AI app connections; 30 claims-file upload attempts and 120 claims-file checks an hour; and 10 requests in progress at once on each server, of which 2 may be sending a body over 1 MB. Past a limit the answer is 429 rate_limited with a Retry-After header in seconds.", "title": "HomeCareBilling API", "version": "1" }, "openapi": "3.0.0", "paths": { "/api/v1/agency": { "get": { "callbacks": {}, "description": "The agency's name, address, NPI, Tax ID and claim defaults.", "operationId": "getAgency", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/AgencyProfile" } }, "required": [ "data" ], "type": "object" } } }, "description": "The profile" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "The agency profile", "tags": [ "Agency" ] }, "patch": { "callbacks": {}, "description": "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. and saves no part of the body.", "operationId": "patchAgency", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgencyProfileUpdate" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/AgencyProfile" } }, "required": [ "data" ], "type": "object" } } }, "description": "The profile" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change the agency profile", "tags": [ "Agency" ] } }, "/api/v1/agenda/today": { "get": { "callbacks": {}, "description": "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.", "operationId": "getAgendaToday", "parameters": [ { "description": "The day to look at (YYYY-MM-DD). Leave it out for today.", "in": "query", "name": "date", "schema": { "format": "date", "type": "string" } }, { "description": "Reminders due today to skip, to read past the first page.", "in": "query", "name": "due_today_offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Overdue reminders to skip, to read past the first page.", "in": "query", "name": "overdue_offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Agenda" } }, "required": [ "data" ], "type": "object" } } }, "description": "The agenda" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get today's agenda", "tags": [ "Agenda" ] } }, "/api/v1/api-keys": { "get": { "callbacks": {}, "description": "Live keys first, then newest first; never a secret. Needs Agency settings → View (403 forbidden otherwise).", "operationId": "getApiKeys", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "created_at": { "description": "When it was created (UTC).", "format": "date-time", "type": "string" }, "created_by_id": { "description": "The admin who created it.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_used_at": { "description": "Its last request (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "name": { "description": "The key's name.", "nullable": true, "type": "string" }, "revoked_at": { "description": "When it was revoked (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "role": { "description": "What the key may do.", "enum": [ "admin", "billing_staff" ], "type": "string" } }, "required": [ "id", "name", "role" ], "title": "AgencyApiKey", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "AgencyApiKeyPage", "type": "object" } } }, "description": "A page of keys" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List the agency's API keys", "tags": [ "Agency administration" ] }, "post": { "callbacks": {}, "description": "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.", "operationId": "postApiKeys", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "A name for the integration.", "type": "string" }, "role": { "description": "What the key may do.", "enum": [ "admin", "billing_staff" ], "type": "string" } }, "required": [ "name", "role" ], "title": "AgencyApiKeyCreate", "type": "object" } } }, "description": "The key", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "created_at": { "description": "When it was created (UTC).", "format": "date-time", "type": "string" }, "created_by_id": { "description": "The admin who created it.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_used_at": { "description": "Its last request (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "name": { "description": "The key's name.", "nullable": true, "type": "string" }, "revoked_at": { "description": "When it was revoked (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "role": { "description": "What the key may do.", "enum": [ "admin", "billing_staff" ], "type": "string" } }, "required": [ "id", "name", "role" ], "title": "AgencyApiKey", "type": "object" }, "secret": { "description": "The secret, shown this once.", "nullable": true, "type": "string" } }, "required": [ "data", "secret" ], "title": "AgencyApiKeyCreated", "type": "object" } } }, "description": "The key and its secret, once" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code web_only: Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code role_unavailable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create an API key", "tags": [ "Agency administration" ] } }, "/api/v1/api-keys/{id}": { "delete": { "callbacks": {}, "description": "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.", "operationId": "deleteApiKeysById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "created_at": { "description": "When it was created (UTC).", "format": "date-time", "type": "string" }, "created_by_id": { "description": "The admin who created it.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_used_at": { "description": "Its last request (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "name": { "description": "The key's name.", "nullable": true, "type": "string" }, "revoked_at": { "description": "When it was revoked (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "role": { "description": "What the key may do.", "enum": [ "admin", "billing_staff" ], "type": "string" } }, "required": [ "id", "name", "role" ], "title": "AgencyApiKey", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code web_only: Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Revoke an API key", "tags": [ "Agency administration" ] } }, "/api/v1/assignments": { "get": { "callbacks": {}, "description": "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.", "operationId": "getAssignments", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records with this status.", "in": "query", "name": "status", "schema": { "enum": [ "active", "inactive", "temporary", "closed" ], "type": "string" } }, { "description": "Only records of this client.", "in": "query", "name": "client_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only records of this caregiver.", "in": "query", "name": "caregiver_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only records changed at or after this instant (ISO 8601, with an offset), compared to the second. The list is then in change order: updated_at, then id.", "in": "query", "name": "updated_since", "schema": { "format": "date-time", "type": "string" } }, { "description": "With updated_since, a cursor: send the last record's updated_at as updated_since and its id as after_id to get the next page. Use this, not offset, to sync: an offset skips a record when an earlier one changes between two requests. The sync is at least once: timestamps are whole seconds and set before commit, so a record changed in the cursor's second, or committed late, can fall behind the cursor. Start each sync pass a minute before the newest updated_at you saw, and treat every record returned as current: apply it over what you hold. A record can change twice within one second, and not every change moves lock_version, so the same updated_at and lock_version do not mean the same content.", "in": "query", "name": "after_id", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Assignment" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "AssignmentPage", "type": "object" } } }, "description": "A page of assignments" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List assignments", "tags": [ "Assignments" ] }, "post": { "callbacks": {}, "operationId": "postAssignments", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignmentCreate" } } }, "description": "The assignment's fields", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Assignment" } }, "required": [ "data" ], "type": "object" } } }, "description": "The created assignment" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a assignment", "tags": [ "Assignments" ] } }, "/api/v1/assignments/schedule-import": { "post": { "callbacks": {}, "description": "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.", "operationId": "postAssignmentsScheduleImport", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "dry_run": { "description": "true: answer the items the import would add or change and write nothing. Left out or false: import.", "type": "boolean" }, "file": { "format": "binary", "type": "string" } }, "required": [ "file" ], "type": "object" } } }, "description": "A multipart form with InMyTeam's weekly schedule (Schedule in week view, printed to PDF) in the field `file`, at most 10 MB, and optionally dry_run.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ScheduleImportResult" } }, "required": [ "data" ], "type": "object" } } }, "description": "What the import did, or with dry_run true would do" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_a_schedule: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Import InMyTeam's weekly schedule PDF", "tags": [ "Assignments" ] } }, "/api/v1/assignments/{id}": { "get": { "callbacks": {}, "description": "Which caregiver serves which client, under which billing code.", "operationId": "getAssignmentsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Assignment" } }, "required": [ "data" ], "type": "object" } } }, "description": "The assignment" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no assignment with that id in this agency, including another agency's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a assignment", "tags": [ "Assignments" ] }, "patch": { "callbacks": {}, "description": "Sets only the fields sent. lock_version is required: send the value you read, and a record changed since answers 409 stale_record.", "operationId": "patchAssignmentsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignmentUpdate" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Assignment" } }, "required": [ "data" ], "type": "object" } } }, "description": "The updated assignment" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no assignment with that id in this agency, including another agency's." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "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." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a assignment", "tags": [ "Assignments" ] } }, "/api/v1/assignments/{id}/schedule": { "get": { "callbacks": {}, "description": "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.", "operationId": "getAssignmentsByIdSchedule", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/AssignmentSchedule" } }, "required": [ "data" ], "type": "object" } } }, "description": "The schedule" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read an assignment's weekly schedule", "tags": [ "Assignments" ] }, "put": { "callbacks": {}, "description": "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.", "operationId": "putAssignmentsByIdSchedule", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The shift to save, 1 to 4; default 1.", "in": "query", "name": "shift", "required": false, "schema": { "maximum": 4, "minimum": 1, "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "days": { "description": "The shift's days; an empty list clears the shift.", "items": { "properties": { "day_of_week": { "description": "The day.", "enum": [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" ], "type": "string" }, "end_time": { "description": "HH:MM or HH:MM:SS, 24-hour; after start_time, or at or before it when ends_next_day is true.", "type": "string" }, "ends_next_day": { "default": false, "description": "True for a shift that ends after midnight, on the next day (22:30 to 00:30); default false.", "type": "boolean" }, "start_time": { "description": "HH:MM or HH:MM:SS, 24-hour.", "type": "string" } }, "required": [ "day_of_week", "start_time", "end_time" ], "type": "object" }, "type": "array" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "shift_number": { "description": "The shift to save, 1 to 4, as GET names it; default 1. The shift query parameter does the same.", "maximum": 4, "minimum": 1, "type": "integer" } }, "required": [ "days", "lock_version" ], "title": "AssignmentScheduleSave", "type": "object" } } }, "description": "The shift's days", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/AssignmentSchedule" } }, "required": [ "data" ], "type": "object" } } }, "description": "The schedule" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code invalid_schedule: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Save one shift of an assignment's weekly schedule", "tags": [ "Assignments" ] } }, "/api/v1/assignments/{id}/timesheets": { "post": { "callbacks": {}, "description": "Makes the client and caregiver's timesheet for year and month from the assignment, with a blank entry per day, as Timesheets > New does. A month outside the assignment, an inactive assignment or one the Work Order already generated answers 422 or 409. A timesheet of another agency, or a deleted one, answers 404 and nothing is written.", "operationId": "postAssignmentsByIdTimesheets", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "month": { "description": "The month, 1 to 12.", "maximum": 12, "minimum": 1, "type": "integer" }, "year": { "description": "The year.", "maximum": 2100, "minimum": 2020, "type": "integer" } }, "required": [ "year", "month" ], "title": "TimesheetCreate", "type": "object" } } }, "description": "The month", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Timesheet" } }, "required": [ "data" ], "type": "object" } } }, "description": "The timesheet" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a month's timesheet from an assignment", "tags": [ "Timesheets" ] } }, "/api/v1/assignments/{id}/transition": { "post": { "callbacks": {}, "description": "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.", "operationId": "postAssignmentsByIdTransition", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "reason": { "description": "Why, kept in the status history.", "maxLength": 1000, "nullable": true, "type": "string" }, "status": { "description": "The new status.", "enum": [ "active", "inactive", "temporary", "closed" ], "type": "string" } }, "required": [ "status", "lock_version" ], "title": "AssignmentTransition", "type": "object" } } }, "description": "The new status", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Assignment" } }, "required": [ "data" ], "type": "object" } } }, "description": "The assignment" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes has_active_timesheets, invalid_transition: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change an assignment's status", "tags": [ "Assignments" ] } }, "/api/v1/assignments/{id}/work-orders/generate": { "post": { "callbacks": {}, "description": "Lays out the month's Work Order for this assignment's client and caregiver from the client's Plan of Care and the assignment's schedule, as the Plan of Care page's Generate does. A Work Order already in that slot answers 409 work_order_exists unless overwrite is true, which replaces its days. An assignment with no schedule for the shift answers 422 no_schedule. Warnings never stop the generation.", "operationId": "postAssignmentsByIdWorkOrdersGenerate", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lrp": { "description": "Optional: generate the Homemaker Work Order from the client's LRP (legally responsible person) Homemaker plan instead of the regular one, as that plan's page does. Default false.", "type": "boolean" }, "month": { "description": "The month, 1 to 12.", "maximum": 12, "minimum": 1, "type": "integer" }, "overwrite": { "description": "Optional: replace the days of a Work Order already in the slot. Default false.", "type": "boolean" }, "schedule_pattern": { "description": "Optional: the weekdays the Work Order runs on, as the Work Order takes them.", "items": { "type": "integer" }, "type": "array" }, "service_type_override": { "description": "Optional: generate this service instead of the assignment's own; legacy is one Work Order carrying both.", "enum": [ "homemaker", "legacy", "personal_care" ], "type": "string" }, "shift_number": { "description": "Optional: the shift, 1 to 4; default 1.", "maximum": 4, "minimum": 1, "type": "integer" }, "year": { "description": "The year.", "maximum": 2100, "minimum": 2020, "type": "integer" } }, "required": [ "month", "year" ], "title": "WorkOrderGenerate", "type": "object" } } }, "description": "The month and options", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/WorkOrder" }, "warnings": { "description": "What the generation found; never a refusal.", "items": { "type": "string" }, "type": "array" } }, "required": [ "data", "warnings" ], "type": "object" } } }, "description": "The Work Order and its warnings" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code work_order_exists: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code no_schedule: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Generate a month's Work Order from a Plan of Care", "tags": [ "Work orders" ] } }, "/api/v1/attention": { "get": { "callbacks": {}, "description": "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.", "operationId": "getAttention", "parameters": [ { "description": "Keep only one kind of row.", "in": "query", "name": "kind", "required": false, "schema": { "enum": [ "due_today", "overdue", "compliance", "oig", "supervisory_visit", "recertification", "authorization_ending", "follow_up" ], "type": "string" } }, { "description": "Rows per page (default 20, at most 100; a larger value is served as 100).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/AttentionRow" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "AttentionRowPage", "type": "object" } } }, "description": "A page of rows" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List what needs attention", "tags": [ "Agenda" ] } }, "/api/v1/audit-readiness": { "get": { "callbacks": {}, "description": "The summary's counts and a page (limit, offset) of the clients and caregivers with a gap, most missing first, as audit_readiness_summary returns it.", "operationId": "getAuditReadiness", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/AuditReadiness" } }, "required": [ "data" ], "type": "object" } } }, "description": "The summary" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get the agency's audit readiness", "tags": [ "Compliance" ] } }, "/api/v1/authorizations": { "get": { "callbacks": {}, "description": "A service authorization is a PAR: the units of a service HCPF authorized for a client. Each carries the units used, committed and remaining; those are the authorization's own figures, not a client-wide total. The agency's service authorizations in end-date order, soonest first, deleted ones left out unless include_deleted=true. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getAuthorizations", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records with this status.", "in": "query", "name": "status", "schema": { "enum": [ "pending", "active", "expired", "suspended" ], "type": "string" } }, { "description": "Only records of this client.", "in": "query", "name": "client_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only records of this HCPCS code, like T1019, in any letter case.", "in": "query", "name": "service_code", "schema": { "maxLength": 10, "type": "string" } }, { "description": "Only records changed at or after this instant (ISO 8601, with an offset), compared to the second. The list is then in change order: updated_at, then id.", "in": "query", "name": "updated_since", "schema": { "format": "date-time", "type": "string" } }, { "description": "With updated_since, a cursor: send the last record's updated_at as updated_since and its id as after_id to get the next page. Use this, not offset, to sync: an offset skips a record when an earlier one changes between two requests. The sync is at least once: timestamps are whole seconds and set before commit, so a record changed in the cursor's second, or committed late, can fall behind the cursor. Start each sync pass a minute before the newest updated_at you saw, and treat every record returned as current: apply it over what you hold. A record can change twice within one second, and not every change moves lock_version, so the same updated_at and lock_version do not mean the same content.", "in": "query", "name": "after_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "true also lists deleted records, with deleted_at set, so a sync learns of deletions.", "in": "query", "name": "include_deleted", "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ServiceAuthorization" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Service authorizationPage", "type": "object" } } }, "description": "A page of service authorizations" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List service authorizations", "tags": [ "Service authorizations" ] }, "post": { "callbacks": {}, "operationId": "postAuthorizations", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAuthorizationCreate" } } }, "description": "The service authorization's fields", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ServiceAuthorization" } }, "required": [ "data" ], "type": "object" } } }, "description": "The created service authorization" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a service authorization", "tags": [ "Service authorizations" ] } }, "/api/v1/authorizations/import": { "post": { "callbacks": {}, "description": "Reads InMyTeam's Authorization export as Import PARs does (format inmyteam_authorizations): each row one PAR service line, its PatientName matched to exactly one of the agency's clients, its Total read in 15-minute units. Needs imports.manage and authorizations.manage. A row whose client is not found, or found twice, fails with the reason. Any other file is 422 not_an_authorization_export. The file is csv (text) or csv_base64, header row first, at most 5,000 rows, in a body of at most 1 MB (the MCP tool takes a larger one). dry_run true runs the same import and rolls it all back, so the counts are the ones the real import would answer and nothing is written: no record, audit row or import history. Sending the same file again writes nothing twice: its rows are skipped with the reason already_on_file, also when two sends run at once. Refusals: 403 forbidden naming the missing permission; 422 file_required (no csv or csv_base64, or base64 that does not decode), empty_file, too_many_rows, csv_parse_error, invalid_dry_run; none writes anything.", "operationId": "postAuthorizationsImport", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "csv": { "description": "The file as CSV text, header row first.", "type": "string" }, "csv_base64": { "description": "Or the file's bytes, base64.", "type": "string" }, "dry_run": { "description": "true: answer what the import would do, counted the same way, and write nothing. Left out or false: import.", "type": "boolean" } }, "type": "object" } } }, "description": "The file", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/RecordImportResult" } }, "required": [ "data" ], "type": "object" } } }, "description": "What the import did, or with dry_run true would do" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes file_required, not_an_authorization_export: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Import PARs from InMyTeam's Authorization export", "tags": [ "Imports" ] } }, "/api/v1/authorizations/{id}": { "delete": { "callbacks": {}, "description": "Soft-deletes the PAR, as the web does. An active PAR answers 422 cannot_delete_active. lock_version is the one the PAR was read with: a PAR changed since answers 409 stale_record.", "operationId": "deleteAuthorizationsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The lock_version the record was read with: missing answers 400, changed since 409 stale_record.", "in": "query", "name": "lock_version", "required": true, "schema": { "description": "The value the record was read with; a record changed since answers 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ServiceAuthorization" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted authorization" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code cannot_delete_active: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a service authorization", "tags": [ "Service authorizations" ] }, "get": { "callbacks": {}, "description": "A service authorization is a PAR: the units of a service HCPF authorized for a client. Each carries the units used, committed and remaining; those are the authorization's own figures, not a client-wide total.", "operationId": "getAuthorizationsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ServiceAuthorization" } }, "required": [ "data" ], "type": "object" } } }, "description": "The service authorization" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no service authorization with that id in this agency, including another agency's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a service authorization", "tags": [ "Service authorizations" ] }, "patch": { "callbacks": {}, "description": "Sets only the fields sent. lock_version is required: send the value you read, and a record changed since answers 409 stale_record.", "operationId": "patchAuthorizationsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAuthorizationUpdate" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ServiceAuthorization" } }, "required": [ "data" ], "type": "object" } } }, "description": "The updated service authorization" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no service authorization with that id in this agency, including another agency's." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: the service authorization changed since the lock_version sent was read, or while this request ran. Nothing was saved; read it again and retry." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a service authorization", "tags": [ "Service authorizations" ] } }, "/api/v1/authorizations/{id}/recertifications": { "post": { "callbacks": {}, "operationId": "postAuthorizationsByIdRecertifications", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "case_manager": { "description": "The case manager handling the renewal.", "nullable": true, "type": "string" }, "notes": { "description": "Free text.", "nullable": true, "type": "string" }, "target_date": { "description": "When the renewal is due, YYYY-MM-DD; null leaves it unset.", "format": "date", "nullable": true, "type": "string" } }, "type": "object" } } }, "description": "The recertification", "required": false }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Recertification" } }, "required": [ "data" ], "type": "object" } } }, "description": "The recertification, requested" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Start a PAR's recertification", "tags": [ "Service authorizations" ] } }, "/api/v1/authorizations/{id}/transition": { "post": { "callbacks": {}, "description": "Moves the PAR to status, as the web's status buttons do; a transition the PAR's status does not allow answers 422 validation_failed. lock_version is the one the PAR was read with: a PAR changed since answers 409 stale_record.", "operationId": "postAuthorizationsByIdTransition", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "status": { "description": "The new status.", "enum": [ "pending", "active", "expired", "suspended" ], "type": "string" } }, "required": [ "status", "lock_version" ], "type": "object" } } }, "description": "The new status", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ServiceAuthorization" } }, "required": [ "data" ], "type": "object" } } }, "description": "The authorization" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a service authorization's status", "tags": [ "Service authorizations" ] } }, "/api/v1/batches": { "get": { "callbacks": {}, "description": "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.", "operationId": "getBatches", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records with this status.", "in": "query", "name": "status", "schema": { "enum": [ "pending", "validating", "validated", "generating", "generated", "submitting", "submitted", "processing", "completed", "partially_completed", "failed", "cancelled" ], "type": "string" } }, { "description": "Only records changed at or after this instant (ISO 8601, with an offset), compared to the second. The list is then in change order: updated_at, then id.", "in": "query", "name": "updated_since", "schema": { "format": "date-time", "type": "string" } }, { "description": "With updated_since, a cursor: send the last record's updated_at as updated_since and its id as after_id to get the next page. Use this, not offset, to sync: an offset skips a record when an earlier one changes between two requests. The sync is at least once: timestamps are whole seconds and set before commit, so a record changed in the cursor's second, or committed late, can fall behind the cursor. Start each sync pass a minute before the newest updated_at you saw, and treat every record returned as current: apply it over what you hold. A record can change twice within one second, and not every change moves lock_version, so the same updated_at and lock_version do not mean the same content.", "in": "query", "name": "after_id", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Batch" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "BatchPage", "type": "object" } } }, "description": "A page of batches" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List batches", "tags": [ "Batches" ] }, "post": { "callbacks": {}, "description": "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.", "operationId": "postBatches", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "multipart/form-data": { "encoding": { "column_mapping": { "contentType": "application/json" } }, "schema": { "properties": { "column_mapping": { "additionalProperties": { "type": "string" }, "description": "Optional, as {field: column header}, for example {\"member_id\": \"Medicaid #\"}, applied over the agency's saved mapping as POST /api/v1/batches/validate applies it.", "type": "object" }, "file": { "format": "binary", "type": "string" }, "save_mapping": { "description": "Keep the mapping this file was read with as the agency's saved one once the batch is stored, as Upload claims keeps matched columns.", "type": "boolean" } }, "required": [ "file" ], "type": "object" } } }, "description": "A multipart form with the claims file in the field `file` (.csv or .xlsx), optionally which column holds which claim field, and whether to keep that mapping.", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Batch" }, "warnings": { "items": { "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "type": "object" } } }, "description": "The created batch, and any warning" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code submission_blocked: Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code unmapped_columns: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Upload a claims file", "tags": [ "Batches" ] } }, "/api/v1/batches/from-timesheets": { "post": { "callbacks": {}, "description": "Bills the approved timesheets among timesheet_ids as one batch, as Billing > Generate batch does: each is mapped to its claims (PAR numbers found), the claims are priced, and the batch validates in the background; it is never submitted automatically. left_out names every selected timesheet not in it, in the order sent, and why (not approved, already billed, no hours, missing billing data); warnings says when charges could not be calculated, and carries every warning Billing > Generate batch shows for the selection (code, message, record_type, record_id, and the dismiss_key of one the agency may dismiss there), less the ones the agency already dismissed on the page, over /api/v1 or over MCP; findings carries the same warnings as findings (rule_id, message, subject_type, subject_id, subject_date, fingerprint, context, dismissible), each one dismissible with POST /api/v1/finding-dismissals as sent; none of them blocks the batch. Refused, creating nothing: 422 critical_issues with the issues when the selection breaks a blocking rule (a missing Medicaid ID or billing code, a strict modifier rule), as the page refuses; 422 nothing_billable with left_out when no selected timesheet has a claim; 409 timesheets_already_exported or stale_record when a selected timesheet was billed or changed meanwhile, or the client, assignment, work order or service authorization its claims bill from changed; 403 submission_blocked when the agency may not submit. 422 timesheet_ids_required when timesheet_ids is not a list of 1 to 500 UUIDs (an id that is not a UUID refuses the whole request). Ids are answered in lower case. Another agency's ids are left out as not approved, and nothing of theirs is read or written.", "operationId": "postBatchesFromTimesheets", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "timesheet_ids": { "description": "The approved timesheets to bill (find_timesheets with status approved).", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "maxItems": 500, "minItems": 1, "type": "array" } }, "required": [ "timesheet_ids" ], "type": "object" } } }, "description": "The timesheets", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Batch" }, "findings": { "items": { "properties": { "context": { "description": "The inputs the warning was found from beyond its subject.", "type": "object" }, "dismissible": { "description": "Whether the agency may dismiss it.", "type": "boolean" }, "fingerprint": { "description": "The figures the warning states, as a dismissal names them.", "nullable": true, "type": "string" }, "message": { "description": "What the warning says.", "nullable": true, "type": "string" }, "rule_id": { "description": "The warning's rule (batch.hospital_day, say).", "nullable": true, "type": "string" }, "subject_date": { "description": "The day, for a warning about one day of its subject.", "format": "date", "nullable": true, "type": "string" }, "subject_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "subject_type": { "description": "What the warning is about (client, say).", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "left_out": { "items": { "properties": { "reason": { "description": "Why it is not in the batch.", "nullable": true, "type": "string" }, "timesheet_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "type": "object" }, "type": "array" }, "warnings": { "items": { "type": "object" }, "type": "array" } }, "required": [ "data", "left_out", "warnings", "findings" ], "type": "object" } } }, "description": "The batch, the timesheets left out, and any warning" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code submission_blocked: Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code timesheets_already_exported: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes critical_issues, nothing_billable, timesheet_ids_required: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a batch from approved timesheets", "tags": [ "Claims", "Batches" ] } }, "/api/v1/batches/validate": { "post": { "callbacks": {}, "description": "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.", "operationId": "postBatchesValidate", "parameters": [], "requestBody": { "content": { "multipart/form-data": { "encoding": { "column_mapping": { "contentType": "application/json" } }, "schema": { "properties": { "column_mapping": { "additionalProperties": { "type": "string" }, "description": "Optional. Which column holds which claim field, as {field: column header}, for example {\"member_id\": \"Medicaid #\"}: over /api/v1 a JSON part, or form fields column_mapping[member_id]=Medicaid #. Applied over the agency's saved mapping for this check only; a field a claim does not have or a column the sheet lacks is refused with 422 unknown_mapping_fields or mapping_columns_missing.", "type": "object" }, "file": { "format": "binary", "type": "string" } }, "required": [ "file" ], "type": "object" } } }, "description": "A multipart form with the claims file in the field `file` (.csv or .xlsx), and optionally which column holds which claim field.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "errors": { "items": { "properties": { "code": { "description": "Stable, e.g. required or invalid_format.", "type": "string" }, "field": { "description": "The claim field.", "type": "string" }, "message": { "description": "For a person to read.", "type": "string" } }, "type": "object" }, "type": "array" }, "row_number": { "type": "integer" }, "warnings": { "description": "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.", "items": { "properties": { "code": { "description": "Stable, e.g. required or invalid_format.", "type": "string" }, "field": { "description": "The claim field.", "type": "string" }, "message": { "description": "For a person to read.", "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "row_number", "errors", "warnings" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Every row, its errors and its warnings" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Validate a claims file without storing it", "tags": [ "Batches" ] } }, "/api/v1/batches/{id}": { "delete": { "callbacks": {}, "description": "Deletes the batch and its claims, returning its returned timesheets to approved so they can be billed again, as the batch page does. A batch already sent to HCPF, or being sent, answers 422 already_submitted or submission_in_progress; one being validated or generated now 422 not_eligible; the batch of a recurring run already sent 422 run_submitted. Another agency's batch or claim answers 404 and nothing is written.", "operationId": "deleteBatchesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Batch" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted batch" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_submitted, not_eligible, run_submitted: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a batch not yet sent", "tags": [ "Claims", "Batches" ] }, "get": { "callbacks": {}, "description": "A batch is one uploaded claims file and the claims made from it.", "operationId": "getBatchesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Batch" } }, "required": [ "data" ], "type": "object" } } }, "description": "The batch" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no batch with that id in this agency, including another agency's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a batch", "tags": [ "Batches" ] } }, "/api/v1/batches/{id}/837": { "get": { "callbacks": {}, "description": "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.", "operationId": "getBatchesById837", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/edi-x12": { "schema": { "format": "binary", "type": "string" } } }, "description": "The 837 file" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Download a batch's 837 file", "tags": [ "Batches" ] } }, "/api/v1/batches/{id}/prepare-resubmissions": { "post": { "callbacks": {}, "description": "Releases the returned timesheet of every claim in the batch that can be resubmitted, as the batch page's Prepare all control does, and answers how many timesheets went back to Approved and the claims prepared. Needs billing.manage (403 forbidden otherwise). A batch with none eligible answers 422 no_resubmittable_claims; one whose every eligible claim is blocked by an active claim holding its patient account number 409 all_pan_blocked. Another agency's batch or claim answers 404 and nothing is written.", "operationId": "postBatchesByIdPrepareResubmissions", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "claims": { "items": { "$ref": "#/components/schemas/Claim" }, "type": "array" }, "timesheets_released": { "type": "integer" } }, "required": [ "timesheets_released", "claims" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The timesheets released and the claims prepared" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code all_pan_blocked: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code no_resubmittable_claims: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Release every refused claim's timesheet in a batch", "tags": [ "Claims", "Batches" ] } }, "/api/v1/batches/{id}/recurring-proposal": { "get": { "callbacks": {}, "description": "As the batch page's Make recurring dialog proposes it: the cadence and period 1 read from the claims' service dates, the default name and send settings (auto, 09:00 Mountain, on the weekday the batch was sent), and one page of the batch's claims, each with the warnings it would carry (lines_total counts them all). Computed on every call and never stored. Refused: 422 not_upload_source for a batch not made from an uploaded file, 422 not_proposable when the claims cannot repeat as one week, two weeks or a month (the message says why), 403 submission_blocked or insufficient_scope as Submit refuses. Another agency's batch answers 404 not_found.", "operationId": "getBatchesByIdRecurringProposal", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 50, at most 100; a larger value is served as 100).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "anchor_date": { "description": "Period 0's first day.", "format": "date", "nullable": true, "type": "string" }, "batch_id": { "description": "The batch.", "format": "uuid", "type": "string" }, "cadence": { "enum": [ "weekly", "biweekly", "monthly" ], "type": "string" }, "limit": { "type": "integer" }, "lines": { "items": { "type": "object" }, "type": "array" }, "lines_total": { "type": "integer" }, "name": { "type": "string" }, "offset": { "type": "integer" }, "period": { "nullable": true, "properties": { "period_end": { "description": "The last day billed.", "format": "date", "nullable": true, "type": "string" }, "period_start": { "description": "The first day billed.", "format": "date", "nullable": true, "type": "string" } }, "required": [ "period_start", "period_end" ], "title": "RecurringPeriod", "type": "object" }, "submit_mode": { "enum": [ "auto", "approval" ], "type": "string" }, "submit_time": { "format": "time", "type": "string" }, "submit_weekday": { "type": "integer" } }, "title": "RecurringProposal", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The proposal" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code submission_blocked: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes not_proposable, not_upload_source: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "What Make recurring would create from a batch", "tags": [ "Recurring batches" ] } }, "/api/v1/batches/{id}/revenue-warnings": { "get": { "callbacks": {}, "description": "Every revenue warning on the batch's claims, in row order, each saying whether a member dismissed it. A warning blocks nothing. The batch's claims are read to the upload's row ceiling, and the warnings paged from them. Another agency's batch is 404.", "operationId": "getBatchesByIdRevenueWarnings", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/RevenueWarning" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "RevenueWarningPage", "type": "object" } } }, "description": "The warnings" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a batch's revenue warnings", "tags": [ "Claims" ] } }, "/api/v1/batches/{id}/submit": { "post": { "callbacks": {}, "description": "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.", "operationId": "postBatchesByIdSubmit", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "description": "The batch id.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Batch" } }, "required": [ "data" ], "type": "object" } } }, "description": "The batch, as it stands once the submission is queued" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes read_only, submission_blocked: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes batch_not_submittable, submission_blocked, submission_held: Unprocessable Content, as the operation's description says." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal Server Error, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Submit a batch to HCPF", "tags": [ "Batches" ] } }, "/api/v1/billing-codes": { "get": { "callbacks": {}, "description": "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.", "operationId": "getBillingCodes", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/BillingCode" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "BillingCodePage", "type": "object" } } }, "description": "A page of billing codes" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List billing codes", "tags": [ "Billing codes" ] } }, "/api/v1/broadcasts": { "get": { "callbacks": {}, "description": "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.", "operationId": "getBroadcasts", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "delivery_method": { "description": "How it went out.", "enum": [ "email", "sms", "both" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "message": { "description": "What it said.", "nullable": true, "type": "string", "x-untrusted": "text" }, "recipient_count": { "description": "Caregivers sent to.", "type": "integer" }, "reply_count": { "description": "Caregivers who texted back to it.", "type": "integer" }, "sent_at": { "description": "When it was sent (UTC).", "format": "date-time", "type": "string" }, "skipped_count": { "description": "Caregivers skipped: no contact for the method, or opted out of SMS.", "type": "integer" }, "yes_count": { "description": "Of those, how many replies read as a yes.", "type": "integer" } }, "required": [ "id", "delivery_method", "recipient_count" ], "title": "BroadcastSummary", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "BroadcastPage", "type": "object" } } }, "description": "A page of broadcasts" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List broadcasts", "tags": [ "Broadcasts and notifications" ] }, "post": { "callbacks": {}, "description": "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.", "operationId": "postBroadcasts", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "caregiver_ids": { "description": "pick: the caregivers to send to, whatever their status (former ones included). At most 1000.", "items": { "description": "A caregiver of the agency.", "format": "uuid", "type": "string" }, "type": "array" }, "delivery_method": { "description": "How to send it: email, sms or both. Leave it out for email.", "enum": [ "email", "sms", "both" ], "type": "string" }, "include_former": { "description": "With tag: also caregivers no longer active. Leave it out for active only.", "type": "boolean" }, "message": { "description": "The message.", "type": "string" }, "recipient_scope": { "description": "Who to send it to. Leave it out for all, or for pick when caregiver_ids or tag is given.", "enum": [ "all", "expired", "expiring_soon", "training", "evaluation", "pick" ], "type": "string" }, "tag": { "description": "pick: every caregiver carrying this tag (any case).", "type": "string" } }, "required": [ "message" ], "title": "BroadcastCreate", "type": "object" } } }, "description": "The broadcast", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "delivery_method": { "description": "How it went out.", "enum": [ "email", "sms", "both" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "recipient_count": { "description": "Caregivers sent to.", "type": "integer" }, "recipient_scope": { "description": "Who it went to.", "enum": [ "all", "expired", "expiring_soon", "training", "evaluation", "pick" ], "type": "string" }, "reply_count": { "description": "Caregivers who texted back to it (#2567).", "type": "integer" }, "sent_at": { "description": "When it was sent (UTC).", "format": "date-time", "type": "string" }, "skipped_count": { "description": "Caregivers skipped: no contact for the method, or opted out of SMS.", "type": "integer" }, "yes_count": { "description": "Of those, how many replies read as a yes.", "type": "integer" } }, "required": [ "id", "delivery_method", "recipient_count" ], "title": "Broadcast", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The broadcast sent" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes no_recipients, validation_failed: Unprocessable Content, as the operation's description says." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code rate_limited: Too Many Requests, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Send a broadcast to caregivers", "tags": [ "Broadcasts and notifications" ] } }, "/api/v1/broadcasts/{id}/replies": { "get": { "callbacks": {}, "description": "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.", "operationId": "getBroadcastsByIdReplies", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "caregiver_id": { "description": "The caregiver who replied.", "format": "uuid", "type": "string" }, "caregiver_name": { "description": "The caregiver, last name first.", "nullable": true, "type": "string", "x-untrusted": "text" }, "replied_at": { "description": "When it arrived (UTC).", "format": "date-time", "type": "string" }, "reply": { "description": "Their latest text back.", "nullable": true, "type": "string", "x-untrusted": "text" }, "yes": { "description": "Whether the reply reads as a yes.", "type": "boolean" } }, "required": [ "caregiver_id", "reply", "yes" ], "title": "BroadcastReply", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "BroadcastReplyPage", "type": "object" } } }, "description": "A page of replies" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a broadcast's replies", "tags": [ "Broadcasts and notifications" ] } }, "/api/v1/calendar-events/{id}/restore": { "post": { "callbacks": {}, "description": "As the Today page's Undo does: puts the event back to the status and due date it had, upcoming or overdue, and clears any completion. A done or dismissed status is 422; use complete or dismiss for those. One changed by another write while this request ran answers 409 stale_record, and nothing is saved.", "operationId": "postCalendarEventsByIdRestore", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "due_date": { "description": "The day it was due, YYYY-MM-DD.", "format": "date", "nullable": true, "type": "string" }, "due_time": { "description": "The time it was due, HH:MM:SS, Mountain time.", "nullable": true, "type": "string" }, "status": { "description": "The status it had.", "enum": [ "upcoming", "overdue" ], "type": "string" } }, "required": [ "status" ], "title": "ClientCalendarEventRestore", "type": "object" } } }, "description": "The state to restore", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "client_id": { "description": "The client it is about.", "format": "uuid", "type": "string" }, "completed_at": { "description": "When it was done.", "format": "date-time", "nullable": true, "type": "string" }, "description": { "description": "More about it.", "nullable": true, "type": "string" }, "due_date": { "description": "The day it is due.", "format": "date", "nullable": true, "type": "string" }, "due_time": { "description": "A time of day, HH:MM:SS (Mountain time).", "nullable": true, "type": "string" }, "event_type": { "enum": [ "supervisory_visit", "recertification", "follow_up", "custom" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "lock_version": { "description": "Its version.", "nullable": true, "type": "integer" }, "status": { "enum": [ "upcoming", "overdue", "completed", "dismissed" ], "type": "string" }, "title": { "description": "What is due.", "nullable": true, "type": "string" } }, "required": [ "id", "client_id", "event_type", "title", "due_date", "status", "lock_version" ], "title": "ClientCalendarEvent", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The event" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Undo a change to a calendar event", "tags": [ "Client records" ] } }, "/api/v1/care-logs": { "get": { "callbacks": {}, "description": "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.", "operationId": "getCareLogs", "parameters": [ { "description": "Rows per page (default 50, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only this client's.", "in": "query", "name": "client_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only this caregiver's.", "in": "query", "name": "caregiver_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Service dates on or after, YYYY-MM-DD.", "in": "query", "name": "from", "schema": { "format": "date", "type": "string" } }, { "description": "Service dates on or before, YYYY-MM-DD.", "in": "query", "name": "to", "schema": { "format": "date", "type": "string" } }, { "description": "Where it was captured.", "in": "query", "name": "source", "schema": { "enum": [ "hcb_app", "hcb_phone", "office", "paper_scan", "import" ], "type": "string" } }, { "description": "The record state.", "in": "query", "name": "state", "schema": { "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" } }, { "description": "true: only the care logs still needing the client's signature (drafts), as the screen's Needs client signature box. false or left out filters nothing.", "in": "query", "name": "needs_signature", "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/CareLog" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "CareLogPage", "type": "object" } } }, "description": "A page of care logs" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List care logs", "tags": [ "Care logs" ] }, "post": { "callbacks": {}, "description": "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.", "operationId": "postCareLogs", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "notes": { "description": "The day's notes.", "nullable": true, "type": "string", "x-untrusted": "text" }, "service_date": { "description": "The day.", "format": "date", "nullable": false, "type": "string" }, "service_type": { "description": "The service, as the Work Order's.", "enum": [ "personal_care", "homemaker", "legacy" ], "type": "string" }, "shift_number": { "description": "The shift, 1 to 4 (default 1).", "maximum": 4, "minimum": 1, "type": "integer" }, "time_in": { "description": "The start time, ISO 8601. Sent with time_out or notes, the start records the day: a care log already on the key with the same content is answered as it is, one with different content 409 stale.", "format": "date-time", "nullable": true, "type": "string" }, "time_out": { "description": "The end time, ISO 8601, at or after time_in.", "format": "date-time", "nullable": true, "type": "string" }, "visit_id": { "description": "The Visit to link: the agency's, of the same client, caregiver and day. Left out, the day's one such Visit is linked when exactly one exists.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "client_id", "caregiver_id", "service_date", "service_type" ], "title": "CareLogStart", "type": "object" } } }, "description": "The day", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CareLogDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The care log already holding the day" }, "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CareLogDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The care log started" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code visit_mismatch: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Start a care log", "tags": [ "Care logs" ] } }, "/api/v1/care-logs/{id}": { "get": { "callbacks": {}, "description": "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.", "operationId": "getCareLogsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CareLogDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The care log" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read a care log", "tags": [ "Care logs" ] }, "patch": { "callbacks": {}, "description": "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.", "operationId": "patchCareLogsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "notes": { "description": "The day's notes; null clears them.", "nullable": true, "type": "string", "x-untrusted": "text" }, "time_in": { "description": "The start time, ISO 8601; used only when no Visit is linked. null clears it.", "format": "date-time", "nullable": true, "type": "string" }, "time_out": { "description": "The end time, ISO 8601, after time_in; used only when no Visit is linked. null clears it.", "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "lock_version" ], "title": "CareLogUpdate", "type": "object" } } }, "description": "The fields to set", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CareLogDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The care log" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes record_locked, stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Edit a care log's notes and times", "tags": [ "Care logs" ] } }, "/api/v1/care-logs/{id}/finish": { "post": { "callbacks": {}, "description": "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.", "operationId": "postCareLogsByIdFinish", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CareLogDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The care log" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code record_locked: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Finish a care log", "tags": [ "Care logs" ] } }, "/api/v1/care-logs/{id}/paper-on-file": { "post": { "callbacks": {}, "description": "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.", "operationId": "postCareLogsByIdPaperOnFile", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "document_id": { "description": "A document already on the client's file holding the paper scan; left out, the mark carries no scan.", "format": "uuid", "nullable": true, "type": "string" } }, "title": "CareLogPaperOnFile", "type": "object" } }, "multipart/form-data": { "schema": { "properties": { "file": { "format": "binary", "type": "string" } }, "type": "object" } } }, "description": "The scan, if any", "required": false }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CareLogDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The care log, signed" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code signature_requires_person: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes record_locked, role_already_signed, scan_pending: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes document_not_found, invalid_scan, scan_not_clean: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Mark a care log's paper signature on file", "tags": [ "Care logs" ] } }, "/api/v1/care-logs/{id}/tasks": { "post": { "callbacks": {}, "description": "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.", "operationId": "postCareLogsByIdTasks", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "How many times; 1 when left out.", "minimum": 1, "type": "integer" }, "reason_code": { "description": "Why it was done off the plan.", "enum": [ "client_declined", "client_not_home", "client_asleep_or_unwell", "done_by_someone_else", "not_needed_today", "client_requested", "care_need_changed", "other" ], "nullable": true, "type": "string" }, "reason_note": { "description": "The reason in words.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "Its status; done when left out.", "enum": [ "done", "refused", "not_needed" ], "type": "string" }, "task_definition_id": { "description": "The task to add: one of the agency's tasks or a system one.", "format": "uuid", "type": "string" } }, "required": [ "task_definition_id" ], "title": "CareLogTaskAdd", "type": "object" } } }, "description": "The task", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CareLogDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The care log" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code record_locked: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code task_definition_not_found: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Add a task to a care log", "tags": [ "Care logs" ] } }, "/api/v1/care-logs/{id}/tasks/{task_id}/mark": { "post": { "callbacks": {}, "description": "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.", "operationId": "postCareLogsByIdTasksByTaskIdMark", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The task's task_definition_id, as the care log's tasks list it.", "in": "path", "name": "task_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "How many times; unchanged when left out.", "minimum": 1, "type": "integer" }, "reason_code": { "description": "Why a task was refused or not needed; left out or null clears it, as a mark on the screen does.", "enum": [ "client_declined", "client_not_home", "client_asleep_or_unwell", "done_by_someone_else", "not_needed_today", "client_requested", "care_need_changed", "other" ], "nullable": true, "type": "string" }, "reason_note": { "description": "The reason in words; left out or null clears it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "The status to SET: done, refused or not_needed; null clears it. Sending the status the task already has changes nothing.", "enum": [ "done", "refused", "not_needed" ], "nullable": true, "type": "string" } }, "required": [ "status" ], "title": "CareLogTaskMark", "type": "object" } } }, "description": "The mark", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CareLogDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The care log" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code record_locked: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code task_not_on_log: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Mark a care log's task", "tags": [ "Care logs" ] } }, "/api/v1/caregiver-notes/{id}": { "delete": { "callbacks": {}, "description": "Soft-deletes the note and its attachments, as the caregiver's communication log does. Notes carry no lock_version.", "operationId": "deleteCaregiverNotesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CaregiverNote" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted note" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a caregiver communication note", "tags": [ "Deletes and restores" ] }, "patch": { "callbacks": {}, "description": "Sets only the fields sent; a field sent as null is cleared, and a required one is refused. A body that changes nothing is 422 nothing_to_change. Notes carry no lock_version: the row is locked and re-read for the change.", "operationId": "patchCaregiverNotesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaregiverNoteInput" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CaregiverNote" } }, "required": [ "data" ], "type": "object" } } }, "description": "The note" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code nothing_to_change: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a caregiver note", "tags": [ "Communication notes" ] } }, "/api/v1/caregiver-notes/{id}/attachments": { "get": { "callbacks": {}, "description": "Oldest first, as the note page shows them, each with its scan status.", "operationId": "getCaregiverNotesByIdAttachments", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "content_type": { "description": "Its type.", "nullable": true, "type": "string" }, "file_size": { "description": "Its size in bytes.", "nullable": true, "type": "integer" }, "filename": { "description": "The file's name.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was attached.", "format": "date-time", "type": "string" }, "note_id": { "description": "The note.", "format": "uuid", "type": "string" }, "note_kind": { "description": "The kind of note it is on.", "enum": [ "client", "caregiver" ], "type": "string" }, "scan_status": { "description": "The virus scan's verdict; only a clean file can be downloaded.", "enum": [ "pending", "clean", "infected", "error" ], "type": "string" }, "uploaded_by_id": { "description": "Who attached it.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "note_kind", "note_id", "filename", "content_type", "file_size", "scan_status" ], "title": "NoteAttachment", "type": "object" }, "type": "array" } }, "required": [ "data" ], "title": "NoteAttachmentList", "type": "object" } } }, "description": "The note's attachments" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a caregiver note's attachments", "tags": [ "Communication notes" ] }, "post": { "callbacks": {}, "description": "Attaches a file as the note page's upload does: image/png, image/jpeg, image/gif, image/webp, application/pdf, up to 10 MB, at most 50 on a note, its extension matching its type and its bytes matching both. A refused file writes nothing and answers 422 naming the rule. The file is virus-scanned after it is saved and cannot be downloaded until its scan_status is clean.", "operationId": "postCaregiverNotesByIdAttachments", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "format": "binary", "type": "string" } }, "required": [ "file" ], "type": "object" } } }, "description": "The file", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "content_type": { "description": "Its type.", "nullable": true, "type": "string" }, "file_size": { "description": "Its size in bytes.", "nullable": true, "type": "integer" }, "filename": { "description": "The file's name.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was attached.", "format": "date-time", "type": "string" }, "note_id": { "description": "The note.", "format": "uuid", "type": "string" }, "note_kind": { "description": "The kind of note it is on.", "enum": [ "client", "caregiver" ], "type": "string" }, "scan_status": { "description": "The virus scan's verdict; only a clean file can be downloaded.", "enum": [ "pending", "clean", "infected", "error" ], "type": "string" }, "uploaded_by_id": { "description": "Who attached it.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "note_kind", "note_id", "filename", "content_type", "file_size", "scan_status" ], "title": "NoteAttachment", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The attachment" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code internal_error: a failure on our side, which was logged. When its message says nothing changed (the file store refused the request, the virus scan could not be queued, the upload could not be read), nothing did, the same request fails the same way until it is fixed, and the Idempotency-Key stays free." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code storage_unavailable (the file store did not answer) or, on an upload, temporarily_unavailable (its uploaded file could not be read): nothing changed, and the same request can succeed later. Retry after the Retry-After seconds; a write retried with the same Idempotency-Key runs again.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (30).", "schema": { "type": "integer" }, "style": "simple" } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Attach a file to a caregiver note", "tags": [ "Communication notes" ] } }, "/api/v1/caregiver-sessions": { "post": { "callbacks": {}, "description": "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.", "operationId": "postCaregiverSessions", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaregiverSessionInput" } } }, "description": "The caregiver's credentials", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CaregiverSession" } }, "required": [ "data" ], "type": "object" } } }, "description": "The device token" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code invalid_credentials: Unauthorized, as the operation's description says." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code rate_limited: Too Many Requests, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [], "summary": "Sign in a caregiver", "tags": [ "Caregiver app" ] } }, "/api/v1/caregiver-sessions/current": { "delete": { "callbacks": {}, "description": "Revokes the device token sent as the bearer credential. The token is refused from then on, here and in the caregiver web app.", "operationId": "deleteCaregiverSessionsCurrent", "parameters": [], "responses": { "204": { "description": "Signed out" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Sign out this device", "tags": [ "Caregiver app" ] } }, "/api/v1/caregivers": { "get": { "callbacks": {}, "description": "The agency's caregivers in name order, deleted ones left out unless include_deleted=true. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getCaregivers", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records with this status.", "in": "query", "name": "status", "schema": { "enum": [ "active", "inactive", "on_leave", "terminated", "potential" ], "type": "string" } }, { "description": "Every word must match a returned name or identifier, case-insensitively. At most 100 characters and 8 words.", "in": "query", "name": "search", "schema": { "maxLength": 100, "type": "string" } }, { "description": "Only records changed at or after this instant (ISO 8601, with an offset), compared to the second. The list is then in change order: updated_at, then id.", "in": "query", "name": "updated_since", "schema": { "format": "date-time", "type": "string" } }, { "description": "With updated_since, a cursor: send the last record's updated_at as updated_since and its id as after_id to get the next page. Use this, not offset, to sync: an offset skips a record when an earlier one changes between two requests. The sync is at least once: timestamps are whole seconds and set before commit, so a record changed in the cursor's second, or committed late, can fall behind the cursor. Start each sync pass a minute before the newest updated_at you saw, and treat every record returned as current: apply it over what you hold. A record can change twice within one second, and not every change moves lock_version, so the same updated_at and lock_version do not mean the same content.", "in": "query", "name": "after_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "true also lists deleted records, with deleted_at set, so a sync learns of deletions.", "in": "query", "name": "include_deleted", "schema": { "type": "boolean" } }, { "description": "Only caregivers whose text_status is this value; cannot_text is every value but can_text.", "in": "query", "name": "text_status", "schema": { "enum": [ "cannot_text", "can_text", "no_cell_phone", "opted_out", "no_consent", "not_verified", "phone_changed", "last_text_failed" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Caregiver" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "CaregiverPage", "type": "object" } } }, "description": "A page of caregivers" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List caregivers", "tags": [ "Caregivers" ] }, "post": { "callbacks": {}, "operationId": "postCaregivers", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaregiverInput" } } }, "description": "The caregiver's fields", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Caregiver" }, "warnings": { "description": "What the act was done with that the agency may want to fix; usually empty. Never a refusal: the act was done.", "items": { "properties": { "fix": { "description": "Where it is fixed, when a page fixes it.", "nullable": true, "properties": { "label": { "description": "What the link says.", "type": "string" }, "path": { "description": "The app route that fixes it.", "type": "string" } }, "required": [ "path", "label" ], "type": "object" }, "id": { "description": "The rule that raised it, stable, e.g. client_care.medicaid_id_pending.", "type": "string" }, "message": { "description": "For a person to read.", "type": "string" } }, "required": [ "id", "message" ], "title": "Warning", "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "title": "CaregiverWriteResult", "type": "object" } } }, "description": "The created caregiver" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a caregiver", "tags": [ "Caregivers" ] } }, "/api/v1/caregivers/import": { "post": { "callbacks": {}, "description": "Reads the file as Import Caregivers does: HCB's caregiver columns, or InMyTeam's Caregivers export (format inmyteam_caregivers), whose office roles are skipped as office_staff. Needs imports.manage. A key whose member lacks payroll.manage imports each caregiver without the row's pay rates, W-4 and ADP fields, lists the row under reasons.pay_rates_skipped and answers pay_withheld with the count and the words for it. The file is csv (text) or csv_base64, header row first, at most 5,000 rows, in a body of at most 1 MB (the MCP tool takes a larger one). dry_run true runs the same import and rolls it all back, so the counts are the ones the real import would answer and nothing is written: no record, audit row or import history. Sending the same file again writes nothing twice: its rows are skipped with the reason already_on_file, also when two sends run at once. Refusals: 403 forbidden naming the missing permission; 422 file_required (no csv or csv_base64, or base64 that does not decode), empty_file, too_many_rows, csv_parse_error, invalid_dry_run; none writes anything.", "operationId": "postCaregiversImport", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "csv": { "description": "The file as CSV text, header row first.", "type": "string" }, "csv_base64": { "description": "Or the file's bytes, base64.", "type": "string" }, "dry_run": { "description": "true: answer what the import would do, counted the same way, and write nothing. Left out or false: import.", "type": "boolean" } }, "type": "object" } } }, "description": "The file", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/RecordImportResult" } }, "required": [ "data" ], "type": "object" } } }, "description": "What the import did, or with dry_run true would do" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code file_required: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Import caregivers from a CSV file", "tags": [ "Imports" ] } }, "/api/v1/caregivers/status": { "patch": { "callbacks": {}, "description": "US-109.7: sets status on up to 200 of the agency's caregivers, as the caregivers list's bulk Set status does. Each caregiver saves on its own, with its own audit row against the credential, so one refused never undoes another: it is listed in failed with the reason in words. An id that is not this agency's caregiver is failed with name null. A caregiver already at the status counts as updated and writes no audit row. Caregivers carry a lock_version, but a bulk change takes none: each is set as it is when the change reaches it. One caregiver sent twice, in either letter case, is set and counted once. An unknown status or one that is not a string, no ids, more than 200, or an id that is not a string is refused with 422 validation_failed and nothing is written.", "operationId": "patchCaregiversStatus", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaregiverStatusesUpdate" } } }, "description": "The caregivers and the status", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "failed": { "description": "Not set, each with the reason in words: an id that is not this agency's caregiver (name null), an archived caregiver, or what the caregiver's card refused.", "items": { "properties": { "id": { "description": "The id as sent.", "type": "string" }, "name": { "description": "Last, First; null when no caregiver was found.", "nullable": true, "type": "string" }, "reason": { "description": "Why it was not set, in words.", "type": "string" } }, "required": [ "id", "name", "reason" ], "type": "object" }, "type": "array" }, "updated": { "description": "Caregivers that now hold the status, those that already did included (no audit row for them).", "type": "integer" } }, "required": [ "updated", "failed" ], "title": "CaregiverStatusesUpdateResult", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "What was set" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Set one status on several caregivers", "tags": [ "Caregivers" ] } }, "/api/v1/caregivers/{id}": { "delete": { "callbacks": {}, "description": "Soft-deletes the caregiver, as the caregiver list does: it leaves the default list and is listed with include_deleted=true. A caregiver with active client assignments answers 422 has_active_assignments; one already deleted 422 already_deleted.", "operationId": "deleteCaregiversById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The lock_version the record was read with: missing answers 400, changed since 409 stale_record.", "in": "query", "name": "lock_version", "required": true, "schema": { "description": "The value the record was read with; a record changed since answers 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Caregiver" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted caregiver" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_deleted, has_active_assignments: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a caregiver", "tags": [ "Deletes and restores" ] }, "get": { "callbacks": {}, "operationId": "getCaregiversById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Caregiver" } }, "required": [ "data" ], "type": "object" } } }, "description": "The caregiver" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no caregiver with that id in this agency, including another agency's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a caregiver", "tags": [ "Caregivers" ] }, "patch": { "callbacks": {}, "description": "Sets only the fields sent. lock_version is required: send the value you read, and a record changed since answers 409 stale_record.", "operationId": "patchCaregiversById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaregiverInput" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Caregiver" }, "warnings": { "description": "What the act was done with that the agency may want to fix; usually empty. Never a refusal: the act was done.", "items": { "properties": { "fix": { "description": "Where it is fixed, when a page fixes it.", "nullable": true, "properties": { "label": { "description": "What the link says.", "type": "string" }, "path": { "description": "The app route that fixes it.", "type": "string" } }, "required": [ "path", "label" ], "type": "object" }, "id": { "description": "The rule that raised it, stable, e.g. client_care.medicaid_id_pending.", "type": "string" }, "message": { "description": "For a person to read.", "type": "string" } }, "required": [ "id", "message" ], "title": "Warning", "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "title": "CaregiverWriteResult", "type": "object" } } }, "description": "The updated caregiver" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no caregiver with that id in this agency, including another agency's." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: the caregiver changed since the lock_version sent was read, or while this request ran. Nothing was saved; read it again and retry." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a caregiver", "tags": [ "Caregivers" ] } }, "/api/v1/caregivers/{id}/adp-hire": { "delete": { "callbacks": {}, "description": "As \"I checked RUN: not there\" on ADP workers does: clears the caregiver's send ADP did not answer (or one still in flight two minutes after it started), or one waiting in RUN's New Hire Wizard that was never finished, so Add to ADP is offered again. 409 hire_not_abandonable for any other (none open, or a send still in flight). 403 read_only for a read-only agency. Credentials whose member holds payroll.send_to_adp only (403 forbidden otherwise); 404 for a caregiver this agency does not have, before anything else; 409 payroll_integration_off while the agency's ADP API connection is off; 409 not_api_connection while it sends payroll by file or SFTP.", "operationId": "deleteCaregiversByIdAdpHire", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "message": { "description": "The sentence ADP workers shows on the caregiver's row; null where it offers Add to ADP again.", "nullable": true, "type": "string" }, "status": { "description": "Where the send stands: sent (ADP named the worker, now linked), pending_in_adp (an ADP user finishes it in RUN's New Hire Wizard), unconfirmed (ADP did not answer: check RUN's new hires before sending again), abandoned (cleared by \"I checked RUN: not there\").", "enum": [ "in_flight", "unconfirmed", "pending_in_adp", "sent", "refused", "abandoned" ], "type": "string" } }, "required": [ "caregiver_id", "status", "message" ], "title": "PayrollHireAttempt", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The cleared send" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code read_only: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes hire_not_abandonable, not_api_connection, payroll_integration_off: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Clear a send to ADP that RUN does not have", "tags": [ "Payroll", "Payroll" ] }, "post": { "callbacks": {}, "description": "As Add to ADP on ADP workers does: sends the caregiver to RUN as a new hire (worker.hire) with the legal first and last name, address, hire date and SSN, each left out when missing (RUN's New Hire Wizard asks for it); an ADP user finishes the hire there. Sent once, never retried. Answers what the caregiver's row shows: sent (ADP named the worker; it is now linked), pending_in_adp (linked by the next sync once the hire is finished), or unconfirmed (ADP did not answer: check RUN's new hires before sending again, then DELETE this to clear it). At full access only: 403 submission_blocked while the agency's HomeCareBilling billing blocks submission, 403 read_only for a read-only agency. 409 hire_push_off unless the connection is RUN with allow_hire_push on; 409 already_linked for a caregiver with an ADP worker or an open send; 422 hire_refused when ADP refused the hire; 502 adp_unreachable when the request never reached ADP (nothing sent). Credentials whose member holds payroll.send_to_adp only (403 forbidden otherwise); 404 for a caregiver this agency does not have, before anything else; 409 payroll_integration_off while the agency's ADP API connection is off; 409 not_api_connection while it sends payroll by file or SFTP.", "operationId": "postCaregiversByIdAdpHire", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "message": { "description": "The sentence ADP workers shows on the caregiver's row; null where it offers Add to ADP again.", "nullable": true, "type": "string" }, "status": { "description": "Where the send stands: sent (ADP named the worker, now linked), pending_in_adp (an ADP user finishes it in RUN's New Hire Wizard), unconfirmed (ADP did not answer: check RUN's new hires before sending again), abandoned (cleared by \"I checked RUN: not there\").", "enum": [ "in_flight", "unconfirmed", "pending_in_adp", "sent", "refused", "abandoned" ], "type": "string" } }, "required": [ "caregiver_id", "status", "message" ], "title": "PayrollHireAttempt", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Where the send stands" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes read_only, submission_blocked: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_linked, hire_push_off, not_api_connection, payroll_integration_off: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code hire_refused: Unprocessable Content, as the operation's description says." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code adp_unreachable: Bad Gateway, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Add a caregiver to ADP as a new hire", "tags": [ "Payroll", "Payroll" ] } }, "/api/v1/caregivers/{id}/app-pin": { "delete": { "callbacks": {}, "description": "As the caregiver page's Reset PIN does: a new PIN replaces the old one and the caregiver's app sessions end. The new PIN is never returned (PRD 5.8); set one with PUT, or reset it on the caregiver page to see it.", "operationId": "deleteCaregiversByIdAppPin", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "app_pin_set": { "description": "Whether the caregiver has an app PIN.", "type": "boolean" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "telephony_pin_set": { "description": "Whether the caregiver has a telephony PIN (the PIN is never returned).", "type": "boolean" } }, "required": [ "caregiver_id" ], "title": "CaregiverPinStatus", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The PIN status" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Reset a caregiver's app PIN", "tags": [ "Caregiver records" ] }, "put": { "callbacks": {}, "description": "As the caregiver page's Set PIN does: the caregiver signs in to the app with it. A PIN the rules refuse (length, digits, a trivial sequence) is 422.", "operationId": "putCaregiversByIdAppPin", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "new_pin": { "description": "The PIN.", "type": "string" } }, "required": [ "new_pin" ], "title": "CaregiverAppPin", "type": "object" } } }, "description": "The PIN", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "app_pin_set": { "description": "Whether the caregiver has an app PIN.", "type": "boolean" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "telephony_pin_set": { "description": "Whether the caregiver has a telephony PIN (the PIN is never returned).", "type": "boolean" } }, "required": [ "caregiver_id" ], "title": "CaregiverPinStatus", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The PIN status" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Set a caregiver's app PIN", "tags": [ "Caregiver records" ] } }, "/api/v1/caregivers/{id}/compliance": { "get": { "callbacks": {}, "description": "Training by course, vaccinations by year, the annual evaluation and the credential dates, what needs attention and the latest OIG check, as caregiver_compliance_status returns them. Another agency's caregiver, or a deleted one, is 404.", "operationId": "getCaregiversByIdCompliance", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CaregiverCompliance" } }, "required": [ "data" ], "type": "object" } } }, "description": "The compliance" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a caregiver's compliance", "tags": [ "Compliance" ] } }, "/api/v1/caregivers/{id}/compliance-items": { "get": { "callbacks": {}, "description": "The Compliance tab's credentials, dates and custom items; data is null when none is recorded yet.", "operationId": "getCaregiversByIdComplianceItems", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "nullable": true, "properties": { "caps_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "caps_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "criminal_background_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "criminal_background_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "custom_items": { "additionalProperties": { "type": "object" }, "description": "The agency's custom checklist items by key, each {date, expiry, completed}; the keys sent are set and the others kept.", "type": "object" }, "dora_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "dora_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "driver_license_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "lock_version": { "description": "Its version; send it back to change it.", "nullable": true, "type": "integer" }, "main_training_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "main_training_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "notes": { "description": "Notes, up to 2000 characters.", "nullable": true, "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "caregiver_id", "lock_version" ], "title": "CaregiverComplianceRecord", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The record" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a caregiver's compliance record", "tags": [ "Caregiver records" ] }, "patch": { "callbacks": {}, "description": "As the Compliance tab's Save does: sets the fields sent, and the custom items by key. Send the lock_version it was read with; a newer one is 409.", "operationId": "patchCaregiversByIdComplianceItems", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "caps_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "caps_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "criminal_background_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "criminal_background_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "custom": { "additionalProperties": { "type": "object" }, "description": "The agency's custom checklist items by key, each {date, expiry, completed}; the keys sent are set and the others kept.", "type": "object" }, "dora_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "dora_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "driver_license_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "lock_version": { "description": "On a change: the lock_version it was read with.", "nullable": true, "type": "integer" }, "main_training_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "main_training_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "notes": { "description": "Notes, up to 2000 characters.", "nullable": true, "type": "string" } }, "title": "CaregiverComplianceInput", "type": "object" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "caps_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "caps_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "criminal_background_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "criminal_background_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "custom_items": { "additionalProperties": { "type": "object" }, "description": "The agency's custom checklist items by key, each {date, expiry, completed}; the keys sent are set and the others kept.", "type": "object" }, "dora_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "dora_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "driver_license_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "lock_version": { "description": "Its version; send it back to change it.", "nullable": true, "type": "integer" }, "main_training_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "main_training_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "notes": { "description": "Notes, up to 2000 characters.", "nullable": true, "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "caregiver_id", "lock_version" ], "title": "CaregiverComplianceRecord", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The record" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a caregiver's compliance record", "tags": [ "Caregiver records" ] }, "post": { "callbacks": {}, "description": "As the Compliance tab's first Save does. A caregiver has one: one already recorded is 422 already_recorded with its id in details.compliance_id; change it with PATCH. An expiry before its date is 422.", "operationId": "postCaregiversByIdComplianceItems", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "caps_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "caps_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "criminal_background_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "criminal_background_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "custom": { "additionalProperties": { "type": "object" }, "description": "The agency's custom checklist items by key, each {date, expiry, completed}; the keys sent are set and the others kept.", "type": "object" }, "dora_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "dora_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "driver_license_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "lock_version": { "description": "On a change: the lock_version it was read with.", "nullable": true, "type": "integer" }, "main_training_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "main_training_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "notes": { "description": "Notes, up to 2000 characters.", "nullable": true, "type": "string" } }, "title": "CaregiverComplianceInput", "type": "object" } } }, "description": "The record", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "caps_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "caps_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "criminal_background_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "criminal_background_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "custom_items": { "additionalProperties": { "type": "object" }, "description": "The agency's custom checklist items by key, each {date, expiry, completed}; the keys sent are set and the others kept.", "type": "object" }, "dora_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "dora_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "driver_license_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "lock_version": { "description": "Its version; send it back to change it.", "nullable": true, "type": "integer" }, "main_training_date": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "main_training_expiry": { "description": "As the Compliance tab names it.", "format": "date", "nullable": true, "type": "string" }, "notes": { "description": "Notes, up to 2000 characters.", "nullable": true, "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "caregiver_id", "lock_version" ], "title": "CaregiverComplianceRecord", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The record" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code already_recorded: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Record a caregiver's compliance record", "tags": [ "Caregiver records" ] } }, "/api/v1/caregivers/{id}/documents": { "get": { "callbacks": {}, "description": "Newest first, as the caregiver page's Documents tab lists them, each with its scan status. The read is recorded on the PHI access log.", "operationId": "getCaregiversByIdDocuments", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "content_type": { "description": "Its type.", "nullable": true, "type": "string" }, "document_type": { "description": "What the document is, as the Documents tab's Type.", "enum": [ "care_plan", "authorization", "signed_agreement", "training_certificate", "background_check", "medical_form", "incident_report", "pcsp", "cfc_calculator", "legacy_paper", "other", "paper_capture", "true_copy", "voice_attestation" ], "type": "string" }, "documentable_id": { "description": "The client or caregiver.", "format": "uuid", "type": "string" }, "documentable_type": { "description": "Whose file it is on.", "enum": [ "client", "caregiver" ], "type": "string" }, "expiry_date": { "description": "When it expires, if it does.", "format": "date", "nullable": true, "type": "string" }, "file_name": { "description": "The file's name.", "nullable": true, "type": "string" }, "file_size": { "description": "Its size in bytes.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was uploaded.", "format": "date-time", "type": "string" }, "notes": { "description": "The tab's notes.", "nullable": true, "type": "string" }, "paper_form_type": { "description": "A legacy_paper scan's form type, as the paper archive files it (US-101.7); other when not given. Ignored on any other document_type.", "enum": [ "work_order", "time_services_card", "plan_of_care", "monthly_client_report", "supervisory_visit", "cfc_calculator", "intake_consent", "complaint_incident", "other" ], "nullable": true, "type": "string" }, "record_date": { "description": "A legacy_paper scan's date on the paper; a monthly form's is its month's first day. Ignored on any other document_type.", "format": "date", "nullable": true, "type": "string" }, "scan_status": { "description": "The virus scan's verdict; only a clean file can be downloaded.", "enum": [ "pending", "clean", "infected", "error" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" }, "uploaded_by": { "description": "Who uploaded it.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "documentable_type", "documentable_id", "file_name", "scan_status" ], "title": "PersonDocument", "type": "object" }, "type": "array" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "PersonDocumentList", "type": "object" } } }, "description": "The person's documents" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a caregiver's documents", "tags": [ "Documents" ] }, "post": { "callbacks": {}, "description": "Stores a file on the person's file as the Documents tab's upload does (multipart field file, or JSON file_base64 with file_name and content_type): application/pdf, image/jpeg, image/png, image/gif, image/webp, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, text/plain, its extension matching its type and its first bytes matching both. A multipart file may be up to 50 MB; a JSON body takes at most 1 MB, file_base64 included. document_type defaults to other. A refused file writes nothing and answers 422 naming the rule. It is virus-scanned after it is saved and cannot be downloaded until its scan_status is clean.", "operationId": "postCaregiversByIdDocuments", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "content_type": { "description": "Its type; null or left out reads the extension's.", "nullable": true, "type": "string" }, "document_type": { "description": "What the document is, as the Documents tab's Type.", "enum": [ "care_plan", "authorization", "signed_agreement", "training_certificate", "background_check", "medical_form", "incident_report", "pcsp", "cfc_calculator", "legacy_paper", "other" ], "type": "string" }, "expiry_date": { "description": "When it expires.", "format": "date", "nullable": true, "type": "string" }, "file_base64": { "description": "The file's bytes, base64.", "type": "string" }, "file_name": { "description": "Its name, with its extension.", "type": "string" }, "notes": { "description": "Notes, as the tab's Notes.", "nullable": true, "type": "string" }, "paper_form_type": { "description": "A legacy_paper scan's form type, as the paper archive files it (US-101.7); other when not given. Ignored on any other document_type.", "enum": [ "work_order", "time_services_card", "plan_of_care", "monthly_client_report", "supervisory_visit", "cfc_calculator", "intake_consent", "complaint_incident", "other" ], "type": "string" }, "record_date": { "description": "A legacy_paper scan's date on the paper; a monthly form's is its month's first day. Ignored on any other document_type.", "format": "date", "nullable": true, "type": "string" } }, "required": [ "file_base64", "file_name" ], "title": "PersonDocumentUpload", "type": "object" } }, "multipart/form-data": { "schema": { "properties": { "document_type": { "description": "What the document is, as the Documents tab's Type.", "enum": [ "care_plan", "authorization", "signed_agreement", "training_certificate", "background_check", "medical_form", "incident_report", "pcsp", "cfc_calculator", "legacy_paper", "other" ], "type": "string" }, "expiry_date": { "description": "When it expires.", "format": "date", "nullable": true, "type": "string" }, "file": { "format": "binary", "type": "string" }, "notes": { "description": "Notes, as the tab's Notes.", "nullable": true, "type": "string" }, "paper_form_type": { "description": "A legacy_paper scan's form type, as the paper archive files it (US-101.7); other when not given. Ignored on any other document_type.", "enum": [ "work_order", "time_services_card", "plan_of_care", "monthly_client_report", "supervisory_visit", "cfc_calculator", "intake_consent", "complaint_incident", "other" ], "type": "string" }, "record_date": { "description": "A legacy_paper scan's date on the paper; a monthly form's is its month's first day. Ignored on any other document_type.", "format": "date", "nullable": true, "type": "string" } }, "required": [ "file" ], "type": "object" } } }, "description": "The file and its details", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "content_type": { "description": "Its type.", "nullable": true, "type": "string" }, "document_type": { "description": "What the document is, as the Documents tab's Type.", "enum": [ "care_plan", "authorization", "signed_agreement", "training_certificate", "background_check", "medical_form", "incident_report", "pcsp", "cfc_calculator", "legacy_paper", "other", "paper_capture", "true_copy", "voice_attestation" ], "type": "string" }, "documentable_id": { "description": "The client or caregiver.", "format": "uuid", "type": "string" }, "documentable_type": { "description": "Whose file it is on.", "enum": [ "client", "caregiver" ], "type": "string" }, "expiry_date": { "description": "When it expires, if it does.", "format": "date", "nullable": true, "type": "string" }, "file_name": { "description": "The file's name.", "nullable": true, "type": "string" }, "file_size": { "description": "Its size in bytes.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was uploaded.", "format": "date-time", "type": "string" }, "notes": { "description": "The tab's notes.", "nullable": true, "type": "string" }, "paper_form_type": { "description": "A legacy_paper scan's form type, as the paper archive files it (US-101.7); other when not given. Ignored on any other document_type.", "enum": [ "work_order", "time_services_card", "plan_of_care", "monthly_client_report", "supervisory_visit", "cfc_calculator", "intake_consent", "complaint_incident", "other" ], "nullable": true, "type": "string" }, "record_date": { "description": "A legacy_paper scan's date on the paper; a monthly form's is its month's first day. Ignored on any other document_type.", "format": "date", "nullable": true, "type": "string" }, "scan_status": { "description": "The virus scan's verdict; only a clean file can be downloaded.", "enum": [ "pending", "clean", "infected", "error" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" }, "uploaded_by": { "description": "Who uploaded it.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "documentable_type", "documentable_id", "file_name", "scan_status" ], "title": "PersonDocument", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The document" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code internal_error: a failure on our side, which was logged. When its message says nothing changed (the file store refused the request, the virus scan could not be queued, the upload could not be read), nothing did, the same request fails the same way until it is fixed, and the Idempotency-Key stays free." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code storage_unavailable (the file store did not answer) or, on an upload, temporarily_unavailable (its uploaded file could not be read): nothing changed, and the same request can succeed later. Retry after the Retry-After seconds; a write retried with the same Idempotency-Key runs again.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (30).", "schema": { "type": "integer" }, "style": "simple" } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Upload a document to a caregiver's file", "tags": [ "Documents" ] } }, "/api/v1/caregivers/{id}/evaluations": { "get": { "callbacks": {}, "description": "The caregiver's evaluations, newest first. A caregiver of another agency, or a deleted one, is 404.", "operationId": "getCaregiversByIdEvaluations", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/CaregiverEvaluation" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "CaregiverEvaluationPage", "type": "object" } } }, "description": "A page of evaluations" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a caregiver's evaluations", "tags": [ "Caregiver records" ] }, "post": { "callbacks": {}, "description": "Records one evaluation. One already on file is 422 already_recorded with its id in details.evaluation_id. A caregiver of another agency, or a deleted one, is 404 and nothing is written.", "operationId": "postCaregiversByIdEvaluations", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaregiverEvaluationInput" } } }, "description": "The evaluation", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CaregiverEvaluation" } }, "required": [ "data" ], "type": "object" } } }, "description": "Recorded" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code already_recorded: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Record a caregiver's evaluation", "tags": [ "Caregiver records" ] } }, "/api/v1/caregivers/{id}/file-checklist": { "get": { "callbacks": {}, "description": "The Employee File tab's checklist: the agency's active items, each done or not with its date and notes, and when it was last reviewed. Created on first read, as the tab does.", "operationId": "getCaregiversByIdFileChecklist", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "completed": { "description": "How many items are done.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "items": { "description": "The agency's active items, in its order.", "items": { "properties": { "completed": { "description": "Whether it is done.", "type": "boolean" }, "date": { "description": "Its date, as entered.", "nullable": true, "type": "string" }, "key": { "description": "The item's key.", "nullable": true, "type": "string" }, "notes": { "description": "Its notes.", "nullable": true, "type": "string" }, "text": { "description": "What it asks for.", "nullable": true, "type": "string" } }, "required": [ "key", "text", "completed" ], "title": "CaregiverFileChecklistItem", "type": "object" }, "type": "array" }, "last_reviewed_at": { "description": "When it was last reviewed.", "format": "date-time", "nullable": true, "type": "string" }, "lock_version": { "description": "Its version.", "nullable": true, "type": "integer" }, "percentage": { "description": "completed of total, in percent.", "type": "number" }, "reviewed_by_id": { "description": "Who reviewed it.", "format": "uuid", "nullable": true, "type": "string" }, "total": { "description": "How many items there are.", "nullable": true, "type": "integer" } }, "required": [ "id", "caregiver_id", "items", "lock_version" ], "title": "CaregiverFileChecklist", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The checklist" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a caregiver's Employee File checklist", "tags": [ "Caregiver records" ] }, "patch": { "callbacks": {}, "description": "As ticking a box or entering a date or note on the tab does, for several items at once, all or none: items maps an item key to the fields to set (completed, date, notes; a blank date or note clears it). A key the agency has hidden is 422 hidden_item, any other unknown key 422 unknown_item. A concurrent change is merged per field and retried once; still stale is 409.", "operationId": "patchCaregiversByIdFileChecklist", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "items": { "additionalProperties": { "properties": { "completed": { "description": "Whether it is done.", "type": "boolean" }, "date": { "description": "Its date; blank clears it.", "nullable": true, "type": "string" }, "notes": { "description": "Its notes; blank clears them.", "nullable": true, "type": "string" } }, "title": "CaregiverFileChecklistItemUpdate", "type": "object" }, "description": "Item key => {completed, date, notes}; a blank date or note clears it. Keys are get_caregiver_file_checklist's.", "type": "object" } }, "required": [ "items" ], "title": "CaregiverFileChecklistUpdate", "type": "object" } } }, "description": "The items", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "completed": { "description": "How many items are done.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "items": { "description": "The agency's active items, in its order.", "items": { "properties": { "completed": { "description": "Whether it is done.", "type": "boolean" }, "date": { "description": "Its date, as entered.", "nullable": true, "type": "string" }, "key": { "description": "The item's key.", "nullable": true, "type": "string" }, "notes": { "description": "Its notes.", "nullable": true, "type": "string" }, "text": { "description": "What it asks for.", "nullable": true, "type": "string" } }, "required": [ "key", "text", "completed" ], "title": "CaregiverFileChecklistItem", "type": "object" }, "type": "array" }, "last_reviewed_at": { "description": "When it was last reviewed.", "format": "date-time", "nullable": true, "type": "string" }, "lock_version": { "description": "Its version.", "nullable": true, "type": "integer" }, "percentage": { "description": "completed of total, in percent.", "type": "number" }, "reviewed_by_id": { "description": "Who reviewed it.", "format": "uuid", "nullable": true, "type": "string" }, "total": { "description": "How many items there are.", "nullable": true, "type": "integer" } }, "required": [ "id", "caregiver_id", "items", "lock_version" ], "title": "CaregiverFileChecklist", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The checklist" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes hidden_item, unknown_item: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Set items of a caregiver's Employee File checklist", "tags": [ "Caregiver records" ] } }, "/api/v1/caregivers/{id}/file-checklist/review": { "post": { "callbacks": {}, "description": "As the tab's Mark reviewed does, by the caller. Send the lock_version the checklist was read with to review what was read: one changed since is 409.", "operationId": "postCaregiversByIdFileChecklistReview", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lock_version": { "description": "The lock_version it was read with.", "nullable": true, "type": "integer" } }, "title": "CaregiverFileChecklistReview", "type": "object" } } }, "description": "The version reviewed", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "completed": { "description": "How many items are done.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "items": { "description": "The agency's active items, in its order.", "items": { "properties": { "completed": { "description": "Whether it is done.", "type": "boolean" }, "date": { "description": "Its date, as entered.", "nullable": true, "type": "string" }, "key": { "description": "The item's key.", "nullable": true, "type": "string" }, "notes": { "description": "Its notes.", "nullable": true, "type": "string" }, "text": { "description": "What it asks for.", "nullable": true, "type": "string" } }, "required": [ "key", "text", "completed" ], "title": "CaregiverFileChecklistItem", "type": "object" }, "type": "array" }, "last_reviewed_at": { "description": "When it was last reviewed.", "format": "date-time", "nullable": true, "type": "string" }, "lock_version": { "description": "Its version.", "nullable": true, "type": "integer" }, "percentage": { "description": "completed of total, in percent.", "type": "number" }, "reviewed_by_id": { "description": "Who reviewed it.", "format": "uuid", "nullable": true, "type": "string" }, "total": { "description": "How many items there are.", "nullable": true, "type": "integer" } }, "required": [ "id", "caregiver_id", "items", "lock_version" ], "title": "CaregiverFileChecklist", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The checklist" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Mark a caregiver's Employee File checklist reviewed", "tags": [ "Caregiver records" ] } }, "/api/v1/caregivers/{id}/file-completeness": { "get": { "callbacks": {}, "description": "Each item of the caregiver's employee file, as caregiver_file_completeness returns it. Another agency's caregiver is 404.", "operationId": "getCaregiversByIdFileCompleteness", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/FileCompleteness" } }, "required": [ "data" ], "type": "object" } } }, "description": "The file" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a caregiver's file completeness", "tags": [ "Compliance" ] } }, "/api/v1/caregivers/{id}/notes": { "get": { "callbacks": {}, "description": "The caregiver's communication log, newest first. With updated_since the order is change order, for a sync that pages with after_id. A caregiver of another agency, or a deleted one, is 404.", "operationId": "getCaregiversByIdNotes", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records changed at or after this instant (ISO 8601, with an offset), compared to the second. The list is then in change order: updated_at, then id.", "in": "query", "name": "updated_since", "schema": { "format": "date-time", "type": "string" } }, { "description": "With updated_since, a cursor: send the last record's updated_at as updated_since and its id as after_id to get the next page. Use this, not offset, to sync: an offset skips a record when an earlier one changes between two requests. The sync is at least once: timestamps are whole seconds and set before commit, so a record changed in the cursor's second, or committed late, can fall behind the cursor. Start each sync pass a minute before the newest updated_at you saw, and treat every record returned as current: apply it over what you hold. A record can change twice within one second, and not every change moves lock_version, so the same updated_at and lock_version do not mean the same content.", "in": "query", "name": "after_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only notes of this contact type.", "in": "query", "name": "contact_type", "schema": { "enum": [ "phone", "email", "in_person", "text_message", "other" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/CaregiverNote" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "CaregiverNotePage", "type": "object" } } }, "description": "A page of caregiver notes" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a caregiver's notes", "tags": [ "Communication notes" ] }, "post": { "callbacks": {}, "description": "Files one note against the caregiver. manager_initials defaults to the API key's user's initials. A caregiver of another agency, or a deleted one, is 404 and nothing is written. Attachments are not accepted here.", "operationId": "postCaregiversByIdNotes", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaregiverNoteInput" } } }, "description": "The note", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CaregiverNote" } }, "required": [ "data" ], "type": "object" } } }, "description": "The note" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Add a note to a caregiver's log", "tags": [ "Communication notes" ] } }, "/api/v1/caregivers/{id}/oig-checks": { "get": { "callbacks": {}, "description": "Newest first, as the caregiver page's OIG history lists them.", "operationId": "getCaregiversByIdOigChecks", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "checked_by": { "description": "Who recorded it.", "format": "uuid", "nullable": true, "type": "string" }, "checked_on": { "description": "The day the LEIE was checked.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was recorded.", "format": "date-time", "type": "string" }, "notes": { "description": "Notes.", "nullable": true, "type": "string" }, "result": { "enum": [ "clear", "excluded", "review" ], "type": "string" }, "source": { "description": "Recorded by a person or by a screen run.", "enum": [ "person", "screen" ], "type": "string" } }, "required": [ "id", "caregiver_id", "checked_on", "result" ], "title": "OigExclusionCheck", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "OigExclusionCheckPage", "type": "object" } } }, "description": "A page of checks" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a caregiver's OIG exclusion checks", "tags": [ "Caregiver records" ] }, "post": { "callbacks": {}, "description": "As the caregiver page's Record check does: an attestation of a manual LEIE lookup, clear or excluded, appended to the caregiver's history. A date in the future, or more than a year old, is 422.", "operationId": "postCaregiversByIdOigChecks", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "checked_on": { "description": "The day the LEIE was checked, YYYY-MM-DD; not in the future, not over a year ago.", "format": "date", "type": "string" }, "notes": { "description": "Notes, e.g. how a match was reconciled.", "nullable": true, "type": "string" }, "result": { "description": "The result.", "enum": [ "clear", "excluded", "review" ], "type": "string" } }, "required": [ "checked_on", "result" ], "title": "OigExclusionCheckCreate", "type": "object" } } }, "description": "The check", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "checked_by": { "description": "Who recorded it.", "format": "uuid", "nullable": true, "type": "string" }, "checked_on": { "description": "The day the LEIE was checked.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was recorded.", "format": "date-time", "type": "string" }, "notes": { "description": "Notes.", "nullable": true, "type": "string" }, "result": { "enum": [ "clear", "excluded", "review" ], "type": "string" }, "source": { "description": "Recorded by a person or by a screen run.", "enum": [ "person", "screen" ], "type": "string" } }, "required": [ "id", "caregiver_id", "checked_on", "result" ], "title": "OigExclusionCheck", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The check" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Record a caregiver's OIG exclusion check", "tags": [ "Caregiver records" ] } }, "/api/v1/caregivers/{id}/pay-rates": { "get": { "callbacks": {}, "description": "Newest first, as the Pay Rates tab's history lists them, current and ended.", "operationId": "getCaregiversByIdPayRates", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client a work rate is for; null is the general rate.", "format": "uuid", "nullable": true, "type": "string" }, "effective_date": { "description": "When it starts.", "format": "date", "nullable": true, "type": "string" }, "end_date": { "description": "When a newer rate of its type ended it.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "rate": { "description": "Dollars an hour.", "format": "decimal", "nullable": true, "type": "string" }, "rate_type": { "enum": [ "work", "attendant", "travel" ], "type": "string" } }, "required": [ "id", "caregiver_id", "rate_type", "rate", "effective_date" ], "title": "CaregiverPayRate", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "CaregiverPayRatePage", "type": "object" } } }, "description": "A page of pay rates" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a caregiver's pay rates", "tags": [ "Caregiver records" ] }, "post": { "callbacks": {}, "description": "As the Pay Rates tab's Add does: the new rate starts on effective_date and ends the caregiver's current rate of its type.", "operationId": "postCaregiversByIdPayRates", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "client_id": { "description": "A work rate for this one client: that client's hours are paid at it instead of the general work rate. Absent or null is the general rate.", "format": "uuid", "nullable": true, "type": "string" }, "effective_date": { "description": "When it starts, YYYY-MM-DD.", "format": "date", "type": "string" }, "rate": { "description": "Dollars an hour, e.g. 18.50.", "format": "decimal", "type": "string" }, "rate_type": { "description": "The kind of rate.", "enum": [ "work", "attendant", "travel" ], "type": "string" } }, "required": [ "rate_type", "rate", "effective_date" ], "title": "CaregiverPayRateCreate", "type": "object" } } }, "description": "The rate", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client a work rate is for; null is the general rate.", "format": "uuid", "nullable": true, "type": "string" }, "effective_date": { "description": "When it starts.", "format": "date", "nullable": true, "type": "string" }, "end_date": { "description": "When a newer rate of its type ended it.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "rate": { "description": "Dollars an hour.", "format": "decimal", "nullable": true, "type": "string" }, "rate_type": { "enum": [ "work", "attendant", "travel" ], "type": "string" } }, "required": [ "id", "caregiver_id", "rate_type", "rate", "effective_date" ], "title": "CaregiverPayRate", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The rate" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Add a caregiver's pay rate", "tags": [ "Caregiver records" ] } }, "/api/v1/caregivers/{id}/restore": { "post": { "callbacks": {}, "description": "Restores a deleted caregiver, as the caregiver list's Restore does. While the caregiver was deleted their telephony PIN may have gone to someone else: meta.pin_resolution says what happened (noop: kept; regenerated: a new PIN, in meta.new_pin; cleared: none could be issued, assign one). meta.new_pin appears in this response only, once; it is never logged, and no later read returns it.", "operationId": "postCaregiversByIdRestore", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lock_version": { "description": "The lock_version the deleted record has: the one its DELETE answered, or read it by listing with include_deleted=true.", "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": [ "lock_version" ], "title": "RestoreBody", "type": "object" } } }, "description": "The lock_version read", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Caregiver" }, "meta": { "properties": { "new_pin": { "description": "The reissued PIN, when pin_resolution is regenerated.", "nullable": true, "type": "string" }, "pin_resolution": { "description": "What happened to the PIN.", "enum": [ "noop", "regenerated", "cleared" ], "type": "string" } }, "required": [ "pin_resolution" ], "type": "object" } }, "required": [ "data", "meta" ], "title": "CaregiverRestored", "type": "object" } } }, "description": "The restored caregiver" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Restore a deleted caregiver", "tags": [ "Deletes and restores" ] } }, "/api/v1/caregivers/{id}/restore-open-shift-access": { "post": { "callbacks": {}, "description": "US-122.15, as the coordinator's Restore access does: clears the caregiver's open-shift pause and voids every strike they hold, in one transaction, so the count starts again from zero; one audit row names how many were voided. A caregiver with no pause running and no unvoided strike is left as they are, answered with lifted false and nothing audited. The pause blocks responding to open shifts only; sign-in, clock-in and EVV never stopped. Another agency's caregiver answers 404. Needs open_shifts.administer.", "operationId": "postCaregiversByIdRestoreOpenShiftAccess", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "caregiver_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "lifted": { "description": "False when there was nothing to lift.", "type": "boolean" }, "voided": { "description": "How many strikes were voided.", "nullable": true, "type": "integer" } }, "required": [ "caregiver_id", "voided", "lifted" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "What was lifted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Lift a caregiver's open-shift pause", "tags": [ "Caregivers" ] } }, "/api/v1/caregivers/{id}/telephony-pin": { "post": { "callbacks": {}, "description": "As the caregiver page's Generate PIN does: a new unique PIN replaces any the caregiver had. The PIN itself is never returned (PRD 5.8); the caregiver page shows it.", "operationId": "postCaregiversByIdTelephonyPin", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "app_pin_set": { "description": "Whether the caregiver has an app PIN.", "type": "boolean" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "telephony_pin_set": { "description": "Whether the caregiver has a telephony PIN (the PIN is never returned).", "type": "boolean" } }, "required": [ "caregiver_id" ], "title": "CaregiverPinStatus", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The PIN status" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Generate a caregiver's telephony PIN", "tags": [ "Caregiver records" ] } }, "/api/v1/caregivers/{id}/trainings": { "get": { "callbacks": {}, "description": "The caregiver's training records, newest year first, then by course. A caregiver of another agency, or a deleted one, is 404.", "operationId": "getCaregiversByIdTrainings", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/CaregiverTraining" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "CaregiverTrainingPage", "type": "object" } } }, "description": "A page of training records" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a caregiver's training records", "tags": [ "Caregiver records" ] }, "post": { "callbacks": {}, "description": "Records one training record. One already on file is 422 already_recorded with its id in details.training_id. A caregiver of another agency, or a deleted one, is 404 and nothing is written.", "operationId": "postCaregiversByIdTrainings", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaregiverTrainingCreate" } } }, "description": "The training record", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CaregiverTraining" } }, "required": [ "data" ], "type": "object" } } }, "description": "Recorded" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code already_recorded: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Record a caregiver's training record", "tags": [ "Caregiver records" ] } }, "/api/v1/caregivers/{id}/vaccinations": { "get": { "callbacks": {}, "description": "The caregiver's vaccination records, newest year first. A caregiver of another agency, or a deleted one, is 404.", "operationId": "getCaregiversByIdVaccinations", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/CaregiverVaccination" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "CaregiverVaccinationPage", "type": "object" } } }, "description": "A page of vaccination records" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a caregiver's vaccination records", "tags": [ "Caregiver records" ] }, "post": { "callbacks": {}, "description": "Records the vaccination for year and vaccination_type: 201 when none was recorded, 200 when it updates the one already recorded. A caregiver of another agency, or a deleted one, is 404 and nothing is written.", "operationId": "postCaregiversByIdVaccinations", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaregiverVaccinationInput" } } }, "description": "The vaccination record", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CaregiverVaccination" } }, "required": [ "data" ], "type": "object" } } }, "description": "Updated" }, "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CaregiverVaccination" } }, "required": [ "data" ], "type": "object" } } }, "description": "Recorded" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Record a caregiver's vaccination record", "tags": [ "Caregiver records" ] } }, "/api/v1/caregivers/{id}/w4-sent-to-payroll": { "post": { "callbacks": {}, "description": "US-102.35: as the Payroll Summary's \"Sent to payroll\" does, records that the payroll processor was sent the caregiver's changed W-4 filing status or dependents, and clears the change. A caregiver with none waiting answers 422 no_w4_change. With w4_changed_at, a change other than the one waiting now (the W-4 changed again since it was read) answers 409 stale_record and is kept; a w4_changed_at that is not a timestamp answers 400 bad_request. The W-4 values are never returned. Audited against the credential.", "operationId": "postCaregiversByIdW4SentToPayroll", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "w4_changed_at": { "description": "The time of the change as it was read; refused with 409 stale_record when the W-4 changed again since. Not sent: the change waiting now is marked sent.", "format": "date-time", "type": "string" } }, "title": "CaregiverW4SentInput", "type": "object" } } }, "description": "The change as it was read", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "w4_changed_at": { "description": "null: the payroll processor has been sent the change.", "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "id", "w4_changed_at" ], "title": "CaregiverW4Sent", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The change, cleared" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: Bad Request, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code no_w4_change: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Mark a caregiver's W-4 change sent to payroll", "tags": [ "Caregiver records" ] } }, "/api/v1/cash-advances": { "get": { "callbacks": {}, "description": "US-102.37: as the Cash advances page lists them, newest first, filtered by status, search (the caregiver's name) and deduct_in_month (YYYY-MM, the payroll month an advance is deducted in; absent is every month, where the page starts at the current one). totals sums amount and remaining_balance over every advance the filters match, not this page.", "operationId": "getCashAdvances", "parameters": [ { "description": "One of outstanding, partially_repaid, fully_repaid, written_off.", "in": "query", "name": "status", "schema": { "enum": [ "outstanding", "partially_repaid", "fully_repaid", "written_off" ], "type": "string" } }, { "description": "Part of the caregiver's name (at most 100 characters).", "in": "query", "name": "search", "schema": { "maxLength": 100, "type": "string" } }, { "description": "YYYY-MM: the payroll month the advances are deducted in.", "in": "query", "name": "deduct_in_month", "schema": { "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "advance_date": { "format": "date", "nullable": true, "type": "string" }, "amount": { "description": "The amount advanced.", "format": "decimal", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "caregiver_name": { "description": "\"Last, First\". In GET /cash-advances; a write's answer leaves it out.", "nullable": true, "type": "string" }, "check_number": { "description": "The check the advance was paid by.", "nullable": true, "type": "string" }, "deduct_in_month": { "description": "The 1st of the payroll month the advance is deducted in.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reason": { "description": "Why it was advanced, as typed.", "nullable": true, "type": "string", "x-untrusted": "text" }, "remaining_balance": { "description": "What is still owed.", "format": "decimal", "nullable": true, "type": "string" }, "status": { "description": "outstanding, partially_repaid, fully_repaid or written_off.", "nullable": true, "type": "string" } }, "title": "CashAdvance", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" }, "totals": { "description": "Over every advance the filters match, not this page.", "properties": { "amount": { "description": "The amounts advanced.", "format": "decimal", "nullable": true, "type": "string" }, "remaining_balance": { "description": "What is still owed.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "required": [ "totals", "data", "limit", "offset", "total" ], "title": "CashAdvancePage", "type": "object" } } }, "description": "A page of cash advances" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List the agency's cash advances", "tags": [ "Payroll" ] }, "post": { "callbacks": {}, "description": "Records a cash advance to one of the agency's caregivers, as Cash advances does; payroll recovers it. A caregiver of another agency answers 422.", "operationId": "postCashAdvances", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "advance_date": { "description": "YYYY-MM-DD.", "format": "date", "type": "string" }, "amount": { "description": "A positive decimal.", "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "check_number": { "description": "The check the advance was paid by, at most 20 characters.", "nullable": true, "type": "string" }, "deduct_in_month": { "description": "The payroll month the advance is deducted in, held as the 1st of that month; absent, the advance date's month.", "format": "date", "nullable": true, "type": "string" }, "reason": { "description": "Why it is advanced; optional.", "nullable": true, "type": "string" } }, "required": [ "caregiver_id", "amount", "advance_date" ], "type": "object" } } }, "description": "The advance", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "advance_date": { "format": "date", "nullable": true, "type": "string" }, "amount": { "description": "The amount advanced.", "format": "decimal", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "caregiver_name": { "description": "\"Last, First\". In GET /cash-advances; a write's answer leaves it out.", "nullable": true, "type": "string" }, "check_number": { "description": "The check the advance was paid by.", "nullable": true, "type": "string" }, "deduct_in_month": { "description": "The 1st of the payroll month the advance is deducted in.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reason": { "description": "Why it was advanced, as typed.", "nullable": true, "type": "string", "x-untrusted": "text" }, "remaining_balance": { "description": "What is still owed.", "format": "decimal", "nullable": true, "type": "string" }, "status": { "description": "outstanding, partially_repaid, fully_repaid or written_off.", "nullable": true, "type": "string" } }, "title": "CashAdvance", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The advance" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Advance cash to a caregiver", "tags": [ "Payroll", "Cash advances" ] } }, "/api/v1/cash-advances/{id}/repayments": { "post": { "callbacks": {}, "description": "Lowers the advance's remaining balance by amount, as Cash advances does. A repaid or written-off advance answers 422. Another agency's record answers 404 and nothing is written.", "operationId": "postCashAdvancesByIdRepayments", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "amount": { "description": "A positive decimal.", "type": "string" }, "notes": { "description": "Free text on the repayment.", "nullable": true, "type": "string" }, "repayment_date": { "description": "YYYY-MM-DD.", "format": "date", "type": "string" } }, "required": [ "amount", "repayment_date" ], "type": "object" } } }, "description": "The repayment", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "advance_date": { "format": "date", "nullable": true, "type": "string" }, "amount": { "description": "The amount advanced.", "format": "decimal", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "caregiver_name": { "description": "\"Last, First\". In GET /cash-advances; a write's answer leaves it out.", "nullable": true, "type": "string" }, "check_number": { "description": "The check the advance was paid by.", "nullable": true, "type": "string" }, "deduct_in_month": { "description": "The 1st of the payroll month the advance is deducted in.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reason": { "description": "Why it was advanced, as typed.", "nullable": true, "type": "string", "x-untrusted": "text" }, "remaining_balance": { "description": "What is still owed.", "format": "decimal", "nullable": true, "type": "string" }, "status": { "description": "outstanding, partially_repaid, fully_repaid or written_off.", "nullable": true, "type": "string" } }, "title": "CashAdvance", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The advance" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Record a repayment of an advance", "tags": [ "Payroll", "Cash advances" ] } }, "/api/v1/cash-advances/{id}/write-off": { "post": { "callbacks": {}, "description": "As Cash advances does, with written_off_reason. A repaid or written-off advance answers 422. Another agency's record answers 404 and nothing is written.", "operationId": "postCashAdvancesByIdWriteOff", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "written_off_reason": { "description": "Why it is written off.", "type": "string" } }, "type": "object" } } }, "description": "Why", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "advance_date": { "format": "date", "nullable": true, "type": "string" }, "amount": { "description": "The amount advanced.", "format": "decimal", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "caregiver_name": { "description": "\"Last, First\". In GET /cash-advances; a write's answer leaves it out.", "nullable": true, "type": "string" }, "check_number": { "description": "The check the advance was paid by.", "nullable": true, "type": "string" }, "deduct_in_month": { "description": "The 1st of the payroll month the advance is deducted in.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reason": { "description": "Why it was advanced, as typed.", "nullable": true, "type": "string", "x-untrusted": "text" }, "remaining_balance": { "description": "What is still owed.", "format": "decimal", "nullable": true, "type": "string" }, "status": { "description": "outstanding, partially_repaid, fully_repaid or written_off.", "nullable": true, "type": "string" } }, "title": "CashAdvance", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The advance" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Write off what remains of an advance", "tags": [ "Payroll", "Cash advances" ] } }, "/api/v1/cfc-calculator": { "post": { "callbacks": {}, "description": "As the import page's \"New client from a calculator\": the card makes the client, and the calculator is imported for it as POST /api/v1/clients/{id}/cfc-calculator does. When the card's Medicaid ID (or, with none, its name) is already on file for the same person, no client is made and the import is for that client (outcome existing). When the Medicaid ID is on file under another name, nothing is written (outcome conflict, 200, import null): correct the ID, or import for that client with POST /api/v1/clients/{id}/cfc-calculator. A card the client form would refuse (no name, a malformed Medicaid ID) is 422. A file over max_file_size (5 MB) answers 422 file_too_large, and a body over the upload cap, which holds a 10 MB file, 413. What the file holds is judged by the job: a file the parser cannot read ends it failed, unreadable_calculator, and a scan (a PDF with no text, PNG or JPG) ends it failed, paper_capture_consent_required, unless the agency has accepted the paper_capture consent (POST /api/v1/consents/paper_capture).", "operationId": "postCfcCalculator", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "address": { "type": "string" }, "file": { "format": "binary", "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "medicaid_id": { "type": "string" }, "phone": { "type": "string" }, "task_names": { "items": { "type": "string" }, "type": "array" } }, "required": [ "file", "last_name", "first_name" ], "type": "object" } } }, "description": "A multipart form: the calculator in the field `file` (.xlsx, .pdf, .png, .jpg or .jpeg, at most 5 MB), the client's card read from it (last_name and first_name, and medicaid_id, address and phone when the calculator has them; address as one line, \"street, city, ST 12345\"), and optionally task_names[] naming the tasks to import when not all of them.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CfcNewClient" } }, "required": [ "data" ], "type": "object" } } }, "description": "outcome conflict: the Medicaid ID is on file under another name; nothing was written" }, "202": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CfcNewClient" } }, "required": [ "data" ], "type": "object" } } }, "description": "The client, made or found, and its import job; GET /api/v1/cfc-imports/{id} until it has ended" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Request Entity Too Large, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code file_too_large: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Make a new client from a CFC calculator and import it", "tags": [ "Plans of care" ] } }, "/api/v1/cfc-imports/{id}": { "get": { "callbacks": {}, "description": "A preview or import job: queued or running until its worker ends it, then succeeded with its rows or plans, or failed with its error.", "operationId": "getCfcImportsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CfcImportJob" } }, "required": [ "data" ], "type": "object" } } }, "description": "The job" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read a CFC calculator job", "tags": [ "Plans of care" ] } }, "/api/v1/cfc-programs": { "get": { "callbacks": {}, "description": "Every category, offered or not, each with its tasks in order, as Settings > CFC programs shows them. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "getCfcPrograms", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "active": { "description": "Whether the agency offers it.", "type": "boolean" }, "category": { "description": "The category.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" }, "position": { "description": "Its place.", "type": "integer" }, "tasks": { "description": "Its tasks, in order.", "items": { "properties": { "active": { "description": "Whether it is offered.", "type": "boolean" }, "category": { "description": "Its category.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "minutes_per_task": { "description": "Minutes each time.", "format": "decimal", "nullable": true, "type": "string" }, "position": { "description": "Its place in the category.", "type": "integer" }, "task_name": { "description": "The task.", "nullable": true, "type": "string" }, "times_per_week": { "description": "Times a week.", "type": "integer" } }, "required": [ "id", "category", "task_name", "active" ], "title": "CfcTask", "type": "object" }, "type": "array" } }, "required": [ "category", "active", "tasks" ], "title": "CfcProgram", "type": "object" }, "title": "CfcPrograms", "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The programs" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List the CFC programs and their tasks", "tags": [ "Settings lists" ] } }, "/api/v1/cfc-programs/{category}": { "patch": { "callbacks": {}, "description": "As the page's toggle does. Turning off the last active category answers 422 last_active_category. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "patchCfcProgramsByCategory", "parameters": [ { "description": "A CFC program category.", "in": "path", "name": "category", "required": true, "schema": { "description": "The category.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "active": { "description": "Whether the agency offers it.", "type": "boolean" } }, "required": [ "active" ], "title": "CfcProgramUpdate", "type": "object" } } }, "description": "Whether it is offered", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "active": { "description": "Whether it is offered.", "type": "boolean" }, "category": { "description": "The category.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" } }, "required": [ "category", "active" ], "title": "CfcProgramActive", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The category" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code last_active_category: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Offer or stop offering a CFC program", "tags": [ "Settings lists" ] } }, "/api/v1/cfc-programs/{category}/tasks": { "post": { "callbacks": {}, "description": "At the end of the category, as the page's Add does. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "postCfcProgramsByCategoryTasks", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "description": "A CFC program category.", "in": "path", "name": "category", "required": true, "schema": { "description": "The category.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "minutes_per_task": { "description": "Minutes each time.", "format": "decimal", "nullable": false, "type": "string" }, "task_name": { "description": "The task.", "maxLength": 200, "type": "string" }, "times_per_week": { "description": "Times a week.", "type": "integer" } }, "required": [ "task_name", "minutes_per_task", "times_per_week" ], "title": "CfcTaskCreate", "type": "object" } } }, "description": "The task", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "active": { "description": "Whether it is offered.", "type": "boolean" }, "category": { "description": "Its category.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "minutes_per_task": { "description": "Minutes each time.", "format": "decimal", "nullable": true, "type": "string" }, "position": { "description": "Its place in the category.", "type": "integer" }, "task_name": { "description": "The task.", "nullable": true, "type": "string" }, "times_per_week": { "description": "Times a week.", "type": "integer" } }, "required": [ "id", "category", "task_name", "active" ], "title": "CfcTask", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The task" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Add a task to a CFC program", "tags": [ "Settings lists" ] } }, "/api/v1/cfc-tasks/{id}": { "patch": { "callbacks": {}, "description": "Its name, minutes or times a week; send only what changes. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "patchCfcTasksById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "minutes_per_task": { "description": "Minutes each time.", "format": "decimal", "nullable": false, "type": "string" }, "task_name": { "description": "The task.", "maxLength": 200, "type": "string" }, "times_per_week": { "description": "Times a week.", "type": "integer" } }, "title": "CfcTaskUpdate", "type": "object" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "active": { "description": "Whether it is offered.", "type": "boolean" }, "category": { "description": "Its category.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "minutes_per_task": { "description": "Minutes each time.", "format": "decimal", "nullable": true, "type": "string" }, "position": { "description": "Its place in the category.", "type": "integer" }, "task_name": { "description": "The task.", "nullable": true, "type": "string" }, "times_per_week": { "description": "Times a week.", "type": "integer" } }, "required": [ "id", "category", "task_name", "active" ], "title": "CfcTask", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The task" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a CFC task", "tags": [ "Settings lists" ] } }, "/api/v1/cfc-tasks/{id}/deactivate": { "post": { "callbacks": {}, "description": "The last active task of a category answers 422 last_active_task. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "postCfcTasksByIdDeactivate", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "active": { "description": "Whether it is offered.", "type": "boolean" }, "category": { "description": "Its category.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "minutes_per_task": { "description": "Minutes each time.", "format": "decimal", "nullable": true, "type": "string" }, "position": { "description": "Its place in the category.", "type": "integer" }, "task_name": { "description": "The task.", "nullable": true, "type": "string" }, "times_per_week": { "description": "Times a week.", "type": "integer" } }, "required": [ "id", "category", "task_name", "active" ], "title": "CfcTask", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The task" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code last_active_task: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Hide a CFC task", "tags": [ "Settings lists" ] } }, "/api/v1/cfc-tasks/{id}/move": { "post": { "callbacks": {}, "description": "One place within its category, as the page's arrows do; answers the category's tasks. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "postCfcTasksByIdMove", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "direction": { "description": "Which way to move it one place.", "enum": [ "up", "down" ], "type": "string" } }, "required": [ "direction" ], "title": "MoveDirection", "type": "object" } } }, "description": "Which way", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "active": { "description": "Whether it is offered.", "type": "boolean" }, "category": { "description": "Its category.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "minutes_per_task": { "description": "Minutes each time.", "format": "decimal", "nullable": true, "type": "string" }, "position": { "description": "Its place in the category.", "type": "integer" }, "task_name": { "description": "The task.", "nullable": true, "type": "string" }, "times_per_week": { "description": "Times a week.", "type": "integer" } }, "required": [ "id", "category", "task_name", "active" ], "title": "CfcTask", "type": "object" }, "title": "CfcTasksMoved", "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The tasks" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Move a CFC task up or down", "tags": [ "Settings lists" ] } }, "/api/v1/cfc-tasks/{id}/reactivate": { "post": { "callbacks": {}, "description": "As the page's Show does. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "postCfcTasksByIdReactivate", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "active": { "description": "Whether it is offered.", "type": "boolean" }, "category": { "description": "Its category.", "enum": [ "homemaker", "personal_care", "hma" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "minutes_per_task": { "description": "Minutes each time.", "format": "decimal", "nullable": true, "type": "string" }, "position": { "description": "Its place in the category.", "type": "integer" }, "task_name": { "description": "The task.", "nullable": true, "type": "string" }, "times_per_week": { "description": "Times a week.", "type": "integer" } }, "required": [ "id", "category", "task_name", "active" ], "title": "CfcTask", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The task" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Show a hidden CFC task", "tags": [ "Settings lists" ] } }, "/api/v1/checklist-items/{id}": { "patch": { "callbacks": {}, "description": "Its key, and caregivers' records under it, stay. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "patchChecklistItemsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "label": { "description": "The new label.", "type": "string" } }, "required": [ "label" ], "title": "ChecklistItemRename", "type": "object" } } }, "description": "The label", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "active": { "description": "Whether it is shown.", "type": "boolean" }, "checklist": { "description": "Which checklist.", "enum": [ "employee_file", "compliance" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_key": { "description": "The key caregivers' records are kept under; never changes.", "nullable": true, "type": "string" }, "item_type": { "description": "How it is kept.", "enum": [ "checkbox", "date_expiry", "attestation_link" ], "type": "string" }, "label": { "description": "What the item is called.", "nullable": true, "type": "string" }, "position": { "description": "Its place in the checklist.", "type": "integer" } }, "required": [ "id", "checklist", "item_key", "label", "active" ], "title": "ChecklistItem", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The item" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Rename a checklist item", "tags": [ "Settings lists" ] } }, "/api/v1/checklist-items/{id}/deactivate": { "post": { "callbacks": {}, "description": "Hides it from caregivers' checklists; saved records stay. The last visible item answers 422 last_active. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "postChecklistItemsByIdDeactivate", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "active": { "description": "Whether it is shown.", "type": "boolean" }, "checklist": { "description": "Which checklist.", "enum": [ "employee_file", "compliance" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_key": { "description": "The key caregivers' records are kept under; never changes.", "nullable": true, "type": "string" }, "item_type": { "description": "How it is kept.", "enum": [ "checkbox", "date_expiry", "attestation_link" ], "type": "string" }, "label": { "description": "What the item is called.", "nullable": true, "type": "string" }, "position": { "description": "Its place in the checklist.", "type": "integer" } }, "required": [ "id", "checklist", "item_key", "label", "active" ], "title": "ChecklistItem", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The item" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code last_active: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Hide a checklist item", "tags": [ "Settings lists" ] } }, "/api/v1/checklist-items/{id}/move": { "post": { "callbacks": {}, "description": "One place, as the page's arrows do; answers the checklist in its new order. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "postChecklistItemsByIdMove", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "direction": { "description": "Which way to move it one place.", "enum": [ "up", "down" ], "type": "string" } }, "required": [ "direction" ], "title": "MoveDirection", "type": "object" } } }, "description": "Which way", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "active": { "description": "Whether it is shown.", "type": "boolean" }, "checklist": { "description": "Which checklist.", "enum": [ "employee_file", "compliance" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_key": { "description": "The key caregivers' records are kept under; never changes.", "nullable": true, "type": "string" }, "item_type": { "description": "How it is kept.", "enum": [ "checkbox", "date_expiry", "attestation_link" ], "type": "string" }, "label": { "description": "What the item is called.", "nullable": true, "type": "string" }, "position": { "description": "Its place in the checklist.", "type": "integer" } }, "required": [ "id", "checklist", "item_key", "label", "active" ], "title": "ChecklistItem", "type": "object" }, "title": "ChecklistItemsMoved", "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The items" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Move a checklist item up or down", "tags": [ "Settings lists" ] } }, "/api/v1/checklist-items/{id}/reactivate": { "post": { "callbacks": {}, "description": "As the page's Show does. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "postChecklistItemsByIdReactivate", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "active": { "description": "Whether it is shown.", "type": "boolean" }, "checklist": { "description": "Which checklist.", "enum": [ "employee_file", "compliance" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_key": { "description": "The key caregivers' records are kept under; never changes.", "nullable": true, "type": "string" }, "item_type": { "description": "How it is kept.", "enum": [ "checkbox", "date_expiry", "attestation_link" ], "type": "string" }, "label": { "description": "What the item is called.", "nullable": true, "type": "string" }, "position": { "description": "Its place in the checklist.", "type": "integer" } }, "required": [ "id", "checklist", "item_key", "label", "active" ], "title": "ChecklistItem", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The item" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Show a hidden checklist item", "tags": [ "Settings lists" ] } }, "/api/v1/checklists/{checklist}/items": { "get": { "callbacks": {}, "description": "Every item of the employee-file or compliance checklist, hidden ones included, in order, as Settings > Checklists shows them. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "getChecklistsByChecklistItems", "parameters": [ { "description": "employee_file or compliance.", "in": "path", "name": "checklist", "required": true, "schema": { "description": "The checklist.", "enum": [ "employee_file", "compliance" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "active": { "description": "Whether it is shown.", "type": "boolean" }, "checklist": { "description": "Which checklist.", "enum": [ "employee_file", "compliance" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_key": { "description": "The key caregivers' records are kept under; never changes.", "nullable": true, "type": "string" }, "item_type": { "description": "How it is kept.", "enum": [ "checkbox", "date_expiry", "attestation_link" ], "type": "string" }, "label": { "description": "What the item is called.", "nullable": true, "type": "string" }, "position": { "description": "Its place in the checklist.", "type": "integer" } }, "required": [ "id", "checklist", "item_key", "label", "active" ], "title": "ChecklistItem", "type": "object" }, "title": "ChecklistItems", "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The items" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a checklist's items", "tags": [ "Settings lists" ] }, "post": { "callbacks": {}, "description": "Adds an item at the end, as the page's Add does; its key is made from the label. A compliance item is a date-expiry item unless item_type is checkbox. A label that keys an existing item answers 422 validation_failed. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "postChecklistsByChecklistItems", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "description": "employee_file or compliance.", "in": "path", "name": "checklist", "required": true, "schema": { "description": "The checklist.", "enum": [ "employee_file", "compliance" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "item_type": { "description": "Compliance only.", "enum": [ "checkbox", "date_expiry" ], "type": "string" }, "label": { "description": "What the item is called.", "type": "string" } }, "required": [ "label" ], "title": "ChecklistItemCreate", "type": "object" } } }, "description": "The item", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "active": { "description": "Whether it is shown.", "type": "boolean" }, "checklist": { "description": "Which checklist.", "enum": [ "employee_file", "compliance" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_key": { "description": "The key caregivers' records are kept under; never changes.", "nullable": true, "type": "string" }, "item_type": { "description": "How it is kept.", "enum": [ "checkbox", "date_expiry", "attestation_link" ], "type": "string" }, "label": { "description": "What the item is called.", "nullable": true, "type": "string" }, "position": { "description": "Its place in the checklist.", "type": "integer" } }, "required": [ "id", "checklist", "item_key", "label", "active" ], "title": "ChecklistItem", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The item" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Add a checklist item", "tags": [ "Settings lists" ] } }, "/api/v1/checks/{number}/reconcile": { "post": { "callbacks": {}, "description": "Marks every unreconciled claim of the agency's paid by the check reconciled, as the payment report's bulk action does, and answers how many it marked (0 when none was left).", "operationId": "postChecksByNumberReconcile", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "description": "", "in": "path", "name": "number", "required": true, "schema": { "nullable": true, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "check_number": { "nullable": true, "type": "string" }, "reconciled": { "description": "Claims marked.", "nullable": true, "type": "integer" } }, "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "How many were marked" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Mark every claim a check paid reconciled", "tags": [ "Claims" ] } }, "/api/v1/claims": { "get": { "callbacks": {}, "description": "Claims are created by uploading a file to /api/v1/batches. The agency's claims in batch order, and row order within each batch. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getClaims", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records with this status.", "in": "query", "name": "status", "schema": { "enum": [ "pending", "validated", "invalid", "submitted", "accepted", "not_accepted", "rejected", "paid" ], "type": "string" } }, { "description": "Only claims of this batch.", "in": "query", "name": "batch_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only claims whose Medicaid ID or patient name contains this text, case-insensitively. At most 64 characters.", "in": "query", "name": "member", "schema": { "maxLength": 64, "type": "string" } }, { "description": "Only claims whose service period reaches this date or later (YYYY-MM-DD); a period straddling the bound is included.", "in": "query", "name": "service_date_from", "schema": { "format": "date", "type": "string" } }, { "description": "Only claims whose service period starts on or before this date (YYYY-MM-DD).", "in": "query", "name": "service_date_to", "schema": { "format": "date", "type": "string" } }, { "description": "Only records changed at or after this instant (ISO 8601, with an offset), compared to the second. The list is then in change order: updated_at, then id.", "in": "query", "name": "updated_since", "schema": { "format": "date-time", "type": "string" } }, { "description": "With updated_since, a cursor: send the last record's updated_at as updated_since and its id as after_id to get the next page. Use this, not offset, to sync: an offset skips a record when an earlier one changes between two requests. The sync is at least once: timestamps are whole seconds and set before commit, so a record changed in the cursor's second, or committed late, can fall behind the cursor. Start each sync pass a minute before the newest updated_at you saw, and treat every record returned as current: apply it over what you hold. A record can change twice within one second, and not every change moves lock_version, so the same updated_at and lock_version do not mean the same content.", "in": "query", "name": "after_id", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Claim" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClaimPage", "type": "object" } } }, "description": "A page of claims" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List claims", "tags": [ "Claims" ] } }, "/api/v1/claims/{id}": { "get": { "callbacks": {}, "description": "Claims are created by uploading a file to /api/v1/batches.", "operationId": "getClaimsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Claim" } }, "required": [ "data" ], "type": "object" } } }, "description": "The claim" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no claim with that id in this agency, including another agency's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a claim", "tags": [ "Claims" ] }, "patch": { "callbacks": {}, "description": "Changes the fields sent on a rejected or denied claim from an uploaded file and validates it again, as the batch page's correction form does. A reason is required. Needs billing.manage (403 forbidden otherwise), as the page does. A claim built from a returned timesheet answers 422 timesheet_derived; one HCPF holds as paid 422 held_as_paid; any other status 422 not_editable. validation_errors names what is still wrong; the correction is saved either way. Another agency's batch or claim answers 404 and nothing is written.", "operationId": "patchClaimsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The claim fields to change, as the batch page's correction form takes them (member, dates, codes, modifiers, diagnosis, units, charge, PAR number), and why.", "properties": { "charge_amount": { "description": "Amount billed.", "format": "decimal", "type": "string" }, "diagnosis_code_1": { "description": "The diagnosis code; null or blank clears it.", "nullable": true, "type": "string" }, "member_id": { "description": "The Medicaid member id.", "type": "string" }, "modifier_1": { "description": "A modifier; null or blank clears it.", "nullable": true, "type": "string" }, "modifier_2": { "description": "A modifier; null or blank clears it.", "nullable": true, "type": "string" }, "modifier_3": { "description": "A modifier; null or blank clears it.", "nullable": true, "type": "string" }, "modifier_4": { "description": "A modifier; null or blank clears it.", "nullable": true, "type": "string" }, "par_number": { "description": "The prior authorization request number; null or blank clears it.", "nullable": true, "type": "string" }, "place_of_service": { "description": "The place of service code.", "type": "string" }, "procedure_code": { "description": "The procedure code, e.g. T1019.", "type": "string" }, "reason": { "description": "Why the claim is corrected; kept on its audit trail.", "type": "string" }, "service_date_from": { "description": "YYYY-MM-DD.", "format": "date", "type": "string" }, "service_date_to": { "description": "YYYY-MM-DD.", "format": "date", "type": "string" }, "units": { "description": "Units billed.", "format": "decimal", "type": "string" } }, "required": [ "reason" ], "type": "object" } } }, "description": "The changes and the reason", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Claim" } }, "required": [ "data" ], "type": "object" } } }, "description": "The claim" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes held_as_paid, not_editable, timesheet_derived: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Correct an uploaded claim", "tags": [ "Claims" ] } }, "/api/v1/claims/{id}/evv-correction": { "delete": { "callbacks": {}, "description": "Restores the units and charge the claim billed before its EVV unit correction and validates it again, as the batch drawer's Undo does. A claim with no correction to undo answers 422 no_correction; one whose units or charge changed since the correction 409 changed_since. A claim already sent to HCPF, or whose batch is being sent, answers 422 already_sent; one whose batch is being checked, has its 837 built, or failed or was cancelled, but never went to HCPF, 422 batch_not_open; one not compared with EVV visits (a spreadsheet claim, a live-in caregiver, a code with no unit rule, no verified visits in its dates) 422 not_checkable; one whose verified visits add up to 0 units 422 no_evv_units; a batch being changed right now 409 busy. Another agency's batch or claim answers 404 and nothing is written.", "operationId": "deleteClaimsByIdEvvCorrection", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Claim" } }, "required": [ "data" ], "type": "object" } } }, "description": "The claim" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code changed_since: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_sent, batch_not_open, no_correction, no_evv_units, not_checkable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Undo a claim's EVV unit correction", "tags": [ "Claims" ] }, "get": { "callbacks": {}, "description": "The claim's billed units beside the units its verified EVV visits add up to, the counted visits, its charge now and at the EVV units, as the batch drawer's Use EVV units shows them. refusal is null when POST would succeed now, and otherwise the code and message it would answer; correction is the live correction, which DELETE undoes. Nothing changes. Another agency's batch or claim answers 404 and nothing is written.", "operationId": "getClaimsByIdEvvCorrection", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "billed_units": { "description": "Units the claim bills now.", "format": "decimal", "nullable": true, "type": "string" }, "claim_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "correction": { "description": "A claim's units set to its verified EVV visits' units, and the figures before.", "nullable": true, "properties": { "applied_at": { "format": "date-time", "type": "string" }, "applied_by_id": { "description": "The record's id.", "format": "uuid", "nullable": true, "type": "string" }, "batch_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "claim_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "evv_units": { "description": "Units the verified EVV visits add up to.", "nullable": true, "type": "integer" }, "from_charge": { "description": "Charge before.", "format": "decimal", "nullable": true, "type": "string" }, "from_units": { "description": "Units the claim billed before.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "to_charge": { "description": "Charge after, at the claim's own price per unit.", "format": "decimal", "nullable": true, "type": "string" }, "to_units": { "description": "Units it bills after: the EVV units.", "format": "decimal", "nullable": true, "type": "string" }, "undone_at": { "format": "date-time", "nullable": true, "type": "string" }, "undone_by_id": { "description": "The record's id.", "format": "uuid", "nullable": true, "type": "string" }, "visit_ids": { "description": "The visits counted.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "type": "array" } }, "title": "ClaimEvvCorrection", "type": "object" }, "current_charge": { "description": "The claim's charge now.", "format": "decimal", "nullable": true, "type": "string" }, "evv_units": { "description": "Units its verified EVV visits add up to; null when it is not compared.", "nullable": true, "type": "integer" }, "proposed_charge": { "description": "The charge at evv_units, at the claim's own price per unit, rounded to cents; null when it has no charge or bills 0 units, and then applying leaves the charge as it is.", "format": "decimal", "nullable": true, "type": "string" }, "refusal": { "description": "Null when applying now would succeed; otherwise what it would answer: code and message.", "nullable": true, "properties": { "code": { "nullable": true, "type": "string" }, "message": { "nullable": true, "type": "string" } }, "type": "object" }, "visit_ids": { "description": "The visits counted.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "type": "array" } }, "required": [ "claim_id", "billed_units", "visit_ids", "refusal", "correction" ], "title": "ClaimEvvCorrectionProposal", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "What would change" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "See what using a claim's EVV units would change", "tags": [ "Claims" ] }, "post": { "callbacks": {}, "description": "Sets an unsent claim's units to what its verified EVV visits add up to and its charge to the same price per unit, validates it again and keeps the change on its audit trail, as the batch drawer's Bill {evv} units does. The claim's status, its timesheet and its visits do not change. Send the billed_units GET answered: a claim billing anything else, or already corrected, answers 409 changed_since; one already billing its EVV units 422 no_difference. A claim already sent to HCPF, or whose batch is being sent, answers 422 already_sent; one whose batch is being checked, has its 837 built, or failed or was cancelled, but never went to HCPF, 422 batch_not_open; one not compared with EVV visits (a spreadsheet claim, a live-in caregiver, a code with no unit rule, no verified visits in its dates) 422 not_checkable; one whose verified visits add up to 0 units 422 no_evv_units; a batch being changed right now 409 busy. Another agency's batch or claim answers 404 and nothing is written.", "operationId": "postClaimsByIdEvvCorrection", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "expected_billed_units": { "description": "The units the claim bills as you saw them: billed_units from GET /claims/{id}/evv-correction. A claim that bills anything else now answers 409 changed_since and nothing changes.", "format": "decimal", "type": "string" } }, "required": [ "expected_billed_units" ], "type": "object" } } }, "description": "The units you saw", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "correction": { "description": "A claim's units set to its verified EVV visits' units, and the figures before.", "properties": { "applied_at": { "format": "date-time", "type": "string" }, "applied_by_id": { "description": "The record's id.", "format": "uuid", "nullable": true, "type": "string" }, "batch_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "claim_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "evv_units": { "description": "Units the verified EVV visits add up to.", "nullable": true, "type": "integer" }, "from_charge": { "description": "Charge before.", "format": "decimal", "nullable": true, "type": "string" }, "from_units": { "description": "Units the claim billed before.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "to_charge": { "description": "Charge after, at the claim's own price per unit.", "format": "decimal", "nullable": true, "type": "string" }, "to_units": { "description": "Units it bills after: the EVV units.", "format": "decimal", "nullable": true, "type": "string" }, "undone_at": { "format": "date-time", "nullable": true, "type": "string" }, "undone_by_id": { "description": "The record's id.", "format": "uuid", "nullable": true, "type": "string" }, "visit_ids": { "description": "The visits counted.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "type": "array" } }, "title": "ClaimEvvCorrection", "type": "object" }, "data": { "$ref": "#/components/schemas/Claim" } }, "required": [ "data", "correction" ], "type": "object" } } }, "description": "The corrected claim and the correction" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code changed_since: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_sent, batch_not_open, no_difference, no_evv_units, not_checkable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Bill a claim's EVV units", "tags": [ "Claims" ] } }, "/api/v1/claims/{id}/evv-override": { "post": { "callbacks": {}, "description": "Overrides the claim's EVV warning with a reason, kept on its audit trail, as the batch page does. The reason must be at least 10 characters (422 override_reason_too_short); a claim without an EVV warning answers 422 not_warning_status. Another agency's batch or claim answers 404 and nothing is written.", "operationId": "postClaimsByIdEvvOverride", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Why the warning is overridden; at least 10 characters, kept on the claim's audit trail.", "type": "string" } }, "required": [ "reason" ], "type": "object" } } }, "description": "Why the warning is overridden", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Claim" } }, "required": [ "data" ], "type": "object" } } }, "description": "The claim" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes not_warning_status, override_reason_too_short: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Override a claim's EVV warning", "tags": [ "Claims" ] } }, "/api/v1/claims/{id}/follow-up": { "post": { "callbacks": {}, "description": "Opens the follow-up for the claim's client in the month of its first service date, as the denials page's Follow-up control does. One already open for that client and month answers 409 follow_up_exists; a claim naming no client 422 no_client. Another agency's batch or claim answers 404 and nothing is written.", "operationId": "postClaimsByIdFollowUp", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "billing_period": { "description": "The month followed up, as the follow-ups page names it.", "nullable": true, "type": "string" }, "client_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "completed": { "type": "boolean" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "month": { "type": "integer" }, "year": { "type": "integer" } }, "required": [ "id", "client_id", "billing_period" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The follow-up" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code follow_up_exists: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code no_client: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Open a follow-up for a denied claim", "tags": [ "Claims" ] } }, "/api/v1/claims/{id}/investigation": { "patch": { "callbacks": {}, "description": "Sets investigation_status and resolution_notes on a denied claim, as the denials page does. Another agency's batch or claim answers 404 and nothing is written.", "operationId": "patchClaimsByIdInvestigation", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "investigation_status": { "enum": [ "unresolved", "investigating", "corrected", "resubmitted", "written_off" ], "type": "string" }, "resolution_notes": { "description": "The notes; null or blank clears them.", "nullable": true, "type": "string" } }, "type": "object" } } }, "description": "The status and notes", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Claim" } }, "required": [ "data" ], "type": "object" } } }, "description": "The claim" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a denial's investigation status", "tags": [ "Claims" ] } }, "/api/v1/claims/{id}/prepare-resubmission": { "post": { "callbacks": {}, "description": "Returns the claim's returned timesheet to Approved so it can be corrected and exported again, as the batch page's Release control does, and marks the claim prepared. Needs billing.manage (403 forbidden otherwise), as the page does. A claim already prepared answers 422 already_prepared. A claim that is not rejected or denied answers 422 not_resubmittable; one uploaded from a spreadsheet 422 no_timesheet; one whose returned timesheet another claim already released, whose sibling is still processing or was paid, or whose timesheet is no longer exported 409 already_released_by_sibling, siblings_still_processing, paid_sibling_exists or timesheet_not_exported; one HCPF holds as paid 422 held_as_paid; one a correction replaces 409 already_replaced; one whose patient account number an active claim holds 409 pan_blocked. Another agency's batch or claim answers 404 and nothing is written.", "operationId": "postClaimsByIdPrepareResubmission", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Claim" } }, "required": [ "data" ], "type": "object" } } }, "description": "The claim" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_released_by_sibling, already_replaced, pan_blocked: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_prepared, held_as_paid, no_timesheet, not_resubmittable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Release a refused claim's timesheet for resubmission", "tags": [ "Claims" ] } }, "/api/v1/claims/{id}/reconcile": { "post": { "callbacks": {}, "description": "Marks the claim reconciled with its payment, as the payment report does. A claim already reconciled keeps its mark. Another agency's batch or claim answers 404 and nothing is written.", "operationId": "postClaimsByIdReconcile", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Claim" } }, "required": [ "data" ], "type": "object" } } }, "description": "The claim" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Mark a claim reconciled", "tags": [ "Claims" ] } }, "/api/v1/claims/{id}/replacement": { "post": { "callbacks": {}, "description": "Creates a corrected copy of the claim in a batch of its own, sent to HCPF as a replacement (or an adjustment of a claim HCPF holds as paid), as the batch page does. A reason is required. Needs billing.manage (403 forbidden otherwise). A claim that already has one answers 409 already_replaced; one whose timesheet can simply be released for resubmission 422 release_available. Another agency's batch or claim answers 404 and nothing is written.", "operationId": "postClaimsByIdReplacement", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The claim fields to change, as the batch page's correction form takes them (member, dates, codes, modifiers, diagnosis, units, charge, PAR number), and why.", "properties": { "charge_amount": { "description": "Amount billed.", "format": "decimal", "type": "string" }, "diagnosis_code_1": { "description": "The diagnosis code; null or blank clears it.", "nullable": true, "type": "string" }, "member_id": { "description": "The Medicaid member id.", "type": "string" }, "modifier_1": { "description": "A modifier; null or blank clears it.", "nullable": true, "type": "string" }, "modifier_2": { "description": "A modifier; null or blank clears it.", "nullable": true, "type": "string" }, "modifier_3": { "description": "A modifier; null or blank clears it.", "nullable": true, "type": "string" }, "modifier_4": { "description": "A modifier; null or blank clears it.", "nullable": true, "type": "string" }, "par_number": { "description": "The prior authorization request number; null or blank clears it.", "nullable": true, "type": "string" }, "place_of_service": { "description": "The place of service code.", "type": "string" }, "procedure_code": { "description": "The procedure code, e.g. T1019.", "type": "string" }, "reason": { "description": "Why the claim is corrected; kept on its audit trail.", "type": "string" }, "service_date_from": { "description": "YYYY-MM-DD.", "format": "date", "type": "string" }, "service_date_to": { "description": "YYYY-MM-DD.", "format": "date", "type": "string" }, "units": { "description": "Units billed.", "format": "decimal", "type": "string" } }, "required": [ "reason" ], "type": "object" } } }, "description": "The changes and the reason", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "batch": { "$ref": "#/components/schemas/Batch" }, "data": { "$ref": "#/components/schemas/Claim" } }, "required": [ "data", "batch" ], "type": "object" } } }, "description": "The replacement claim and its batch" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code already_replaced: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code release_available: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a replacement claim", "tags": [ "Claims" ] } }, "/api/v1/claims/{id}/unreconcile": { "post": { "callbacks": {}, "description": "As the payment report's toggle does. Another agency's batch or claim answers 404 and nothing is written.", "operationId": "postClaimsByIdUnreconcile", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Claim" } }, "required": [ "data" ], "type": "object" } } }, "description": "The claim" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Remove a claim's reconciled mark", "tags": [ "Claims" ] } }, "/api/v1/client-certifications/{id}": { "delete": { "callbacks": {}, "description": "Removes it, as the Certifications tab does; the audit trail keeps what it was.", "operationId": "deleteClientCertificationsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ClientCertification" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted certification" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a certification period", "tags": [ "Client records" ] }, "patch": { "callbacks": {}, "description": "Send only what changes. An overlap with another period answers 422.", "operationId": "patchClientCertificationsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientCertificationInput" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ClientCertification" } }, "required": [ "data" ], "type": "object" } } }, "description": "The certification" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a certification period", "tags": [ "Client records" ] } }, "/api/v1/client-notes/{id}": { "delete": { "callbacks": {}, "description": "Soft-deletes the note and its attachments, as the client's communication log does. Notes carry no lock_version.", "operationId": "deleteClientNotesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ClientNote" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted note" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a client communication note", "tags": [ "Deletes and restores" ] }, "patch": { "callbacks": {}, "description": "Sets only the fields sent; a field sent as null is cleared, and a required one is refused. A body that changes nothing is 422 nothing_to_change. Notes carry no lock_version: the row is locked and re-read for the change.", "operationId": "patchClientNotesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientNoteInput" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ClientNote" } }, "required": [ "data" ], "type": "object" } } }, "description": "The note" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code nothing_to_change: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a client note", "tags": [ "Communication notes" ] } }, "/api/v1/client-notes/{id}/attachments": { "get": { "callbacks": {}, "description": "Oldest first, as the note page shows them, each with its scan status.", "operationId": "getClientNotesByIdAttachments", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "content_type": { "description": "Its type.", "nullable": true, "type": "string" }, "file_size": { "description": "Its size in bytes.", "nullable": true, "type": "integer" }, "filename": { "description": "The file's name.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was attached.", "format": "date-time", "type": "string" }, "note_id": { "description": "The note.", "format": "uuid", "type": "string" }, "note_kind": { "description": "The kind of note it is on.", "enum": [ "client", "caregiver" ], "type": "string" }, "scan_status": { "description": "The virus scan's verdict; only a clean file can be downloaded.", "enum": [ "pending", "clean", "infected", "error" ], "type": "string" }, "uploaded_by_id": { "description": "Who attached it.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "note_kind", "note_id", "filename", "content_type", "file_size", "scan_status" ], "title": "NoteAttachment", "type": "object" }, "type": "array" } }, "required": [ "data" ], "title": "NoteAttachmentList", "type": "object" } } }, "description": "The note's attachments" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a client note's attachments", "tags": [ "Communication notes" ] }, "post": { "callbacks": {}, "description": "Attaches a file as the note page's upload does: image/png, image/jpeg, image/gif, image/webp, application/pdf, up to 10 MB, at most 50 on a note, its extension matching its type and its bytes matching both. A refused file writes nothing and answers 422 naming the rule. The file is virus-scanned after it is saved and cannot be downloaded until its scan_status is clean.", "operationId": "postClientNotesByIdAttachments", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "format": "binary", "type": "string" } }, "required": [ "file" ], "type": "object" } } }, "description": "The file", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "content_type": { "description": "Its type.", "nullable": true, "type": "string" }, "file_size": { "description": "Its size in bytes.", "nullable": true, "type": "integer" }, "filename": { "description": "The file's name.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was attached.", "format": "date-time", "type": "string" }, "note_id": { "description": "The note.", "format": "uuid", "type": "string" }, "note_kind": { "description": "The kind of note it is on.", "enum": [ "client", "caregiver" ], "type": "string" }, "scan_status": { "description": "The virus scan's verdict; only a clean file can be downloaded.", "enum": [ "pending", "clean", "infected", "error" ], "type": "string" }, "uploaded_by_id": { "description": "Who attached it.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "note_kind", "note_id", "filename", "content_type", "file_size", "scan_status" ], "title": "NoteAttachment", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The attachment" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code internal_error: a failure on our side, which was logged. When its message says nothing changed (the file store refused the request, the virus scan could not be queued, the upload could not be read), nothing did, the same request fails the same way until it is fixed, and the Idempotency-Key stays free." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code storage_unavailable (the file store did not answer) or, on an upload, temporarily_unavailable (its uploaded file could not be read): nothing changed, and the same request can succeed later. Retry after the Retry-After seconds; a write retried with the same Idempotency-Key runs again.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (30).", "schema": { "type": "integer" }, "style": "simple" } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Attach a file to a client note", "tags": [ "Communication notes" ] } }, "/api/v1/client-other-services/{id}": { "delete": { "callbacks": {}, "description": "Removes it, as the client page does; the audit trail keeps what it was.", "operationId": "deleteClientOtherServicesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ClientOtherService" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted other service" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a client's other service", "tags": [ "Client records" ] }, "patch": { "callbacks": {}, "description": "Send only what changes; days replaces the list, and times replaces the map. A refused value answers 422 naming the field.", "operationId": "patchClientOtherServicesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientOtherServiceInput" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ClientOtherService" } }, "required": [ "data" ], "type": "object" } } }, "description": "The other service" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a client's other service", "tags": [ "Client records" ] } }, "/api/v1/clients": { "get": { "callbacks": {}, "description": "The agency's clients in name order, deleted ones left out unless include_deleted=true. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getClients", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records with this status.", "in": "query", "name": "status", "schema": { "enum": [ "active", "inactive", "potential", "discharged" ], "type": "string" } }, { "description": "Every word must match a returned name or identifier, case-insensitively. At most 100 characters and 8 words.", "in": "query", "name": "search", "schema": { "maxLength": 100, "type": "string" } }, { "description": "Only records changed at or after this instant (ISO 8601, with an offset), compared to the second. The list is then in change order: updated_at, then id.", "in": "query", "name": "updated_since", "schema": { "format": "date-time", "type": "string" } }, { "description": "With updated_since, a cursor: send the last record's updated_at as updated_since and its id as after_id to get the next page. Use this, not offset, to sync: an offset skips a record when an earlier one changes between two requests. The sync is at least once: timestamps are whole seconds and set before commit, so a record changed in the cursor's second, or committed late, can fall behind the cursor. Start each sync pass a minute before the newest updated_at you saw, and treat every record returned as current: apply it over what you hold. A record can change twice within one second, and not every change moves lock_version, so the same updated_at and lock_version do not mean the same content.", "in": "query", "name": "after_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "true also lists deleted records, with deleted_at set, so a sync learns of deletions.", "in": "query", "name": "include_deleted", "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Client" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClientPage", "type": "object" } } }, "description": "A page of clients" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List clients", "tags": [ "Clients" ] }, "post": { "callbacks": {}, "operationId": "postClients", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientInput" } } }, "description": "The client's fields", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientWriteResult" } } }, "description": "The created client" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a client", "tags": [ "Clients" ] } }, "/api/v1/clients/import": { "post": { "callbacks": {}, "description": "Reads the file as Import Clients does: HCB's client columns, or InMyTeam's Patients export as it comes out of InMyTeam (format inmyteam_patients). Needs imports.manage. A row matching a client on file by Medicaid ID fills in only what that client left blank (updated); one matching by name and date of birth is skipped. The file is csv (text) or csv_base64, header row first, at most 5,000 rows, in a body of at most 1 MB (the MCP tool takes a larger one). dry_run true runs the same import and rolls it all back, so the counts are the ones the real import would answer and nothing is written: no record, audit row or import history. Sending the same file again writes nothing twice: its rows are skipped with the reason already_on_file, also when two sends run at once. Refusals: 403 forbidden naming the missing permission; 422 file_required (no csv or csv_base64, or base64 that does not decode), empty_file, too_many_rows, csv_parse_error, invalid_dry_run; none writes anything.", "operationId": "postClientsImport", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "csv": { "description": "The file as CSV text, header row first.", "type": "string" }, "csv_base64": { "description": "Or the file's bytes, base64.", "type": "string" }, "dry_run": { "description": "true: answer what the import would do, counted the same way, and write nothing. Left out or false: import.", "type": "boolean" } }, "type": "object" } } }, "description": "The file", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/RecordImportResult" } }, "required": [ "data" ], "type": "object" } } }, "description": "What the import did, or with dry_run true would do" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code file_required: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Import clients from a CSV file", "tags": [ "Imports" ] } }, "/api/v1/clients/{client_id}/contacts/{contact_id}/history": { "get": { "callbacks": {}, "description": "As the People section's History does: the contact's edits, newest first, each with when it was saved, who saved it (\"System\" when no member is recorded) and the names of the fields it changed; never an old or new value. The contact must hold a relation to the client, current or ended; one that does not answers 404. Needs clients.view; a client outside the caller's reach answers 403 forbidden.", "operationId": "getClientsByClientIdContactsByContactIdHistory", "parameters": [ { "description": "The client.", "in": "path", "name": "client_id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The contact.", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ContactHistoryEntry" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ContactHistoryPage", "type": "object" } } }, "description": "A page of revisions" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read a client's contact's history", "tags": [ "Client records" ] } }, "/api/v1/clients/{id}": { "delete": { "callbacks": {}, "description": "Soft-deletes the client, as the client list does: it leaves the default list and is listed with include_deleted=true, the web's Show archived. A client with active caregiver assignments or active service authorizations answers 422 has_active_references; one already deleted 422 already_deleted. A client changed since it was read answers 409 stale_record.", "operationId": "deleteClientsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The lock_version the record was read with: missing answers 400, changed since 409 stale_record.", "in": "query", "name": "lock_version", "required": true, "schema": { "description": "The value the record was read with; a record changed since answers 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Client" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted client" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_deleted, has_active_references: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a client", "tags": [ "Deletes and restores" ] }, "get": { "callbacks": {}, "operationId": "getClientsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Client" } }, "required": [ "data" ], "type": "object" } } }, "description": "The client" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no client with that id in this agency, including another agency's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a client", "tags": [ "Clients" ] }, "patch": { "callbacks": {}, "description": "Sets only the fields sent. lock_version is required: send the value you read, and a record changed since answers 409 stale_record.", "operationId": "patchClientsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientInput" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientWriteResult" } } }, "description": "The updated client" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no client with that id in this agency, including another agency's." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: the client changed since the lock_version sent was read, or while this request ran. Nothing was saved; read it again and retry." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a client", "tags": [ "Clients" ] } }, "/api/v1/clients/{id}/acp-protection": { "post": { "callbacks": {}, "description": "US-74.1: a client in Colorado's Address Confidentiality Program (PM 20-007) has its real address, phones and every call location withheld from Sandata; the ACP substitute address and phone sent here go in their place (the address whole or not at all, else 422). Removing the mark needs a reason (422 reason_required or reason_too_short). A request that changes nothing changes nothing and needs no reason. Audited against the credential.", "operationId": "postClientsByIdAcpProtection", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientAcpProtection" } } }, "description": "The mark", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Client" } }, "required": [ "data" ], "type": "object" } } }, "description": "The client" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code reason_required: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Mark a client ACP-protected, or remove the mark", "tags": [ "Clients" ] } }, "/api/v1/clients/{id}/agency-services-only": { "post": { "callbacks": {}, "description": "US-102.34: true says the client has no outside providers (Access's MHS ONLY), as the client page's Other services section sets it. The body carries the lock_version the client was read with; a client changed since answers 409 stale_record. Audited against the credential.", "operationId": "postClientsByIdAgencyServicesOnly", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientAgencyServicesOnly" } } }, "description": "The flag", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Client" } }, "required": [ "data" ], "type": "object" } } }, "description": "The client" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Set or clear a client's Agency services only flag", "tags": [ "Clients" ] } }, "/api/v1/clients/{id}/calendar-events": { "get": { "callbacks": {}, "description": "As the client's Calendar tab lists them: every event, done and dismissed included, earliest due first (by time of day within a date, untimed last). `open=upcoming` keeps the open events due today or later, `open=overdue` the open ones whose date has passed; any other value is 400. Close one with `POST /api/v1/reminders/{id}/complete` or `/dismiss`, whatever its date.", "operationId": "getClientsByIdCalendarEvents", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "upcoming or overdue; every event when left out.", "in": "query", "name": "open", "schema": { "enum": [ "upcoming", "overdue" ], "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "client_id": { "description": "The client it is about.", "format": "uuid", "type": "string" }, "completed_at": { "description": "When it was done.", "format": "date-time", "nullable": true, "type": "string" }, "description": { "description": "More about it.", "nullable": true, "type": "string" }, "due_date": { "description": "The day it is due.", "format": "date", "nullable": true, "type": "string" }, "due_time": { "description": "A time of day, HH:MM:SS (Mountain time).", "nullable": true, "type": "string" }, "event_type": { "enum": [ "supervisory_visit", "recertification", "follow_up", "custom" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "lock_version": { "description": "Its version.", "nullable": true, "type": "integer" }, "status": { "enum": [ "upcoming", "overdue", "completed", "dismissed" ], "type": "string" }, "title": { "description": "What is due.", "nullable": true, "type": "string" } }, "required": [ "id", "client_id", "event_type", "title", "due_date", "status", "lock_version" ], "title": "ClientCalendarEvent", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClientCalendarEventPage", "type": "object" } } }, "description": "A page of events" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Bad Request, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a client's calendar events", "tags": [ "Client records" ] }, "post": { "callbacks": {}, "description": "As the client's Calendar tab's Add Event does: a custom event, upcoming until it is done or dismissed (`POST /api/v1/reminders/{id}/complete` and `/dismiss` close it).", "operationId": "postClientsByIdCalendarEvents", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "description": { "description": "More about it, up to 5000 characters.", "nullable": true, "type": "string" }, "due_date": { "description": "The day it is due, YYYY-MM-DD.", "format": "date", "type": "string" }, "due_time": { "description": "The time it is due, HH:MM:SS, Mountain time.", "nullable": true, "type": "string" }, "title": { "description": "What is due, up to 200 characters.", "type": "string" } }, "required": [ "title", "due_date" ], "title": "ClientCalendarEventCreate", "type": "object" } } }, "description": "The event", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "client_id": { "description": "The client it is about.", "format": "uuid", "type": "string" }, "completed_at": { "description": "When it was done.", "format": "date-time", "nullable": true, "type": "string" }, "description": { "description": "More about it.", "nullable": true, "type": "string" }, "due_date": { "description": "The day it is due.", "format": "date", "nullable": true, "type": "string" }, "due_time": { "description": "A time of day, HH:MM:SS (Mountain time).", "nullable": true, "type": "string" }, "event_type": { "enum": [ "supervisory_visit", "recertification", "follow_up", "custom" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "lock_version": { "description": "Its version.", "nullable": true, "type": "integer" }, "status": { "enum": [ "upcoming", "overdue", "completed", "dismissed" ], "type": "string" }, "title": { "description": "What is due.", "nullable": true, "type": "string" } }, "required": [ "id", "client_id", "event_type", "title", "due_date", "status", "lock_version" ], "title": "ClientCalendarEvent", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The event" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Add an event to a client's calendar", "tags": [ "Client records" ] } }, "/api/v1/clients/{id}/certifications": { "get": { "callbacks": {}, "description": "Newest first, as the client's Certifications tab lists them.", "operationId": "getClientsByIdCertifications", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ClientCertification" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClientCertificationPage", "type": "object" } } }, "description": "A page of certifications" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a client's certification periods", "tags": [ "Client records" ] }, "post": { "callbacks": {}, "description": "As the Certifications tab does. A period overlapping another of the client's answers 422 naming effective_date.", "operationId": "postClientsByIdCertifications", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientCertificationInput" } } }, "description": "The period", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ClientCertification" } }, "required": [ "data" ], "type": "object" } } }, "description": "The certification" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Record a client's certification period", "tags": [ "Client records" ] } }, "/api/v1/clients/{id}/cfc-calculator": { "post": { "callbacks": {}, "description": "Starts an import as the CFC import page does: one current Plan of Care per service on the sheet, each making that service's current plan past, every task or the task_names sent (422 invalid_task_names for any other value). Answers 202 with the job; when it succeeds it carries the new plans and warnings. A file over max_file_size (5 MB) answers 422 file_too_large, and a body over the upload cap, which holds a 10 MB file, 413. What the file holds is judged by the job: a file the parser cannot read ends it failed, unreadable_calculator, and a scan (a PDF with no text, PNG or JPG) ends it failed, paper_capture_consent_required, unless the agency has accepted the paper_capture consent (POST /api/v1/consents/paper_capture).", "operationId": "postClientsByIdCfcCalculator", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "format": "binary", "type": "string" }, "task_names": { "items": { "type": "string" }, "type": "array" } }, "required": [ "file" ], "type": "object" } } }, "description": "A multipart form with the calculator in the field `file`: .xlsx, .pdf, .png, .jpg or .jpeg, at most 5 MB; for an import, optionally task_names[] fields naming the tasks to import when not all of them.", "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CfcImportJob" } }, "required": [ "data" ], "type": "object" } } }, "description": "The job, queued; GET /api/v1/cfc-imports/{id} until it has ended" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Request Entity Too Large, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes file_too_large, invalid_task_names: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Import a CFC calculator into a client's Plans of Care", "tags": [ "Plans of care" ] } }, "/api/v1/clients/{id}/cfc-calculator/preview": { "post": { "callbacks": {}, "description": "Starts a preview: when it succeeds the job carries each task with the per-day minutes an import would write for this client, or over_cap, and the warnings an import would carry. Changes no plan. A file over max_file_size (5 MB) answers 422 file_too_large, and a body over the upload cap, which holds a 10 MB file, 413. What the file holds is judged by the job: a file the parser cannot read ends it failed, unreadable_calculator, and a scan (a PDF with no text, PNG or JPG) ends it failed, paper_capture_consent_required, unless the agency has accepted the paper_capture consent (POST /api/v1/consents/paper_capture).", "operationId": "postClientsByIdCfcCalculatorPreview", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "format": "binary", "type": "string" }, "task_names": { "items": { "type": "string" }, "type": "array" } }, "required": [ "file" ], "type": "object" } } }, "description": "A multipart form with the calculator in the field `file`: .xlsx, .pdf, .png, .jpg or .jpeg, at most 5 MB; for an import, optionally task_names[] fields naming the tasks to import when not all of them.", "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CfcImportJob" } }, "required": [ "data" ], "type": "object" } } }, "description": "The job, queued; GET /api/v1/cfc-imports/{id} until it has ended" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Request Entity Too Large, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code file_too_large: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Preview a CFC calculator import", "tags": [ "Plans of care" ] } }, "/api/v1/clients/{id}/chart": { "get": { "callbacks": {}, "description": "As the /clients/:id/chart page: every record the agency holds for the client, newest first (by occurred_on, then when it was made), with each signed record's state, signers, open signature lines, true copy, signed addenda and void; each document's scan status; each care log's source and attestation. A draft is not an entry, except a care log. Another agency's client answers 404; a filter it cannot read answers 400 naming it.", "operationId": "getClientsByIdChart", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Record kinds, comma-separated (supervisory_visit, plan_of_care, monthly_client_report, complaint, critical_incident, consent_notice, emergency_information, care_log, half_month_summary, document, legacy_scan); every kind when left out.", "in": "query", "name": "types", "schema": { "type": "string" } }, { "description": "Only entries of this service (personal_care, homemaker, hma); a kind with no service leaves the page while it is set.", "in": "query", "name": "service_type", "schema": { "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" } }, { "description": "Only entries of this caregiver; a kind with no caregiver leaves the page while it is set.", "in": "query", "name": "caregiver_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "The first date, YYYY-MM-DD, inclusive.", "in": "query", "name": "from", "schema": { "format": "date", "type": "string" } }, { "description": "The last date, YYYY-MM-DD, inclusive.", "in": "query", "name": "to", "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "addenda": { "description": "The record's signed addenda, in signing order.", "items": { "properties": { "body": { "description": "What it adds.", "nullable": true, "type": "string", "x-untrusted": "text" }, "id": { "description": "The addendum.", "format": "uuid", "type": "string" }, "reason": { "description": "Why it was added.", "nullable": true, "type": "string", "x-untrusted": "text" }, "signatures": { "description": "Its live signatures, oldest first.", "items": { "properties": { "channel": { "description": "Where it was signed.", "enum": [ "app", "phone", "office", "scan", "docusign", "import" ], "nullable": true, "type": "string" }, "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin", "voice", "docusign_agency", "docusign_platform", "paper_on_file", "imported" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "caregiver", "supervisor", "pcp", "office" ], "type": "string" }, "role_label": { "description": "The line as the record names it, e.g. \"complainant\".", "nullable": true, "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed, as given.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "role_label", "signer_name", "method", "signed_at" ], "title": "ClientChartSignature", "type": "object" }, "type": "array" }, "signed_at": { "description": "When it was signed.", "format": "date-time", "type": "string" }, "state": { "description": "The addendum's own state.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "true_copy": { "properties": { "document_id": { "description": "The true copy, at /documents/{id}/download, once stored.", "format": "uuid", "nullable": true, "type": "string" }, "status": { "description": "none for a draft, an incomplete signing or a record signed before the electronic record; pending while the copy is made; stored once filed; failed when it could not be made.", "enum": [ "none", "pending", "stored", "failed" ], "type": "string" } }, "required": [ "status" ], "title": "ClientChartTrueCopy", "type": "object" } }, "required": [ "id", "body", "signed_at", "signatures", "true_copy" ], "title": "ClientChartAddendum", "type": "object" }, "type": "array" }, "care_log": { "nullable": true, "properties": { "attested": { "description": "Whether the client's attestation is on it: a client or representative signature, or recorded words.", "type": "boolean" }, "source": { "description": "Where the log was kept.", "enum": [ "hcb_app", "hcb_phone", "office", "paper_scan", "import" ], "type": "string" } }, "required": [ "source", "attested" ], "title": "ClientChartCareLog", "type": "object" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_name": { "description": "The caregiver's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "document": { "nullable": true, "properties": { "file_name": { "description": "Its file name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "id": { "description": "The document.", "format": "uuid", "type": "string" }, "scan_status": { "description": "Its virus scan; only a clean document can be downloaded.", "enum": [ "pending", "clean", "infected", "error", "rejected" ], "type": "string" } }, "required": [ "id", "file_name", "scan_status" ], "title": "ClientChartDocument", "type": "object" }, "kind": { "description": "The kind of record.", "enum": [ "supervisory_visit", "plan_of_care", "monthly_client_report", "complaint", "critical_incident", "consent_notice", "emergency_information", "care_log", "half_month_summary", "document", "legacy_scan" ], "type": "string" }, "legacy_signed": { "description": "True for a record signed before the electronic record: its signatures are on paper, and it has no true copy.", "type": "boolean" }, "missing_signers": { "description": "Each required line no live signature fills, e.g. \"caregiver or PCP\"; empty unless the record is signed or amended.", "items": { "type": "string" }, "type": "array" }, "occurred_on": { "description": "The date the entry is filed under: the visit, effective, service or complaint date, the first of a report's month, the first signature (Mountain) of a notice or emergency information, a scan's paper date, else the upload date (Mountain).", "format": "date", "nullable": true, "type": "string" }, "path": { "description": "The app page the title opens, or a document's download; null for a document whose virus scan is not clean.", "nullable": true, "type": "string" }, "record_id": { "description": "The record, or for a document or scan the document.", "format": "uuid", "type": "string" }, "service_type": { "description": "The service.", "enum": [ "personal_care", "homemaker", "hma", "legacy" ], "nullable": true, "type": "string" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "channel": { "description": "Where it was signed.", "enum": [ "app", "phone", "office", "scan", "docusign", "import" ], "nullable": true, "type": "string" }, "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin", "voice", "docusign_agency", "docusign_platform", "paper_on_file", "imported" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "caregiver", "supervisor", "pcp", "office" ], "type": "string" }, "role_label": { "description": "The line as the record names it, e.g. \"complainant\".", "nullable": true, "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed, as given.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "role_label", "signer_name", "method", "signed_at" ], "title": "ClientChartSignature", "type": "object" }, "type": "array" }, "state": { "description": "The record's state; null for a document.", "enum": [ "draft", "signed", "amended", "voided" ], "nullable": true, "type": "string" }, "title": { "description": "The entry's title, as the chart shows it.", "nullable": true, "type": "string" }, "true_copy": { "properties": { "document_id": { "description": "The true copy, at /documents/{id}/download, once stored.", "format": "uuid", "nullable": true, "type": "string" }, "status": { "description": "none for a draft, an incomplete signing or a record signed before the electronic record; pending while the copy is made; stored once filed; failed when it could not be made.", "enum": [ "none", "pending", "stored", "failed" ], "type": "string" } }, "required": [ "status" ], "title": "ClientChartTrueCopy", "type": "object" }, "void": { "nullable": true, "properties": { "actor_name": { "description": "Who voided it; null for an API key.", "nullable": true, "type": "string", "x-untrusted": "text" }, "reason": { "description": "Why it was voided.", "nullable": true, "type": "string", "x-untrusted": "text" }, "replaced_by_id": { "description": "The draft made to replace it, when one was made.", "format": "uuid", "nullable": true, "type": "string" }, "voided_at": { "description": "When it was voided.", "format": "date-time", "type": "string" } }, "required": [ "voided_at", "reason" ], "title": "ClientChartVoid", "type": "object" }, "work_order_id": { "description": "A Monthly Client Report's Work Order.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "kind", "record_id", "occurred_on", "title", "legacy_signed", "signatures", "missing_signers", "true_copy", "addenda" ], "title": "ClientChartEntry", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClientChartPage", "type": "object" } } }, "description": "A page of the chart" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Bad Request, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read a page of a client's chart", "tags": [ "Client records" ] } }, "/api/v1/clients/{id}/consent-forms": { "get": { "callbacks": {}, "description": "Newest first, the disclosure notices and rights acknowledgements alike.", "operationId": "getClientsByIdConsentForms", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 25, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "answers": { "description": "The answers, by question key: a disclosure item's responsible party (agency or consumer), the complaint contact.", "type": "object" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "declined_reason": { "description": "Why the client declined to sign a disclosure notice; the office then signs that it was conveyed verbally.", "nullable": true, "type": "string", "x-untrusted": "text" }, "defaulted_keys": { "description": "The choices still holding the answer the notice was prefilled with (its first option): defaults nobody has chosen.", "items": { "type": "string" }, "type": "array" }, "form_type": { "description": "agency_disclosure_notice (Chapter 26 6.7) or client_rights_acknowledgement (6.4).", "enum": [ "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the notice was started.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "missing_signers": { "description": "Each required line no live signature fills yet, in order; empty when complete or voided.", "items": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "type": "array" }, "record_state": { "description": "draft until the first signature; signed notices are corrected by addendum or void.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "signer_name", "method", "signed_at" ], "title": "RecordSignatureSummary", "type": "object" }, "type": "array" }, "signed_at": { "description": "When the first signature locked it; null on a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing_complete": { "description": "True once the record is signed or amended and every required line holds a signature. A signed record can be false: signed by one line, with another still open. A voided record is always false, whatever it holds, and its missing_signers is empty: nothing can sign it, and its replacement is the record to complete.", "type": "boolean" } }, "required": [ "id", "client_id", "form_type", "record_state", "answers", "lock_version" ], "title": "ClientConsentForm", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClientConsentFormPage", "type": "object" } } }, "description": "A page of notices" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a client's intake notices", "tags": [ "Client records" ] }, "post": { "callbacks": {}, "description": "Starts a draft stamped with the agency's current wording, each disclosure item prefilled with its first option (Agency). The client's open draft of that type, when there is one, is returned instead. Another agency's client is 404, before the body is judged.", "operationId": "postClientsByIdConsentForms", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "form_type": { "description": "The notice to start.", "enum": [ "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" } }, "required": [ "form_type" ], "title": "ClientConsentFormStart", "type": "object" } } }, "description": "The notice", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "answers": { "description": "The answers, by question key: a disclosure item's responsible party (agency or consumer), the complaint contact.", "type": "object" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "declined_reason": { "description": "Why the client declined to sign a disclosure notice; the office then signs that it was conveyed verbally.", "nullable": true, "type": "string", "x-untrusted": "text" }, "defaulted_keys": { "description": "The choices still holding the answer the notice was prefilled with (its first option): defaults nobody has chosen.", "items": { "type": "string" }, "type": "array" }, "form_type": { "description": "agency_disclosure_notice (Chapter 26 6.7) or client_rights_acknowledgement (6.4).", "enum": [ "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the notice was started.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "missing_signers": { "description": "Each required line no live signature fills yet, in order; empty when complete or voided.", "items": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "type": "array" }, "record_state": { "description": "draft until the first signature; signed notices are corrected by addendum or void.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "signer_name", "method", "signed_at" ], "title": "RecordSignatureSummary", "type": "object" }, "type": "array" }, "signed_at": { "description": "When the first signature locked it; null on a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing_complete": { "description": "True once the record is signed or amended and every required line holds a signature. A signed record can be false: signed by one line, with another still open. A voided record is always false, whatever it holds, and its missing_signers is empty: nothing can sign it, and its replacement is the record to complete.", "type": "boolean" } }, "required": [ "id", "client_id", "form_type", "record_state", "answers", "lock_version" ], "title": "ClientConsentForm", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The notice" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Start a client's intake notice", "tags": [ "Client records" ] } }, "/api/v1/clients/{id}/documents": { "get": { "callbacks": {}, "description": "Newest first, as the client page's Documents tab lists them, legacy paper scans included, each with its scan status. The read is recorded on the PHI access log.", "operationId": "getClientsByIdDocuments", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only documents of this type; legacy_paper is the paper archive.", "in": "query", "name": "document_type", "schema": { "description": "What the document is, as the Documents tab's Type.", "enum": [ "care_plan", "authorization", "signed_agreement", "training_certificate", "background_check", "medical_form", "incident_report", "pcsp", "cfc_calculator", "legacy_paper", "other", "paper_capture", "true_copy", "voice_attestation" ], "type": "string" } }, { "description": "Only legacy_paper scans of this form type.", "in": "query", "name": "form_type", "schema": { "description": "A legacy_paper scan's form type, as the paper archive files it (US-101.7); other when not given. Ignored on any other document_type.", "enum": [ "work_order", "time_services_card", "plan_of_care", "monthly_client_report", "supervisory_visit", "cfc_calculator", "intake_consent", "complaint_incident", "other" ], "type": "string" } }, { "description": "Only documents whose record_date is on or after this day (YYYY-MM-DD).", "in": "query", "name": "from", "schema": { "format": "date", "type": "string" } }, { "description": "Only documents whose record_date is on or before this day (YYYY-MM-DD).", "in": "query", "name": "to", "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "content_type": { "description": "Its type.", "nullable": true, "type": "string" }, "document_type": { "description": "What the document is, as the Documents tab's Type.", "enum": [ "care_plan", "authorization", "signed_agreement", "training_certificate", "background_check", "medical_form", "incident_report", "pcsp", "cfc_calculator", "legacy_paper", "other", "paper_capture", "true_copy", "voice_attestation" ], "type": "string" }, "documentable_id": { "description": "The client or caregiver.", "format": "uuid", "type": "string" }, "documentable_type": { "description": "Whose file it is on.", "enum": [ "client", "caregiver" ], "type": "string" }, "expiry_date": { "description": "When it expires, if it does.", "format": "date", "nullable": true, "type": "string" }, "file_name": { "description": "The file's name.", "nullable": true, "type": "string" }, "file_size": { "description": "Its size in bytes.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was uploaded.", "format": "date-time", "type": "string" }, "notes": { "description": "The tab's notes.", "nullable": true, "type": "string" }, "paper_form_type": { "description": "A legacy_paper scan's form type, as the paper archive files it (US-101.7); other when not given. Ignored on any other document_type.", "enum": [ "work_order", "time_services_card", "plan_of_care", "monthly_client_report", "supervisory_visit", "cfc_calculator", "intake_consent", "complaint_incident", "other" ], "nullable": true, "type": "string" }, "record_date": { "description": "A legacy_paper scan's date on the paper; a monthly form's is its month's first day. Ignored on any other document_type.", "format": "date", "nullable": true, "type": "string" }, "scan_status": { "description": "The virus scan's verdict; only a clean file can be downloaded.", "enum": [ "pending", "clean", "infected", "error" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" }, "uploaded_by": { "description": "Who uploaded it.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "documentable_type", "documentable_id", "file_name", "scan_status" ], "title": "PersonDocument", "type": "object" }, "type": "array" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "PersonDocumentList", "type": "object" } } }, "description": "The person's documents" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a client's documents", "tags": [ "Documents" ] }, "post": { "callbacks": {}, "description": "Stores a file on the person's file as the Documents tab's upload does (multipart field file, or JSON file_base64 with file_name and content_type): application/pdf, image/jpeg, image/png, image/gif, image/webp, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, text/plain, its extension matching its type and its first bytes matching both. A multipart file may be up to 50 MB; a JSON body takes at most 1 MB, file_base64 included. document_type defaults to other. A refused file writes nothing and answers 422 naming the rule. It is virus-scanned after it is saved and cannot be downloaded until its scan_status is clean.", "operationId": "postClientsByIdDocuments", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "content_type": { "description": "Its type; null or left out reads the extension's.", "nullable": true, "type": "string" }, "document_type": { "description": "What the document is, as the Documents tab's Type.", "enum": [ "care_plan", "authorization", "signed_agreement", "training_certificate", "background_check", "medical_form", "incident_report", "pcsp", "cfc_calculator", "legacy_paper", "other" ], "type": "string" }, "expiry_date": { "description": "When it expires.", "format": "date", "nullable": true, "type": "string" }, "file_base64": { "description": "The file's bytes, base64.", "type": "string" }, "file_name": { "description": "Its name, with its extension.", "type": "string" }, "notes": { "description": "Notes, as the tab's Notes.", "nullable": true, "type": "string" }, "paper_form_type": { "description": "A legacy_paper scan's form type, as the paper archive files it (US-101.7); other when not given. Ignored on any other document_type.", "enum": [ "work_order", "time_services_card", "plan_of_care", "monthly_client_report", "supervisory_visit", "cfc_calculator", "intake_consent", "complaint_incident", "other" ], "type": "string" }, "record_date": { "description": "A legacy_paper scan's date on the paper; a monthly form's is its month's first day. Ignored on any other document_type.", "format": "date", "nullable": true, "type": "string" } }, "required": [ "file_base64", "file_name" ], "title": "PersonDocumentUpload", "type": "object" } }, "multipart/form-data": { "schema": { "properties": { "document_type": { "description": "What the document is, as the Documents tab's Type.", "enum": [ "care_plan", "authorization", "signed_agreement", "training_certificate", "background_check", "medical_form", "incident_report", "pcsp", "cfc_calculator", "legacy_paper", "other" ], "type": "string" }, "expiry_date": { "description": "When it expires.", "format": "date", "nullable": true, "type": "string" }, "file": { "format": "binary", "type": "string" }, "notes": { "description": "Notes, as the tab's Notes.", "nullable": true, "type": "string" }, "paper_form_type": { "description": "A legacy_paper scan's form type, as the paper archive files it (US-101.7); other when not given. Ignored on any other document_type.", "enum": [ "work_order", "time_services_card", "plan_of_care", "monthly_client_report", "supervisory_visit", "cfc_calculator", "intake_consent", "complaint_incident", "other" ], "type": "string" }, "record_date": { "description": "A legacy_paper scan's date on the paper; a monthly form's is its month's first day. Ignored on any other document_type.", "format": "date", "nullable": true, "type": "string" } }, "required": [ "file" ], "type": "object" } } }, "description": "The file and its details", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "content_type": { "description": "Its type.", "nullable": true, "type": "string" }, "document_type": { "description": "What the document is, as the Documents tab's Type.", "enum": [ "care_plan", "authorization", "signed_agreement", "training_certificate", "background_check", "medical_form", "incident_report", "pcsp", "cfc_calculator", "legacy_paper", "other", "paper_capture", "true_copy", "voice_attestation" ], "type": "string" }, "documentable_id": { "description": "The client or caregiver.", "format": "uuid", "type": "string" }, "documentable_type": { "description": "Whose file it is on.", "enum": [ "client", "caregiver" ], "type": "string" }, "expiry_date": { "description": "When it expires, if it does.", "format": "date", "nullable": true, "type": "string" }, "file_name": { "description": "The file's name.", "nullable": true, "type": "string" }, "file_size": { "description": "Its size in bytes.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was uploaded.", "format": "date-time", "type": "string" }, "notes": { "description": "The tab's notes.", "nullable": true, "type": "string" }, "paper_form_type": { "description": "A legacy_paper scan's form type, as the paper archive files it (US-101.7); other when not given. Ignored on any other document_type.", "enum": [ "work_order", "time_services_card", "plan_of_care", "monthly_client_report", "supervisory_visit", "cfc_calculator", "intake_consent", "complaint_incident", "other" ], "nullable": true, "type": "string" }, "record_date": { "description": "A legacy_paper scan's date on the paper; a monthly form's is its month's first day. Ignored on any other document_type.", "format": "date", "nullable": true, "type": "string" }, "scan_status": { "description": "The virus scan's verdict; only a clean file can be downloaded.", "enum": [ "pending", "clean", "infected", "error" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" }, "uploaded_by": { "description": "Who uploaded it.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "documentable_type", "documentable_id", "file_name", "scan_status" ], "title": "PersonDocument", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The document" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code internal_error: a failure on our side, which was logged. When its message says nothing changed (the file store refused the request, the virus scan could not be queued, the upload could not be read), nothing did, the same request fails the same way until it is fixed, and the Idempotency-Key stays free." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code storage_unavailable (the file store did not answer) or, on an upload, temporarily_unavailable (its uploaded file could not be read): nothing changed, and the same request can succeed later. Retry after the Retry-After seconds; a write retried with the same Idempotency-Key runs again.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (30).", "schema": { "type": "integer" }, "style": "simple" } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Upload a document to a client's file", "tags": [ "Documents" ] } }, "/api/v1/clients/{id}/eligibility-verified": { "post": { "callbacks": {}, "operationId": "postClientsByIdEligibilityVerified", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Client" } }, "required": [ "data" ], "type": "object" } } }, "description": "The client" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Mark a client's eligibility verified", "tags": [ "Service authorizations", "Clients" ] } }, "/api/v1/clients/{id}/emergency-info": { "get": { "callbacks": {}, "description": "Newest first; the first is the current sheet. Each save is a new revision.", "operationId": "getClientsByIdEmergencyInfo", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "answers": { "description": "The answers, by question key.", "type": "object" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When this revision was saved.", "format": "date-time", "type": "string" }, "missing_signers": { "description": "Each required line no live signature fills yet, in order; empty when complete or voided.", "items": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "type": "array" }, "record_state": { "description": "draft until the first signature (US-101.32). A signed revision is never deleted or changed: it is corrected with an addendum, voided, or followed by a new revision.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "signer_name", "method", "signed_at" ], "title": "RecordSignatureSummary", "type": "object" }, "type": "array" }, "signed_at": { "description": "When the first signature locked it; null on a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing_complete": { "description": "True once the record is signed or amended and every required line holds a signature. A signed record can be false: signed by one line, with another still open. A voided record is always false, whatever it holds, and its missing_signers is empty: nothing can sign it, and its replacement is the record to complete.", "type": "boolean" }, "superseded": { "description": "True for a draft never signed whose client has a later signed revision: it is no longer the sheet in force, and may still be deleted.", "type": "boolean" }, "version": { "description": "Its revision number.", "type": "integer" } }, "required": [ "id", "client_id", "version", "answers", "record_state" ], "title": "ClientEmergencyInfo", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClientEmergencyInfoPage", "type": "object" } } }, "description": "A page of revisions" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a client's emergency information revisions", "tags": [ "Client records" ] }, "post": { "callbacks": {}, "description": "Saves a new revision, as the Emergency information page does; answers to questions not sent keep their current value. An answer the form refuses answers 422 naming the question.", "operationId": "postClientsByIdEmergencyInfo", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "answers": { "description": "Answers by question key.", "type": "object" } }, "required": [ "answers" ], "title": "ClientEmergencyInfoInput", "type": "object" } } }, "description": "The answers", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "answers": { "description": "The answers, by question key.", "type": "object" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When this revision was saved.", "format": "date-time", "type": "string" }, "missing_signers": { "description": "Each required line no live signature fills yet, in order; empty when complete or voided.", "items": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "type": "array" }, "record_state": { "description": "draft until the first signature (US-101.32). A signed revision is never deleted or changed: it is corrected with an addendum, voided, or followed by a new revision.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "signer_name", "method", "signed_at" ], "title": "RecordSignatureSummary", "type": "object" }, "type": "array" }, "signed_at": { "description": "When the first signature locked it; null on a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing_complete": { "description": "True once the record is signed or amended and every required line holds a signature. A signed record can be false: signed by one line, with another still open. A voided record is always false, whatever it holds, and its missing_signers is empty: nothing can sign it, and its replacement is the record to complete.", "type": "boolean" }, "superseded": { "description": "True for a draft never signed whose client has a later signed revision: it is no longer the sheet in force, and may still be deleted.", "type": "boolean" }, "version": { "description": "Its revision number.", "type": "integer" } }, "required": [ "id", "client_id", "version", "answers", "record_state" ], "title": "ClientEmergencyInfo", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The revision" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Save a client's emergency information", "tags": [ "Client records" ] } }, "/api/v1/clients/{id}/evidence": { "get": { "callbacks": {}, "description": "As the /clients/:id/evidence grid: every calendar day of the month for the client and caregiver, with the day's state (none, corroborated, single_source, conflict or conflict_dismissed), each evidence source's visits and billable times, timesheet_drifts (deprecated, always empty: a Timesheet day references its care log, so the two cannot differ), the keys of the day's open conflicts, and who dismissed each dismissed one, when and why. Another agency's client or caregiver answers 404.", "operationId": "getClientsByIdEvidence", "parameters": [ { "description": "The client.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "The caregiver.", "in": "query", "name": "caregiver_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "The month, YYYY-MM; this month (Mountain) when left out.", "in": "query", "name": "month", "required": false, "schema": { "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "days": { "description": "Every calendar day of the month, in order.", "items": { "properties": { "care_logs": { "items": { "properties": { "attestation_method": { "description": "How the client or representative signed it, if they did.", "nullable": true, "type": "string" }, "attestation_skip_reason": { "description": "Why the client could not sign, when the caregiver said.", "nullable": true, "type": "string" }, "care_log_id": { "description": "The care log.", "format": "uuid", "type": "string" }, "comparisons": { "items": { "properties": { "conflict_key": { "description": "The conflict's key, on a conflict only; dismiss it as a visit conflict is dismissed.", "nullable": true, "type": "string" }, "fields": { "description": "On a conflict, the fields that differ: start, end, tasks or attestation.", "items": { "type": "string" }, "type": "array" }, "kind": { "description": "What was compared: the care log's times with the visit evidence, its done tasks with the Work Order's office-typed marks, or the client's signature with the visit's client verification.", "enum": [ "care_log_times", "care_log_tasks", "attestation" ], "type": "string" }, "only_care_log": { "description": "Task codes done on the care log and not marked on the Work Order.", "items": { "type": "string" }, "type": "array" }, "only_work_order": { "description": "Task codes marked on the Work Order and not done on the care log.", "items": { "type": "string" }, "type": "array" }, "state": { "description": "The comparison's state.", "enum": [ "conflict", "conflict_dismissed", "corroborated", "single_source" ], "type": "string" }, "visit_id": { "description": "The visit it was compared with, when one was.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "kind", "state", "fields", "only_care_log", "only_work_order" ], "title": "ClientMonthEvidenceCareLogComparison", "type": "object" }, "type": "array" }, "end": { "description": "Its end (the linked visit's, else entered).", "format": "date-time", "nullable": true, "type": "string" }, "service_type": { "description": "Its service.", "nullable": true, "type": "string" }, "shift_number": { "description": "Its shift of the day.", "nullable": true, "type": "integer" }, "source": { "description": "How the care log was captured.", "enum": [ "hcb_app", "hcb_phone", "office", "paper_scan", "import" ], "type": "string" }, "start": { "description": "Its start (the linked visit's, else entered).", "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "care_log_id", "source", "service_type", "shift_number", "comparisons" ], "title": "ClientMonthEvidenceCareLog", "type": "object" }, "type": "array" }, "claim_changes": { "items": { "properties": { "batch_id": { "description": "The claim's batch.", "format": "uuid", "type": "string" }, "care_log_ids": { "description": "The care logs of the day that changed.", "items": { "type": "string" }, "type": "array" }, "claim_id": { "description": "The claim sent before the day's care log changed.", "format": "uuid", "type": "string" }, "fingerprint": { "description": "The warning's fingerprint; dismiss it through POST /api/v1/revenue-warnings/dismissals with the claim_id as subject_id.", "nullable": true, "type": "string" }, "kind": { "description": "changed_after_claim.", "nullable": true, "type": "string" }, "state": { "description": "Whether the warning is open or dismissed.", "enum": [ "conflict", "conflict_dismissed" ], "type": "string" } }, "required": [ "claim_id", "batch_id", "kind", "fingerprint", "state", "care_log_ids" ], "title": "ClientMonthEvidenceClaimChange", "type": "object" }, "type": "array" }, "date": { "description": "The day (Mountain).", "format": "date", "nullable": true, "type": "string" }, "dismissals": { "items": { "properties": { "conflict_key": { "description": "The conflict dismissed.", "nullable": true, "type": "string" }, "dismissed_at": { "description": "When it was dismissed.", "format": "date-time", "type": "string" }, "dismissed_by": { "description": "Who dismissed it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "dismissed_by_user_id": { "description": "The member who dismissed it; null for an API key.", "format": "uuid", "nullable": true, "type": "string" }, "reason": { "description": "Why it was dismissed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "conflict_key", "dismissed_by", "dismissed_at", "reason" ], "title": "ClientMonthEvidenceDismissal", "type": "object" }, "type": "array" }, "open_conflict_keys": { "description": "The keys of the day's visit, care-log and timesheet-drift conflicts nobody has dismissed.", "items": { "type": "string" }, "type": "array" }, "sources": { "items": { "properties": { "source": { "description": "The evidence source; paper_scan, on a day with no visit, is the times of its paper-scan care log.", "enum": [ "sandata", "other_evv", "hcb_app", "hcb_phone", "office", "paper_scan" ], "type": "string" }, "visits": { "items": { "properties": { "care_log_id": { "description": "On a paper_scan row, the paper-scan care log whose times it shows.", "format": "uuid", "nullable": true, "type": "string" }, "conflict_key": { "description": "The entry's conflict key, on a conflict only.", "nullable": true, "type": "string" }, "end": { "description": "Its billable end; null while it is open.", "format": "date-time", "nullable": true, "type": "string" }, "procedure_code": { "description": "Its procedure code.", "nullable": true, "type": "string" }, "start": { "description": "Its billable start (adjusted, else actual).", "format": "date-time", "nullable": true, "type": "string" }, "state": { "description": "The state of the reconciliation entry the visit is in.", "enum": [ "conflict", "conflict_dismissed", "corroborated", "single_source" ], "type": "string" }, "visit_id": { "description": "The visit; null on a paper_scan row, which has none.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "visit_id", "state" ], "title": "ClientMonthEvidenceVisit", "type": "object" }, "type": "array" } }, "required": [ "source", "visits" ], "title": "ClientMonthEvidenceSource", "type": "object" }, "type": "array" }, "state": { "description": "The day's state, the worst of its entries; none with no evidence.", "enum": [ "none", "conflict", "conflict_dismissed", "corroborated", "single_source" ], "type": "string" }, "timesheet_drifts": { "deprecated": true, "description": "Deprecated, always empty: a Timesheet day now references the day's care log itself, so the two cannot differ. Kept for one release; read nothing from it.", "items": { "properties": { "care_log_id": { "description": "The care log of the day.", "format": "uuid", "type": "string" }, "conflict_key": { "description": "The drift's key, built from the differing values; dismiss it through POST /api/v1/evidence-dismissals (or the month through POST /api/v1/clients/{id}/evidence/dismissals).", "nullable": true, "type": "string" }, "dismissed": { "description": "Whether it has been dismissed.", "type": "boolean" }, "fields": { "description": "The fields that differ: time_in, time_out or tasks.", "items": { "type": "string" }, "type": "array" }, "only_other": { "description": "Task names done on the other record and not on the timesheet.", "items": { "type": "string" }, "type": "array" }, "only_timesheet": { "description": "Task names done on the timesheet and not on the other record.", "items": { "type": "string" }, "type": "array" }, "other": { "properties": { "tasks": { "description": "The names of the tasks marked done that day.", "items": { "type": "string" }, "type": "array" }, "time_in": { "description": "Time In, Mountain, HH:MM; null when it has none.", "nullable": true, "type": "string" }, "time_out": { "description": "Time Out, Mountain, HH:MM; null when it has none.", "nullable": true, "type": "string" } }, "required": [ "time_in", "time_out", "tasks" ], "title": "ClientMonthEvidenceDriftSide", "type": "object" }, "source": { "description": "What the returned timesheet's day was compared with: the care log, or the Work Order entry and marks assembled from it.", "enum": [ "care_log", "work_order" ], "type": "string" }, "state": { "description": "Whether the warning is open or dismissed.", "enum": [ "conflict", "conflict_dismissed" ], "type": "string" }, "timesheet": { "properties": { "tasks": { "description": "The names of the tasks marked done that day.", "items": { "type": "string" }, "type": "array" }, "time_in": { "description": "Time In, Mountain, HH:MM; null when it has none.", "nullable": true, "type": "string" }, "time_out": { "description": "Time Out, Mountain, HH:MM; null when it has none.", "nullable": true, "type": "string" } }, "required": [ "time_in", "time_out", "tasks" ], "title": "ClientMonthEvidenceDriftSide", "type": "object" }, "timesheet_id": { "description": "The month's returned timesheet.", "format": "uuid", "type": "string" } }, "required": [ "source", "state", "fields", "conflict_key", "care_log_id", "timesheet_id", "dismissed", "timesheet", "other", "only_timesheet", "only_other" ], "title": "ClientMonthEvidenceTimesheetDrift", "type": "object" }, "type": "array" }, "visit_evidence": { "description": "The day's visit evidence: visits when it has one, else paper_scan when a paper-scan care log holds its times, else none.", "enum": [ "visits", "paper_scan", "none" ], "type": "string" } }, "required": [ "date", "state", "visit_evidence", "sources", "care_logs", "timesheet_drifts", "claim_changes", "open_conflict_keys", "dismissals" ], "title": "ClientMonthEvidenceDay", "type": "object" }, "type": "array" }, "month": { "description": "YYYY-MM.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" }, "open_conflicts": { "description": "How many conflicts in the month are open.", "nullable": true, "type": "integer" } }, "required": [ "client_id", "caregiver_id", "month", "open_conflicts", "days" ], "title": "ClientMonthEvidence", "type": "object" } } }, "description": "The client's month" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read a client's month of visit evidence", "tags": [ "Visits" ] } }, "/api/v1/clients/{id}/evidence/dismissals": { "post": { "callbacks": {}, "description": "As the grid's Dismiss all: every conflict still open in the month for the client and caregiver is dismissed with one reason, under one batch, with one audit row; dismissed answers how many. A month with none open answers 200 with dismissed 0, so a repeat dismisses nothing. A reason outside 3 to 500 characters is 422, and so is a field the body does not take (unknown_field): to dismiss one conflict, POST /api/v1/evidence-dismissals. Another agency's client or caregiver answers 404 and nothing is written. No visit changes.", "operationId": "postClientsByIdEvidenceDismissals", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "description": "The client.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "month": { "description": "The month, YYYY-MM; this month (Mountain) when left out.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" }, "reason": { "description": "Why the month's conflicts can be dismissed, as the grid asks.", "maxLength": 500, "minLength": 3, "type": "string" } }, "required": [ "caregiver_id", "reason" ], "type": "object" } } }, "description": "The month and the reason", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "dismissed": { "description": "How many conflicts this request dismissed; 0 when none was open.", "nullable": true, "type": "integer" }, "month": { "description": "YYYY-MM.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } }, "required": [ "client_id", "caregiver_id", "month", "dismissed" ], "title": "ClientMonthEvidenceDismissed", "type": "object" } } }, "description": "None was open, so none was dismissed" }, "201": { "content": { "application/json": { "schema": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "dismissed": { "description": "How many conflicts this request dismissed; 0 when none was open.", "nullable": true, "type": "integer" }, "month": { "description": "YYYY-MM.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } }, "required": [ "client_id", "caregiver_id", "month", "dismissed" ], "title": "ClientMonthEvidenceDismissed", "type": "object" } } }, "description": "How many were dismissed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Dismiss every open evidence conflict of a client's month", "tags": [ "Visits" ] } }, "/api/v1/clients/{id}/file-completeness": { "get": { "callbacks": {}, "description": "Each item of the client's file with its status, what is wrong and its expiry, as client_file_completeness returns it. Another agency's client is 404.", "operationId": "getClientsByIdFileCompleteness", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/FileCompleteness" } }, "required": [ "data" ], "type": "object" } } }, "description": "The file" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a client's file completeness", "tags": [ "Compliance" ] } }, "/api/v1/clients/{id}/follow-up/log": { "post": { "callbacks": {}, "description": "As the Log form of Operations > Follow-Ups: completes the client's open monthly follow-up with how they were reached, the day, and optional notes. A client has at most one open. One with nothing open (not due yet, or logged already) is 422 no_open_follow_up and nothing changes. Another agency's client is 404.", "operationId": "postClientsByIdFollowUpLog", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonthlyFollowUpLogInput" } } }, "description": "The contact", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MonthlyFollowUp" } }, "required": [ "data" ], "type": "object" } } }, "description": "The follow-up" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code no_open_follow_up: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Log a client's monthly follow-up", "tags": [ "Follow-ups" ] } }, "/api/v1/clients/{id}/health-summary": { "delete": { "callbacks": {}, "description": "As the Medical tab's Delete does; the audit trail keeps it.", "operationId": "deleteClientsByIdHealthSummary", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "edited_at": { "description": "When it was last edited.", "format": "date-time", "nullable": true, "type": "string" }, "generated_at": { "description": "When it was written.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "lock_version": { "description": "Its version; send it back to edit.", "nullable": true, "type": "integer" }, "model_used": { "description": "The AI model that wrote it.", "nullable": true, "type": "string" }, "text": { "description": "The summary, in Markdown.", "nullable": true, "type": "string" } }, "required": [ "id", "client_id", "text", "lock_version" ], "title": "ClientHealthSummary", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted summary" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a client's health summary", "tags": [ "Client records" ] }, "get": { "callbacks": {}, "description": "The AI-written summary on the client's Medical tab. None yet is 404.", "operationId": "getClientsByIdHealthSummary", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "edited_at": { "description": "When it was last edited.", "format": "date-time", "nullable": true, "type": "string" }, "generated_at": { "description": "When it was written.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "lock_version": { "description": "Its version; send it back to edit.", "nullable": true, "type": "integer" }, "model_used": { "description": "The AI model that wrote it.", "nullable": true, "type": "string" }, "text": { "description": "The summary, in Markdown.", "nullable": true, "type": "string" } }, "required": [ "id", "client_id", "text", "lock_version" ], "title": "ClientHealthSummary", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The summary" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a client's health summary", "tags": [ "Client records" ] }, "patch": { "callbacks": {}, "description": "As the Medical tab's Edit does: replaces the summary's text. Send the lock_version it was read with; a newer one answers 409.", "operationId": "patchClientsByIdHealthSummary", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lock_version": { "description": "The lock_version it was read with.", "nullable": true, "type": "integer" }, "text": { "description": "The summary, in Markdown.", "type": "string" } }, "required": [ "text", "lock_version" ], "title": "ClientHealthSummaryUpdate", "type": "object" } } }, "description": "The new text", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "edited_at": { "description": "When it was last edited.", "format": "date-time", "nullable": true, "type": "string" }, "generated_at": { "description": "When it was written.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "lock_version": { "description": "Its version; send it back to edit.", "nullable": true, "type": "integer" }, "model_used": { "description": "The AI model that wrote it.", "nullable": true, "type": "string" }, "text": { "description": "The summary, in Markdown.", "nullable": true, "type": "string" } }, "required": [ "id", "client_id", "text", "lock_version" ], "title": "ClientHealthSummary", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The summary" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Edit a client's health summary", "tags": [ "Client records" ] }, "post": { "callbacks": {}, "description": "As the Medical tab's Generate and Regenerate do: the AI summarises the client's conditions, allergies, medications and surgeries, replacing any summary there was. A client whose medical record lists none of them, and who has no summary yet, is 422 no_conditions. The AI being unavailable is 503 ai_unavailable.", "operationId": "postClientsByIdHealthSummary", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "edited_at": { "description": "When it was last edited.", "format": "date-time", "nullable": true, "type": "string" }, "generated_at": { "description": "When it was written.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "lock_version": { "description": "Its version; send it back to edit.", "nullable": true, "type": "integer" }, "model_used": { "description": "The AI model that wrote it.", "nullable": true, "type": "string" }, "text": { "description": "The summary, in Markdown.", "nullable": true, "type": "string" } }, "required": [ "id", "client_id", "text", "lock_version" ], "title": "ClientHealthSummary", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The summary" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code no_conditions: Unprocessable Content, as the operation's description says." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code ai_unavailable: Service Unavailable, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Write or rewrite a client's health summary", "tags": [ "Client records" ] } }, "/api/v1/clients/{id}/information-sheet": { "patch": { "callbacks": {}, "description": "Writes the fields sent, as the Information Sheet page's Save does, the client, medical and case manager parts in one transaction; null or blank clears a field, except first_name, last_name and ssn, where it is 422 null_not_allowed. The answer names the fields written; the SSN is never returned.", "operationId": "patchClientsByIdInformationSheet", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "address": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "allergies": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "city": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "clinic_name": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "date_of_birth": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "doctor_address": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "doctor_name": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "doctor_phone": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "emergency_contact_name": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "emergency_contact_phone": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "field_staff_instructions": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "first_name": { "description": "As the Information Sheet names it; never blank.", "type": "string" }, "gender": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "home_phone": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "last_name": { "description": "As the Information Sheet names it; never blank.", "type": "string" }, "manager_email": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "manager_fax": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "manager_name": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "manager_phone": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "medicaid_id": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "medications": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "mobile_phone": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "other_conditions": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "physical_conditions": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "ssn": { "description": "The client's SSN, never returned; leave it out to keep the stored one.", "type": "string" }, "state": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "supervisor_name": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "supervisor_phone": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" }, "zip": { "description": "As the Information Sheet names it; null or blank clears it.", "nullable": true, "type": "string" } }, "title": "ClientInformationSheetUpdate", "type": "object" } } }, "description": "The fields to write", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "fields": { "description": "The fields written.", "items": { "type": "string" }, "type": "array" } }, "required": [ "client_id", "fields" ], "title": "ClientInformationSheetSaved", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "What was written" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code null_not_allowed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a client's information sheet", "tags": [ "Client records" ] } }, "/api/v1/clients/{id}/intake-warning-dismissals": { "post": { "callbacks": {}, "description": "As the client page's Dismiss on its missing-intake warning (US-101.42): stores who dismissed it, when, the optional reason and the forms missing now (intake_missing). The warning shows again only when a form outside that list goes missing. 201 for the client's first dismissal, 200 when it replaces one. It blocks nothing. Another agency's client is 404, before the body is judged, and nothing is written. Audited against the credential.", "operationId": "postClientsByIdIntakeWarningDismissals", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Why the warning is dismissed, e.g. the intake packet was signed on paper and filed. Optional.", "maxLength": 500, "type": "string" } }, "title": "IntakeWarningDismissalInput", "type": "object" } } }, "description": "The dismissal", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "client_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "dismissed_at": { "description": "When it was dismissed.", "format": "date-time", "type": "string" }, "dismissed_by_id": { "description": "The user who dismissed it; the credential's user here.", "format": "uuid", "type": "string" }, "missing_forms": { "description": "The forms missing when it was dismissed; the warning shows again only when another form goes missing.", "items": { "enum": [ "agency_disclosure_notice", "client_rights_acknowledgement", "emergency_information" ], "type": "string" }, "type": "array" }, "reason": { "description": "The reason given, or null.", "nullable": true, "type": "string" } }, "required": [ "client_id", "missing_forms", "dismissed_at" ], "title": "IntakeWarningDismissal", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The dismissal, replaced" }, "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "client_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "dismissed_at": { "description": "When it was dismissed.", "format": "date-time", "type": "string" }, "dismissed_by_id": { "description": "The user who dismissed it; the credential's user here.", "format": "uuid", "type": "string" }, "missing_forms": { "description": "The forms missing when it was dismissed; the warning shows again only when another form goes missing.", "items": { "enum": [ "agency_disclosure_notice", "client_rights_acknowledgement", "emergency_information" ], "type": "string" }, "type": "array" }, "reason": { "description": "The reason given, or null.", "nullable": true, "type": "string" } }, "required": [ "client_id", "missing_forms", "dismissed_at" ], "title": "IntakeWarningDismissal", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The dismissal" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Dismiss a client's missing-intake warning", "tags": [ "Clients" ] } }, "/api/v1/clients/{id}/medical": { "get": { "callbacks": {}, "description": "The doctor, conditions, allergies, medications, field staff instructions and functional limitations the client page's Medical tab shows; every field null when none were ever saved. The read is recorded on the PHI access log.", "operationId": "getClientsByIdMedical", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "allergies": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "clinic_name": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "doctor_address": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "doctor_name": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "doctor_phone": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "field_staff_instructions": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "functional_limitations": { "description": "The Functional Limitations checkboxes and their Other text; null when none were ever saved. A write changes only the keys sent.", "nullable": true, "properties": { "breathing": { "description": "Whether the client has this limitation.", "type": "boolean" }, "hearing": { "description": "Whether the client has this limitation.", "type": "boolean" }, "mobility": { "description": "Whether the client has this limitation.", "type": "boolean" }, "other": { "description": "Any other limitation.", "nullable": true, "type": "string" }, "special_diet": { "description": "Whether the client has this limitation.", "type": "boolean" }, "speech": { "description": "Whether the client has this limitation.", "type": "boolean" }, "swallowing": { "description": "Whether the client has this limitation.", "type": "boolean" }, "vision": { "description": "Whether the client has this limitation.", "type": "boolean" } }, "type": "object" }, "medications": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "other_conditions": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "physical_conditions": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "special_needs": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "surgeries": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" } }, "required": [ "client_id" ], "title": "ClientMedical", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The medical information" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read a client's medical information", "tags": [ "Client records" ] }, "patch": { "callbacks": {}, "description": "Writes the fields sent, as the Medical tab's Save does, creating the record on the first write; a blank or null clears a field. 422 nothing_to_change for a body with none of these fields. Audited against the credential.", "operationId": "patchClientsByIdMedical", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "allergies": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "clinic_name": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "doctor_address": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "doctor_name": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "doctor_phone": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "field_staff_instructions": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "functional_limitations": { "description": "The Functional Limitations checkboxes and their Other text; null when none were ever saved. A write changes only the keys sent.", "nullable": true, "properties": { "breathing": { "description": "Whether the client has this limitation.", "type": "boolean" }, "hearing": { "description": "Whether the client has this limitation.", "type": "boolean" }, "mobility": { "description": "Whether the client has this limitation.", "type": "boolean" }, "other": { "description": "Any other limitation.", "nullable": true, "type": "string" }, "special_diet": { "description": "Whether the client has this limitation.", "type": "boolean" }, "speech": { "description": "Whether the client has this limitation.", "type": "boolean" }, "swallowing": { "description": "Whether the client has this limitation.", "type": "boolean" }, "vision": { "description": "Whether the client has this limitation.", "type": "boolean" } }, "type": "object" }, "medications": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "other_conditions": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "physical_conditions": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "special_needs": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "surgeries": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" } }, "title": "ClientMedicalUpdate", "type": "object" } } }, "description": "The fields to write", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "allergies": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "clinic_name": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "doctor_address": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "doctor_name": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "doctor_phone": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "field_staff_instructions": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "functional_limitations": { "description": "The Functional Limitations checkboxes and their Other text; null when none were ever saved. A write changes only the keys sent.", "nullable": true, "properties": { "breathing": { "description": "Whether the client has this limitation.", "type": "boolean" }, "hearing": { "description": "Whether the client has this limitation.", "type": "boolean" }, "mobility": { "description": "Whether the client has this limitation.", "type": "boolean" }, "other": { "description": "Any other limitation.", "nullable": true, "type": "string" }, "special_diet": { "description": "Whether the client has this limitation.", "type": "boolean" }, "speech": { "description": "Whether the client has this limitation.", "type": "boolean" }, "swallowing": { "description": "Whether the client has this limitation.", "type": "boolean" }, "vision": { "description": "Whether the client has this limitation.", "type": "boolean" } }, "type": "object" }, "medications": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "other_conditions": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "physical_conditions": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "special_needs": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" }, "surgeries": { "description": "As the Medical tab shows it; a blank or null clears it on a write.", "nullable": true, "type": "string" } }, "required": [ "client_id" ], "title": "ClientMedicalSaved", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The medical information" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code nothing_to_change: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a client's medical information", "tags": [ "Client records" ] } }, "/api/v1/clients/{id}/next-action-snoozes": { "delete": { "callbacks": {}, "description": "As the page's Undo does: the suggestion is back on the caller's Next Actions for that client. A suggestion that was not snoozed answers the same.", "operationId": "deleteClientsByIdNextActionSnoozes", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The suggestion to bring back.", "in": "query", "name": "suggestion_id", "required": true, "schema": { "description": "The Next Actions suggestion.", "enum": [ "no_active_plan_of_care", "no_active_assignment", "missing_medicaid_id", "no_work_order_this_month", "expiring_certification", "overdue_supervisor_visit" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "suggestion_id": { "description": "The Next Actions suggestion.", "enum": [ "no_active_plan_of_care", "no_active_assignment", "missing_medicaid_id", "no_work_order_this_month", "expiring_certification", "overdue_supervisor_visit" ], "type": "string" } }, "required": [ "client_id", "suggestion_id" ], "title": "NextActionUnsnoozed", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The suggestion" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Undo a Next Actions snooze", "tags": [ "Client records" ] }, "post": { "callbacks": {}, "description": "As the client page's Snooze does: the suggestion leaves the caller's Next Actions for that client until the snooze ends. Snoozing it again moves the end.", "operationId": "postClientsByIdNextActionSnoozes", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "days": { "description": "Days to snooze it, 1 to 365. Leave it out for 7, as the page does.", "maximum": 365, "minimum": 1, "type": "integer" }, "suggestion_id": { "description": "The Next Actions suggestion.", "enum": [ "no_active_plan_of_care", "no_active_assignment", "missing_medicaid_id", "no_work_order_this_month", "expiring_certification", "overdue_supervisor_visit" ], "type": "string" } }, "required": [ "suggestion_id" ], "title": "NextActionSnoozeCreate", "type": "object" } } }, "description": "The suggestion", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "snoozed_until": { "description": "When it comes back.", "format": "date-time", "type": "string" }, "suggestion_id": { "description": "The Next Actions suggestion.", "enum": [ "no_active_plan_of_care", "no_active_assignment", "missing_medicaid_id", "no_work_order_this_month", "expiring_certification", "overdue_supervisor_visit" ], "type": "string" } }, "required": [ "client_id", "suggestion_id", "snoozed_until" ], "title": "NextActionSnooze", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The snooze" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Snooze a client's Next Actions suggestion", "tags": [ "Client records" ] } }, "/api/v1/clients/{id}/notes": { "get": { "callbacks": {}, "description": "The client's communication log, newest first. With updated_since the order is change order, for a sync that pages with after_id. A client of another agency, or a deleted one, is 404.", "operationId": "getClientsByIdNotes", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records changed at or after this instant (ISO 8601, with an offset), compared to the second. The list is then in change order: updated_at, then id.", "in": "query", "name": "updated_since", "schema": { "format": "date-time", "type": "string" } }, { "description": "With updated_since, a cursor: send the last record's updated_at as updated_since and its id as after_id to get the next page. Use this, not offset, to sync: an offset skips a record when an earlier one changes between two requests. The sync is at least once: timestamps are whole seconds and set before commit, so a record changed in the cursor's second, or committed late, can fall behind the cursor. Start each sync pass a minute before the newest updated_at you saw, and treat every record returned as current: apply it over what you hold. A record can change twice within one second, and not every change moves lock_version, so the same updated_at and lock_version do not mean the same content.", "in": "query", "name": "after_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only notes with this party among their contact_types.", "in": "query", "name": "contact_type", "schema": { "enum": [ "case_manager", "consumer", "employee", "other" ], "type": "string" } }, { "description": "Only notes linked to this caregiver.", "in": "query", "name": "caregiver_id", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ClientNote" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClientNotePage", "type": "object" } } }, "description": "A page of client notes" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a client's notes", "tags": [ "Communication notes" ] }, "post": { "callbacks": {}, "description": "Files one note against the client. manager_initials defaults to the API key's user's initials. A client of another agency, or a deleted one, is 404 and nothing is written. Attachments are not accepted here.", "operationId": "postClientsByIdNotes", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientNoteInput" } } }, "description": "The note", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ClientNote" } }, "required": [ "data" ], "type": "object" } } }, "description": "The note" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Add a note to a client's log", "tags": [ "Communication notes" ] } }, "/api/v1/clients/{id}/other-services": { "get": { "callbacks": {}, "description": "The outside providers serving the client (adult day care, a CNA, an RN, PT, another), oldest first, as the client page lists them.", "operationId": "getClientsByIdOtherServices", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ClientOtherService" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClientOtherServicePage", "type": "object" } } }, "description": "A page of other services" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a client's other services", "tags": [ "Client records" ] }, "post": { "callbacks": {}, "description": "As the client page does. No kind, an unknown day or a field past its length answers 422 naming the field.", "operationId": "postClientsByIdOtherServices", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientOtherServiceInput" } } }, "description": "The other service", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ClientOtherService" } }, "required": [ "data" ], "type": "object" } } }, "description": "The other service" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Record a client's other service", "tags": [ "Client records" ] } }, "/api/v1/clients/{id}/par-check": { "get": { "callbacks": {}, "description": "The client page's PAR panel: the current PAR's units by our arithmetic beside the units on the case manager's letter. A client with no current plan carrying a PAR is 404.", "operationId": "getClientsByIdParCheck", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "flags": { "description": "MI, BI, PLWA: the client's conditions the PAR carries.", "items": { "type": "string" }, "type": "array" }, "other_pars": { "description": "The client's other current PARs, each with only the services it has a plan for: separate Personal Care and Homemaker PARs are both current (RW1-N2). The top-level check then lists only its own services.", "items": { "properties": { "flags": { "description": "MI, BI, PLWA: the client's conditions the PAR carries.", "items": { "type": "string" }, "type": "array" }, "par_effective_date": { "description": "The PAR's first day.", "format": "date", "nullable": true, "type": "string" }, "par_expiry_date": { "description": "The PAR's last day.", "format": "date", "nullable": true, "type": "string" }, "par_number": { "description": "The PAR's number.", "nullable": true, "type": "string" }, "services": { "description": "One column per service, Personal Care, Homemaker, HMA.", "items": { "properties": { "base_units": { "description": "(hours_weekly + travel_hours) × weeks × 4, unrounded.", "format": "decimal", "nullable": true, "type": "string" }, "billing_code": { "description": "The billing code.", "nullable": true, "type": "string" }, "extra_hours": { "description": "Extra hours a week, for extra_weeks: a second segment.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours": { "description": "Travel hours a week, counted with extra_hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_units": { "description": "(extra_hours + extra_travel_hours) × extra_weeks × 4, unrounded.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks": { "description": "Weeks the extra hours run. None means the extra adds no units.", "format": "decimal", "nullable": true, "type": "string" }, "extra_without_weeks": { "description": "Extra hours are set with no extra_weeks, so add nothing.", "type": "boolean" }, "hours_weekly": { "description": "Authorized hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "mismatch": { "description": "total_units and units_on_par disagree.", "type": "boolean" }, "plan_of_care_id": { "description": "The plan it is read from; none when not authorized.", "format": "uuid", "nullable": true, "type": "string" }, "service": { "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "total_units": { "description": "base_units + extra_units, rounded half-up.", "nullable": true, "type": "integer" }, "travel_hours": { "description": "Travel hours a week, counted with the hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "units_on_par": { "description": "The units the case manager's letter carries.", "nullable": true, "type": "integer" }, "variance": { "description": "units_on_par less total_units.", "nullable": true, "type": "integer" } }, "required": [ "service", "mismatch" ], "title": "ParCheckService", "type": "object" }, "type": "array" }, "weeks": { "description": "The PAR's weeks, as the panel prints them.", "nullable": true, "type": "string" } }, "required": [ "services" ], "title": "ParCheckOther", "type": "object" }, "type": "array" }, "par_effective_date": { "description": "The PAR's first day.", "format": "date", "nullable": true, "type": "string" }, "par_expiry_date": { "description": "The PAR's last day.", "format": "date", "nullable": true, "type": "string" }, "par_number": { "description": "The PAR's number.", "nullable": true, "type": "string" }, "services": { "description": "One column per service, Personal Care, Homemaker, HMA.", "items": { "properties": { "base_units": { "description": "(hours_weekly + travel_hours) × weeks × 4, unrounded.", "format": "decimal", "nullable": true, "type": "string" }, "billing_code": { "description": "The billing code.", "nullable": true, "type": "string" }, "extra_hours": { "description": "Extra hours a week, for extra_weeks: a second segment.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours": { "description": "Travel hours a week, counted with extra_hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_units": { "description": "(extra_hours + extra_travel_hours) × extra_weeks × 4, unrounded.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks": { "description": "Weeks the extra hours run. None means the extra adds no units.", "format": "decimal", "nullable": true, "type": "string" }, "extra_without_weeks": { "description": "Extra hours are set with no extra_weeks, so add nothing.", "type": "boolean" }, "hours_weekly": { "description": "Authorized hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "mismatch": { "description": "total_units and units_on_par disagree.", "type": "boolean" }, "plan_of_care_id": { "description": "The plan it is read from; none when not authorized.", "format": "uuid", "nullable": true, "type": "string" }, "service": { "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "total_units": { "description": "base_units + extra_units, rounded half-up.", "nullable": true, "type": "integer" }, "travel_hours": { "description": "Travel hours a week, counted with the hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "units_on_par": { "description": "The units the case manager's letter carries.", "nullable": true, "type": "integer" }, "variance": { "description": "units_on_par less total_units.", "nullable": true, "type": "integer" } }, "required": [ "service", "mismatch" ], "title": "ParCheckService", "type": "object" }, "type": "array" }, "weeks": { "description": "The PAR's weeks, as the panel prints them.", "nullable": true, "type": "string" } }, "required": [ "client_id", "services", "other_pars" ], "title": "ParCheck", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The check" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a client's PAR unit check", "tags": [ "Client records" ] }, "patch": { "callbacks": {}, "description": "As the PAR panel's Save does: writes the figures sent onto the PAR's plans of care, all or none. Send a service's figures under its name; each goes to the current PAR that has a plan for that service (the check or one of other_pars). A figure left out keeps its value, and null or blank clears it. A service no current PAR has a plan for is 422.", "operationId": "patchClientsByIdParCheck", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "hma": { "description": "This service's figures: travel_hours, extra_hours, extra_travel_hours, extra_weeks, units_on_par.", "properties": { "extra_hours": { "description": "Extra hours a week, for extra_weeks: a second segment.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours": { "description": "Travel hours a week, counted with extra_hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks": { "description": "Weeks the extra hours run. None means the extra adds no units.", "format": "decimal", "nullable": true, "type": "string" }, "travel_hours": { "description": "Travel hours a week, counted with the hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "units_on_par": { "description": "The units the case manager's letter carries.", "nullable": true, "type": "integer" } }, "title": "ParCheckFigures", "type": "object" }, "homemaker": { "description": "This service's figures: travel_hours, extra_hours, extra_travel_hours, extra_weeks, units_on_par.", "properties": { "extra_hours": { "description": "Extra hours a week, for extra_weeks: a second segment.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours": { "description": "Travel hours a week, counted with extra_hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks": { "description": "Weeks the extra hours run. None means the extra adds no units.", "format": "decimal", "nullable": true, "type": "string" }, "travel_hours": { "description": "Travel hours a week, counted with the hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "units_on_par": { "description": "The units the case manager's letter carries.", "nullable": true, "type": "integer" } }, "title": "ParCheckFigures", "type": "object" }, "personal_care": { "description": "This service's figures: travel_hours, extra_hours, extra_travel_hours, extra_weeks, units_on_par.", "properties": { "extra_hours": { "description": "Extra hours a week, for extra_weeks: a second segment.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours": { "description": "Travel hours a week, counted with extra_hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks": { "description": "Weeks the extra hours run. None means the extra adds no units.", "format": "decimal", "nullable": true, "type": "string" }, "travel_hours": { "description": "Travel hours a week, counted with the hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "units_on_par": { "description": "The units the case manager's letter carries.", "nullable": true, "type": "integer" } }, "title": "ParCheckFigures", "type": "object" } }, "title": "ParCheckUpdate", "type": "object" } } }, "description": "The figures", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "flags": { "description": "MI, BI, PLWA: the client's conditions the PAR carries.", "items": { "type": "string" }, "type": "array" }, "other_pars": { "description": "The client's other current PARs, each with only the services it has a plan for: separate Personal Care and Homemaker PARs are both current (RW1-N2). The top-level check then lists only its own services.", "items": { "properties": { "flags": { "description": "MI, BI, PLWA: the client's conditions the PAR carries.", "items": { "type": "string" }, "type": "array" }, "par_effective_date": { "description": "The PAR's first day.", "format": "date", "nullable": true, "type": "string" }, "par_expiry_date": { "description": "The PAR's last day.", "format": "date", "nullable": true, "type": "string" }, "par_number": { "description": "The PAR's number.", "nullable": true, "type": "string" }, "services": { "description": "One column per service, Personal Care, Homemaker, HMA.", "items": { "properties": { "base_units": { "description": "(hours_weekly + travel_hours) × weeks × 4, unrounded.", "format": "decimal", "nullable": true, "type": "string" }, "billing_code": { "description": "The billing code.", "nullable": true, "type": "string" }, "extra_hours": { "description": "Extra hours a week, for extra_weeks: a second segment.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours": { "description": "Travel hours a week, counted with extra_hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_units": { "description": "(extra_hours + extra_travel_hours) × extra_weeks × 4, unrounded.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks": { "description": "Weeks the extra hours run. None means the extra adds no units.", "format": "decimal", "nullable": true, "type": "string" }, "extra_without_weeks": { "description": "Extra hours are set with no extra_weeks, so add nothing.", "type": "boolean" }, "hours_weekly": { "description": "Authorized hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "mismatch": { "description": "total_units and units_on_par disagree.", "type": "boolean" }, "plan_of_care_id": { "description": "The plan it is read from; none when not authorized.", "format": "uuid", "nullable": true, "type": "string" }, "service": { "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "total_units": { "description": "base_units + extra_units, rounded half-up.", "nullable": true, "type": "integer" }, "travel_hours": { "description": "Travel hours a week, counted with the hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "units_on_par": { "description": "The units the case manager's letter carries.", "nullable": true, "type": "integer" }, "variance": { "description": "units_on_par less total_units.", "nullable": true, "type": "integer" } }, "required": [ "service", "mismatch" ], "title": "ParCheckService", "type": "object" }, "type": "array" }, "weeks": { "description": "The PAR's weeks, as the panel prints them.", "nullable": true, "type": "string" } }, "required": [ "services" ], "title": "ParCheckOther", "type": "object" }, "type": "array" }, "par_effective_date": { "description": "The PAR's first day.", "format": "date", "nullable": true, "type": "string" }, "par_expiry_date": { "description": "The PAR's last day.", "format": "date", "nullable": true, "type": "string" }, "par_number": { "description": "The PAR's number.", "nullable": true, "type": "string" }, "services": { "description": "One column per service, Personal Care, Homemaker, HMA.", "items": { "properties": { "base_units": { "description": "(hours_weekly + travel_hours) × weeks × 4, unrounded.", "format": "decimal", "nullable": true, "type": "string" }, "billing_code": { "description": "The billing code.", "nullable": true, "type": "string" }, "extra_hours": { "description": "Extra hours a week, for extra_weeks: a second segment.", "format": "decimal", "nullable": true, "type": "string" }, "extra_travel_hours": { "description": "Travel hours a week, counted with extra_hours.", "format": "decimal", "nullable": true, "type": "string" }, "extra_units": { "description": "(extra_hours + extra_travel_hours) × extra_weeks × 4, unrounded.", "format": "decimal", "nullable": true, "type": "string" }, "extra_weeks": { "description": "Weeks the extra hours run. None means the extra adds no units.", "format": "decimal", "nullable": true, "type": "string" }, "extra_without_weeks": { "description": "Extra hours are set with no extra_weeks, so add nothing.", "type": "boolean" }, "hours_weekly": { "description": "Authorized hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "mismatch": { "description": "total_units and units_on_par disagree.", "type": "boolean" }, "plan_of_care_id": { "description": "The plan it is read from; none when not authorized.", "format": "uuid", "nullable": true, "type": "string" }, "service": { "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "total_units": { "description": "base_units + extra_units, rounded half-up.", "nullable": true, "type": "integer" }, "travel_hours": { "description": "Travel hours a week, counted with the hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "units_on_par": { "description": "The units the case manager's letter carries.", "nullable": true, "type": "integer" }, "variance": { "description": "units_on_par less total_units.", "nullable": true, "type": "integer" } }, "required": [ "service", "mismatch" ], "title": "ParCheckService", "type": "object" }, "type": "array" }, "weeks": { "description": "The PAR's weeks, as the panel prints them.", "nullable": true, "type": "string" } }, "required": [ "client_id", "services", "other_pars" ], "title": "ParCheck", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The check" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Save a client's PAR unit check", "tags": [ "Client records" ] } }, "/api/v1/clients/{id}/pcsp-documents": { "post": { "callbacks": {}, "description": "Stores the PCSP as the plan form's upload does (a multipart field file, up to 50 MB); its id is the source_document_id a plan is then saved with and previewed from.", "operationId": "postClientsByIdPcspDocuments", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "format": "binary", "type": "string" } }, "required": [ "file" ], "type": "object" } } }, "description": "The PCSP", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "content_type": { "description": "Its type.", "nullable": true, "type": "string" }, "file_name": { "description": "Its name.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "uploaded_at": { "description": "When it was stored.", "format": "date-time", "type": "string" } }, "required": [ "id", "client_id" ], "title": "PcspDocument", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The stored document" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code internal_error: a failure on our side, which was logged. When its message says nothing changed (the file store refused the request, the virus scan could not be queued, the upload could not be read), nothing did, the same request fails the same way until it is fixed, and the Idempotency-Key stays free." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code storage_unavailable (the file store did not answer) or, on an upload, temporarily_unavailable (its uploaded file could not be read): nothing changed, and the same request can succeed later. Retry after the Retry-After seconds; a write retried with the same Idempotency-Key runs again.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (30).", "schema": { "type": "integer" }, "style": "simple" } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Store a client's PCSP", "tags": [ "Provider care plans" ] } }, "/api/v1/clients/{id}/relations": { "get": { "callbacks": {}, "description": "The client's relations, current and ended, each with its contact, ordered by kind, then rank, then start date, as the client page's People section lists them. kind narrows to one kind. Needs clients.view; a client outside the caller's reach answers 403 forbidden.", "operationId": "getClientsByIdRelations", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Only this kind of relation.", "in": "query", "name": "kind", "required": false, "schema": { "enum": [ "responsible_party", "representative", "emergency", "case_manager", "case_manager_supervisor", "cma_office", "physician", "pharmacy", "key_holder" ], "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ClientRelation" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ClientRelationPage", "type": "object" } } }, "description": "A page of relations" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a client's people", "tags": [ "Client records" ] }, "post": { "callbacks": {}, "description": "As the People section's Add does: names an existing contact by contact_id or creates one from contact. A current relation of the same single-current kind, or of the same kind and rank, is ended on the new one's start date and kept as history. Replacing a single-current kind (responsible_party, representative, case_manager, case_manager_supervisor, cma_office) must name the relation it replaces in replaces; without it, or naming one no longer current or at an old lock_version, it answers 409 stale_record and saves nothing. An unknown kind, or a contact with every field blank, answers 422 validation_failed naming the field. warnings lists what the agency may want to check (a possible duplicate person, a representative who is also the client's caregiver); they never stop the save. Needs clients.manage.", "operationId": "postClientsByIdRelations", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientRelationInput" } } }, "description": "The relation", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ClientRelation" }, "warnings": { "description": "What the act was done with that the agency may want to fix; usually empty. Never a refusal: the act was done.", "items": { "properties": { "fix": { "description": "Where it is fixed, when a page fixes it.", "nullable": true, "properties": { "label": { "description": "What the link says.", "type": "string" }, "path": { "description": "The app route that fixes it.", "type": "string" } }, "required": [ "path", "label" ], "type": "object" }, "id": { "description": "The rule that raised it, stable, e.g. client_care.medicaid_id_pending.", "type": "string" }, "message": { "description": "For a person to read.", "type": "string" } }, "required": [ "id", "message" ], "title": "Warning", "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "type": "object" } } }, "description": "The relation and its warnings" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Relate a person to a client", "tags": [ "Client records" ] } }, "/api/v1/clients/{id}/relations/{relation_id}/end": { "post": { "callbacks": {}, "description": "As the People section's End does: the relation stays as history with ends_on set, today (Mountain) when the body sends none. A relation already ended answers 200 with it unchanged. A relation that is not this client's answers 404. Needs clients.manage.", "operationId": "postClientsByIdRelationsByRelationIdEnd", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The relation.", "in": "path", "name": "relation_id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "ends_on": { "description": "YYYY-MM-DD; today (Mountain) when left out.", "format": "date", "nullable": true, "type": "string" } }, "title": "ClientRelationEnd", "type": "object" } } }, "description": "When it ends", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ClientRelation" } }, "required": [ "data" ], "type": "object" } } }, "description": "The ended relation" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "End a client's relation", "tags": [ "Client records" ] } }, "/api/v1/clients/{id}/restore": { "post": { "callbacks": {}, "description": "Restores a deleted client to the default list, as the client list's Restore does. A client that is not deleted answers 422 not_deleted.", "operationId": "postClientsByIdRestore", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lock_version": { "description": "The lock_version the deleted record has: the one its DELETE answered, or read it by listing with include_deleted=true.", "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": [ "lock_version" ], "title": "RestoreBody", "type": "object" } } }, "description": "The lock_version read", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Client" } }, "required": [ "data" ], "type": "object" } } }, "description": "The restored client" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_deleted: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Restore a deleted client", "tags": [ "Deletes and restores" ] } }, "/api/v1/clients/{id}/satisfaction-surveys": { "get": { "callbacks": {}, "description": "Newest first, drafts and completed, as the client's Surveys tab lists them.", "operationId": "getClientsByIdSatisfactionSurveys", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/SatisfactionSurvey" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "SatisfactionSurveyPage", "type": "object" } } }, "description": "A page of surveys" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a client's satisfaction surveys", "tags": [ "Client records" ] }, "post": { "callbacks": {}, "description": "A draft, as the Surveys tab's New does; survey_date is required.", "operationId": "postClientsByIdSatisfactionSurveys", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SatisfactionSurveyInput" } } }, "description": "The survey", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SatisfactionSurvey" } }, "required": [ "data" ], "type": "object" } } }, "description": "The survey" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Start a satisfaction survey", "tags": [ "Client records" ] } }, "/api/v1/clients/{id}/shift-plan": { "get": { "callbacks": {}, "description": "What the Shift Plan screen shows: the plan's settings (made with the agency's defaults on the first read), each service's week against its calculator, one card per shift with its Work Order, its day columns and its rows of day cells (marks and minutes), the task table, the warnings and the checks before a print. Another agency's client answers 404.", "operationId": "getClientsByIdShiftPlan", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "addable": { "description": "Per service, the state form's tasks the table does not hold: what Add task offers.", "properties": { "hm": { "items": { "type": "string" }, "type": "array" }, "pc": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "cards": { "items": { "description": "One shift and its Work Order.", "properties": { "after": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "nullable": true, "type": "string" }, "care_instructions": { "description": "The shift's Care Instructions.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "Its Work Order's caregiver.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_week": { "description": "The shift's caregiver's week across the agency's clients: this client's shifts as the screen times them, the others from their Work Orders.", "nullable": true, "properties": { "by_client": { "items": { "properties": { "client": { "type": "string" }, "minutes": { "description": "A week.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "caregiver": { "description": "Last, First.", "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "minutes": { "description": "Her minutes a week.", "nullable": true, "type": "integer" }, "visits": { "items": { "properties": { "client": { "description": "Last, First.", "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" }, "here": { "description": "A shift of this client's plan.", "type": "boolean" }, "minutes": { "description": "The visit's minutes.", "nullable": true, "type": "integer" }, "service": { "type": "string" }, "start": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "days": { "description": "Its columns in the agency's week order.", "items": { "properties": { "by_day": { "description": "It starts at a time of its own that day (shift_settings by_day).", "type": "boolean" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight it ends; past 1440 runs past midnight.", "nullable": true, "type": "integer" }, "label": { "type": "string" }, "minutes": { "description": "The minutes it holds that day.", "nullable": true, "type": "integer" }, "overlap": { "description": "It overlaps another shift that day.", "type": "boolean" }, "start": { "description": "Minutes after midnight the shift starts, null when off.", "nullable": true, "type": "integer" }, "working": { "description": "A day the service works.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "effective_date": { "description": "Its Work Order's Effective Date.", "format": "date", "nullable": true, "type": "string" }, "empty": { "description": "No visits fall on this shift.", "type": "boolean" }, "label": { "type": "string" }, "lock_version": { "description": "Its Work Order's lock_version, null before Generate.", "nullable": true, "type": "integer" }, "rows": { "items": { "properties": { "cells": { "items": { "properties": { "count": { "description": "The marks that day.", "nullable": true, "type": "integer" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "edited": { "description": "Differs from the layout; Undo puts it back.", "type": "boolean" }, "minutes": { "description": "The minutes they hold.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "in_plan": { "description": "One of the plan's tasks, so its cells can be changed.", "type": "boolean" }, "min_task": { "description": "Min / Task on this shift, as the printed Work Order writes it: the row's week over its visits, at most 2 places (40 + 35 is 37.5). Null with no marks.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "One visit's minutes.", "nullable": true, "type": "integer" }, "name": { "description": "What a cell change names as row.", "type": "string" }, "slug": { "type": "string" }, "times": { "description": "Times / Week: the row's marks on this shift. Null with no marks.", "nullable": true, "type": "integer" }, "week": { "description": "Week: the row's day minutes added on this shift. Null with no marks.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "shift_id": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "shift_number": { "description": "k of the service's shifts.", "nullable": true, "type": "integer" }, "work_order_id": { "description": "Its generated Work Order, null before Generate.", "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "caregivers": { "additionalProperties": { "description": "The caregiver's id.", "format": "uuid", "type": "string" }, "description": "Shift id => the caregiver picked for it, which Generate reads. A shift left out has none yet: it is planned and printable, and Generate makes it no Work Order.", "type": "object" }, "client_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "edited": { "description": "Some cell differs from the layout.", "type": "boolean" }, "hma": { "description": "The client's HMA calculator week, which the Shift Plan does not lay out: HMA stays on its Plan of Care. Null when the client has no current HMA plan with tasks.", "nullable": true, "properties": { "plan_id": { "description": "The HMA Plan of Care's id.", "format": "uuid", "type": "string" }, "weekly_minutes": { "description": "Its tasks' minutes a week.", "type": "integer" } }, "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "other_work_orders": { "description": "The client's live Work Orders made outside the Shift Plan, in force this month or later, by Effective Date (at most 50): the screen names them so the month is not made twice.", "items": { "properties": { "caregiver": { "description": "The Work Order's caregiver; null when it has none.", "nullable": true, "properties": { "first_name": { "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "nullable": true, "type": "string" } }, "type": "object" }, "closing_date": { "description": "Its Closing Date; null while it stays open.", "format": "date", "nullable": true, "type": "string" }, "effective_date": { "description": "Its Effective Date.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "number": { "description": "The Work Order's WO #.", "nullable": true, "type": "integer" }, "service": { "description": "The Work Order's service.", "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "shift_id": { "description": "The Shift Plan's shift that made it; only on a Work Order the plan made.", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } }, "required": [ "id", "number", "service", "caregiver", "effective_date", "closing_date" ], "title": "ShiftPlanWorkOrderLine", "type": "object" }, "type": "array" }, "overlaps": { "items": { "properties": { "a": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "b": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" } }, "type": "object" }, "type": "array" }, "print_problems": { "description": "What the screen asks to check before a print or Download Excel.", "items": { "type": "string" }, "type": "array" }, "services": { "properties": { "hm": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "settings": { "description": "days, shifts_per_day, shift_settings, gap_minutes, split_long_tasks, marks_mode, as PATCH takes them, task_overrides, the task table's edits, and care_instructions, shift id => text.", "type": "object" }, "task_table": { "items": { "properties": { "edited": { "description": "A figure differs from the Plan of Care's.", "type": "boolean" }, "fractional": { "description": "Min / task is not whole.", "type": "boolean" }, "max": { "description": "The state's weekly maximum, in minutes; null for a task it does not list.", "nullable": true, "type": "integer" }, "min_task": { "description": "Min / task.", "format": "decimal", "nullable": true, "type": "string" }, "min_week": { "description": "Min / week.", "format": "decimal", "nullable": true, "type": "string" }, "name": { "description": "What a task change names as task.", "type": "string" }, "norm": { "description": "The state's norm and weekly maximum, as the screen shows it under the task.", "nullable": true, "type": "string" }, "over_max": { "description": "Min / week is above the state's weekly maximum: needs justification and supervisor approval. Never a refusal.", "type": "boolean" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "split": { "description": "A split task: its visits and the minutes of each.", "nullable": true, "properties": { "minutes": { "description": "Each.", "nullable": true, "type": "integer" }, "visits": { "description": "Visits.", "nullable": true, "type": "integer" } }, "type": "object" }, "times": { "description": "Times / week.", "nullable": true, "type": "integer" }, "uneven": { "description": "Times / week was rounded.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "task_totals": { "properties": { "hm": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "warnings": { "description": "What the screen warns of; never a refusal.", "items": { "type": "string" }, "type": "array" } }, "title": "ShiftPlan", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The Shift Plan" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "A client's Shift Plan", "tags": [ "Shift plans" ] }, "patch": { "callbacks": {}, "description": "Saves the settings sent, as the screen saves each field: days and shifts_per_day by service, shift_settings by shift and key, the others whole. A malformed value answers 422 naming its field and nothing is saved. The generated Work Orders follow at once, with no Generate: each takes the new lines and Time In and Time Out, and the Work Order of a shift the change removes, or leaves with no visits, is archived and named in archived. A shift the change adds gets its Work Order at Generate. Answers the Shift Plan as the screen shows it next.", "operationId": "patchClientsByIdShiftPlan", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "days": { "description": "Optional: pc and/or hm => the service's working days; a service left out keeps its days.", "properties": { "hm": { "description": "The service's working days.", "items": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "type": "array" }, "pc": { "description": "The service's working days.", "items": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "type": "array" } }, "type": "object" }, "gap_minutes": { "description": "Optional: minutes between a shift and the one it starts after.", "minimum": 0, "type": "integer" }, "marks_mode": { "description": "Optional: the day cells as marks (x) or minutes.", "enum": [ "x", "minutes" ], "type": "string" }, "shift_settings": { "additionalProperties": { "properties": { "after": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "nullable": true, "type": "string" }, "by_day": { "additionalProperties": { "type": "string" }, "type": "object" }, "time": { "description": "HH:MM.", "type": "string" } }, "type": "object" }, "description": "Optional: shift id => the keys that change: time (HH:MM, its start), after (the shift it starts after, null for none), by_day (day => HH:MM, a start of its own that day). A key left out is kept.", "type": "object" }, "shifts_per_day": { "description": "Optional: pc and/or hm => shifts a day; a service left out keeps its count.", "properties": { "hm": { "description": "Shifts a day, 0 to 4.", "maximum": 4, "minimum": 0, "type": "integer" }, "pc": { "description": "Shifts a day, 0 to 4.", "maximum": 4, "minimum": 0, "type": "integer" } }, "type": "object" }, "split_long_tasks": { "description": "Optional: whether a long, rare task is split.", "type": "boolean" } }, "title": "ShiftPlanSettingsUpdate", "type": "object" } } }, "description": "The settings that change", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "archived": { "items": { "type": "string" }, "type": "array" }, "data": { "properties": { "addable": { "description": "Per service, the state form's tasks the table does not hold: what Add task offers.", "properties": { "hm": { "items": { "type": "string" }, "type": "array" }, "pc": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "cards": { "items": { "description": "One shift and its Work Order.", "properties": { "after": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "nullable": true, "type": "string" }, "care_instructions": { "description": "The shift's Care Instructions.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "Its Work Order's caregiver.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_week": { "description": "The shift's caregiver's week across the agency's clients: this client's shifts as the screen times them, the others from their Work Orders.", "nullable": true, "properties": { "by_client": { "items": { "properties": { "client": { "type": "string" }, "minutes": { "description": "A week.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "caregiver": { "description": "Last, First.", "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "minutes": { "description": "Her minutes a week.", "nullable": true, "type": "integer" }, "visits": { "items": { "properties": { "client": { "description": "Last, First.", "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" }, "here": { "description": "A shift of this client's plan.", "type": "boolean" }, "minutes": { "description": "The visit's minutes.", "nullable": true, "type": "integer" }, "service": { "type": "string" }, "start": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "days": { "description": "Its columns in the agency's week order.", "items": { "properties": { "by_day": { "description": "It starts at a time of its own that day (shift_settings by_day).", "type": "boolean" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight it ends; past 1440 runs past midnight.", "nullable": true, "type": "integer" }, "label": { "type": "string" }, "minutes": { "description": "The minutes it holds that day.", "nullable": true, "type": "integer" }, "overlap": { "description": "It overlaps another shift that day.", "type": "boolean" }, "start": { "description": "Minutes after midnight the shift starts, null when off.", "nullable": true, "type": "integer" }, "working": { "description": "A day the service works.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "effective_date": { "description": "Its Work Order's Effective Date.", "format": "date", "nullable": true, "type": "string" }, "empty": { "description": "No visits fall on this shift.", "type": "boolean" }, "label": { "type": "string" }, "lock_version": { "description": "Its Work Order's lock_version, null before Generate.", "nullable": true, "type": "integer" }, "rows": { "items": { "properties": { "cells": { "items": { "properties": { "count": { "description": "The marks that day.", "nullable": true, "type": "integer" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "edited": { "description": "Differs from the layout; Undo puts it back.", "type": "boolean" }, "minutes": { "description": "The minutes they hold.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "in_plan": { "description": "One of the plan's tasks, so its cells can be changed.", "type": "boolean" }, "min_task": { "description": "Min / Task on this shift, as the printed Work Order writes it: the row's week over its visits, at most 2 places (40 + 35 is 37.5). Null with no marks.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "One visit's minutes.", "nullable": true, "type": "integer" }, "name": { "description": "What a cell change names as row.", "type": "string" }, "slug": { "type": "string" }, "times": { "description": "Times / Week: the row's marks on this shift. Null with no marks.", "nullable": true, "type": "integer" }, "week": { "description": "Week: the row's day minutes added on this shift. Null with no marks.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "shift_id": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "shift_number": { "description": "k of the service's shifts.", "nullable": true, "type": "integer" }, "work_order_id": { "description": "Its generated Work Order, null before Generate.", "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "caregivers": { "additionalProperties": { "description": "The caregiver's id.", "format": "uuid", "type": "string" }, "description": "Shift id => the caregiver picked for it, which Generate reads. A shift left out has none yet: it is planned and printable, and Generate makes it no Work Order.", "type": "object" }, "client_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "edited": { "description": "Some cell differs from the layout.", "type": "boolean" }, "hma": { "description": "The client's HMA calculator week, which the Shift Plan does not lay out: HMA stays on its Plan of Care. Null when the client has no current HMA plan with tasks.", "nullable": true, "properties": { "plan_id": { "description": "The HMA Plan of Care's id.", "format": "uuid", "type": "string" }, "weekly_minutes": { "description": "Its tasks' minutes a week.", "type": "integer" } }, "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "other_work_orders": { "description": "The client's live Work Orders made outside the Shift Plan, in force this month or later, by Effective Date (at most 50): the screen names them so the month is not made twice.", "items": { "properties": { "caregiver": { "description": "The Work Order's caregiver; null when it has none.", "nullable": true, "properties": { "first_name": { "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "nullable": true, "type": "string" } }, "type": "object" }, "closing_date": { "description": "Its Closing Date; null while it stays open.", "format": "date", "nullable": true, "type": "string" }, "effective_date": { "description": "Its Effective Date.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "number": { "description": "The Work Order's WO #.", "nullable": true, "type": "integer" }, "service": { "description": "The Work Order's service.", "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "shift_id": { "description": "The Shift Plan's shift that made it; only on a Work Order the plan made.", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } }, "required": [ "id", "number", "service", "caregiver", "effective_date", "closing_date" ], "title": "ShiftPlanWorkOrderLine", "type": "object" }, "type": "array" }, "overlaps": { "items": { "properties": { "a": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "b": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" } }, "type": "object" }, "type": "array" }, "print_problems": { "description": "What the screen asks to check before a print or Download Excel.", "items": { "type": "string" }, "type": "array" }, "services": { "properties": { "hm": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "settings": { "description": "days, shifts_per_day, shift_settings, gap_minutes, split_long_tasks, marks_mode, as PATCH takes them, task_overrides, the task table's edits, and care_instructions, shift id => text.", "type": "object" }, "task_table": { "items": { "properties": { "edited": { "description": "A figure differs from the Plan of Care's.", "type": "boolean" }, "fractional": { "description": "Min / task is not whole.", "type": "boolean" }, "max": { "description": "The state's weekly maximum, in minutes; null for a task it does not list.", "nullable": true, "type": "integer" }, "min_task": { "description": "Min / task.", "format": "decimal", "nullable": true, "type": "string" }, "min_week": { "description": "Min / week.", "format": "decimal", "nullable": true, "type": "string" }, "name": { "description": "What a task change names as task.", "type": "string" }, "norm": { "description": "The state's norm and weekly maximum, as the screen shows it under the task.", "nullable": true, "type": "string" }, "over_max": { "description": "Min / week is above the state's weekly maximum: needs justification and supervisor approval. Never a refusal.", "type": "boolean" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "split": { "description": "A split task: its visits and the minutes of each.", "nullable": true, "properties": { "minutes": { "description": "Each.", "nullable": true, "type": "integer" }, "visits": { "description": "Visits.", "nullable": true, "type": "integer" } }, "type": "object" }, "times": { "description": "Times / week.", "nullable": true, "type": "integer" }, "uneven": { "description": "Times / week was rounded.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "task_totals": { "properties": { "hm": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "warnings": { "description": "What the screen warns of; never a refusal.", "items": { "type": "string" }, "type": "array" } }, "title": "ShiftPlan", "type": "object" } }, "required": [ "data", "archived" ], "type": "object" } } }, "description": "The Shift Plan, and the shifts whose Work Orders were archived" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a Shift Plan's settings", "tags": [ "Shift plans" ] } }, "/api/v1/clients/{id}/shift-plan/care-instructions/{shift_id}": { "put": { "callbacks": {}, "description": "Keeps the text as the shift's Care Instructions, as the card's box does; they are that shift's Work Order notes: Generate writes them, and a change rewrites the notes of a Work Order already generated for the shift (audited as a relayed setting). The Work Order's print shows them under Care Instructions. Blank or null removes them. A shift id no plan has answers 404, a text longer than a Work Order's notes hold 422 too_long. Answers the Shift Plan as the screen shows it next.", "operationId": "putClientsByIdShiftPlanCareInstructionsByShiftId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "", "in": "path", "name": "shift_id", "required": true, "schema": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "text": { "description": "The shift's Care Instructions, as the card's box takes them; blank or null removes them. At most the characters a Work Order's notes hold, else 422 too_long.", "nullable": true, "type": "string" } }, "required": [ "text" ], "title": "ShiftPlanCareInstructions", "type": "object" } } }, "description": "The Care Instructions", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "addable": { "description": "Per service, the state form's tasks the table does not hold: what Add task offers.", "properties": { "hm": { "items": { "type": "string" }, "type": "array" }, "pc": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "cards": { "items": { "description": "One shift and its Work Order.", "properties": { "after": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "nullable": true, "type": "string" }, "care_instructions": { "description": "The shift's Care Instructions.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "Its Work Order's caregiver.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_week": { "description": "The shift's caregiver's week across the agency's clients: this client's shifts as the screen times them, the others from their Work Orders.", "nullable": true, "properties": { "by_client": { "items": { "properties": { "client": { "type": "string" }, "minutes": { "description": "A week.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "caregiver": { "description": "Last, First.", "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "minutes": { "description": "Her minutes a week.", "nullable": true, "type": "integer" }, "visits": { "items": { "properties": { "client": { "description": "Last, First.", "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" }, "here": { "description": "A shift of this client's plan.", "type": "boolean" }, "minutes": { "description": "The visit's minutes.", "nullable": true, "type": "integer" }, "service": { "type": "string" }, "start": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "days": { "description": "Its columns in the agency's week order.", "items": { "properties": { "by_day": { "description": "It starts at a time of its own that day (shift_settings by_day).", "type": "boolean" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight it ends; past 1440 runs past midnight.", "nullable": true, "type": "integer" }, "label": { "type": "string" }, "minutes": { "description": "The minutes it holds that day.", "nullable": true, "type": "integer" }, "overlap": { "description": "It overlaps another shift that day.", "type": "boolean" }, "start": { "description": "Minutes after midnight the shift starts, null when off.", "nullable": true, "type": "integer" }, "working": { "description": "A day the service works.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "effective_date": { "description": "Its Work Order's Effective Date.", "format": "date", "nullable": true, "type": "string" }, "empty": { "description": "No visits fall on this shift.", "type": "boolean" }, "label": { "type": "string" }, "lock_version": { "description": "Its Work Order's lock_version, null before Generate.", "nullable": true, "type": "integer" }, "rows": { "items": { "properties": { "cells": { "items": { "properties": { "count": { "description": "The marks that day.", "nullable": true, "type": "integer" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "edited": { "description": "Differs from the layout; Undo puts it back.", "type": "boolean" }, "minutes": { "description": "The minutes they hold.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "in_plan": { "description": "One of the plan's tasks, so its cells can be changed.", "type": "boolean" }, "min_task": { "description": "Min / Task on this shift, as the printed Work Order writes it: the row's week over its visits, at most 2 places (40 + 35 is 37.5). Null with no marks.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "One visit's minutes.", "nullable": true, "type": "integer" }, "name": { "description": "What a cell change names as row.", "type": "string" }, "slug": { "type": "string" }, "times": { "description": "Times / Week: the row's marks on this shift. Null with no marks.", "nullable": true, "type": "integer" }, "week": { "description": "Week: the row's day minutes added on this shift. Null with no marks.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "shift_id": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "shift_number": { "description": "k of the service's shifts.", "nullable": true, "type": "integer" }, "work_order_id": { "description": "Its generated Work Order, null before Generate.", "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "caregivers": { "additionalProperties": { "description": "The caregiver's id.", "format": "uuid", "type": "string" }, "description": "Shift id => the caregiver picked for it, which Generate reads. A shift left out has none yet: it is planned and printable, and Generate makes it no Work Order.", "type": "object" }, "client_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "edited": { "description": "Some cell differs from the layout.", "type": "boolean" }, "hma": { "description": "The client's HMA calculator week, which the Shift Plan does not lay out: HMA stays on its Plan of Care. Null when the client has no current HMA plan with tasks.", "nullable": true, "properties": { "plan_id": { "description": "The HMA Plan of Care's id.", "format": "uuid", "type": "string" }, "weekly_minutes": { "description": "Its tasks' minutes a week.", "type": "integer" } }, "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "other_work_orders": { "description": "The client's live Work Orders made outside the Shift Plan, in force this month or later, by Effective Date (at most 50): the screen names them so the month is not made twice.", "items": { "properties": { "caregiver": { "description": "The Work Order's caregiver; null when it has none.", "nullable": true, "properties": { "first_name": { "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "nullable": true, "type": "string" } }, "type": "object" }, "closing_date": { "description": "Its Closing Date; null while it stays open.", "format": "date", "nullable": true, "type": "string" }, "effective_date": { "description": "Its Effective Date.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "number": { "description": "The Work Order's WO #.", "nullable": true, "type": "integer" }, "service": { "description": "The Work Order's service.", "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "shift_id": { "description": "The Shift Plan's shift that made it; only on a Work Order the plan made.", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } }, "required": [ "id", "number", "service", "caregiver", "effective_date", "closing_date" ], "title": "ShiftPlanWorkOrderLine", "type": "object" }, "type": "array" }, "overlaps": { "items": { "properties": { "a": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "b": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" } }, "type": "object" }, "type": "array" }, "print_problems": { "description": "What the screen asks to check before a print or Download Excel.", "items": { "type": "string" }, "type": "array" }, "services": { "properties": { "hm": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "settings": { "description": "days, shifts_per_day, shift_settings, gap_minutes, split_long_tasks, marks_mode, as PATCH takes them, task_overrides, the task table's edits, and care_instructions, shift id => text.", "type": "object" }, "task_table": { "items": { "properties": { "edited": { "description": "A figure differs from the Plan of Care's.", "type": "boolean" }, "fractional": { "description": "Min / task is not whole.", "type": "boolean" }, "max": { "description": "The state's weekly maximum, in minutes; null for a task it does not list.", "nullable": true, "type": "integer" }, "min_task": { "description": "Min / task.", "format": "decimal", "nullable": true, "type": "string" }, "min_week": { "description": "Min / week.", "format": "decimal", "nullable": true, "type": "string" }, "name": { "description": "What a task change names as task.", "type": "string" }, "norm": { "description": "The state's norm and weekly maximum, as the screen shows it under the task.", "nullable": true, "type": "string" }, "over_max": { "description": "Min / week is above the state's weekly maximum: needs justification and supervisor approval. Never a refusal.", "type": "boolean" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "split": { "description": "A split task: its visits and the minutes of each.", "nullable": true, "properties": { "minutes": { "description": "Each.", "nullable": true, "type": "integer" }, "visits": { "description": "Visits.", "nullable": true, "type": "integer" } }, "type": "object" }, "times": { "description": "Times / week.", "nullable": true, "type": "integer" }, "uneven": { "description": "Times / week was rounded.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "task_totals": { "properties": { "hm": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "warnings": { "description": "What the screen warns of; never a refusal.", "items": { "type": "string" }, "type": "array" } }, "title": "ShiftPlan", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The Shift Plan" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code too_long: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Set a Shift Plan card's Care Instructions", "tags": [ "Shift plans" ] } }, "/api/v1/clients/{id}/shift-plan/caregivers/{shift_id}": { "put": { "callbacks": {}, "description": "Saves the caregiver picked for the shift, as the screen's caregiver select does, before Generate or after; null lets go of the pick. The pick takes effect at Generate. Any caregiver of the agency on file may be picked: one no longer active comes back as a warning and Generate skips its shift. A caregiver id the agency has no caregiver of on file, or a shift that is no shift, answers 404 and nothing is saved. Answers the Shift Plan as the screen shows it next.", "operationId": "putClientsByIdShiftPlanCaregiversByShiftId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The shift.", "in": "path", "name": "shift_id", "required": true, "schema": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "caregiver_id": { "description": "The caregiver picked for the shift, any of the agency's on file, or null to let go of the pick.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "caregiver_id" ], "title": "ShiftPlanCaregiverSet", "type": "object" } } }, "description": "The caregiver", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "addable": { "description": "Per service, the state form's tasks the table does not hold: what Add task offers.", "properties": { "hm": { "items": { "type": "string" }, "type": "array" }, "pc": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "cards": { "items": { "description": "One shift and its Work Order.", "properties": { "after": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "nullable": true, "type": "string" }, "care_instructions": { "description": "The shift's Care Instructions.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "Its Work Order's caregiver.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_week": { "description": "The shift's caregiver's week across the agency's clients: this client's shifts as the screen times them, the others from their Work Orders.", "nullable": true, "properties": { "by_client": { "items": { "properties": { "client": { "type": "string" }, "minutes": { "description": "A week.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "caregiver": { "description": "Last, First.", "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "minutes": { "description": "Her minutes a week.", "nullable": true, "type": "integer" }, "visits": { "items": { "properties": { "client": { "description": "Last, First.", "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" }, "here": { "description": "A shift of this client's plan.", "type": "boolean" }, "minutes": { "description": "The visit's minutes.", "nullable": true, "type": "integer" }, "service": { "type": "string" }, "start": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "days": { "description": "Its columns in the agency's week order.", "items": { "properties": { "by_day": { "description": "It starts at a time of its own that day (shift_settings by_day).", "type": "boolean" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight it ends; past 1440 runs past midnight.", "nullable": true, "type": "integer" }, "label": { "type": "string" }, "minutes": { "description": "The minutes it holds that day.", "nullable": true, "type": "integer" }, "overlap": { "description": "It overlaps another shift that day.", "type": "boolean" }, "start": { "description": "Minutes after midnight the shift starts, null when off.", "nullable": true, "type": "integer" }, "working": { "description": "A day the service works.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "effective_date": { "description": "Its Work Order's Effective Date.", "format": "date", "nullable": true, "type": "string" }, "empty": { "description": "No visits fall on this shift.", "type": "boolean" }, "label": { "type": "string" }, "lock_version": { "description": "Its Work Order's lock_version, null before Generate.", "nullable": true, "type": "integer" }, "rows": { "items": { "properties": { "cells": { "items": { "properties": { "count": { "description": "The marks that day.", "nullable": true, "type": "integer" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "edited": { "description": "Differs from the layout; Undo puts it back.", "type": "boolean" }, "minutes": { "description": "The minutes they hold.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "in_plan": { "description": "One of the plan's tasks, so its cells can be changed.", "type": "boolean" }, "min_task": { "description": "Min / Task on this shift, as the printed Work Order writes it: the row's week over its visits, at most 2 places (40 + 35 is 37.5). Null with no marks.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "One visit's minutes.", "nullable": true, "type": "integer" }, "name": { "description": "What a cell change names as row.", "type": "string" }, "slug": { "type": "string" }, "times": { "description": "Times / Week: the row's marks on this shift. Null with no marks.", "nullable": true, "type": "integer" }, "week": { "description": "Week: the row's day minutes added on this shift. Null with no marks.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "shift_id": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "shift_number": { "description": "k of the service's shifts.", "nullable": true, "type": "integer" }, "work_order_id": { "description": "Its generated Work Order, null before Generate.", "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "caregivers": { "additionalProperties": { "description": "The caregiver's id.", "format": "uuid", "type": "string" }, "description": "Shift id => the caregiver picked for it, which Generate reads. A shift left out has none yet: it is planned and printable, and Generate makes it no Work Order.", "type": "object" }, "client_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "edited": { "description": "Some cell differs from the layout.", "type": "boolean" }, "hma": { "description": "The client's HMA calculator week, which the Shift Plan does not lay out: HMA stays on its Plan of Care. Null when the client has no current HMA plan with tasks.", "nullable": true, "properties": { "plan_id": { "description": "The HMA Plan of Care's id.", "format": "uuid", "type": "string" }, "weekly_minutes": { "description": "Its tasks' minutes a week.", "type": "integer" } }, "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "other_work_orders": { "description": "The client's live Work Orders made outside the Shift Plan, in force this month or later, by Effective Date (at most 50): the screen names them so the month is not made twice.", "items": { "properties": { "caregiver": { "description": "The Work Order's caregiver; null when it has none.", "nullable": true, "properties": { "first_name": { "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "nullable": true, "type": "string" } }, "type": "object" }, "closing_date": { "description": "Its Closing Date; null while it stays open.", "format": "date", "nullable": true, "type": "string" }, "effective_date": { "description": "Its Effective Date.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "number": { "description": "The Work Order's WO #.", "nullable": true, "type": "integer" }, "service": { "description": "The Work Order's service.", "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "shift_id": { "description": "The Shift Plan's shift that made it; only on a Work Order the plan made.", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } }, "required": [ "id", "number", "service", "caregiver", "effective_date", "closing_date" ], "title": "ShiftPlanWorkOrderLine", "type": "object" }, "type": "array" }, "overlaps": { "items": { "properties": { "a": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "b": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" } }, "type": "object" }, "type": "array" }, "print_problems": { "description": "What the screen asks to check before a print or Download Excel.", "items": { "type": "string" }, "type": "array" }, "services": { "properties": { "hm": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "settings": { "description": "days, shifts_per_day, shift_settings, gap_minutes, split_long_tasks, marks_mode, as PATCH takes them, task_overrides, the task table's edits, and care_instructions, shift id => text.", "type": "object" }, "task_table": { "items": { "properties": { "edited": { "description": "A figure differs from the Plan of Care's.", "type": "boolean" }, "fractional": { "description": "Min / task is not whole.", "type": "boolean" }, "max": { "description": "The state's weekly maximum, in minutes; null for a task it does not list.", "nullable": true, "type": "integer" }, "min_task": { "description": "Min / task.", "format": "decimal", "nullable": true, "type": "string" }, "min_week": { "description": "Min / week.", "format": "decimal", "nullable": true, "type": "string" }, "name": { "description": "What a task change names as task.", "type": "string" }, "norm": { "description": "The state's norm and weekly maximum, as the screen shows it under the task.", "nullable": true, "type": "string" }, "over_max": { "description": "Min / week is above the state's weekly maximum: needs justification and supervisor approval. Never a refusal.", "type": "boolean" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "split": { "description": "A split task: its visits and the minutes of each.", "nullable": true, "properties": { "minutes": { "description": "Each.", "nullable": true, "type": "integer" }, "visits": { "description": "Visits.", "nullable": true, "type": "integer" } }, "type": "object" }, "times": { "description": "Times / week.", "nullable": true, "type": "integer" }, "uneven": { "description": "Times / week was rounded.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "task_totals": { "properties": { "hm": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "warnings": { "description": "What the screen warns of; never a refusal.", "items": { "type": "string" }, "type": "array" } }, "title": "ShiftPlan", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The Shift Plan" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Pick the caregiver for a Shift Plan shift", "tags": [ "Shift plans" ] } }, "/api/v1/clients/{id}/shift-plan/cells": { "post": { "callbacks": {}, "description": "Keeps count marks on day in the row of the shift as the office's own change, as the screen's cell select does, before Generate or after: every later change to the settings or the task table lays the week out again under it. On a generated shift the row's line on its Work Order is written too, then every shift is timed again. The count the automatic layout gives that cell lets go of the change. A shift the plan does not have, or a row on no Work Order task of the plan, answers 404. Answers the Shift Plan as the screen shows it next.", "operationId": "postClientsByIdShiftPlanCells", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "The marks that day; the screen offers 0 to 8. The count the automatic layout gives that cell lets go of the change.", "minimum": 0, "type": "integer" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "row": { "description": "The row's name, as the card's rows name it (Bathing, Toileting).", "type": "string" }, "shift_id": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } }, "required": [ "shift_id", "day", "row", "count" ], "title": "ShiftPlanCellSet", "type": "object" } } }, "description": "The cell", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "addable": { "description": "Per service, the state form's tasks the table does not hold: what Add task offers.", "properties": { "hm": { "items": { "type": "string" }, "type": "array" }, "pc": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "cards": { "items": { "description": "One shift and its Work Order.", "properties": { "after": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "nullable": true, "type": "string" }, "care_instructions": { "description": "The shift's Care Instructions.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "Its Work Order's caregiver.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_week": { "description": "The shift's caregiver's week across the agency's clients: this client's shifts as the screen times them, the others from their Work Orders.", "nullable": true, "properties": { "by_client": { "items": { "properties": { "client": { "type": "string" }, "minutes": { "description": "A week.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "caregiver": { "description": "Last, First.", "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "minutes": { "description": "Her minutes a week.", "nullable": true, "type": "integer" }, "visits": { "items": { "properties": { "client": { "description": "Last, First.", "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" }, "here": { "description": "A shift of this client's plan.", "type": "boolean" }, "minutes": { "description": "The visit's minutes.", "nullable": true, "type": "integer" }, "service": { "type": "string" }, "start": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "days": { "description": "Its columns in the agency's week order.", "items": { "properties": { "by_day": { "description": "It starts at a time of its own that day (shift_settings by_day).", "type": "boolean" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight it ends; past 1440 runs past midnight.", "nullable": true, "type": "integer" }, "label": { "type": "string" }, "minutes": { "description": "The minutes it holds that day.", "nullable": true, "type": "integer" }, "overlap": { "description": "It overlaps another shift that day.", "type": "boolean" }, "start": { "description": "Minutes after midnight the shift starts, null when off.", "nullable": true, "type": "integer" }, "working": { "description": "A day the service works.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "effective_date": { "description": "Its Work Order's Effective Date.", "format": "date", "nullable": true, "type": "string" }, "empty": { "description": "No visits fall on this shift.", "type": "boolean" }, "label": { "type": "string" }, "lock_version": { "description": "Its Work Order's lock_version, null before Generate.", "nullable": true, "type": "integer" }, "rows": { "items": { "properties": { "cells": { "items": { "properties": { "count": { "description": "The marks that day.", "nullable": true, "type": "integer" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "edited": { "description": "Differs from the layout; Undo puts it back.", "type": "boolean" }, "minutes": { "description": "The minutes they hold.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "in_plan": { "description": "One of the plan's tasks, so its cells can be changed.", "type": "boolean" }, "min_task": { "description": "Min / Task on this shift, as the printed Work Order writes it: the row's week over its visits, at most 2 places (40 + 35 is 37.5). Null with no marks.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "One visit's minutes.", "nullable": true, "type": "integer" }, "name": { "description": "What a cell change names as row.", "type": "string" }, "slug": { "type": "string" }, "times": { "description": "Times / Week: the row's marks on this shift. Null with no marks.", "nullable": true, "type": "integer" }, "week": { "description": "Week: the row's day minutes added on this shift. Null with no marks.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "shift_id": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "shift_number": { "description": "k of the service's shifts.", "nullable": true, "type": "integer" }, "work_order_id": { "description": "Its generated Work Order, null before Generate.", "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "caregivers": { "additionalProperties": { "description": "The caregiver's id.", "format": "uuid", "type": "string" }, "description": "Shift id => the caregiver picked for it, which Generate reads. A shift left out has none yet: it is planned and printable, and Generate makes it no Work Order.", "type": "object" }, "client_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "edited": { "description": "Some cell differs from the layout.", "type": "boolean" }, "hma": { "description": "The client's HMA calculator week, which the Shift Plan does not lay out: HMA stays on its Plan of Care. Null when the client has no current HMA plan with tasks.", "nullable": true, "properties": { "plan_id": { "description": "The HMA Plan of Care's id.", "format": "uuid", "type": "string" }, "weekly_minutes": { "description": "Its tasks' minutes a week.", "type": "integer" } }, "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "other_work_orders": { "description": "The client's live Work Orders made outside the Shift Plan, in force this month or later, by Effective Date (at most 50): the screen names them so the month is not made twice.", "items": { "properties": { "caregiver": { "description": "The Work Order's caregiver; null when it has none.", "nullable": true, "properties": { "first_name": { "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "nullable": true, "type": "string" } }, "type": "object" }, "closing_date": { "description": "Its Closing Date; null while it stays open.", "format": "date", "nullable": true, "type": "string" }, "effective_date": { "description": "Its Effective Date.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "number": { "description": "The Work Order's WO #.", "nullable": true, "type": "integer" }, "service": { "description": "The Work Order's service.", "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "shift_id": { "description": "The Shift Plan's shift that made it; only on a Work Order the plan made.", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } }, "required": [ "id", "number", "service", "caregiver", "effective_date", "closing_date" ], "title": "ShiftPlanWorkOrderLine", "type": "object" }, "type": "array" }, "overlaps": { "items": { "properties": { "a": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "b": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" } }, "type": "object" }, "type": "array" }, "print_problems": { "description": "What the screen asks to check before a print or Download Excel.", "items": { "type": "string" }, "type": "array" }, "services": { "properties": { "hm": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "settings": { "description": "days, shifts_per_day, shift_settings, gap_minutes, split_long_tasks, marks_mode, as PATCH takes them, task_overrides, the task table's edits, and care_instructions, shift id => text.", "type": "object" }, "task_table": { "items": { "properties": { "edited": { "description": "A figure differs from the Plan of Care's.", "type": "boolean" }, "fractional": { "description": "Min / task is not whole.", "type": "boolean" }, "max": { "description": "The state's weekly maximum, in minutes; null for a task it does not list.", "nullable": true, "type": "integer" }, "min_task": { "description": "Min / task.", "format": "decimal", "nullable": true, "type": "string" }, "min_week": { "description": "Min / week.", "format": "decimal", "nullable": true, "type": "string" }, "name": { "description": "What a task change names as task.", "type": "string" }, "norm": { "description": "The state's norm and weekly maximum, as the screen shows it under the task.", "nullable": true, "type": "string" }, "over_max": { "description": "Min / week is above the state's weekly maximum: needs justification and supervisor approval. Never a refusal.", "type": "boolean" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "split": { "description": "A split task: its visits and the minutes of each.", "nullable": true, "properties": { "minutes": { "description": "Each.", "nullable": true, "type": "integer" }, "visits": { "description": "Visits.", "nullable": true, "type": "integer" } }, "type": "object" }, "times": { "description": "Times / week.", "nullable": true, "type": "integer" }, "uneven": { "description": "Times / week was rounded.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "task_totals": { "properties": { "hm": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "warnings": { "description": "What the screen warns of; never a refusal.", "items": { "type": "string" }, "type": "array" } }, "title": "ShiftPlan", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The Shift Plan" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Set one day cell of a Shift Plan card", "tags": [ "Shift plans" ] } }, "/api/v1/clients/{id}/shift-plan/export": { "get": { "callbacks": {}, "description": "The screen's Download Excel: the Calculator sheet and one sheet per generated Work Order, named \"POC .xlsx\". The checks the screen shows first are GET /clients/{id}/shift-plan's print_problems; they never stop the file. Audited as an export of the client's information before it is sent.", "operationId": "getClientsByIdShiftPlanExport", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "format": "binary", "type": "string" } } }, "description": "The workbook" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "A Shift Plan as an Excel workbook", "tags": [ "Shift plans" ] } }, "/api/v1/clients/{id}/shift-plan/generate": { "post": { "callbacks": {}, "description": "Lays out the client's week and writes one standing Work Order per shift, as the screen's Generate does: a new one for a shift that has none, the plan in force of the one it has (a backup kept), and an archive for a shift the plan no longer has. Each shift's caregiver is its saved pick unless caregivers names it. Nothing is refused for the layout: a shift with no visits or no active caregiver is skipped and named, a day past midnight is written with no Time Out, and each is a warning.", "operationId": "postClientsByIdShiftPlanGenerate", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "caregivers": { "additionalProperties": { "description": "The caregiver's id.", "format": "uuid", "nullable": true, "type": "string" }, "description": "Optional: shift id => the caregiver for its Work Order, or null for none, each saved as the shift's pick as PUT /clients/{id}/shift-plan/caregivers/{shift_id} saves it. A shift left out takes its saved pick (the plan's caregivers); a shift with no caregiver gets no Work Order and keeps the one it has.", "type": "object" } }, "title": "ShiftPlanGenerate", "type": "object" } } }, "description": "The caregivers chosen", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "addable": { "description": "Per service, the state form's tasks the table does not hold: what Add task offers.", "properties": { "hm": { "items": { "type": "string" }, "type": "array" }, "pc": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "cards": { "items": { "description": "One shift and its Work Order.", "properties": { "after": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "nullable": true, "type": "string" }, "care_instructions": { "description": "The shift's Care Instructions.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "Its Work Order's caregiver.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_week": { "description": "The shift's caregiver's week across the agency's clients: this client's shifts as the screen times them, the others from their Work Orders.", "nullable": true, "properties": { "by_client": { "items": { "properties": { "client": { "type": "string" }, "minutes": { "description": "A week.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "caregiver": { "description": "Last, First.", "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "minutes": { "description": "Her minutes a week.", "nullable": true, "type": "integer" }, "visits": { "items": { "properties": { "client": { "description": "Last, First.", "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" }, "here": { "description": "A shift of this client's plan.", "type": "boolean" }, "minutes": { "description": "The visit's minutes.", "nullable": true, "type": "integer" }, "service": { "type": "string" }, "start": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "days": { "description": "Its columns in the agency's week order.", "items": { "properties": { "by_day": { "description": "It starts at a time of its own that day (shift_settings by_day).", "type": "boolean" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight it ends; past 1440 runs past midnight.", "nullable": true, "type": "integer" }, "label": { "type": "string" }, "minutes": { "description": "The minutes it holds that day.", "nullable": true, "type": "integer" }, "overlap": { "description": "It overlaps another shift that day.", "type": "boolean" }, "start": { "description": "Minutes after midnight the shift starts, null when off.", "nullable": true, "type": "integer" }, "working": { "description": "A day the service works.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "effective_date": { "description": "Its Work Order's Effective Date.", "format": "date", "nullable": true, "type": "string" }, "empty": { "description": "No visits fall on this shift.", "type": "boolean" }, "label": { "type": "string" }, "lock_version": { "description": "Its Work Order's lock_version, null before Generate.", "nullable": true, "type": "integer" }, "rows": { "items": { "properties": { "cells": { "items": { "properties": { "count": { "description": "The marks that day.", "nullable": true, "type": "integer" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "edited": { "description": "Differs from the layout; Undo puts it back.", "type": "boolean" }, "minutes": { "description": "The minutes they hold.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "in_plan": { "description": "One of the plan's tasks, so its cells can be changed.", "type": "boolean" }, "min_task": { "description": "Min / Task on this shift, as the printed Work Order writes it: the row's week over its visits, at most 2 places (40 + 35 is 37.5). Null with no marks.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "One visit's minutes.", "nullable": true, "type": "integer" }, "name": { "description": "What a cell change names as row.", "type": "string" }, "slug": { "type": "string" }, "times": { "description": "Times / Week: the row's marks on this shift. Null with no marks.", "nullable": true, "type": "integer" }, "week": { "description": "Week: the row's day minutes added on this shift. Null with no marks.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "shift_id": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "shift_number": { "description": "k of the service's shifts.", "nullable": true, "type": "integer" }, "work_order_id": { "description": "Its generated Work Order, null before Generate.", "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "caregivers": { "additionalProperties": { "description": "The caregiver's id.", "format": "uuid", "type": "string" }, "description": "Shift id => the caregiver picked for it, which Generate reads. A shift left out has none yet: it is planned and printable, and Generate makes it no Work Order.", "type": "object" }, "client_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "edited": { "description": "Some cell differs from the layout.", "type": "boolean" }, "hma": { "description": "The client's HMA calculator week, which the Shift Plan does not lay out: HMA stays on its Plan of Care. Null when the client has no current HMA plan with tasks.", "nullable": true, "properties": { "plan_id": { "description": "The HMA Plan of Care's id.", "format": "uuid", "type": "string" }, "weekly_minutes": { "description": "Its tasks' minutes a week.", "type": "integer" } }, "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "other_work_orders": { "description": "The client's live Work Orders made outside the Shift Plan, in force this month or later, by Effective Date (at most 50): the screen names them so the month is not made twice.", "items": { "properties": { "caregiver": { "description": "The Work Order's caregiver; null when it has none.", "nullable": true, "properties": { "first_name": { "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "nullable": true, "type": "string" } }, "type": "object" }, "closing_date": { "description": "Its Closing Date; null while it stays open.", "format": "date", "nullable": true, "type": "string" }, "effective_date": { "description": "Its Effective Date.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "number": { "description": "The Work Order's WO #.", "nullable": true, "type": "integer" }, "service": { "description": "The Work Order's service.", "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "shift_id": { "description": "The Shift Plan's shift that made it; only on a Work Order the plan made.", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } }, "required": [ "id", "number", "service", "caregiver", "effective_date", "closing_date" ], "title": "ShiftPlanWorkOrderLine", "type": "object" }, "type": "array" }, "overlaps": { "items": { "properties": { "a": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "b": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" } }, "type": "object" }, "type": "array" }, "print_problems": { "description": "What the screen asks to check before a print or Download Excel.", "items": { "type": "string" }, "type": "array" }, "services": { "properties": { "hm": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "settings": { "description": "days, shifts_per_day, shift_settings, gap_minutes, split_long_tasks, marks_mode, as PATCH takes them, task_overrides, the task table's edits, and care_instructions, shift id => text.", "type": "object" }, "task_table": { "items": { "properties": { "edited": { "description": "A figure differs from the Plan of Care's.", "type": "boolean" }, "fractional": { "description": "Min / task is not whole.", "type": "boolean" }, "max": { "description": "The state's weekly maximum, in minutes; null for a task it does not list.", "nullable": true, "type": "integer" }, "min_task": { "description": "Min / task.", "format": "decimal", "nullable": true, "type": "string" }, "min_week": { "description": "Min / week.", "format": "decimal", "nullable": true, "type": "string" }, "name": { "description": "What a task change names as task.", "type": "string" }, "norm": { "description": "The state's norm and weekly maximum, as the screen shows it under the task.", "nullable": true, "type": "string" }, "over_max": { "description": "Min / week is above the state's weekly maximum: needs justification and supervisor approval. Never a refusal.", "type": "boolean" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "split": { "description": "A split task: its visits and the minutes of each.", "nullable": true, "properties": { "minutes": { "description": "Each.", "nullable": true, "type": "integer" }, "visits": { "description": "Visits.", "nullable": true, "type": "integer" } }, "type": "object" }, "times": { "description": "Times / week.", "nullable": true, "type": "integer" }, "uneven": { "description": "Times / week was rounded.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "task_totals": { "properties": { "hm": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "warnings": { "description": "What the screen warns of; never a refusal.", "items": { "type": "string" }, "type": "array" } }, "title": "ShiftPlan", "type": "object" }, "generated": { "properties": { "archived": { "description": "Shifts whose Work Order was archived.", "items": { "type": "string" }, "type": "array" }, "replaced": { "description": "Shifts whose Work Order was rewritten, with the backup kept.", "items": { "properties": { "backup_id": { "description": "The record's id.", "format": "uuid", "nullable": true, "type": "string" }, "shift_id": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } }, "type": "object" }, "type": "array" }, "skipped": { "description": "Shifts given no Work Order: no_visits, no_caregiver or inactive_caregiver. Never a refusal.", "items": { "properties": { "reason": { "enum": [ "no_visits", "no_caregiver", "inactive_caregiver" ], "type": "string" }, "shift_id": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } }, "type": "object" }, "type": "array" }, "warnings": { "items": { "type": "string" }, "type": "array" }, "work_orders": { "description": "The shifts written, each with its Work Order.", "items": { "properties": { "caregiver_id": { "description": "The record's id.", "format": "uuid", "nullable": true, "type": "string" }, "shift_id": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "work_order_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } }, "required": [ "data", "generated" ], "type": "object" } } }, "description": "What Generate wrote, and the Shift Plan" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Generate a Shift Plan's Work Orders", "tags": [ "Shift plans" ] } }, "/api/v1/clients/{id}/shift-plan/tasks": { "post": { "callbacks": {}, "description": "Saves one task-table figure on the Shift Plan, never on the Plan of Care, as the screen's task table does, and lays the task out again on the generated Work Orders. times divides the same week into that many visits; min_task or min_week recomputes Times / week. A value that is not above 0 (or not whole, for times) answers 422 invalid_figure, one past a week 422 too_large; a task the plan does not hold 404. Answers the Shift Plan as the screen shows it next.", "operationId": "postClientsByIdShiftPlanTasks", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "field": { "description": "The figure: times (Times / week), min_task (Min / task) or min_week (Min / week).", "enum": [ "min_task", "min_week", "times" ], "type": "string" }, "service": { "description": "The task's service.", "enum": [ "homemaker", "personal_care" ], "type": "string" }, "task": { "description": "The task, as the task table names it (Bathing).", "type": "string" }, "value": { "description": "Above 0; a whole number for times. Past a week answers 422 too_large.", "type": "number" } }, "required": [ "service", "task", "field", "value" ], "title": "ShiftPlanTaskUpdate", "type": "object" } } }, "description": "The figure", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "addable": { "description": "Per service, the state form's tasks the table does not hold: what Add task offers.", "properties": { "hm": { "items": { "type": "string" }, "type": "array" }, "pc": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "cards": { "items": { "description": "One shift and its Work Order.", "properties": { "after": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "nullable": true, "type": "string" }, "care_instructions": { "description": "The shift's Care Instructions.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "Its Work Order's caregiver.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_week": { "description": "The shift's caregiver's week across the agency's clients: this client's shifts as the screen times them, the others from their Work Orders.", "nullable": true, "properties": { "by_client": { "items": { "properties": { "client": { "type": "string" }, "minutes": { "description": "A week.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "caregiver": { "description": "Last, First.", "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "minutes": { "description": "Her minutes a week.", "nullable": true, "type": "integer" }, "visits": { "items": { "properties": { "client": { "description": "Last, First.", "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" }, "here": { "description": "A shift of this client's plan.", "type": "boolean" }, "minutes": { "description": "The visit's minutes.", "nullable": true, "type": "integer" }, "service": { "type": "string" }, "start": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "days": { "description": "Its columns in the agency's week order.", "items": { "properties": { "by_day": { "description": "It starts at a time of its own that day (shift_settings by_day).", "type": "boolean" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight it ends; past 1440 runs past midnight.", "nullable": true, "type": "integer" }, "label": { "type": "string" }, "minutes": { "description": "The minutes it holds that day.", "nullable": true, "type": "integer" }, "overlap": { "description": "It overlaps another shift that day.", "type": "boolean" }, "start": { "description": "Minutes after midnight the shift starts, null when off.", "nullable": true, "type": "integer" }, "working": { "description": "A day the service works.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "effective_date": { "description": "Its Work Order's Effective Date.", "format": "date", "nullable": true, "type": "string" }, "empty": { "description": "No visits fall on this shift.", "type": "boolean" }, "label": { "type": "string" }, "lock_version": { "description": "Its Work Order's lock_version, null before Generate.", "nullable": true, "type": "integer" }, "rows": { "items": { "properties": { "cells": { "items": { "properties": { "count": { "description": "The marks that day.", "nullable": true, "type": "integer" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "edited": { "description": "Differs from the layout; Undo puts it back.", "type": "boolean" }, "minutes": { "description": "The minutes they hold.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "in_plan": { "description": "One of the plan's tasks, so its cells can be changed.", "type": "boolean" }, "min_task": { "description": "Min / Task on this shift, as the printed Work Order writes it: the row's week over its visits, at most 2 places (40 + 35 is 37.5). Null with no marks.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "One visit's minutes.", "nullable": true, "type": "integer" }, "name": { "description": "What a cell change names as row.", "type": "string" }, "slug": { "type": "string" }, "times": { "description": "Times / Week: the row's marks on this shift. Null with no marks.", "nullable": true, "type": "integer" }, "week": { "description": "Week: the row's day minutes added on this shift. Null with no marks.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "shift_id": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "shift_number": { "description": "k of the service's shifts.", "nullable": true, "type": "integer" }, "work_order_id": { "description": "Its generated Work Order, null before Generate.", "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "caregivers": { "additionalProperties": { "description": "The caregiver's id.", "format": "uuid", "type": "string" }, "description": "Shift id => the caregiver picked for it, which Generate reads. A shift left out has none yet: it is planned and printable, and Generate makes it no Work Order.", "type": "object" }, "client_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "edited": { "description": "Some cell differs from the layout.", "type": "boolean" }, "hma": { "description": "The client's HMA calculator week, which the Shift Plan does not lay out: HMA stays on its Plan of Care. Null when the client has no current HMA plan with tasks.", "nullable": true, "properties": { "plan_id": { "description": "The HMA Plan of Care's id.", "format": "uuid", "type": "string" }, "weekly_minutes": { "description": "Its tasks' minutes a week.", "type": "integer" } }, "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "other_work_orders": { "description": "The client's live Work Orders made outside the Shift Plan, in force this month or later, by Effective Date (at most 50): the screen names them so the month is not made twice.", "items": { "properties": { "caregiver": { "description": "The Work Order's caregiver; null when it has none.", "nullable": true, "properties": { "first_name": { "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "nullable": true, "type": "string" } }, "type": "object" }, "closing_date": { "description": "Its Closing Date; null while it stays open.", "format": "date", "nullable": true, "type": "string" }, "effective_date": { "description": "Its Effective Date.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "number": { "description": "The Work Order's WO #.", "nullable": true, "type": "integer" }, "service": { "description": "The Work Order's service.", "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "shift_id": { "description": "The Shift Plan's shift that made it; only on a Work Order the plan made.", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } }, "required": [ "id", "number", "service", "caregiver", "effective_date", "closing_date" ], "title": "ShiftPlanWorkOrderLine", "type": "object" }, "type": "array" }, "overlaps": { "items": { "properties": { "a": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "b": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" } }, "type": "object" }, "type": "array" }, "print_problems": { "description": "What the screen asks to check before a print or Download Excel.", "items": { "type": "string" }, "type": "array" }, "services": { "properties": { "hm": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "settings": { "description": "days, shifts_per_day, shift_settings, gap_minutes, split_long_tasks, marks_mode, as PATCH takes them, task_overrides, the task table's edits, and care_instructions, shift id => text.", "type": "object" }, "task_table": { "items": { "properties": { "edited": { "description": "A figure differs from the Plan of Care's.", "type": "boolean" }, "fractional": { "description": "Min / task is not whole.", "type": "boolean" }, "max": { "description": "The state's weekly maximum, in minutes; null for a task it does not list.", "nullable": true, "type": "integer" }, "min_task": { "description": "Min / task.", "format": "decimal", "nullable": true, "type": "string" }, "min_week": { "description": "Min / week.", "format": "decimal", "nullable": true, "type": "string" }, "name": { "description": "What a task change names as task.", "type": "string" }, "norm": { "description": "The state's norm and weekly maximum, as the screen shows it under the task.", "nullable": true, "type": "string" }, "over_max": { "description": "Min / week is above the state's weekly maximum: needs justification and supervisor approval. Never a refusal.", "type": "boolean" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "split": { "description": "A split task: its visits and the minutes of each.", "nullable": true, "properties": { "minutes": { "description": "Each.", "nullable": true, "type": "integer" }, "visits": { "description": "Visits.", "nullable": true, "type": "integer" } }, "type": "object" }, "times": { "description": "Times / week.", "nullable": true, "type": "integer" }, "uneven": { "description": "Times / week was rounded.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "task_totals": { "properties": { "hm": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "warnings": { "description": "What the screen warns of; never a refusal.", "items": { "type": "string" }, "type": "array" } }, "title": "ShiftPlan", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The Shift Plan" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes invalid_figure, too_large: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a figure of a Shift Plan's task table", "tags": [ "Shift plans" ] } }, "/api/v1/clients/{id}/shift-plan/tasks/add": { "post": { "callbacks": {}, "description": "Puts a task of the state form in the task table, as the screen's Add task does: on the Shift Plan, never on the Plan of Care. A task the Plan of Care lacks starts at 15 min × 1 = 15 min a week; one taken out earlier comes back with the calculator's figures. It is laid out and reaches the generated Work Orders. A task already in the table changes nothing; a name the form does not list for the service answers 422 unknown_task. Answers the Shift Plan as the screen shows it next.", "operationId": "postClientsByIdShiftPlanTasksAdd", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "service": { "description": "The task's service.", "enum": [ "homemaker", "personal_care" ], "type": "string" }, "task": { "description": "A task on the state form for that service, by its name (Dusting, Meal Prep/Menu Planning); the screen's Add task lists the ones the table does not hold.", "type": "string" } }, "required": [ "service", "task" ], "title": "ShiftPlanTaskAdd", "type": "object" } } }, "description": "The task", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "addable": { "description": "Per service, the state form's tasks the table does not hold: what Add task offers.", "properties": { "hm": { "items": { "type": "string" }, "type": "array" }, "pc": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "cards": { "items": { "description": "One shift and its Work Order.", "properties": { "after": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "nullable": true, "type": "string" }, "care_instructions": { "description": "The shift's Care Instructions.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "Its Work Order's caregiver.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_week": { "description": "The shift's caregiver's week across the agency's clients: this client's shifts as the screen times them, the others from their Work Orders.", "nullable": true, "properties": { "by_client": { "items": { "properties": { "client": { "type": "string" }, "minutes": { "description": "A week.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "caregiver": { "description": "Last, First.", "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "minutes": { "description": "Her minutes a week.", "nullable": true, "type": "integer" }, "visits": { "items": { "properties": { "client": { "description": "Last, First.", "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" }, "here": { "description": "A shift of this client's plan.", "type": "boolean" }, "minutes": { "description": "The visit's minutes.", "nullable": true, "type": "integer" }, "service": { "type": "string" }, "start": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "days": { "description": "Its columns in the agency's week order.", "items": { "properties": { "by_day": { "description": "It starts at a time of its own that day (shift_settings by_day).", "type": "boolean" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight it ends; past 1440 runs past midnight.", "nullable": true, "type": "integer" }, "label": { "type": "string" }, "minutes": { "description": "The minutes it holds that day.", "nullable": true, "type": "integer" }, "overlap": { "description": "It overlaps another shift that day.", "type": "boolean" }, "start": { "description": "Minutes after midnight the shift starts, null when off.", "nullable": true, "type": "integer" }, "working": { "description": "A day the service works.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "effective_date": { "description": "Its Work Order's Effective Date.", "format": "date", "nullable": true, "type": "string" }, "empty": { "description": "No visits fall on this shift.", "type": "boolean" }, "label": { "type": "string" }, "lock_version": { "description": "Its Work Order's lock_version, null before Generate.", "nullable": true, "type": "integer" }, "rows": { "items": { "properties": { "cells": { "items": { "properties": { "count": { "description": "The marks that day.", "nullable": true, "type": "integer" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "edited": { "description": "Differs from the layout; Undo puts it back.", "type": "boolean" }, "minutes": { "description": "The minutes they hold.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "in_plan": { "description": "One of the plan's tasks, so its cells can be changed.", "type": "boolean" }, "min_task": { "description": "Min / Task on this shift, as the printed Work Order writes it: the row's week over its visits, at most 2 places (40 + 35 is 37.5). Null with no marks.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "One visit's minutes.", "nullable": true, "type": "integer" }, "name": { "description": "What a cell change names as row.", "type": "string" }, "slug": { "type": "string" }, "times": { "description": "Times / Week: the row's marks on this shift. Null with no marks.", "nullable": true, "type": "integer" }, "week": { "description": "Week: the row's day minutes added on this shift. Null with no marks.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "shift_id": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "shift_number": { "description": "k of the service's shifts.", "nullable": true, "type": "integer" }, "work_order_id": { "description": "Its generated Work Order, null before Generate.", "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "caregivers": { "additionalProperties": { "description": "The caregiver's id.", "format": "uuid", "type": "string" }, "description": "Shift id => the caregiver picked for it, which Generate reads. A shift left out has none yet: it is planned and printable, and Generate makes it no Work Order.", "type": "object" }, "client_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "edited": { "description": "Some cell differs from the layout.", "type": "boolean" }, "hma": { "description": "The client's HMA calculator week, which the Shift Plan does not lay out: HMA stays on its Plan of Care. Null when the client has no current HMA plan with tasks.", "nullable": true, "properties": { "plan_id": { "description": "The HMA Plan of Care's id.", "format": "uuid", "type": "string" }, "weekly_minutes": { "description": "Its tasks' minutes a week.", "type": "integer" } }, "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "other_work_orders": { "description": "The client's live Work Orders made outside the Shift Plan, in force this month or later, by Effective Date (at most 50): the screen names them so the month is not made twice.", "items": { "properties": { "caregiver": { "description": "The Work Order's caregiver; null when it has none.", "nullable": true, "properties": { "first_name": { "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "nullable": true, "type": "string" } }, "type": "object" }, "closing_date": { "description": "Its Closing Date; null while it stays open.", "format": "date", "nullable": true, "type": "string" }, "effective_date": { "description": "Its Effective Date.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "number": { "description": "The Work Order's WO #.", "nullable": true, "type": "integer" }, "service": { "description": "The Work Order's service.", "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "shift_id": { "description": "The Shift Plan's shift that made it; only on a Work Order the plan made.", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } }, "required": [ "id", "number", "service", "caregiver", "effective_date", "closing_date" ], "title": "ShiftPlanWorkOrderLine", "type": "object" }, "type": "array" }, "overlaps": { "items": { "properties": { "a": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "b": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" } }, "type": "object" }, "type": "array" }, "print_problems": { "description": "What the screen asks to check before a print or Download Excel.", "items": { "type": "string" }, "type": "array" }, "services": { "properties": { "hm": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "settings": { "description": "days, shifts_per_day, shift_settings, gap_minutes, split_long_tasks, marks_mode, as PATCH takes them, task_overrides, the task table's edits, and care_instructions, shift id => text.", "type": "object" }, "task_table": { "items": { "properties": { "edited": { "description": "A figure differs from the Plan of Care's.", "type": "boolean" }, "fractional": { "description": "Min / task is not whole.", "type": "boolean" }, "max": { "description": "The state's weekly maximum, in minutes; null for a task it does not list.", "nullable": true, "type": "integer" }, "min_task": { "description": "Min / task.", "format": "decimal", "nullable": true, "type": "string" }, "min_week": { "description": "Min / week.", "format": "decimal", "nullable": true, "type": "string" }, "name": { "description": "What a task change names as task.", "type": "string" }, "norm": { "description": "The state's norm and weekly maximum, as the screen shows it under the task.", "nullable": true, "type": "string" }, "over_max": { "description": "Min / week is above the state's weekly maximum: needs justification and supervisor approval. Never a refusal.", "type": "boolean" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "split": { "description": "A split task: its visits and the minutes of each.", "nullable": true, "properties": { "minutes": { "description": "Each.", "nullable": true, "type": "integer" }, "visits": { "description": "Visits.", "nullable": true, "type": "integer" } }, "type": "object" }, "times": { "description": "Times / week.", "nullable": true, "type": "integer" }, "uneven": { "description": "Times / week was rounded.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "task_totals": { "properties": { "hm": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "warnings": { "description": "What the screen warns of; never a refusal.", "items": { "type": "string" }, "type": "array" } }, "title": "ShiftPlan", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The Shift Plan" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code unknown_task: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Add a task to a Shift Plan's task table", "tags": [ "Shift plans" ] } }, "/api/v1/clients/{id}/shift-plan/tasks/{service}/{task}": { "delete": { "callbacks": {}, "description": "Takes the task out of the task table and the layout, as the screen's × does, with the changed cells of its row: on the Shift Plan, never on the Plan of Care, and it returns to the tasks Add task offers. Its line on the generated Work Orders is laid out again without it. A task the table does not hold answers 404. Answers the Shift Plan as the screen shows it next.", "operationId": "deleteClientsByIdShiftPlanTasksByServiceByTask", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The task's service.", "in": "path", "name": "service", "required": true, "schema": { "description": "The task's service.", "enum": [ "homemaker", "personal_care" ], "type": "string" } }, { "description": "The task, as the task table names it (Bathing), URL-encoded: Meal Prep/Menu Planning is Meal%20Prep%2FMenu%20Planning.", "in": "path", "name": "task", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "addable": { "description": "Per service, the state form's tasks the table does not hold: what Add task offers.", "properties": { "hm": { "items": { "type": "string" }, "type": "array" }, "pc": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "cards": { "items": { "description": "One shift and its Work Order.", "properties": { "after": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "nullable": true, "type": "string" }, "care_instructions": { "description": "The shift's Care Instructions.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "Its Work Order's caregiver.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_week": { "description": "The shift's caregiver's week across the agency's clients: this client's shifts as the screen times them, the others from their Work Orders.", "nullable": true, "properties": { "by_client": { "items": { "properties": { "client": { "type": "string" }, "minutes": { "description": "A week.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "caregiver": { "description": "Last, First.", "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "minutes": { "description": "Her minutes a week.", "nullable": true, "type": "integer" }, "visits": { "items": { "properties": { "client": { "description": "Last, First.", "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" }, "here": { "description": "A shift of this client's plan.", "type": "boolean" }, "minutes": { "description": "The visit's minutes.", "nullable": true, "type": "integer" }, "service": { "type": "string" }, "start": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "days": { "description": "Its columns in the agency's week order.", "items": { "properties": { "by_day": { "description": "It starts at a time of its own that day (shift_settings by_day).", "type": "boolean" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight it ends; past 1440 runs past midnight.", "nullable": true, "type": "integer" }, "label": { "type": "string" }, "minutes": { "description": "The minutes it holds that day.", "nullable": true, "type": "integer" }, "overlap": { "description": "It overlaps another shift that day.", "type": "boolean" }, "start": { "description": "Minutes after midnight the shift starts, null when off.", "nullable": true, "type": "integer" }, "working": { "description": "A day the service works.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "effective_date": { "description": "Its Work Order's Effective Date.", "format": "date", "nullable": true, "type": "string" }, "empty": { "description": "No visits fall on this shift.", "type": "boolean" }, "label": { "type": "string" }, "lock_version": { "description": "Its Work Order's lock_version, null before Generate.", "nullable": true, "type": "integer" }, "rows": { "items": { "properties": { "cells": { "items": { "properties": { "count": { "description": "The marks that day.", "nullable": true, "type": "integer" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "edited": { "description": "Differs from the layout; Undo puts it back.", "type": "boolean" }, "minutes": { "description": "The minutes they hold.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "in_plan": { "description": "One of the plan's tasks, so its cells can be changed.", "type": "boolean" }, "min_task": { "description": "Min / Task on this shift, as the printed Work Order writes it: the row's week over its visits, at most 2 places (40 + 35 is 37.5). Null with no marks.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "One visit's minutes.", "nullable": true, "type": "integer" }, "name": { "description": "What a cell change names as row.", "type": "string" }, "slug": { "type": "string" }, "times": { "description": "Times / Week: the row's marks on this shift. Null with no marks.", "nullable": true, "type": "integer" }, "week": { "description": "Week: the row's day minutes added on this shift. Null with no marks.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "shift_id": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "shift_number": { "description": "k of the service's shifts.", "nullable": true, "type": "integer" }, "work_order_id": { "description": "Its generated Work Order, null before Generate.", "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "caregivers": { "additionalProperties": { "description": "The caregiver's id.", "format": "uuid", "type": "string" }, "description": "Shift id => the caregiver picked for it, which Generate reads. A shift left out has none yet: it is planned and printable, and Generate makes it no Work Order.", "type": "object" }, "client_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "edited": { "description": "Some cell differs from the layout.", "type": "boolean" }, "hma": { "description": "The client's HMA calculator week, which the Shift Plan does not lay out: HMA stays on its Plan of Care. Null when the client has no current HMA plan with tasks.", "nullable": true, "properties": { "plan_id": { "description": "The HMA Plan of Care's id.", "format": "uuid", "type": "string" }, "weekly_minutes": { "description": "Its tasks' minutes a week.", "type": "integer" } }, "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "other_work_orders": { "description": "The client's live Work Orders made outside the Shift Plan, in force this month or later, by Effective Date (at most 50): the screen names them so the month is not made twice.", "items": { "properties": { "caregiver": { "description": "The Work Order's caregiver; null when it has none.", "nullable": true, "properties": { "first_name": { "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "nullable": true, "type": "string" } }, "type": "object" }, "closing_date": { "description": "Its Closing Date; null while it stays open.", "format": "date", "nullable": true, "type": "string" }, "effective_date": { "description": "Its Effective Date.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "number": { "description": "The Work Order's WO #.", "nullable": true, "type": "integer" }, "service": { "description": "The Work Order's service.", "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "shift_id": { "description": "The Shift Plan's shift that made it; only on a Work Order the plan made.", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } }, "required": [ "id", "number", "service", "caregiver", "effective_date", "closing_date" ], "title": "ShiftPlanWorkOrderLine", "type": "object" }, "type": "array" }, "overlaps": { "items": { "properties": { "a": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "b": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" } }, "type": "object" }, "type": "array" }, "print_problems": { "description": "What the screen asks to check before a print or Download Excel.", "items": { "type": "string" }, "type": "array" }, "services": { "properties": { "hm": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "settings": { "description": "days, shifts_per_day, shift_settings, gap_minutes, split_long_tasks, marks_mode, as PATCH takes them, task_overrides, the task table's edits, and care_instructions, shift id => text.", "type": "object" }, "task_table": { "items": { "properties": { "edited": { "description": "A figure differs from the Plan of Care's.", "type": "boolean" }, "fractional": { "description": "Min / task is not whole.", "type": "boolean" }, "max": { "description": "The state's weekly maximum, in minutes; null for a task it does not list.", "nullable": true, "type": "integer" }, "min_task": { "description": "Min / task.", "format": "decimal", "nullable": true, "type": "string" }, "min_week": { "description": "Min / week.", "format": "decimal", "nullable": true, "type": "string" }, "name": { "description": "What a task change names as task.", "type": "string" }, "norm": { "description": "The state's norm and weekly maximum, as the screen shows it under the task.", "nullable": true, "type": "string" }, "over_max": { "description": "Min / week is above the state's weekly maximum: needs justification and supervisor approval. Never a refusal.", "type": "boolean" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "split": { "description": "A split task: its visits and the minutes of each.", "nullable": true, "properties": { "minutes": { "description": "Each.", "nullable": true, "type": "integer" }, "visits": { "description": "Visits.", "nullable": true, "type": "integer" } }, "type": "object" }, "times": { "description": "Times / week.", "nullable": true, "type": "integer" }, "uneven": { "description": "Times / week was rounded.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "task_totals": { "properties": { "hm": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "warnings": { "description": "What the screen warns of; never a refusal.", "items": { "type": "string" }, "type": "array" } }, "title": "ShiftPlan", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The Shift Plan" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Take a task out of a Shift Plan's task table", "tags": [ "Shift plans" ] } }, "/api/v1/clients/{id}/shift-plan/undo": { "post": { "callbacks": {}, "description": "Lets go of every cell change, as the screen's Undo my changes does, and returns every row of every generated Work Order that differs from the layout to it; the settings and the task table are kept. Answers the Shift Plan and the shifts written.", "operationId": "postClientsByIdShiftPlanUndo", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "addable": { "description": "Per service, the state form's tasks the table does not hold: what Add task offers.", "properties": { "hm": { "items": { "type": "string" }, "type": "array" }, "pc": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "cards": { "items": { "description": "One shift and its Work Order.", "properties": { "after": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "nullable": true, "type": "string" }, "care_instructions": { "description": "The shift's Care Instructions.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "Its Work Order's caregiver.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_week": { "description": "The shift's caregiver's week across the agency's clients: this client's shifts as the screen times them, the others from their Work Orders.", "nullable": true, "properties": { "by_client": { "items": { "properties": { "client": { "type": "string" }, "minutes": { "description": "A week.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "caregiver": { "description": "Last, First.", "type": "string" }, "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "minutes": { "description": "Her minutes a week.", "nullable": true, "type": "integer" }, "visits": { "items": { "properties": { "client": { "description": "Last, First.", "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" }, "here": { "description": "A shift of this client's plan.", "type": "boolean" }, "minutes": { "description": "The visit's minutes.", "nullable": true, "type": "integer" }, "service": { "type": "string" }, "start": { "description": "Minutes after midnight.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "days": { "description": "Its columns in the agency's week order.", "items": { "properties": { "by_day": { "description": "It starts at a time of its own that day (shift_settings by_day).", "type": "boolean" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "end": { "description": "Minutes after midnight it ends; past 1440 runs past midnight.", "nullable": true, "type": "integer" }, "label": { "type": "string" }, "minutes": { "description": "The minutes it holds that day.", "nullable": true, "type": "integer" }, "overlap": { "description": "It overlaps another shift that day.", "type": "boolean" }, "start": { "description": "Minutes after midnight the shift starts, null when off.", "nullable": true, "type": "integer" }, "working": { "description": "A day the service works.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "effective_date": { "description": "Its Work Order's Effective Date.", "format": "date", "nullable": true, "type": "string" }, "empty": { "description": "No visits fall on this shift.", "type": "boolean" }, "label": { "type": "string" }, "lock_version": { "description": "Its Work Order's lock_version, null before Generate.", "nullable": true, "type": "integer" }, "rows": { "items": { "properties": { "cells": { "items": { "properties": { "count": { "description": "The marks that day.", "nullable": true, "type": "integer" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" }, "edited": { "description": "Differs from the layout; Undo puts it back.", "type": "boolean" }, "minutes": { "description": "The minutes they hold.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "in_plan": { "description": "One of the plan's tasks, so its cells can be changed.", "type": "boolean" }, "min_task": { "description": "Min / Task on this shift, as the printed Work Order writes it: the row's week over its visits, at most 2 places (40 + 35 is 37.5). Null with no marks.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "One visit's minutes.", "nullable": true, "type": "integer" }, "name": { "description": "What a cell change names as row.", "type": "string" }, "slug": { "type": "string" }, "times": { "description": "Times / Week: the row's marks on this shift. Null with no marks.", "nullable": true, "type": "integer" }, "week": { "description": "Week: the row's day minutes added on this shift. Null with no marks.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "shift_id": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "shift_number": { "description": "k of the service's shifts.", "nullable": true, "type": "integer" }, "work_order_id": { "description": "Its generated Work Order, null before Generate.", "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "caregivers": { "additionalProperties": { "description": "The caregiver's id.", "format": "uuid", "type": "string" }, "description": "Shift id => the caregiver picked for it, which Generate reads. A shift left out has none yet: it is planned and printable, and Generate makes it no Work Order.", "type": "object" }, "client_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "edited": { "description": "Some cell differs from the layout.", "type": "boolean" }, "hma": { "description": "The client's HMA calculator week, which the Shift Plan does not lay out: HMA stays on its Plan of Care. Null when the client has no current HMA plan with tasks.", "nullable": true, "properties": { "plan_id": { "description": "The HMA Plan of Care's id.", "format": "uuid", "type": "string" }, "weekly_minutes": { "description": "Its tasks' minutes a week.", "type": "integer" } }, "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "other_work_orders": { "description": "The client's live Work Orders made outside the Shift Plan, in force this month or later, by Effective Date (at most 50): the screen names them so the month is not made twice.", "items": { "properties": { "caregiver": { "description": "The Work Order's caregiver; null when it has none.", "nullable": true, "properties": { "first_name": { "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "nullable": true, "type": "string" } }, "type": "object" }, "closing_date": { "description": "Its Closing Date; null while it stays open.", "format": "date", "nullable": true, "type": "string" }, "effective_date": { "description": "Its Effective Date.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "number": { "description": "The Work Order's WO #.", "nullable": true, "type": "integer" }, "service": { "description": "The Work Order's service.", "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "shift_id": { "description": "The Shift Plan's shift that made it; only on a Work Order the plan made.", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } }, "required": [ "id", "number", "service", "caregiver", "effective_date", "closing_date" ], "title": "ShiftPlanWorkOrderLine", "type": "object" }, "type": "array" }, "overlaps": { "items": { "properties": { "a": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "b": { "description": "The shift: PC1 ... PC4, HM1 ...", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" }, "day": { "description": "The Shift Plan's day: 0 Saturday, 1 Sunday, 2 Monday ... 6 Friday.", "maximum": 6, "minimum": 0, "type": "integer" } }, "type": "object" }, "type": "array" }, "print_problems": { "description": "What the screen asks to check before a print or Download Excel.", "items": { "type": "string" }, "type": "array" }, "services": { "properties": { "hm": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's week against its calculator.", "properties": { "authorized": { "description": "The calculator's minutes a week.", "nullable": true, "type": "integer" }, "cfc_hours": { "description": "The tasks' CFC hours a week.", "format": "decimal", "nullable": true, "type": "string" }, "off_tasks": { "description": "When the week is off: each row whose placed minutes differ from its tasks' Min / week.", "items": { "properties": { "calculator": { "description": "The tasks' Min / week.", "nullable": true, "type": "integer" }, "name": { "type": "string" }, "placed": { "description": "The minutes the shifts place.", "nullable": true, "type": "integer" } }, "type": "object" }, "type": "array" }, "pill": { "description": "As the screen shows it.", "type": "string" }, "placed": { "description": "The minutes the shifts place in the week.", "nullable": true, "type": "integer" }, "status": { "enum": [ "matches", "off", "no_tasks" ], "type": "string" }, "total": { "description": "The calculator's TOTAL hours, null without a Plan of Care.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "settings": { "description": "days, shifts_per_day, shift_settings, gap_minutes, split_long_tasks, marks_mode, as PATCH takes them, task_overrides, the task table's edits, and care_instructions, shift id => text.", "type": "object" }, "task_table": { "items": { "properties": { "edited": { "description": "A figure differs from the Plan of Care's.", "type": "boolean" }, "fractional": { "description": "Min / task is not whole.", "type": "boolean" }, "max": { "description": "The state's weekly maximum, in minutes; null for a task it does not list.", "nullable": true, "type": "integer" }, "min_task": { "description": "Min / task.", "format": "decimal", "nullable": true, "type": "string" }, "min_week": { "description": "Min / week.", "format": "decimal", "nullable": true, "type": "string" }, "name": { "description": "What a task change names as task.", "type": "string" }, "norm": { "description": "The state's norm and weekly maximum, as the screen shows it under the task.", "nullable": true, "type": "string" }, "over_max": { "description": "Min / week is above the state's weekly maximum: needs justification and supervisor approval. Never a refusal.", "type": "boolean" }, "service": { "enum": [ "personal_care", "homemaker" ], "type": "string" }, "split": { "description": "A split task: its visits and the minutes of each.", "nullable": true, "properties": { "minutes": { "description": "Each.", "nullable": true, "type": "integer" }, "visits": { "description": "Visits.", "nullable": true, "type": "integer" } }, "type": "object" }, "times": { "description": "Times / week.", "nullable": true, "type": "integer" }, "uneven": { "description": "Times / week was rounded.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "task_totals": { "properties": { "hm": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "pc": { "description": "The service's task table summed, as its Total row reads.", "properties": { "hours": { "description": "Their CFC hours, to 2 places.", "format": "decimal", "nullable": true, "type": "string" }, "minutes": { "description": "The sum of the rows' Min / week.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "warnings": { "description": "What the screen warns of; never a refusal.", "items": { "type": "string" }, "type": "array" } }, "title": "ShiftPlan", "type": "object" }, "undone_shifts": { "items": { "type": "string" }, "type": "array" } }, "required": [ "data", "undone_shifts" ], "type": "object" } } }, "description": "The Shift Plan" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Undo the changes to a Shift Plan's cells", "tags": [ "Shift plans" ] } }, "/api/v1/clients/{id}/supervisory-plan": { "post": { "callbacks": {}, "description": "US-102.35, #2606: for each quarter N, the month of that quarter (planned_supervisory_qN_offset, 1-3) and the day of that month (planned_supervisory_qN_day) the client's supervisory visit is planned on, as the client page's Supervisory slots set them. Both null leaves a quarter unplanned; a day needs a month (422 validation_failed, in the page's words). planned_supervisory_offset / planned_supervisory_day set all four quarters alike when no per-quarter field is sent. Refused with 409 stale_record when the client changed since lock_version was read. Audited against the credential.", "operationId": "postClientsByIdSupervisoryPlan", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientSupervisoryPlan" } } }, "description": "The slot", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Client" } }, "required": [ "data" ], "type": "object" } } }, "description": "The client" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Set or clear a client's planned supervisory visit slots", "tags": [ "Clients" ] } }, "/api/v1/company-documents": { "get": { "callbacks": {}, "description": "The agency's documents, as Agency Compliance > Company Documents lists them.", "operationId": "getCompanyDocuments", "parameters": [ { "description": "", "in": "query", "name": "limit", "required": false, "schema": { "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "", "in": "query", "name": "offset", "required": false, "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "type": "object" }, "type": "array" }, "total_count": { "description": "All of them.", "nullable": true, "type": "integer" } }, "required": [ "data" ], "type": "object" } } }, "description": "The records" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List company documents", "tags": [ "Company documents" ] }, "post": { "callbacks": {}, "description": "Stores the file (multipart field file, or JSON file_base64 with file_name and content_type) with name, description and expires_at, as Company documents > Upload does: its size, type, extension, the agency's quota and its first bytes are checked, then it is scanned for viruses. scan_status is pending until the scan marks it clean; only then can its file be read. A multipart upload takes a file up to 50 MB, the page's limit; a JSON body takes at most 1 MB, file_base64 included. A JSON client with a larger file, up to 50 MB, asks POST /api/v1/company-documents/uploads for a slot and PUTs the bytes to it.", "operationId": "postCompanyDocuments", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "content_type": { "description": "Optional; else the extension's.", "type": "string" }, "description": { "description": "What it is; null or blank clears it.", "nullable": true, "type": "string" }, "expires_at": { "description": "YYYY-MM-DD, if it expires; null clears it.", "format": "date", "nullable": true, "type": "string" }, "file_base64": { "description": "The file's bytes, base64.", "type": "string" }, "file_name": { "description": "Its name, with its extension.", "type": "string" }, "name": { "description": "Its name.", "type": "string" } }, "type": "object" } } }, "description": "The file and its details", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The record" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code internal_error: a failure on our side, which was logged. When its message says nothing changed (the file store refused the request, the virus scan could not be queued, the upload could not be read), nothing did, the same request fails the same way until it is fixed, and the Idempotency-Key stays free." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code storage_unavailable (the file store did not answer) or, on an upload, temporarily_unavailable (its uploaded file could not be read): nothing changed, and the same request can succeed later. Retry after the Retry-After seconds; a write retried with the same Idempotency-Key runs again.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (30).", "schema": { "type": "integer" }, "style": "simple" } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Upload a company document", "tags": [ "Company documents" ] } }, "/api/v1/company-documents/uploads": { "post": { "callbacks": {}, "description": "For a file larger than a JSON body carries (1 MB), up to 50 MB, the page's limit: answers upload_url, single-use, bound to this credential and this agency, and valid for 30 minutes (expires_at). PUT the file's bytes to it (PUT /api/v1/company-documents/uploads/{token}) with the same credential; the answer is the stored document. The details are checked now, as Company documents > Upload checks them (type, extension, name, expiry), and the size, the agency's quota and the file's first bytes when the bytes arrive. content_type is optional, else the one file_name's extension names; name defaults to file_name.", "operationId": "postCompanyDocumentsUploads", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "content_type": { "description": "Optional; else the extension's.", "type": "string" }, "description": { "description": "What it is; null or blank clears it.", "nullable": true, "type": "string" }, "expires_at": { "description": "YYYY-MM-DD, if it expires; null clears it.", "format": "date", "nullable": true, "type": "string" }, "file_name": { "description": "Its name, with its extension.", "type": "string" }, "name": { "description": "Its name.", "type": "string" } }, "required": [ "file_name" ], "type": "object" } } }, "description": "The document's details", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "content_type": { "nullable": true, "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "file_name": { "nullable": true, "type": "string" }, "max_file_size": { "description": "The largest file the slot takes, in bytes.", "nullable": true, "type": "integer" }, "method": { "description": "PUT.", "nullable": true, "type": "string" }, "name": { "nullable": true, "type": "string" }, "upload_url": { "description": "Where to PUT the file's bytes, once, with this credential.", "nullable": true, "type": "string" } }, "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The slot" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Request a slot to upload a large company document", "tags": [ "Company documents" ] } }, "/api/v1/company-documents/uploads/{token}": { "put": { "callbacks": {}, "description": "The body is the file's bytes, nothing else (any content type but JSON, form or multipart, which answer 415), up to 50 MB; over it answers 413 file_too_large. Sent with the credential that requested the slot: another credential's or another agency's slot answers 404, as an unknown one does. A slot stores one document: a slot already used answers 409 upload_slot_used with the document's id in details, one another PUT is still storing 409 upload_slot_in_progress, and one past expires_at 410 upload_slot_expired. A file the upload refuses (422) leaves the slot usable until it expires. The answer is the document, scan_status pending until its virus scan marks it clean.", "operationId": "putCompanyDocumentsUploadsByToken", "parameters": [ { "description": "The slot's token, from its upload_url.", "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "The file's bytes", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The record" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes upload_slot_in_progress, upload_slot_used: Conflict, as the operation's description says." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code upload_slot_expired: Gone, as the operation's description says." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code file_too_large: Request Entity Too Large, as the operation's description says." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unsupported Media Type, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code internal_error: a failure on our side, which was logged. When its message says nothing changed (the file store refused the request, the virus scan could not be queued, the upload could not be read), nothing did, the same request fails the same way until it is fixed, and the Idempotency-Key stays free." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code storage_unavailable (the file store did not answer) or, on an upload, temporarily_unavailable (its uploaded file could not be read): nothing changed, and the same request can succeed later. Retry after the Retry-After seconds; a write retried with the same Idempotency-Key runs again.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (30).", "schema": { "type": "integer" }, "style": "simple" } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Upload a company document's bytes to its slot", "tags": [ "Company documents" ] } }, "/api/v1/company-documents/{id}": { "delete": { "callbacks": {}, "description": "As the page deletes one, at the lock_version it was read with (400 missing, 409 stale_record changed since). The screen report of an OIG attestation is kept with it for seven years: 422 retained. Another agency's record answers 404 and nothing is written.", "operationId": "deleteCompanyDocumentsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The lock_version the record was read with: missing answers 400, changed since 409 stale_record.", "in": "query", "name": "lock_version", "required": true, "schema": { "description": "The value the record was read with; a record changed since answers 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The record" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Bad Request, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a company document", "tags": [ "Company documents" ] }, "get": { "callbacks": {}, "description": "Its details and scan_status; the file is GET .../file. Another agency's record answers 404 and nothing is written.", "operationId": "getCompanyDocumentsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The record" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "A company document", "tags": [ "Company documents" ] }, "patch": { "callbacks": {}, "description": "name, description and expires_at, as the page's Edit does, with the lock_version the document was read with: missing answers 400, a document changed since 409 stale_record. Another agency's record answers 404 and nothing is written.", "operationId": "patchCompanyDocumentsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "description": { "description": "What it is; null or blank clears it.", "nullable": true, "type": "string" }, "expires_at": { "description": "YYYY-MM-DD, if it expires; null clears it.", "format": "date", "nullable": true, "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "name": { "description": "Its name.", "type": "string" } }, "required": [ "lock_version" ], "type": "object" } } }, "description": "The details", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The record" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Bad Request, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a company document's details", "tags": [ "Company documents" ] } }, "/api/v1/company-documents/{id}/file": { "get": { "callbacks": {}, "description": "The file once its virus scan marked it clean, as Download serves it. Still scanning answers 409 scan_pending; a threat found 410 scan_infected; a scan that failed 409 scan_error. Another agency's record answers 404 and nothing is written.", "operationId": "getCompanyDocumentsByIdFile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "The file" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes scan_error, scan_pending: Conflict, as the operation's description says." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code file_missing: the record exists and its file does not. Nothing changed." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code internal_error: a failure on our side, which was logged. When its message says nothing changed (the file store refused the request, the virus scan could not be queued, the upload could not be read), nothing did, the same request fails the same way until it is fixed, and the Idempotency-Key stays free." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code storage_unavailable (the file store did not answer) or, on an upload, temporarily_unavailable (its uploaded file could not be read): nothing changed, and the same request can succeed later. Retry after the Retry-After seconds; a write retried with the same Idempotency-Key runs again.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (30).", "schema": { "type": "integer" }, "style": "simple" } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read a company document's file", "tags": [ "Company documents" ] } }, "/api/v1/complaints": { "get": { "callbacks": {}, "description": "Each with its answers by the agency's question key. A complaint stays on record: there is no delete, as there is none on the web. The status moves only along the complaint's phases. The agency's complaints in complaint date order, newest first. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getComplaints", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records with this status.", "in": "query", "name": "status", "schema": { "enum": [ "intake", "investigating", "interviewing", "visiting", "following_up", "resolved", "closed" ], "type": "string" } }, { "description": "Only this client's complaints.", "in": "query", "name": "client_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only complaints about this caregiver.", "in": "query", "name": "caregiver_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Complaints received on or between these days. on or after this date (YYYY-MM-DD, Colorado).", "in": "query", "name": "complaint_date_from", "schema": { "format": "date", "type": "string" } }, { "description": "Complaints received on or between these days. on or before this date (YYYY-MM-DD, Colorado).", "in": "query", "name": "complaint_date_to", "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Complaint" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ComplaintPage", "type": "object" } } }, "description": "A page of complaints" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List complaints", "tags": [ "Complaints" ] }, "post": { "callbacks": {}, "operationId": "postComplaints", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplaintCreate" } } }, "description": "The complaint's fields", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Complaint" } }, "required": [ "data" ], "type": "object" } } }, "description": "The created complaint" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a complaint", "tags": [ "Complaints" ] } }, "/api/v1/complaints/{id}": { "get": { "callbacks": {}, "description": "Each with its answers by the agency's question key. A complaint stays on record: there is no delete, as there is none on the web. The status moves only along the complaint's phases.", "operationId": "getComplaintsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Complaint" } }, "required": [ "data" ], "type": "object" } } }, "description": "The complaint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no complaint with that id in this agency, including another agency's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a complaint", "tags": [ "Complaints" ] }, "patch": { "callbacks": {}, "description": "Sets only the fields sent. lock_version is required: send the value you read, and a record changed since answers 409 stale_record.", "operationId": "patchComplaintsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplaintInput" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Complaint" } }, "required": [ "data" ], "type": "object" } } }, "description": "The updated complaint" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no complaint with that id in this agency, including another agency's." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: the complaint changed since the lock_version sent was read, or while this request ran. Nothing was saved; read it again and retry." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a complaint", "tags": [ "Complaints" ] } }, "/api/v1/complaints/{id}/signatures": { "post": { "callbacks": {}, "description": "Records the office investigator's signature, typed as the credential's user. The first signature locks the complaint: after it only its status moves, and a PATCH sending any other field answers 409 record_locked; it is corrected with an addendum, or voided. The complainant's line is drawn on the device in the app, so client and representative answer 422 drawn_required. A line already signed answers 422 already_signed; a complaint whose text cannot be read answers 422 content_unreadable; one another request changed while this one ran answers 409 stale_record; a voided one 409 voided. Another agency's complaint is 404, before the body is judged. 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.", "operationId": "postComplaintsByIdSignatures", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "role": { "description": "Whose line to sign: office, the investigator, signed as you. The complainant's line (client when the complainant is the client, representative for anyone else) is drawn on the device in the app and answers 422 drawn_required here.", "enum": [ "client", "representative", "office" ], "type": "string" } }, "required": [ "role" ], "title": "ComplaintSignature", "type": "object" } } }, "description": "The signature", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Complaint" }, "warnings": { "description": "What the record page warns of before this line is signed, judged on the record as it was before signing; usually empty. Never a refusal: the line is signed. Each has an id (resolved-empty: a Resolved complaint whose investigation and resolution are empty; reporter: an incident's reporter line signed by a member other than the reporter it names; complaint-contact: a rights notice whose complaint contact is empty), the text, and, where answering one of the record's questions fixes it, that question_key.", "items": { "properties": { "id": { "description": "The warning's stable id.", "type": "string" }, "question_key": { "description": "The record's question that fixes it, when one does.", "type": "string" }, "text": { "description": "What the signer is warned of.", "type": "string" } }, "required": [ "id", "text" ], "title": "SignWarning", "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "type": "object" } } }, "description": "The complaint, and what signing it warned of" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code signature_requires_person: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes record_locked, stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_signed, content_unreadable, drawn_required: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Sign a complaint", "tags": [ "Complaints" ] } }, "/api/v1/compliance-alerts": { "get": { "callbacks": {}, "description": "The agency's active caregivers with one kind of problem (alert_type), or with any of them when alert_type is left out, as compliance_alerts returns them; each row's alert_types names every problem it has.", "operationId": "getComplianceAlerts", "parameters": [ { "description": "criminal_background: criminal background check expired or expiring; dora: DORA check expired or expiring; caps: CAPS check expired or expiring; driver_license: driver's license expired or expiring; main_training: main training expired or expiring; training: annual training missing, expired or expiring; evaluation: no current annual evaluation", "in": "query", "name": "alert_type", "required": false, "schema": { "enum": [ "criminal_background", "dora", "caps", "driver_license", "main_training", "training", "evaluation" ], "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ComplianceAlert" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ComplianceAlertPage", "type": "object" } } }, "description": "A page of caregivers" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List caregivers with a compliance problem", "tags": [ "Compliance" ] } }, "/api/v1/connected-apps": { "get": { "callbacks": {}, "description": "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.", "operationId": "getConnectedApps", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "app_name": { "description": "The AI app.", "nullable": true, "type": "string" }, "connected_at": { "description": "When it was connected (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_used_at": { "description": "Its last request (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "scopes": { "description": "What it may do.", "items": { "type": "string" }, "type": "array" }, "user_email": { "description": "Their email.", "nullable": true, "type": "string" }, "user_id": { "description": "The member who connected it.", "format": "uuid", "type": "string" } }, "required": [ "id", "app_name", "user_id" ], "title": "ConnectedApp", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ConnectedAppPage", "type": "object" } } }, "description": "A page of connections" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List AI app connections", "tags": [ "Agency administration" ] } }, "/api/v1/connected-apps/{id}": { "delete": { "callbacks": {}, "description": "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.", "operationId": "deleteConnectedAppsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "revoked_at": { "description": "When it was revoked (UTC).", "format": "date-time", "type": "string" } }, "required": [ "id", "revoked_at" ], "title": "ConnectedAppRevoked", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The revoked connection" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code already_revoked: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Revoke an AI app connection", "tags": [ "Agency administration" ] } }, "/api/v1/consent-forms/{id}": { "get": { "callbacks": {}, "description": "Its answers, state and signatures.", "operationId": "getConsentFormsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "answers": { "description": "The answers, by question key: a disclosure item's responsible party (agency or consumer), the complaint contact.", "type": "object" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "declined_reason": { "description": "Why the client declined to sign a disclosure notice; the office then signs that it was conveyed verbally.", "nullable": true, "type": "string", "x-untrusted": "text" }, "defaulted_keys": { "description": "The choices still holding the answer the notice was prefilled with (its first option): defaults nobody has chosen.", "items": { "type": "string" }, "type": "array" }, "form_type": { "description": "agency_disclosure_notice (Chapter 26 6.7) or client_rights_acknowledgement (6.4).", "enum": [ "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the notice was started.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "missing_signers": { "description": "Each required line no live signature fills yet, in order; empty when complete or voided.", "items": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "type": "array" }, "record_state": { "description": "draft until the first signature; signed notices are corrected by addendum or void.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "signer_name", "method", "signed_at" ], "title": "RecordSignatureSummary", "type": "object" }, "type": "array" }, "signed_at": { "description": "When the first signature locked it; null on a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing_complete": { "description": "True once the record is signed or amended and every required line holds a signature. A signed record can be false: signed by one line, with another still open. A voided record is always false, whatever it holds, and its missing_signers is empty: nothing can sign it, and its replacement is the record to complete.", "type": "boolean" } }, "required": [ "id", "client_id", "form_type", "record_state", "answers", "lock_version" ], "title": "ClientConsentForm", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The notice" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get an intake notice", "tags": [ "Client records" ] }, "patch": { "callbacks": {}, "description": "Saves answers on a draft notice, as its page does. A signed notice answers 409 record_locked; it is corrected with an addendum or voided. A stale lock_version answers 409. Another agency's notice is 404, before the body is judged.", "operationId": "patchConsentFormsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "answers": { "description": "Answers by question key; a key sent counts as chosen, and a blank clears its answer. Keys not sent keep their answer.", "type": "object" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": [ "answers", "lock_version" ], "title": "ClientConsentFormAnswers", "type": "object" } } }, "description": "The answers", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "answers": { "description": "The answers, by question key: a disclosure item's responsible party (agency or consumer), the complaint contact.", "type": "object" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "declined_reason": { "description": "Why the client declined to sign a disclosure notice; the office then signs that it was conveyed verbally.", "nullable": true, "type": "string", "x-untrusted": "text" }, "defaulted_keys": { "description": "The choices still holding the answer the notice was prefilled with (its first option): defaults nobody has chosen.", "items": { "type": "string" }, "type": "array" }, "form_type": { "description": "agency_disclosure_notice (Chapter 26 6.7) or client_rights_acknowledgement (6.4).", "enum": [ "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the notice was started.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "missing_signers": { "description": "Each required line no live signature fills yet, in order; empty when complete or voided.", "items": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "type": "array" }, "record_state": { "description": "draft until the first signature; signed notices are corrected by addendum or void.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "signer_name", "method", "signed_at" ], "title": "RecordSignatureSummary", "type": "object" }, "type": "array" }, "signed_at": { "description": "When the first signature locked it; null on a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing_complete": { "description": "True once the record is signed or amended and every required line holds a signature. A signed record can be false: signed by one line, with another still open. A voided record is always false, whatever it holds, and its missing_signers is empty: nothing can sign it, and its replacement is the record to complete.", "type": "boolean" } }, "required": [ "id", "client_id", "form_type", "record_state", "answers", "lock_version" ], "title": "ClientConsentForm", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The notice" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code record_locked: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Answer an intake notice", "tags": [ "Client records" ] } }, "/api/v1/consent-forms/{id}/signatures": { "post": { "callbacks": {}, "description": "Records agency staff's signature, typed as the credential's user: on a rights acknowledgement it documents that the notice was given; on a disclosure notice only with declined_reason, which records that the client declined and the notice was conveyed verbally. The first signature locks the notice. A line already signed answers 422 already_signed, one the notice does not take 422 role_not_allowed, a voided notice 409 voided. Another agency's notice is 404, before the body is judged. 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.", "operationId": "postConsentFormsByIdSignatures", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "declined_reason": { "description": "On a draft disclosure notice: why the client declined to sign. Saved with the office signature in one step, that the notice was conveyed verbally.", "nullable": true, "type": "string", "x-untrusted": "text" }, "role": { "description": "office: agency staff, signed as you. A rights acknowledgement is complete with it; a disclosure notice takes it only with declined_reason. client and representative are drawn on the device in the app and answer 422 drawn_required here.", "enum": [ "client", "representative", "office" ], "type": "string" } }, "required": [ "role" ], "title": "ClientConsentFormSignature", "type": "object" } } }, "description": "The signature", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "answers": { "description": "The answers, by question key: a disclosure item's responsible party (agency or consumer), the complaint contact.", "type": "object" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "declined_reason": { "description": "Why the client declined to sign a disclosure notice; the office then signs that it was conveyed verbally.", "nullable": true, "type": "string", "x-untrusted": "text" }, "defaulted_keys": { "description": "The choices still holding the answer the notice was prefilled with (its first option): defaults nobody has chosen.", "items": { "type": "string" }, "type": "array" }, "form_type": { "description": "agency_disclosure_notice (Chapter 26 6.7) or client_rights_acknowledgement (6.4).", "enum": [ "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When the notice was started.", "format": "date-time", "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "missing_signers": { "description": "Each required line no live signature fills yet, in order; empty when complete or voided.", "items": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "type": "array" }, "record_state": { "description": "draft until the first signature; signed notices are corrected by addendum or void.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "signer_name", "method", "signed_at" ], "title": "RecordSignatureSummary", "type": "object" }, "type": "array" }, "signed_at": { "description": "When the first signature locked it; null on a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing_complete": { "description": "True once the record is signed or amended and every required line holds a signature. A signed record can be false: signed by one line, with another still open. A voided record is always false, whatever it holds, and its missing_signers is empty: nothing can sign it, and its replacement is the record to complete.", "type": "boolean" } }, "required": [ "id", "client_id", "form_type", "record_state", "answers", "lock_version" ], "title": "ClientConsentForm", "type": "object" }, "warnings": { "description": "What the record page warns of before this line is signed, judged on the record as it was before signing; usually empty. Never a refusal: the line is signed. Each has an id (resolved-empty: a Resolved complaint whose investigation and resolution are empty; reporter: an incident's reporter line signed by a member other than the reporter it names; complaint-contact: a rights notice whose complaint contact is empty), the text, and, where answering one of the record's questions fixes it, that question_key.", "items": { "properties": { "id": { "description": "The warning's stable id.", "type": "string" }, "question_key": { "description": "The record's question that fixes it, when one does.", "type": "string" }, "text": { "description": "What the signer is warned of.", "type": "string" } }, "required": [ "id", "text" ], "title": "SignWarning", "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "type": "object" } } }, "description": "The notice, and what signing it warned of" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code signature_requires_person: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_signed, role_not_allowed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Sign an intake notice", "tags": [ "Client records" ] } }, "/api/v1/consents/{purpose}": { "delete": { "callbacks": {}, "description": "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).", "operationId": "deleteConsentsByPurpose", "parameters": [ { "description": "external_ai_clients (AI Access), api_access (API Keys), paper_capture (Paper forms: reading scanned forms with AI) or docusign_agency (DocuSign: sending records for signature through the agency's own DocuSign account).", "in": "path", "name": "purpose", "required": true, "schema": { "description": "The consent.", "enum": [ "external_ai_clients", "api_access", "paper_capture", "docusign_agency" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "accepted": { "description": "Whether a current consent stands.", "type": "boolean" }, "accepted_at": { "description": "When it was accepted.", "format": "date-time", "nullable": true, "type": "string" }, "accepted_by_id": { "description": "The member who accepted it.", "format": "uuid", "nullable": true, "type": "string" }, "accepted_disclosure_version": { "description": "The disclosure version accepted; null when none stands.", "nullable": true, "type": "integer" }, "disclosure_version": { "description": "The disclosure's current version.", "type": "integer" }, "lapsed": { "description": "Accepted, but the disclosure changed since: accept it again.", "type": "boolean" }, "purpose": { "description": "The consent.", "enum": [ "external_ai_clients", "api_access", "paper_capture", "docusign_agency" ], "type": "string" }, "text": { "description": "The disclosure a member holding agency_settings.manage accepts.", "nullable": true, "type": "string" }, "title": { "description": "The disclosure's title.", "nullable": true, "type": "string" } }, "required": [ "purpose", "accepted", "lapsed", "disclosure_version", "title", "text" ], "title": "Consent", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The consent" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Revoke a consent", "tags": [ "Agency settings" ] }, "get": { "callbacks": {}, "description": "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).", "operationId": "getConsentsByPurpose", "parameters": [ { "description": "external_ai_clients (AI Access), api_access (API Keys), paper_capture (Paper forms: reading scanned forms with AI) or docusign_agency (DocuSign: sending records for signature through the agency's own DocuSign account).", "in": "path", "name": "purpose", "required": true, "schema": { "description": "The consent.", "enum": [ "external_ai_clients", "api_access", "paper_capture", "docusign_agency" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "accepted": { "description": "Whether a current consent stands.", "type": "boolean" }, "accepted_at": { "description": "When it was accepted.", "format": "date-time", "nullable": true, "type": "string" }, "accepted_by_id": { "description": "The member who accepted it.", "format": "uuid", "nullable": true, "type": "string" }, "accepted_disclosure_version": { "description": "The disclosure version accepted; null when none stands.", "nullable": true, "type": "integer" }, "disclosure_version": { "description": "The disclosure's current version.", "type": "integer" }, "lapsed": { "description": "Accepted, but the disclosure changed since: accept it again.", "type": "boolean" }, "purpose": { "description": "The consent.", "enum": [ "external_ai_clients", "api_access", "paper_capture", "docusign_agency" ], "type": "string" }, "text": { "description": "The disclosure a member holding agency_settings.manage accepts.", "nullable": true, "type": "string" }, "title": { "description": "The disclosure's title.", "nullable": true, "type": "string" } }, "required": [ "purpose", "accepted", "lapsed", "disclosure_version", "title", "text" ], "title": "Consent", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The consent" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read a consent", "tags": [ "Agency settings" ] }, "post": { "callbacks": {}, "description": "Accepts the current disclosure, as the tab's Accept does; accepting one already current changes nothing. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "postConsentsByPurpose", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "description": "external_ai_clients (AI Access), api_access (API Keys), paper_capture (Paper forms: reading scanned forms with AI) or docusign_agency (DocuSign: sending records for signature through the agency's own DocuSign account).", "in": "path", "name": "purpose", "required": true, "schema": { "description": "The consent.", "enum": [ "external_ai_clients", "api_access", "paper_capture", "docusign_agency" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "accepted": { "description": "Whether a current consent stands.", "type": "boolean" }, "accepted_at": { "description": "When it was accepted.", "format": "date-time", "nullable": true, "type": "string" }, "accepted_by_id": { "description": "The member who accepted it.", "format": "uuid", "nullable": true, "type": "string" }, "accepted_disclosure_version": { "description": "The disclosure version accepted; null when none stands.", "nullable": true, "type": "integer" }, "disclosure_version": { "description": "The disclosure's current version.", "type": "integer" }, "lapsed": { "description": "Accepted, but the disclosure changed since: accept it again.", "type": "boolean" }, "purpose": { "description": "The consent.", "enum": [ "external_ai_clients", "api_access", "paper_capture", "docusign_agency" ], "type": "string" }, "text": { "description": "The disclosure a member holding agency_settings.manage accepts.", "nullable": true, "type": "string" }, "title": { "description": "The disclosure's title.", "nullable": true, "type": "string" } }, "required": [ "purpose", "accepted", "lapsed", "disclosure_version", "title", "text" ], "title": "Consent", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The consent" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Accept a consent", "tags": [ "Agency settings" ] } }, "/api/v1/contacts": { "get": { "callbacks": {}, "description": "Contacts whose first name, last name or organization match every word of search, ordered by name, among those related (now or before) to a client the caller may open. A search over 8 words answers 400 bad_request. Needs clients.view.", "operationId": "getContacts", "parameters": [ { "description": "Words a name or organization must all match.", "in": "query", "name": "search", "required": false, "schema": { "maxLength": 100, "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Contact" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ContactPage", "type": "object" } } }, "description": "A page of contacts" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: Bad Request, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Find contacts", "tags": [ "Client records" ] } }, "/api/v1/contacts/{id}": { "get": { "callbacks": {}, "description": "One contact. One related only to clients outside the caller's reach answers 403 forbidden. Needs clients.view.", "operationId": "getContactsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Contact" } }, "required": [ "data" ], "type": "object" } } }, "description": "The contact" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a contact", "tags": [ "Client records" ] }, "patch": { "callbacks": {}, "description": "As the People section's Edit does: the change reaches every client the contact serves, each of which must be in the caller's reach. Send the lock_version it was read with; one changed since answers 409 stale_record and saves nothing. A refused value answers 422 naming the field. Needs clients.manage.", "operationId": "patchContactsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Contact" } }, "required": [ "data" ], "type": "object" } } }, "description": "The contact" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a contact", "tags": [ "Client records" ] } }, "/api/v1/contacts/{id}/merge": { "post": { "callbacks": {}, "description": "US-120.13: the contacts loser_ids names are the same person as the one in the path. Every relation of each one, current and ended, moves to the path's contact, whose own fields are kept; a relation that would list the person twice on a client is kept as deleted history; each one named is deleted; one audit row records the merge. Every client of every contact named must be in the credential's reach. An empty loser_ids, more than 50, or the path's own id among them is 422 invalid; a contact that is not this agency's or is already deleted (so repeating a finished merge) is 404 not_found; a credential without clients.manage is 403; a merge another write got to first is 409 stale. Nothing is written on any refusal.", "operationId": "postContactsByIdMerge", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactMerge" } } }, "description": "The contacts to merge", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Contact" } }, "required": [ "data" ], "type": "object" } } }, "description": "The contact merged into" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Merge contacts that are the same person", "tags": [ "Client records" ] } }, "/api/v1/critical-incidents": { "get": { "callbacks": {}, "description": "A report stays on record: there is no delete, as there is none on the web. The status moves only along the incident's transitions. The agency's critical incidents in incident date order, newest first. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getCriticalIncidents", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records with this status.", "in": "query", "name": "status", "schema": { "enum": [ "draft", "reported", "under_investigation", "resolved", "closed" ], "type": "string" } }, { "description": "Only incidents of this kind.", "in": "query", "name": "incident_type", "schema": { "enum": [ "death", "abuse_neglect_exploitation", "serious_injury", "property_damage_theft", "medication_management", "other_high_risk" ], "type": "string" } }, { "description": "Only this client's incidents.", "in": "query", "name": "client_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Incidents on or between these days. on or after this date (YYYY-MM-DD, Colorado).", "in": "query", "name": "incident_date_from", "schema": { "format": "date", "type": "string" } }, { "description": "Incidents on or between these days. on or before this date (YYYY-MM-DD, Colorado).", "in": "query", "name": "incident_date_to", "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/CriticalIncident" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Critical incidentPage", "type": "object" } } }, "description": "A page of critical incidents" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List critical incidents", "tags": [ "Critical incidents" ] }, "post": { "callbacks": {}, "operationId": "postCriticalIncidents", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CriticalIncidentCreate" } } }, "description": "The critical incident's fields", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CriticalIncident" } }, "required": [ "data" ], "type": "object" } } }, "description": "The created critical incident" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a critical incident", "tags": [ "Critical incidents" ] } }, "/api/v1/critical-incidents/{id}": { "get": { "callbacks": {}, "description": "A report stays on record: there is no delete, as there is none on the web. The status moves only along the incident's transitions.", "operationId": "getCriticalIncidentsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CriticalIncident" } }, "required": [ "data" ], "type": "object" } } }, "description": "The critical incident" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no critical incident with that id in this agency, including another agency's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a critical incident", "tags": [ "Critical incidents" ] }, "patch": { "callbacks": {}, "description": "Sets only the fields sent. lock_version is required: send the value you read, and a record changed since answers 409 stale_record.", "operationId": "patchCriticalIncidentsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CriticalIncidentInput" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CriticalIncident" } }, "required": [ "data" ], "type": "object" } } }, "description": "The updated critical incident" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no critical incident with that id in this agency, including another agency's." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: the critical incident changed since the lock_version sent was read, or while this request ran. Nothing was saved; read it again and retry." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a critical incident", "tags": [ "Critical incidents" ] } }, "/api/v1/critical-incidents/{id}/signatures": { "post": { "callbacks": {}, "description": "Records one signature line, typed as the credential's user: office (reported by) or supervisor (supervisor review); one member may sign both. The first signature locks the incident: after it only its status moves, and a PATCH sending any other field answers 409 record_locked; it is corrected with an addendum, or voided. A line already signed answers 422 already_signed; an incident whose text cannot be read answers 422 content_unreadable; one another request changed while this one ran answers 409 stale_record; a voided one 409 voided. Another agency's incident is 404, before the body is judged. 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.", "operationId": "postCriticalIncidentsByIdSignatures", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "role": { "description": "Whose line to sign, as you: office (reported by) or supervisor (supervisor review).", "enum": [ "office", "supervisor" ], "type": "string" } }, "required": [ "role" ], "title": "CriticalIncidentSignature", "type": "object" } } }, "description": "The signature", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CriticalIncident" }, "warnings": { "description": "What the record page warns of before this line is signed, judged on the record as it was before signing; usually empty. Never a refusal: the line is signed. Each has an id (resolved-empty: a Resolved complaint whose investigation and resolution are empty; reporter: an incident's reporter line signed by a member other than the reporter it names; complaint-contact: a rights notice whose complaint contact is empty), the text, and, where answering one of the record's questions fixes it, that question_key.", "items": { "properties": { "id": { "description": "The warning's stable id.", "type": "string" }, "question_key": { "description": "The record's question that fixes it, when one does.", "type": "string" }, "text": { "description": "What the signer is warned of.", "type": "string" } }, "required": [ "id", "text" ], "title": "SignWarning", "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "type": "object" } } }, "description": "The incident, and what signing it warned of" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code signature_requires_person: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes record_locked, stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_signed, content_unreadable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Sign a critical incident", "tags": [ "Critical incidents" ] } }, "/api/v1/denials": { "get": { "callbacks": {}, "description": "A denial is a claim the remittance did not pay. The agency's denials in payment date, newest first. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getDenials", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only claims whose Medicaid ID or patient name contains this text, case-insensitively. At most 64 characters.", "in": "query", "name": "member", "schema": { "maxLength": 64, "type": "string" } }, { "description": "Denials whose payment date is on or between these days. on or after this date (YYYY-MM-DD, Colorado).", "in": "query", "name": "payment_date_from", "schema": { "format": "date", "type": "string" } }, { "description": "Denials whose payment date is on or between these days. on or before this date (YYYY-MM-DD, Colorado).", "in": "query", "name": "payment_date_to", "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Denial" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "DenialPage", "type": "object" } } }, "description": "A page of denials" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List denials", "tags": [ "Claims" ] } }, "/api/v1/documents/{id}": { "delete": { "callbacks": {}, "description": "Removes it as the Documents tab's Delete does; the audit trail keeps it.", "operationId": "deleteDocumentsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "content_type": { "description": "Its type.", "nullable": true, "type": "string" }, "document_type": { "description": "What the document is, as the Documents tab's Type.", "enum": [ "care_plan", "authorization", "signed_agreement", "training_certificate", "background_check", "medical_form", "incident_report", "pcsp", "cfc_calculator", "legacy_paper", "other", "paper_capture", "true_copy", "voice_attestation" ], "type": "string" }, "documentable_id": { "description": "The client or caregiver.", "format": "uuid", "type": "string" }, "documentable_type": { "description": "Whose file it is on.", "enum": [ "client", "caregiver" ], "type": "string" }, "expiry_date": { "description": "When it expires, if it does.", "format": "date", "nullable": true, "type": "string" }, "file_name": { "description": "The file's name.", "nullable": true, "type": "string" }, "file_size": { "description": "Its size in bytes.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was uploaded.", "format": "date-time", "type": "string" }, "notes": { "description": "The tab's notes.", "nullable": true, "type": "string" }, "paper_form_type": { "description": "A legacy_paper scan's form type, as the paper archive files it (US-101.7); other when not given. Ignored on any other document_type.", "enum": [ "work_order", "time_services_card", "plan_of_care", "monthly_client_report", "supervisory_visit", "cfc_calculator", "intake_consent", "complaint_incident", "other" ], "nullable": true, "type": "string" }, "record_date": { "description": "A legacy_paper scan's date on the paper; a monthly form's is its month's first day. Ignored on any other document_type.", "format": "date", "nullable": true, "type": "string" }, "scan_status": { "description": "The virus scan's verdict; only a clean file can be downloaded.", "enum": [ "pending", "clean", "infected", "error" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" }, "uploaded_by": { "description": "Who uploaded it.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "documentable_type", "documentable_id", "file_name", "scan_status" ], "title": "PersonDocument", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted document" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a document", "tags": [ "Documents" ] }, "get": { "callbacks": {}, "description": "One document on a client's or caregiver's file, with its scan status. The read is recorded on the PHI access log.", "operationId": "getDocumentsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "content_type": { "description": "Its type.", "nullable": true, "type": "string" }, "document_type": { "description": "What the document is, as the Documents tab's Type.", "enum": [ "care_plan", "authorization", "signed_agreement", "training_certificate", "background_check", "medical_form", "incident_report", "pcsp", "cfc_calculator", "legacy_paper", "other", "paper_capture", "true_copy", "voice_attestation" ], "type": "string" }, "documentable_id": { "description": "The client or caregiver.", "format": "uuid", "type": "string" }, "documentable_type": { "description": "Whose file it is on.", "enum": [ "client", "caregiver" ], "type": "string" }, "expiry_date": { "description": "When it expires, if it does.", "format": "date", "nullable": true, "type": "string" }, "file_name": { "description": "The file's name.", "nullable": true, "type": "string" }, "file_size": { "description": "Its size in bytes.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was uploaded.", "format": "date-time", "type": "string" }, "notes": { "description": "The tab's notes.", "nullable": true, "type": "string" }, "paper_form_type": { "description": "A legacy_paper scan's form type, as the paper archive files it (US-101.7); other when not given. Ignored on any other document_type.", "enum": [ "work_order", "time_services_card", "plan_of_care", "monthly_client_report", "supervisory_visit", "cfc_calculator", "intake_consent", "complaint_incident", "other" ], "nullable": true, "type": "string" }, "record_date": { "description": "A legacy_paper scan's date on the paper; a monthly form's is its month's first day. Ignored on any other document_type.", "format": "date", "nullable": true, "type": "string" }, "scan_status": { "description": "The virus scan's verdict; only a clean file can be downloaded.", "enum": [ "pending", "clean", "infected", "error" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" }, "uploaded_by": { "description": "Who uploaded it.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "documentable_type", "documentable_id", "file_name", "scan_status" ], "title": "PersonDocument", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The document" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a document", "tags": [ "Documents" ] }, "patch": { "callbacks": {}, "description": "As the Documents tab's Edit does. 422 nothing_to_change for a body with none of these fields.", "operationId": "patchDocumentsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "document_type": { "description": "What the document is, as the Documents tab's Type.", "enum": [ "care_plan", "authorization", "signed_agreement", "training_certificate", "background_check", "medical_form", "incident_report", "pcsp", "cfc_calculator", "legacy_paper", "other" ], "type": "string" }, "expiry_date": { "description": "When it expires.", "format": "date", "nullable": true, "type": "string" }, "notes": { "description": "Notes, as the tab's Notes.", "nullable": true, "type": "string" }, "paper_form_type": { "description": "A legacy_paper scan's form type, as the paper archive files it (US-101.7); other when not given. Ignored on any other document_type.", "enum": [ "work_order", "time_services_card", "plan_of_care", "monthly_client_report", "supervisory_visit", "cfc_calculator", "intake_consent", "complaint_incident", "other" ], "type": "string" }, "record_date": { "description": "A legacy_paper scan's date on the paper; a monthly form's is its month's first day. Ignored on any other document_type.", "format": "date", "nullable": true, "type": "string" } }, "title": "PersonDocumentUpdate", "type": "object" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "content_type": { "description": "Its type.", "nullable": true, "type": "string" }, "document_type": { "description": "What the document is, as the Documents tab's Type.", "enum": [ "care_plan", "authorization", "signed_agreement", "training_certificate", "background_check", "medical_form", "incident_report", "pcsp", "cfc_calculator", "legacy_paper", "other", "paper_capture", "true_copy", "voice_attestation" ], "type": "string" }, "documentable_id": { "description": "The client or caregiver.", "format": "uuid", "type": "string" }, "documentable_type": { "description": "Whose file it is on.", "enum": [ "client", "caregiver" ], "type": "string" }, "expiry_date": { "description": "When it expires, if it does.", "format": "date", "nullable": true, "type": "string" }, "file_name": { "description": "The file's name.", "nullable": true, "type": "string" }, "file_size": { "description": "Its size in bytes.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was uploaded.", "format": "date-time", "type": "string" }, "notes": { "description": "The tab's notes.", "nullable": true, "type": "string" }, "paper_form_type": { "description": "A legacy_paper scan's form type, as the paper archive files it (US-101.7); other when not given. Ignored on any other document_type.", "enum": [ "work_order", "time_services_card", "plan_of_care", "monthly_client_report", "supervisory_visit", "cfc_calculator", "intake_consent", "complaint_incident", "other" ], "nullable": true, "type": "string" }, "record_date": { "description": "A legacy_paper scan's date on the paper; a monthly form's is its month's first day. Ignored on any other document_type.", "format": "date", "nullable": true, "type": "string" }, "scan_status": { "description": "The virus scan's verdict; only a clean file can be downloaded.", "enum": [ "pending", "clean", "infected", "error" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" }, "uploaded_by": { "description": "Who uploaded it.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "documentable_type", "documentable_id", "file_name", "scan_status" ], "title": "PersonDocument", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The document" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code nothing_to_change: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a document's type, notes or expiry", "tags": [ "Documents" ] } }, "/api/v1/documents/{id}/file": { "get": { "callbacks": {}, "description": "The file itself, as the Documents tab's Download serves it, and recorded as a download. A file whose virus scan is not clean is 404 not_scanned_clean, as the web refuses it.", "operationId": "getDocumentsByIdFile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "The file" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_scanned_clean: Not Found, as the operation's description says." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code file_missing: the record exists and its file does not. Nothing changed." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code internal_error: a failure on our side, which was logged. When its message says nothing changed (the file store refused the request, the virus scan could not be queued, the upload could not be read), nothing did, the same request fails the same way until it is fixed, and the Idempotency-Key stays free." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code storage_unavailable (the file store did not answer) or, on an upload, temporarily_unavailable (its uploaded file could not be read): nothing changed, and the same request can succeed later. Retry after the Retry-After seconds; a write retried with the same Idempotency-Key runs again.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (30).", "schema": { "type": "integer" }, "style": "simple" } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Download a document", "tags": [ "Documents" ] } }, "/api/v1/eligibility-checks": { "post": { "callbacks": {}, "operationId": "postEligibilityChecks", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "client_id": { "description": "The client checked, from find_client.", "format": "uuid", "type": "string" }, "coverage_month": { "description": "The coverage month, 1 to 12.", "type": "integer" }, "coverage_year": { "description": "The coverage year.", "type": "integer" }, "method": { "description": "How it was checked; hcpf_portal when left out.", "enum": [ "hcpf_portal" ], "type": "string" }, "note": { "description": "Free text on the check.", "nullable": true, "type": "string" }, "status": { "description": "What the check found.", "enum": [ "eligible", "not_eligible", "unknown" ], "type": "string" }, "verified_on": { "description": "When it was checked (YYYY-MM-DD); today when left out.", "format": "date", "type": "string" } }, "required": [ "client_id", "coverage_month", "coverage_year", "status" ], "type": "object" } } }, "description": "The check", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/EligibilityCheck" } }, "required": [ "data" ], "type": "object" } } }, "description": "The check" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Record a client's eligibility check", "tags": [ "Service authorizations", "Clients" ] } }, "/api/v1/emergency-info/{id}": { "delete": { "callbacks": {}, "description": "Deletes a draft revision, as the page's history does; the audit trail keeps it. A signed, amended or voided revision answers 409 record_locked and nothing is deleted. Another agency's revision is 404.", "operationId": "deleteEmergencyInfoById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "answers": { "description": "The answers, by question key.", "type": "object" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When this revision was saved.", "format": "date-time", "type": "string" }, "missing_signers": { "description": "Each required line no live signature fills yet, in order; empty when complete or voided.", "items": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "type": "array" }, "record_state": { "description": "draft until the first signature (US-101.32). A signed revision is never deleted or changed: it is corrected with an addendum, voided, or followed by a new revision.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "signer_name", "method", "signed_at" ], "title": "RecordSignatureSummary", "type": "object" }, "type": "array" }, "signed_at": { "description": "When the first signature locked it; null on a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing_complete": { "description": "True once the record is signed or amended and every required line holds a signature. A signed record can be false: signed by one line, with another still open. A voided record is always false, whatever it holds, and its missing_signers is empty: nothing can sign it, and its replacement is the record to complete.", "type": "boolean" }, "superseded": { "description": "True for a draft never signed whose client has a later signed revision: it is no longer the sheet in force, and may still be deleted.", "type": "boolean" }, "version": { "description": "Its revision number.", "type": "integer" } }, "required": [ "id", "client_id", "version", "answers", "record_state" ], "title": "ClientEmergencyInfo", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted revision" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code record_locked: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete an emergency information revision", "tags": [ "Client records" ] } }, "/api/v1/emergency-info/{id}/signatures": { "post": { "callbacks": {}, "description": "Records agency staff's signature, typed as the credential's user (US-101.32). The revision is complete once the client or their authorized representative has also signed, drawn on the device in the app; that line answers 422 drawn_required here. The first signature locks the revision: it is never deleted or changed, and a later save adds the next revision as a draft. A line already signed answers 422 already_signed, a voided revision 409 voided, one another request changed while this one ran 409 stale_record. Another agency's revision is 404, before the body is judged. 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.", "operationId": "postEmergencyInfoByIdSignatures", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "role": { "description": "Whose line to sign: office, agency staff, signed as you. The client's or authorized representative's line is drawn on the device in the app and answers 422 drawn_required here.", "enum": [ "client", "representative", "office" ], "type": "string" } }, "required": [ "role" ], "title": "ClientEmergencyInfoSignature", "type": "object" } } }, "description": "The signature", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "answers": { "description": "The answers, by question key.", "type": "object" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When this revision was saved.", "format": "date-time", "type": "string" }, "missing_signers": { "description": "Each required line no live signature fills yet, in order; empty when complete or voided.", "items": { "properties": { "label": { "description": "The line as the page names it, e.g. \"client or authorized representative\".", "type": "string" }, "roles": { "description": "The roles that would fill the line: any one of them.", "items": { "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "type": "array" } }, "required": [ "roles", "label" ], "title": "MissingSigner", "type": "object" }, "type": "array" }, "record_state": { "description": "draft until the first signature (US-101.32). A signed revision is never deleted or changed: it is corrected with an addendum, voided, or followed by a new revision.", "enum": [ "draft", "signed", "amended", "voided" ], "type": "string" }, "signatures": { "description": "The live signatures, oldest first.", "items": { "properties": { "method": { "description": "How it was signed.", "enum": [ "drawn", "initials", "typed", "pin" ], "type": "string" }, "role": { "description": "The line signed.", "enum": [ "client", "representative", "office", "caregiver", "pcp", "supervisor" ], "type": "string" }, "signed_at": { "description": "When.", "format": "date-time", "type": "string" }, "signer_name": { "description": "Who signed.", "nullable": true, "type": "string", "x-untrusted": "text" } }, "required": [ "role", "signer_name", "method", "signed_at" ], "title": "RecordSignatureSummary", "type": "object" }, "type": "array" }, "signed_at": { "description": "When the first signature locked it; null on a draft.", "format": "date-time", "nullable": true, "type": "string" }, "signing_complete": { "description": "True once the record is signed or amended and every required line holds a signature. A signed record can be false: signed by one line, with another still open. A voided record is always false, whatever it holds, and its missing_signers is empty: nothing can sign it, and its replacement is the record to complete.", "type": "boolean" }, "superseded": { "description": "True for a draft never signed whose client has a later signed revision: it is no longer the sheet in force, and may still be deleted.", "type": "boolean" }, "version": { "description": "Its revision number.", "type": "integer" } }, "required": [ "id", "client_id", "version", "answers", "record_state" ], "title": "ClientEmergencyInfo", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The revision" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code signature_requires_person: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_signed, drawn_required: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Sign an emergency information revision", "tags": [ "Client records" ] } }, "/api/v1/evaluations/{id}": { "delete": { "callbacks": {}, "description": "Deletes the evaluation, as the caregiver's Evaluations tab does; the audit trail keeps what it was. Evaluations carry no lock_version.", "operationId": "deleteEvaluationsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CaregiverEvaluation" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted evaluation" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a caregiver's evaluation", "tags": [ "Deletes and restores" ] }, "patch": { "callbacks": {}, "description": "Sets only the fields sent; a body that changes nothing is 422 nothing_to_change. Another agency's record is 404.", "operationId": "patchEvaluationsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaregiverEvaluationInput" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CaregiverEvaluation" } }, "required": [ "data" ], "type": "object" } } }, "description": "The evaluation" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code nothing_to_change: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a evaluation", "tags": [ "Caregiver records" ] } }, "/api/v1/evidence-dismissals": { "post": { "callbacks": {}, "description": "As the visit page's Dismiss warning form: records why two sources' times for a client, caregiver and day may differ, and changes neither visit. Dismissing a conflict already dismissed answers 200 with already_dismissed true and that dismissal. A conflict_key that is no longer a conflict of that day (a visit changed since it was read) answers 409 conflict_changed. A reason outside 3 to 500 characters is 422. Another agency's client or caregiver answers 404 and nothing is written.", "operationId": "postEvidenceDismissals", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "caregiver_id": { "description": "The visit's caregiver.", "format": "uuid", "type": "string" }, "client_id": { "description": "The visit's client.", "format": "uuid", "type": "string" }, "conflict_key": { "description": "The conflict's key, as the conflict was read.", "maxLength": 64, "minLength": 64, "type": "string" }, "reason": { "description": "Why the difference can be dismissed, as the visit page asks.", "maxLength": 500, "minLength": 3, "type": "string" }, "service_date": { "description": "The visit's service date (the Mountain day).", "format": "date", "type": "string" } }, "required": [ "client_id", "caregiver_id", "service_date", "conflict_key", "reason" ], "type": "object" } } }, "description": "The conflict to dismiss", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/EvidenceDismissal" } }, "required": [ "data" ], "type": "object" } } }, "description": "Already dismissed" }, "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/EvidenceDismissal" } }, "required": [ "data" ], "type": "object" } } }, "description": "The dismissal" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code conflict_changed: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Dismiss a visit evidence conflict", "tags": [ "Visits" ] } }, "/api/v1/evv-rules": { "get": { "callbacks": {}, "description": "The rules that raise visit exceptions, as Settings > EVV rules shows them; the defaults are set up on first read. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "getEvvRules", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "description": { "description": "What it means.", "nullable": true, "type": "string" }, "enabled": { "description": "Whether it raises exceptions.", "type": "boolean" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "rule_type": { "description": "What the rule checks.", "nullable": true, "type": "string" }, "severity": { "description": "How serious its exceptions are.", "enum": [ "warning", "error" ], "type": "string" }, "threshold_unit": { "description": "The threshold's unit.", "nullable": true, "type": "string" }, "threshold_value": { "description": "Its threshold.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "id", "rule_type", "enabled" ], "title": "EvvExceptionRule", "type": "object" }, "title": "EvvExceptionRules", "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The rules" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List the EVV exception rules", "tags": [ "Settings lists" ] } }, "/api/v1/evv-rules/reset": { "post": { "callbacks": {}, "description": "Replaces every rule with the default set, as the page's Reset does; answers the rules. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "postEvvRulesReset", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "description": { "description": "What it means.", "nullable": true, "type": "string" }, "enabled": { "description": "Whether it raises exceptions.", "type": "boolean" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "rule_type": { "description": "What the rule checks.", "nullable": true, "type": "string" }, "severity": { "description": "How serious its exceptions are.", "enum": [ "warning", "error" ], "type": "string" }, "threshold_unit": { "description": "The threshold's unit.", "nullable": true, "type": "string" }, "threshold_value": { "description": "Its threshold.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "id", "rule_type", "enabled" ], "title": "EvvExceptionRule", "type": "object" }, "title": "EvvExceptionRulesReset", "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The rules" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Reset the EVV exception rules to the defaults", "tags": [ "Settings lists" ] } }, "/api/v1/evv-rules/{id}": { "patch": { "callbacks": {}, "description": "Its severity, threshold, description or whether it is on; send only what changes. A value the rule refuses answers 422 naming the field. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "patchEvvRulesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "description": { "description": "What it means; null clears it.", "nullable": true, "type": "string" }, "enabled": { "description": "Whether it raises exceptions.", "type": "boolean" }, "severity": { "description": "How serious.", "enum": [ "warning", "error" ], "type": "string" }, "threshold_unit": { "description": "The threshold's unit; null clears it.", "maxLength": 50, "nullable": true, "type": "string" }, "threshold_value": { "description": "The threshold; null clears it.", "format": "decimal", "nullable": true, "type": "string" } }, "title": "EvvExceptionRuleUpdate", "type": "object" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "description": { "description": "What it means.", "nullable": true, "type": "string" }, "enabled": { "description": "Whether it raises exceptions.", "type": "boolean" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "rule_type": { "description": "What the rule checks.", "nullable": true, "type": "string" }, "severity": { "description": "How serious its exceptions are.", "enum": [ "warning", "error" ], "type": "string" }, "threshold_unit": { "description": "The threshold's unit.", "nullable": true, "type": "string" }, "threshold_value": { "description": "Its threshold.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "id", "rule_type", "enabled" ], "title": "EvvExceptionRule", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The rule" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change an EVV exception rule", "tags": [ "Settings lists" ] } }, "/api/v1/evv-rules/{id}/toggle": { "post": { "callbacks": {}, "description": "Flips it, as the page's switch does. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "postEvvRulesByIdToggle", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "description": { "description": "What it means.", "nullable": true, "type": "string" }, "enabled": { "description": "Whether it raises exceptions.", "type": "boolean" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "rule_type": { "description": "What the rule checks.", "nullable": true, "type": "string" }, "severity": { "description": "How serious its exceptions are.", "enum": [ "warning", "error" ], "type": "string" }, "threshold_unit": { "description": "The threshold's unit.", "nullable": true, "type": "string" }, "threshold_value": { "description": "Its threshold.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "id", "rule_type", "enabled" ], "title": "EvvExceptionRule", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The rule" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Turn an EVV exception rule on or off", "tags": [ "Settings lists" ] } }, "/api/v1/exports": { "post": { "callbacks": {}, "description": "Starts the CSV a report page's Export button makes, in the background: export_type payment_report, authorization_utilization, authorization_expiration, authorization_over_utilization, punctuality_report or chart_packet (a client's chart as a ZIP, packet.pdf and records.json), with params as the page sends them (payment_report: start_date, end_date, check_number, member, batch_id, date_basis, unreconciled, variance, view, status; authorization_expiration: days, renewed (exclude leaves out renewed authorizations); punctuality_report: start_date, end_date, grace_minutes; chart_packet: client_id, and from and to as dates, both optional; the answer's range says which dates it covers, and a packet of the client already running for another range answers 409 packet_running naming it, while one for the same range is answered again). Read GET /api/v1/exports/{id} until status is completed, then its file.", "operationId": "postExports", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "export_type": { "enum": [ "authorization_expiration", "authorization_over_utilization", "authorization_utilization", "chart_packet", "payment_report", "punctuality_report" ], "type": "string" }, "params": { "description": "The page's filters, e.g. start_date and end_date.", "type": "object" } }, "required": [ "export_type" ], "type": "object" } } }, "description": "The export", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The record" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code packet_running: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Start a data export", "tags": [ "Company documents", "Exports" ] } }, "/api/v1/exports/{id}": { "get": { "callbacks": {}, "description": "One the credential's user started: status pending, processing, completed or failed, and file_ready.", "operationId": "getExportsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The record" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "An export and its status", "tags": [ "Company documents", "Exports" ] } }, "/api/v1/exports/{id}/file": { "get": { "callbacks": {}, "description": "A completed export's file, as Download serves it. Still running answers 409 not_ready; failed 409 export_failed, its message the export's own reason; expired 410 expired; gone 410 file_missing.", "operationId": "getExportsByIdFile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "The file" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes export_failed, not_ready: Conflict, as the operation's description says." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code file_missing: the record exists and its file does not. Nothing changed." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code internal_error: a failure on our side, which was logged. When its message says nothing changed (the file store refused the request, the virus scan could not be queued, the upload could not be read), nothing did, the same request fails the same way until it is fixed, and the Idempotency-Key stays free." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code storage_unavailable (the file store did not answer) or, on an upload, temporarily_unavailable (its uploaded file could not be read): nothing changed, and the same request can succeed later. Retry after the Retry-After seconds; a write retried with the same Idempotency-Key runs again.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (30).", "schema": { "type": "integer" }, "style": "simple" } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read an export's file", "tags": [ "Company documents", "Exports" ] } }, "/api/v1/finding-dismissals": { "post": { "callbacks": {}, "description": "Dismisses any warning by its rule, subject and fingerprint: it is listed as dismissed until its figures change. Dismissing one already dismissed at the same figures answers that dismissal. A fingerprint that is not the subject's current one for the rule (its figures changed since it was listed, or the record is not this agency's) is 409 stale_finding. A rule no warning has is 422 unknown_rule; a warning that refuses (unsendable, or made strict by the agency) or that its rule never lets be dismissed is 422 not_dismissible; a rule that asks why, with no reason of 3 to 500 characters, is 422 reason_required. A credential that may not write is 403. Nothing is written on any refusal.", "operationId": "postFindingDismissals", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "context": { "description": "The inputs the warning was listed with beyond its subject, as it named them.", "nullable": true, "type": "object" }, "fingerprint": { "description": "The warning's fingerprint, as it was listed.", "maxLength": 200, "type": "string" }, "reason": { "description": "Why it is dismissed: 3 to 500 characters where the rule asks for one.", "maxLength": 500, "nullable": true, "type": "string" }, "rule_id": { "description": "The warning's rule, as the warning names it (revenue.underpayment, say).", "maxLength": 255, "type": "string" }, "subject_date": { "description": "The day, for a warning about one day of its subject.", "format": "date", "nullable": true, "type": "string" }, "subject_id": { "description": "The record the warning is about.", "format": "uuid", "type": "string" }, "subject_type": { "description": "What the warning is about, as the warning names it (claim, say).", "type": "string" } }, "required": [ "rule_id", "subject_type", "subject_id", "fingerprint" ], "type": "object" } } }, "description": "The warning to dismiss", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/FindingDismissal" } }, "required": [ "data" ], "type": "object" } } }, "description": "The dismissal" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_finding: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes not_dismissible, reason_required, unknown_rule: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Dismiss a warning", "tags": [ "Claims" ] } }, "/api/v1/finding-dismissals/{id}/restore": { "post": { "callbacks": {}, "description": "Ends the dismissal, so the warning is listed again; the dismissal is kept, with when it was shown again. Another agency's dismissal, or one already shown again, is 404. A credential that may not write is 403.", "operationId": "postFindingDismissalsByIdRestore", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/FindingDismissal" } }, "required": [ "data" ], "type": "object" } } }, "description": "The dismissal" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Show a dismissed warning again", "tags": [ "Claims" ] } }, "/api/v1/half-month-summaries": { "get": { "callbacks": {}, "description": "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.", "operationId": "getHalfMonthSummaries", "parameters": [ { "description": "The client.", "in": "query", "name": "client_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "The caregiver.", "in": "query", "name": "caregiver_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "The half's first day, YYYY-MM-DD: the 1st or the 16th of a month.", "in": "query", "name": "period_start", "required": true, "schema": { "format": "date", "type": "string" } }, { "description": "The service the summary attests (one summary per service). Left out, the half's only service.", "in": "query", "name": "service_type", "required": false, "schema": { "enum": [ "personal_care", "homemaker", "legacy" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/HalfMonthSummary" } }, "required": [ "data" ], "type": "object" } } }, "description": "The summary" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read a half-month summary", "tags": [ "Care logs" ] } }, "/api/v1/import-configurations": { "get": { "callbacks": {}, "description": "As Import > Configurations lists them.", "operationId": "getImportConfigurations", "parameters": [ { "description": "", "in": "query", "name": "limit", "required": false, "schema": { "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "", "in": "query", "name": "offset", "required": false, "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "type": "object" }, "type": "array" }, "total_count": { "description": "All of them.", "nullable": true, "type": "integer" } }, "required": [ "data" ], "type": "object" } } }, "description": "The records" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List import configurations", "tags": [ "Company documents", "Import configurations" ] }, "post": { "callbacks": {}, "description": "As Import > Configurations > New does.", "operationId": "postImportConfigurations", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "column_mappings": { "type": "object" }, "deduplication_keys": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" }, "strategy": { "type": "string" }, "target_schema": { "type": "string" }, "transform_rules": { "type": "object" }, "validation_rules": { "type": "object" } }, "type": "object" } } }, "description": "The configuration", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The record" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create an import configuration", "tags": [ "Company documents", "Import configurations" ] } }, "/api/v1/import-configurations/{id}": { "delete": { "callbacks": {}, "description": "As the page deletes one, at the lock_version it was read with (400 missing, 409 stale_record changed since). Another agency's record answers 404 and nothing is written.", "operationId": "deleteImportConfigurationsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The lock_version the record was read with: missing answers 400, changed since 409 stale_record.", "in": "query", "name": "lock_version", "required": true, "schema": { "description": "The value the record was read with; a record changed since answers 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The record" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Bad Request, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete an import configuration", "tags": [ "Company documents", "Import configurations" ] }, "get": { "callbacks": {}, "description": "Another agency's record answers 404 and nothing is written.", "operationId": "getImportConfigurationsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The record" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "An import configuration", "tags": [ "Company documents", "Import configurations" ] }, "patch": { "callbacks": {}, "description": "The fields sent, as the page's Edit does, with the lock_version the configuration was read with: missing answers 400, changed since 409 stale_record. Another agency's record answers 404 and nothing is written.", "operationId": "patchImportConfigurationsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "column_mappings": { "type": "object" }, "deduplication_keys": { "items": { "type": "string" }, "type": "array" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "name": { "type": "string" }, "strategy": { "type": "string" }, "target_schema": { "type": "string" }, "transform_rules": { "type": "object" }, "validation_rules": { "type": "object" } }, "required": [ "lock_version" ], "type": "object" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The record" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Bad Request, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change an import configuration", "tags": [ "Company documents", "Import configurations" ] } }, "/api/v1/invitations": { "get": { "callbacks": {}, "description": "Invitations not yet accepted, revoked or expired, newest first. Needs Team → View (403 forbidden otherwise).", "operationId": "getInvitations", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "email": { "description": "Who was invited.", "nullable": true, "type": "string" }, "expires_at": { "description": "When the link stops working (UTC).", "format": "date-time", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "invited_at": { "description": "When it was sent (UTC).", "format": "date-time", "type": "string" }, "invited_by_id": { "description": "The member who invited.", "format": "uuid", "nullable": true, "type": "string" }, "role": { "description": "The role they join with.", "enum": [ "admin", "billing_staff" ], "type": "string" }, "status": { "description": "Where it stands.", "enum": [ "pending", "accepted", "revoked", "expired" ], "type": "string" } }, "required": [ "id", "email", "role", "status" ], "title": "AgencyInvitation", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "AgencyInvitationPage", "type": "object" } } }, "description": "A page of invitations" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List pending invitations", "tags": [ "Agency administration" ] }, "post": { "callbacks": {}, "description": "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).", "operationId": "postInvitations", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "description": "Their email address.", "type": "string" }, "role": { "description": "The role they join with.", "enum": [ "admin", "billing_staff" ], "type": "string" } }, "required": [ "email", "role" ], "title": "AgencyInvitationCreate", "type": "object" } } }, "description": "Who and as what", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "email": { "description": "Who was invited.", "nullable": true, "type": "string" }, "expires_at": { "description": "When the link stops working (UTC).", "format": "date-time", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "invited_at": { "description": "When it was sent (UTC).", "format": "date-time", "type": "string" }, "invited_by_id": { "description": "The member who invited.", "format": "uuid", "nullable": true, "type": "string" }, "role": { "description": "The role they join with.", "enum": [ "admin", "billing_staff" ], "type": "string" }, "status": { "description": "Where it stands.", "enum": [ "pending", "accepted", "revoked", "expired" ], "type": "string" } }, "required": [ "id", "email", "role", "status" ], "title": "AgencyInvitation", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The invitation" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_member, pending_invitation, role_unavailable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Invite someone to the agency", "tags": [ "Agency administration" ] } }, "/api/v1/invitations/{id}": { "delete": { "callbacks": {}, "description": "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).", "operationId": "deleteInvitationsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "email": { "description": "Who was invited.", "nullable": true, "type": "string" }, "expires_at": { "description": "When the link stops working (UTC).", "format": "date-time", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "invited_at": { "description": "When it was sent (UTC).", "format": "date-time", "type": "string" }, "invited_by_id": { "description": "The member who invited.", "format": "uuid", "nullable": true, "type": "string" }, "role": { "description": "The role they join with.", "enum": [ "admin", "billing_staff" ], "type": "string" }, "status": { "description": "Where it stands.", "enum": [ "pending", "accepted", "revoked", "expired" ], "type": "string" } }, "required": [ "id", "email", "role", "status" ], "title": "AgencyInvitation", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The invitation" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_pending: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Revoke a pending invitation", "tags": [ "Agency administration" ] } }, "/api/v1/me": { "get": { "callbacks": {}, "operationId": "getMe", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Me" } }, "required": [ "data" ], "type": "object" } } }, "description": "The caregiver" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "The signed-in caregiver", "tags": [ "Caregiver app" ] } }, "/api/v1/me/care-logs": { "get": { "callbacks": {}, "description": "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.", "operationId": "getMeCareLogs", "parameters": [ { "description": "Rows per page (default 20, at most 20; a larger value is served as 20).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/MeCareLog" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "MeCareLogPage", "type": "object" } } }, "description": "A page of care logs" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "List my unfinished care logs", "tags": [ "Caregiver app" ] }, "post": { "callbacks": {}, "description": "As the dashboard's Open care log: starts your care log of the client, day, service and shift with source hcb_app, seeded with the tasks the Work Orders in force plan for the day. One of your Work Orders must plan that client, service and shift on the day (else 422 no_work_order), and the day must be today or up to 90 days back (else 422 service_date_out_of_reach). A day that already has a live care log answers 200 with it, never a second, so a retry is safe; a new one answers 201. A caregiver whose agency has not turned care logs on is 403 care_log_not_enabled; a Visit that is not yours with that client that day 422 visit_mismatch.", "operationId": "postMeCareLogs", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "service_date": { "description": "The day.", "format": "date", "nullable": false, "type": "string" }, "service_type": { "description": "The service, as the Work Order's.", "enum": [ "personal_care", "homemaker", "legacy" ], "type": "string" }, "shift_number": { "description": "The shift, 1 to 4 (default 1).", "maximum": 4, "minimum": 1, "type": "integer" }, "visit_id": { "description": "Your Visit to link, with the same client on the same day. Left out, the day's one such Visit is linked when exactly one exists.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "client_id", "service_date", "service_type" ], "title": "MeCareLogStart", "type": "object" } } }, "description": "The day", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeCareLogDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The care log already holding the day" }, "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeCareLogDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The care log started" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code care_log_not_enabled: Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes no_work_order, service_date_out_of_reach, visit_mismatch: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Start my care log", "tags": [ "Caregiver app" ] } }, "/api/v1/me/care-logs/{id}": { "get": { "callbacks": {}, "description": "One of your care logs as its screen shows it: the day with its tasks, times, warnings and live signatures, the signing_hash to attest it under, and the representatives who may sign in the client's place. The read is recorded on the PHI access log. Another caregiver's care log, another agency's, or one more than 90 days back is 404, whatever the body holds. A caregiver whose agency has not turned care logs on is 403 care_log_not_enabled.", "operationId": "getMeCareLogsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeCareLogDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The care log" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code care_log_not_enabled: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Read my care log", "tags": [ "Caregiver app" ] } }, "/api/v1/me/care-logs/{id}/attestation": { "post": { "callbacks": {}, "description": "As the screen's signature step: the client, or their representative (one the care log lists, by signer_relation_id, or someone else by signer_name), signs the day on your phone (channel app), which signs and locks it, finishes it when it was not, and marks the linked Visit client-signed. The same signature again answers the care log unchanged. Refusals: 409 content_changed (the day changed since the client read it), 409 role_already_signed (a different signature holds the client's line), 409 voided, 422 invalid_image (not base64, not a PNG, or too large), 422 validation_failed (a signer_relation_id that is not one of the client's representatives). Another caregiver's care log, another agency's, or one more than 90 days back is 404, whatever the body holds. A caregiver whose agency has not turned care logs on is 403 care_log_not_enabled.", "operationId": "postMeCareLogsByIdAttestation", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "capture_method": { "description": "drawn (the default) or initials.", "enum": [ "drawn", "initials" ], "type": "string" }, "expected_content_hash": { "description": "The signing_hash of the day the client read; a day changed since is refused with 409 content_changed.", "nullable": true, "type": "string" }, "image": { "description": "The signature as a base64 PNG, at most 51200 bytes.", "nullable": true, "type": "string" }, "role": { "description": "Who signs: the client (the default) or their representative in their place.", "enum": [ "client", "representative" ], "type": "string" }, "signer_name": { "description": "A representative's attestation by someone the office did not record: their name, signed with no relationship. With neither this nor signer_relation_id, the first listed representative signs, else \"Representative\". A client signs under their own name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "signer_relation_id": { "description": "A representative's attestation: the relation_id of one of the representatives the care log lists, whose name and relationship it is signed under (signer_name is then ignored). One the list does not hold is 422 validation_failed.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "image" ], "title": "MeCareLogAttestation", "type": "object" } } }, "description": "The signature", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeCareLogDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The care log, signed" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code care_log_not_enabled: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes content_changed, role_already_signed: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes invalid_image, validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "The client attests my care log", "tags": [ "Caregiver app" ] } }, "/api/v1/me/care-logs/{id}/attestation-skip": { "post": { "callbacks": {}, "description": "As the screen's Client can't sign: keeps why, finishes the day when it was not, and leaves it a draft for the office to collect a signature. The same reason again writes nothing. A reason not listed is 422 validation_failed, and other needs a note. A care log that is not a draft answers 409 record_locked and nothing changes. Another caregiver's care log, another agency's, or one more than 90 days back is 404, whatever the body holds. A caregiver whose agency has not turned care logs on is 403 care_log_not_enabled.", "operationId": "postMeCareLogsByIdAttestationSkip", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "note": { "description": "The reason in words; required for other.", "nullable": true, "type": "string", "x-untrusted": "text" }, "reason": { "description": "Why the client could not sign.", "enum": [ "client_asleep_or_unwell", "client_not_present", "client_declined_to_sign", "client_unable_to_sign", "other" ], "type": "string" } }, "required": [ "reason" ], "title": "MeCareLogAttestationSkip", "type": "object" } } }, "description": "Why", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeCareLogDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The care log" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code care_log_not_enabled: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code record_locked: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "The client cannot sign my care log", "tags": [ "Caregiver app" ] } }, "/api/v1/me/care-logs/{id}/finish": { "post": { "callbacks": {}, "description": "Marks the care log finished, once; finishing a finished care log changes nothing. Warnings never refuse it. The client's attestation (or attestation-skip) finishes it too. A care log that is not a draft answers 409 record_locked and nothing changes. Another caregiver's care log, another agency's, or one more than 90 days back is 404, whatever the body holds. A caregiver whose agency has not turned care logs on is 403 care_log_not_enabled.", "operationId": "postMeCareLogsByIdFinish", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeCareLogDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The care log" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code care_log_not_enabled: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code record_locked: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Finish my care log", "tags": [ "Caregiver app" ] } }, "/api/v1/me/care-logs/{id}/tasks": { "post": { "callbacks": {}, "description": "As the screen's Add a task I did: adds a task done off the plan (planned false, status done), with the reason it was done when sent. A task the care log already holds is set done 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 caregiver's care log, another agency's, or one more than 90 days back is 404, whatever the body holds. A caregiver whose agency has not turned care logs on is 403 care_log_not_enabled.", "operationId": "postMeCareLogsByIdTasks", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "How many times; 1 when left out.", "minimum": 1, "type": "integer" }, "reason_code": { "description": "Why it was done off the plan.", "enum": [ "client_declined", "client_not_home", "client_asleep_or_unwell", "done_by_someone_else", "not_needed_today", "client_requested", "care_need_changed", "other" ], "nullable": true, "type": "string" }, "reason_note": { "description": "The reason in words.", "nullable": true, "type": "string", "x-untrusted": "text" }, "task_definition_id": { "description": "The task to add: one of the agency's tasks or a system one.", "format": "uuid", "type": "string" } }, "required": [ "task_definition_id" ], "title": "MeCareLogTaskAdd", "type": "object" } } }, "description": "The task", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeCareLogDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The care log" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code care_log_not_enabled: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code record_locked: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code task_definition_not_found: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Add a task I did to my care log", "tags": [ "Caregiver app" ] } }, "/api/v1/me/care-logs/{id}/tasks/{task_id}/mark": { "post": { "callbacks": {}, "description": "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 /me/care-logs/{id}/tasks). A care log that is not a draft answers 409 record_locked and nothing changes. Another caregiver's care log, another agency's, or one more than 90 days back is 404, whatever the body holds. A caregiver whose agency has not turned care logs on is 403 care_log_not_enabled.", "operationId": "postMeCareLogsByIdTasksByTaskIdMark", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The task's task_definition_id, as the care log's tasks list it.", "in": "path", "name": "task_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "How many times; unchanged when left out.", "minimum": 1, "type": "integer" }, "expect_status": { "description": "The status the app showed; sent (null included), the mark is refused with 409 stale_record when the task no longer has it, so a clear re-sent after the office changed the task changes nothing.", "enum": [ "done", "refused", "not_needed" ], "nullable": true, "type": "string" }, "reason_code": { "description": "Why a task was refused or not needed; left out or null clears it, as a mark on the screen does.", "enum": [ "client_declined", "client_not_home", "client_asleep_or_unwell", "done_by_someone_else", "not_needed_today", "client_requested", "care_need_changed", "other" ], "nullable": true, "type": "string" }, "reason_note": { "description": "The reason in words; left out or null clears it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "The status to SET: done, refused or not_needed; null clears it. Sending the status the task already has changes nothing.", "enum": [ "done", "refused", "not_needed" ], "nullable": true, "type": "string" } }, "required": [ "status" ], "title": "MeCareLogTaskMark", "type": "object" } } }, "description": "The mark", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeCareLogDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The care log" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code care_log_not_enabled: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code record_locked: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code task_not_on_log: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Mark a task on my care log", "tags": [ "Caregiver app" ] } }, "/api/v1/me/clock-events": { "post": { "callbacks": {}, "description": "Sends up to 100 clocks the app saved while offline. Each is processed on its own, and one failing never stops the others; each is recorded at its captured_at, as a clock-in or clock-out sent online would be. Only your own visits within 90 days back are reached, as the live clock reaches: any other visit fails as visit_not_found, as the live clock answers 404,. Events carrying captured_at in Unix milliseconds run oldest first among themselves; an event without one keeps its place. An id that is not a string is invalid_event, answered with a null id. Clocks only: a task_toggle event is unknown_action. An empty batch is not counted against the hourly limit. Resending an event already recorded reports it in synced and records nothing twice. More than 100 events is 422 and processes none; more than 100 batches in an hour, counted with the caregiver web app's, is 429.", "operationId": "postMeClockEvents", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeClockEventsInput" } } }, "description": "The events", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "failed": { "description": "Events not recorded, each with why; keep them and retry those that can succeed.", "items": { "properties": { "error": { "description": "visit_not_found (not one of your visits within reach), unknown_action, invalid_event (an id that is not a string; answered with a null id), clock_in_required, visit_not_clockable (the visit was closed and the server could not keep the clock: retry), sync_failed (retry), clock_in_failed or clock_out_failed.", "type": "string" }, "id": { "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "synced": { "description": "Ids of events recorded, already recorded, or kept for the office because the visit was closed: drop them.", "items": { "type": "string" }, "type": "array" } }, "required": [ "synced", "failed" ], "title": "MeClockEventsResult", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "What synced and what failed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too Many Requests, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Send clocks recorded offline", "tags": [ "Caregiver app" ] } }, "/api/v1/me/devices": { "get": { "callbacks": {}, "description": "The devices the caregiver is signed in on, most recently used first; current marks the one asking.", "operationId": "getMeDevices", "parameters": [ { "description": "Rows per page (default 20, at most 100; a larger value is served as 100).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/MeDevice" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "MeDevicePage", "type": "object" } } }, "description": "A page of devices" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "My signed-in devices", "tags": [ "Caregiver app" ] } }, "/api/v1/me/devices/{id}": { "delete": { "callbacks": {}, "description": "Signs one of the caregiver's devices out, this one included, and stops its push notifications. Another caregiver's device, or one already signed out, is 404.", "operationId": "deleteMeDevicesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Signed out" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Sign a device out", "tags": [ "Caregiver app" ] } }, "/api/v1/me/half-month-summaries": { "post": { "callbacks": {}, "description": "As the half-month screen: the live summary of the client, you, the service and the half, or a new draft of it, re-read from the evidence grid, with the signing date, the lines signed, and the representatives who may sign the client's line in their place. Repeating it answers the same summary. A period_start that is not the 1st or the 16th is 422 validation_failed; so is a service_type left out on a half with care for more than one service, and one left out on a half with no care recorded and no summary yet (nothing to sign). The read is recorded on the PHI access log. A client you have neither an assignment with nor a care log for in the half, another caregiver's summary, or another agency's is 404, whatever the body holds.", "operationId": "postMeHalfMonthSummaries", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "period_start": { "description": "The half's first day, YYYY-MM-DD: the 1st or the 16th.", "format": "date", "nullable": false, "type": "string" }, "service_type": { "description": "The service the summary attests: the client signs one per service. Left out, the half's only service; a half with care for two services, or with none recorded and no summary yet, is 422 validation_failed.", "enum": [ "personal_care", "homemaker", "legacy" ], "nullable": true, "type": "string" } }, "required": [ "client_id", "period_start" ], "title": "MeHalfMonthSummaryDraft", "type": "object" } } }, "description": "The half", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeHalfMonthSummary" } }, "required": [ "data" ], "type": "object" } } }, "description": "The summary" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Open my half-month summary", "tags": [ "Caregiver app" ] } }, "/api/v1/me/half-month-summaries/{id}/client-skip": { "post": { "callbacks": {}, "description": "As the half-month screen's \"Client can't sign\": records why the client could not sign, and your signed line then completes the half and stores its true copy. The same reason again answers the summary unchanged. Refusals: 409 caregiver_not_signed (your line is not signed yet), 409 record_locked (the client's or a representative's line is signed, or the half is already complete), 409 voided, 422 validation_failed (a reason that is not one of the list). A client you have neither an assignment with nor a care log for in the half, another caregiver's summary, or another agency's is 404, whatever the body holds.", "operationId": "postMeHalfMonthSummariesByIdClientSkip", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Why the client could not sign.", "enum": [ "client_asleep_or_unwell", "client_not_present", "client_declined_to_sign", "client_unable_to_sign", "other" ], "type": "string" } }, "required": [ "reason" ], "title": "MeHalfMonthSummaryClientSkip", "type": "object" } } }, "description": "Why", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/HalfMonthSummary" } }, "required": [ "data" ], "type": "object" } } }, "description": "The summary" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes caregiver_not_signed, record_locked: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "The client can't sign my half-month summary", "tags": [ "Caregiver app" ] } }, "/api/v1/me/half-month-summaries/{id}/signatures": { "post": { "callbacks": {}, "description": "As the half-month screen's pads: signs a line on your phone (channel app). Your line first; then the client's, or a representative's in their place: one the summary lists (signer_relation_id), or someone else by name (signer_name). The first signature freezes the half. The same signature again answers the summary unchanged. Refusals: 422 signature_period_not_reached (before the 15th for a first half, the 20th for a second), 409 content_changed (the half changed since it was read), 409 role_already_signed (a different signature holds the line), 409 record_locked (every line is signed), 409 voided, 422 invalid_image, 422 validation_failed (a signer_relation_id that is not one of the client's representatives). A client you have neither an assignment with nor a care log for in the half, another caregiver's summary, or another agency's is 404, whatever the body holds.", "operationId": "postMeHalfMonthSummariesByIdSignatures", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "capture_method": { "description": "drawn (the default) or initials.", "enum": [ "drawn", "initials" ], "type": "string" }, "expected_content_hash": { "description": "The signing.hash of the half the signer read; a half changed since is refused with 409 content_changed.", "nullable": true, "type": "string" }, "image": { "description": "The signature as a base64 PNG, at most 51200 bytes.", "nullable": true, "type": "string" }, "role": { "description": "The line signed: yours first, then the client's or their representative's.", "enum": [ "caregiver", "client", "representative" ], "type": "string" }, "signer_name": { "description": "A representative's line signed by someone the office did not record: their name, signed with no relationship. With neither this nor signer_relation_id, the first listed representative signs, else \"Representative\".", "nullable": true, "type": "string", "x-untrusted": "text" }, "signer_relation_id": { "description": "A representative's line: the relation_id of one of the representatives the summary lists, whose name and relationship it is signed under (signer_name is then ignored). One the list does not hold is 422 validation_failed.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "role", "image" ], "title": "MeHalfMonthSummarySignature", "type": "object" } } }, "description": "The signature", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/HalfMonthSummary" } }, "required": [ "data" ], "type": "object" } } }, "description": "The summary" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes content_changed, record_locked, role_already_signed: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes invalid_image, signature_period_not_reached, validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Sign my half-month summary", "tags": [ "Caregiver app" ] } }, "/api/v1/me/notifications": { "get": { "callbacks": {}, "description": "The caregiver's notifications, newest first, without dismissed ones unless dismissed=true.", "operationId": "getMeNotifications", "parameters": [ { "description": "Rows per page (default 20, at most 100; a larger value is served as 100).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only notifications of this type.", "in": "query", "name": "type", "schema": { "enum": [ "schedule_change", "admin_message", "exception_alert", "assignment_update", "visit_reminder" ], "type": "string" } }, { "description": "true to include dismissed notifications.", "in": "query", "name": "dismissed", "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/MeNotification" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "MeNotificationPage", "type": "object" } } }, "description": "A page of notifications" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "My notifications", "tags": [ "Caregiver app" ] } }, "/api/v1/me/notifications/read-all": { "post": { "callbacks": {}, "operationId": "postMeNotificationsReadAll", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "marked": { "minimum": 0, "type": "integer" } }, "required": [ "marked" ], "title": "MeNotificationsMarked", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "How many were marked" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Mark every notification read", "tags": [ "Caregiver app" ] } }, "/api/v1/me/notifications/{id}/dismiss": { "post": { "callbacks": {}, "description": "Dismisses it, which also marks it read.", "operationId": "postMeNotificationsByIdDismiss", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeNotification" } }, "required": [ "data" ], "type": "object" } } }, "description": "The notification" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Dismiss a notification", "tags": [ "Caregiver app" ] } }, "/api/v1/me/notifications/{id}/read": { "post": { "callbacks": {}, "operationId": "postMeNotificationsByIdRead", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeNotification" } }, "required": [ "data" ], "type": "object" } } }, "description": "The notification" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Mark a notification read", "tags": [ "Caregiver app" ] } }, "/api/v1/me/pin": { "patch": { "callbacks": {}, "description": "Changes the caregiver's PIN. A wrong current_pin answers 422 invalid_current_pin and counts as one failed sign-in; repeated failures answer 429 rate_limited with a Retry-After header. A new PIN that is not six digits, or is repeated or sequential, answers 422 validation_failed naming new_pin and counts nothing. On success this device stays signed in, and every other device and web app session of the caregiver is signed out.", "operationId": "patchMePin", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MePinChange" } } }, "description": "The PINs", "required": true }, "responses": { "204": { "description": "Changed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes invalid_current_pin, validation_failed: Unprocessable Content, as the operation's description says." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code rate_limited: Too Many Requests, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Change my PIN", "tags": [ "Caregiver app" ] } }, "/api/v1/me/push-tokens": { "post": { "callbacks": {}, "description": "Registers this device's push token: an APNs device token (platform ios) or an FCM registration token (platform android). 201 the first time, 200 when this device registers again (the same token, or a new one replacing it). The same token registered from an earlier sign-in stops there.", "operationId": "postMePushTokens", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "platform": { "enum": [ "ios", "android" ], "type": "string" }, "token": { "maxLength": 4096, "minLength": 8, "type": "string" } }, "required": [ "platform", "token" ], "title": "MePushTokenInput", "type": "object" } } }, "description": "The token", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "platform": { "enum": [ "ios", "android" ], "type": "string" }, "registered_at": { "description": "When this device's token was last registered.", "format": "date-time", "type": "string" } }, "required": [ "platform", "registered_at" ], "title": "MePushToken", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Registered again" }, "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "platform": { "enum": [ "ios", "android" ], "type": "string" }, "registered_at": { "description": "When this device's token was last registered.", "format": "date-time", "type": "string" } }, "required": [ "platform", "registered_at" ], "title": "MePushToken", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Registered" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Register this device for push", "tags": [ "Caregiver app" ] } }, "/api/v1/me/push-tokens/current": { "delete": { "callbacks": {}, "description": "Stops native push to this device; signing out does the same.", "operationId": "deleteMePushTokensCurrent", "parameters": [], "responses": { "204": { "description": "Stopped" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Stop push to this device", "tags": [ "Caregiver app" ] } }, "/api/v1/me/refused-clocks": { "get": { "callbacks": {}, "description": "Your clocks the server kept in the last 30 days that a cancelled, completed or verified visit refused, which the server kept and passed to the office (US-98.14): the clock-in or clock-out answered 422 visit_not_clockable. Newest first; reviewed_at is set once the office has handled it. On visits not deleted.", "operationId": "getMeRefusedClocks", "parameters": [ { "description": "Rows per page (default 20, at most 100; a larger value is served as 100).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/MeRefusedClock" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "MeRefusedClockPage", "type": "object" } } }, "description": "A page of refused clocks" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code visit_not_clockable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "My refused clocks", "tags": [ "Caregiver app" ] } }, "/api/v1/me/reminder-preferences": { "get": { "callbacks": {}, "description": "The caller's own preferences, as /settings/reminders shows them. Any member, for themselves.", "operationId": "getMeReminderPreferences", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "birthday_lead_days": { "description": "Days of notice before a birthday, 0 to 30.", "type": "integer" }, "default_reminder_time": { "description": "The time of day reminders are due, as HH:MM:SS in the agency's timezone.", "type": "string" }, "email_digest_enabled": { "description": "Whether reminders are emailed as a digest.", "type": "boolean" }, "paused_until": { "description": "Reminder email paused until then, an ISO 8601 time in the future; null resumes it.", "format": "date-time", "nullable": true, "type": "string" }, "recert_lead_days": { "description": "Days of notice before a recert, 0 to 180.", "type": "integer" }, "supervisor_visit_cadence_mode": { "description": "How the next supervisory visit is counted.", "enum": [ "exact_days", "calendar_months", "approx_days_same_dow" ], "type": "string" }, "supervisor_visit_cadence_value": { "description": "Days or months between supervisory visits, 0 to 365.", "type": "integer" } }, "required": [ "birthday_lead_days", "default_reminder_time", "email_digest_enabled", "paused_until", "recert_lead_days", "supervisor_visit_cadence_mode", "supervisor_visit_cadence_value" ], "title": "ReminderPreferences", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The preferences" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read your reminder preferences", "tags": [ "Agency settings" ] }, "put": { "callbacks": {}, "description": "As /settings/reminders does, for the caller alone; send only what changes. Any member, for themselves.", "operationId": "putMeReminderPreferences", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "birthday_lead_days": { "description": "Days of notice before a birthday, 0 to 30.", "type": "integer" }, "default_reminder_time": { "description": "The time of day reminders are due, as HH:MM:SS in the agency's timezone.", "type": "string" }, "email_digest_enabled": { "description": "Whether reminders are emailed as a digest.", "type": "boolean" }, "paused_until": { "description": "Reminder email paused until then, an ISO 8601 time in the future; null resumes it.", "format": "date-time", "nullable": true, "type": "string" }, "recert_lead_days": { "description": "Days of notice before a recert, 0 to 180.", "type": "integer" }, "supervisor_visit_cadence_mode": { "description": "How the next supervisory visit is counted.", "enum": [ "exact_days", "calendar_months", "approx_days_same_dow" ], "type": "string" }, "supervisor_visit_cadence_value": { "description": "Days or months between supervisory visits, 0 to 365.", "type": "integer" } }, "title": "ReminderPreferencesUpdate", "type": "object" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "birthday_lead_days": { "description": "Days of notice before a birthday, 0 to 30.", "type": "integer" }, "default_reminder_time": { "description": "The time of day reminders are due, as HH:MM:SS in the agency's timezone.", "type": "string" }, "email_digest_enabled": { "description": "Whether reminders are emailed as a digest.", "type": "boolean" }, "paused_until": { "description": "Reminder email paused until then, an ISO 8601 time in the future; null resumes it.", "format": "date-time", "nullable": true, "type": "string" }, "recert_lead_days": { "description": "Days of notice before a recert, 0 to 180.", "type": "integer" }, "supervisor_visit_cadence_mode": { "description": "How the next supervisory visit is counted.", "enum": [ "exact_days", "calendar_months", "approx_days_same_dow" ], "type": "string" }, "supervisor_visit_cadence_value": { "description": "Days or months between supervisory visits, 0 to 365.", "type": "integer" } }, "required": [ "birthday_lead_days", "default_reminder_time", "email_digest_enabled", "paused_until", "recert_lead_days", "supervisor_visit_cadence_mode", "supervisor_visit_cadence_value" ], "title": "ReminderPreferences", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The preferences" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Save your reminder preferences", "tags": [ "Agency settings" ] } }, "/api/v1/me/visits": { "get": { "callbacks": {}, "description": "The signed-in caregiver's visits with a service date from date_from to date_to (date_from defaults to date_to, else today in Colorado; date_to defaults to date_from), not cancelled, in date order, then scheduled start. At most 31 days at once, starting no more than 90 days before today.", "operationId": "getMeVisits", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "First service date (YYYY-MM-DD).", "in": "query", "name": "date_from", "schema": { "format": "date", "type": "string" } }, { "description": "Last service date (YYYY-MM-DD).", "in": "query", "name": "date_to", "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/MeVisit" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "MeVisitPage", "type": "object" } } }, "description": "A page of visits" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "My visits", "tags": [ "Caregiver app" ] } }, "/api/v1/me/visits/{id}": { "get": { "callbacks": {}, "description": "A visit of the signed-in caregiver, with the client's address and geofence and its clock-in and clock-out once recorded. A cancelled or deleted visit is still returned, with its status and deleted_at, so an app holding its id learns what became of it. Another caregiver's visit, or one more than 90 days back, is 404.", "operationId": "getMeVisitsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeVisitDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The visit" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "One of my visits", "tags": [ "Caregiver app" ] } }, "/api/v1/me/visits/{id}/clock-in": { "post": { "callbacks": {}, "description": "Records the clock-in with the device's location. Whatever the device sends is recorded, with warnings, never refused: no_gps, low_accuracy, moderate_accuracy, suspicious_accuracy, outside_geofence, invalid_coordinates, unknown_accuracy, invalid_captured_at, captured_at_out_of_range, late_sync, manual, outside_schedule, before_clock_in. A captured_at that is not Unix milliseconds, ahead of now, or before the visit existed is recorded at the server's time. A second clock-in answers 200 with the first. A visit not scheduled or in progress takes no clock: 422 visit_not_clockable, nothing recorded on the visit; the clock is kept for the office (US-98.14), and the message says so; when it could not be kept the code is visit_not_clockable_not_kept, so keep the clock and retry.", "operationId": "postMeVisitsByIdClockIn", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeClockInput" } } }, "description": "Where and when", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeClockResult" } }, "required": [ "data" ], "type": "object" } } }, "description": "Already recorded: the existing call, nothing created" }, "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeClockResult" } }, "required": [ "data" ], "type": "object" } } }, "description": "Recorded" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code visit_not_clockable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Clock in", "tags": [ "Caregiver app" ] } }, "/api/v1/me/visits/{id}/clock-out": { "post": { "callbacks": {}, "description": "Records the clock-out, as clock-in does, and sets the visit's actual_end_time. A visit not clocked in is 422 clock_in_required; one timed at or before the clock-in is recorded with before_clock_in and bills no hours. A closed visit answers as clock-in does: 422 visit_not_clockable with the clock kept for the office, or visit_not_clockable_not_kept, so keep the clock and retry.", "operationId": "postMeVisitsByIdClockOut", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeClockInput" } } }, "description": "Where and when", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeClockResult" } }, "required": [ "data" ], "type": "object" } } }, "description": "Already recorded: the existing call, nothing created" }, "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeClockResult" } }, "required": [ "data" ], "type": "object" } } }, "description": "Recorded" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes clock_in_required, visit_not_clockable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Clock out", "tags": [ "Caregiver app" ] } }, "/api/v1/me/visits/{id}/signatures": { "post": { "callbacks": {}, "description": "Keeps the client's or your signature (or initials) on one of your visits, as a PNG; a client signature marks the visit client-signed. A visit holds one signature per signer: sending one it already holds, without replace, answers 200 with it whatever the visit's status since, so a retry is safe. A first signature is kept on any visit not cancelled, a late offline sync included; replace: true replaces the held one only while the visit is scheduled, in progress or completed (else 422 visit_not_signable), answering 200, and a replacement identical to the one held answers it unchanged. A cancelled visit takes no first signature (422 visit_not_signable). captured_at is believed as a clock's is (not ahead of now, not before the visit existed, else the server's time). The input is judged first: an image that is not base64, not a PNG, or larger than 51200 bytes is 422 invalid_image, a signer_name over 255 characters 422 invalid_signer_name, a replace that is not a boolean 422 invalid_replace. Another caregiver's visit, a deleted one, or one more than 90 days back is 404.", "operationId": "postMeVisitsByIdSignatures", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "captured_at": { "description": "When it was signed, in Unix milliseconds; omit for now.", "nullable": true, "type": "number" }, "image": { "description": "The signature as a base64 PNG of at most 51200 bytes once decoded.", "format": "byte", "type": "string" }, "replace": { "description": "true replaces the visit's signature from this signer; otherwise a second one answers 200 with the one it holds.", "type": "boolean" }, "signature_type": { "enum": [ "drawn", "initials" ], "type": "string" }, "signer_name": { "description": "The signer's name.", "type": "string" }, "signer_type": { "enum": [ "client", "caregiver" ], "type": "string" } }, "required": [ "signer_type", "signature_type", "signer_name", "image" ], "title": "MeSignatureInput", "type": "object" } } }, "description": "The signature", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeSignature" } }, "required": [ "data" ], "type": "object" } } }, "description": "The signature the visit holds, or the one replaced" }, "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeSignature" } }, "required": [ "data" ], "type": "object" } } }, "description": "The new signature" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes invalid_image, invalid_replace, invalid_signer_name, visit_not_signable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "Capture a signature on my visit", "tags": [ "Caregiver app" ] } }, "/api/v1/me/visits/{id}/signatures/{signature_id}/image": { "get": { "callbacks": {}, "description": "The PNG of a signature on one of your visits, never cached. Any other visit or signature is 404.", "operationId": "getMeVisitsByIdSignaturesBySignatureIdImage", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The signature's id.", "in": "path", "name": "signature_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "image/png": { "schema": { "format": "binary", "type": "string" } } }, "description": "The PNG" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [ { "caregiverBearer": [] } ], "summary": "A signature's image", "tags": [ "Caregiver app" ] } }, "/api/v1/meeting-minutes": { "get": { "callbacks": {}, "description": "Minutes are a draft until finalized (POST .../finalize); finalized minutes answer 422 not_draft to a change. A search matches the location, who called the meeting, the notes and old business. The agency's meeting minutes in meeting date order, newest first. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getMeetingMinutes", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records with this status.", "in": "query", "name": "status", "schema": { "enum": [ "draft", "finalized" ], "type": "string" } }, { "description": "Every word must match a returned name or identifier, case-insensitively. At most 100 characters and 8 words.", "in": "query", "name": "search", "schema": { "maxLength": 100, "type": "string" } }, { "description": "Only meetings of this kind.", "in": "query", "name": "meeting_type", "schema": { "enum": [ "staff_meeting", "training", "in_service", "supervisory", "other" ], "type": "string" } }, { "description": "Meetings held on or between these days. on or after this date (YYYY-MM-DD, Colorado).", "in": "query", "name": "meeting_date_from", "schema": { "format": "date", "type": "string" } }, { "description": "Meetings held on or between these days. on or before this date (YYYY-MM-DD, Colorado).", "in": "query", "name": "meeting_date_to", "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/MeetingMinutes" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Meeting minutesPage", "type": "object" } } }, "description": "A page of meeting minutes" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_draft: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List meeting minutes", "tags": [ "Meeting minutes" ] }, "post": { "callbacks": {}, "operationId": "postMeetingMinutes", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingMinutesInput" } } }, "description": "The meeting minutes's fields", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeetingMinutes" } }, "required": [ "data" ], "type": "object" } } }, "description": "The created meeting minutes" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a meeting minutes", "tags": [ "Meeting minutes" ] } }, "/api/v1/meeting-minutes/{id}": { "delete": { "callbacks": {}, "description": "As the minutes page's Delete does, a draft or finalized: they leave every list and read, and the deletion is kept on the audit trail.", "operationId": "deleteMeetingMinutesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeetingMinutes" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted minutes" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete meeting minutes", "tags": [ "Meeting minutes" ] }, "get": { "callbacks": {}, "description": "Minutes are a draft until finalized (POST .../finalize); finalized minutes answer 422 not_draft to a change. A search matches the location, who called the meeting, the notes and old business.", "operationId": "getMeetingMinutesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeetingMinutes" } }, "required": [ "data" ], "type": "object" } } }, "description": "The meeting minutes" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no meeting minutes with that id in this agency, including another agency's." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_draft: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a meeting minutes", "tags": [ "Meeting minutes" ] }, "patch": { "callbacks": {}, "description": "Sets only the fields sent. lock_version is required: send the value you read, and a record changed since answers 409 stale_record.", "operationId": "patchMeetingMinutesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingMinutesInput" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeetingMinutes" } }, "required": [ "data" ], "type": "object" } } }, "description": "The updated meeting minutes" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no meeting minutes with that id in this agency, including another agency's." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: the meeting minutes changed since the lock_version sent was read, or while this request ran. Nothing was saved; read it again and retry." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a meeting minutes", "tags": [ "Meeting minutes" ] } }, "/api/v1/meeting-minutes/{id}/finalize": { "post": { "callbacks": {}, "description": "As the minutes page's Finalize does; finalized minutes are never changed again. Minutes already finalized answer 422 not_draft; minutes another request changed while this one ran answer 409 stale_record.", "operationId": "postMeetingMinutesByIdFinalize", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MeetingMinutes" } }, "required": [ "data" ], "type": "object" } } }, "description": "The minutes" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_draft: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Finalize meeting minutes", "tags": [ "Meeting minutes" ] } }, "/api/v1/monthly-client-reports": { "get": { "callbacks": {}, "description": "A client's monthly reports, newest first, each with its questions and answers. client_id is required; a client of another agency is 404.", "operationId": "getMonthlyClientReports", "parameters": [ { "description": "The client.", "in": "query", "name": "client_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/MonthlyClientReport" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "MonthlyClientReportPage", "type": "object" } } }, "description": "A page of reports" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a client's monthly reports", "tags": [ "Monthly client reports" ] } }, "/api/v1/note-attachments/{id}": { "delete": { "callbacks": {}, "description": "Removes it as the note page's Delete does, for a member holding Clients → Manage (a client note) or Caregivers → Manage (a caregiver note); for anyone else it is 403 or 404, as on the web. The audit trail keeps it.", "operationId": "deleteNoteAttachmentsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "content_type": { "description": "Its type.", "nullable": true, "type": "string" }, "file_size": { "description": "Its size in bytes.", "nullable": true, "type": "integer" }, "filename": { "description": "The file's name.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was attached.", "format": "date-time", "type": "string" }, "note_id": { "description": "The note.", "format": "uuid", "type": "string" }, "note_kind": { "description": "The kind of note it is on.", "enum": [ "client", "caregiver" ], "type": "string" }, "scan_status": { "description": "The virus scan's verdict; only a clean file can be downloaded.", "enum": [ "pending", "clean", "infected", "error" ], "type": "string" }, "uploaded_by_id": { "description": "Who attached it.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "id", "note_kind", "note_id", "filename", "content_type", "file_size", "scan_status" ], "title": "NoteAttachment", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted attachment" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a note attachment", "tags": [ "Communication notes" ] }, "get": { "callbacks": {}, "description": "The file itself, as the note page's Download serves it, and recorded as a download. A file whose virus scan is not clean is 404, as on the web.", "operationId": "getNoteAttachmentsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "The file" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code file_missing: the record exists and its file does not. Nothing changed." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code internal_error: a failure on our side, which was logged. When its message says nothing changed (the file store refused the request, the virus scan could not be queued, the upload could not be read), nothing did, the same request fails the same way until it is fixed, and the Idempotency-Key stays free." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code storage_unavailable (the file store did not answer) or, on an upload, temporarily_unavailable (its uploaded file could not be read): nothing changed, and the same request can succeed later. Retry after the Retry-After seconds; a write retried with the same Idempotency-Key runs again.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (30).", "schema": { "type": "integer" }, "style": "simple" } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Download a note attachment", "tags": [ "Communication notes" ] } }, "/api/v1/notifications": { "get": { "callbacks": {}, "description": "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.", "operationId": "getNotifications", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "unread or read; omitted lists both.", "in": "query", "name": "read", "schema": { "description": "Read status.", "enum": [ "read", "unread" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "body": { "description": "Its text.", "nullable": true, "type": "string" }, "created_at": { "description": "When it was raised (UTC).", "format": "date-time", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "priority": { "description": "How urgent it is.", "enum": [ "low", "normal", "high", "urgent" ], "type": "string" }, "read_at": { "description": "When it was read (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "resolved_at": { "description": "When it was resolved (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "source_id": { "description": "The record it is about.", "format": "uuid", "nullable": true, "type": "string" }, "source_type": { "description": "The kind of record it is about.", "nullable": true, "type": "string" }, "title": { "description": "Its headline.", "nullable": true, "type": "string" }, "type": { "description": "The kind of notification.", "nullable": true, "type": "string" } }, "required": [ "id", "type", "title" ], "title": "Notification", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "NotificationPage", "type": "object" } } }, "description": "A page of notifications" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List your notifications", "tags": [ "Broadcasts and notifications" ] } }, "/api/v1/notifications/read-all": { "post": { "callbacks": {}, "description": "As the bell's Mark all read does. Answers how many were marked.", "operationId": "postNotificationsReadAll", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "marked": { "description": "Notifications marked read.", "type": "integer" } }, "required": [ "marked" ], "title": "NotificationsMarked", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "How many were marked" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Mark all your notifications read", "tags": [ "Broadcasts and notifications" ] } }, "/api/v1/notifications/{id}/read": { "post": { "callbacks": {}, "description": "As opening it from the bell does. Another member's notification, or another agency's, answers 404.", "operationId": "postNotificationsByIdRead", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "body": { "description": "Its text.", "nullable": true, "type": "string" }, "created_at": { "description": "When it was raised (UTC).", "format": "date-time", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "priority": { "description": "How urgent it is.", "enum": [ "low", "normal", "high", "urgent" ], "type": "string" }, "read_at": { "description": "When it was read (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "resolved_at": { "description": "When it was resolved (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "source_id": { "description": "The record it is about.", "format": "uuid", "nullable": true, "type": "string" }, "source_type": { "description": "The kind of record it is about.", "nullable": true, "type": "string" }, "title": { "description": "Its headline.", "nullable": true, "type": "string" }, "type": { "description": "The kind of notification.", "nullable": true, "type": "string" } }, "required": [ "id", "type", "title" ], "title": "Notification", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The notification" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Mark a notification read", "tags": [ "Broadcasts and notifications" ] } }, "/api/v1/notifications/{id}/resolve": { "post": { "callbacks": {}, "description": "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.", "operationId": "postNotificationsByIdResolve", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "notes": { "description": "Why it is resolved. Leave it out for none.", "type": "string" } }, "title": "NotificationResolve", "type": "object" } } }, "description": "Notes", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "body": { "description": "Its text.", "nullable": true, "type": "string" }, "created_at": { "description": "When it was raised (UTC).", "format": "date-time", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "priority": { "description": "How urgent it is.", "enum": [ "low", "normal", "high", "urgent" ], "type": "string" }, "read_at": { "description": "When it was read (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "resolved_at": { "description": "When it was resolved (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "source_id": { "description": "The record it is about.", "format": "uuid", "nullable": true, "type": "string" }, "source_type": { "description": "The kind of record it is about.", "nullable": true, "type": "string" }, "title": { "description": "Its headline.", "nullable": true, "type": "string" }, "type": { "description": "The kind of notification.", "nullable": true, "type": "string" } }, "required": [ "id", "type", "title" ], "title": "Notification", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The notification" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Resolve a notification", "tags": [ "Broadcasts and notifications" ] } }, "/api/v1/oig-attestations": { "get": { "callbacks": {}, "description": "A screen the agency ran outside the app, attested monthly. company_document_id names a company document the agency already holds; another agency's or a deleted one answers 422 company_document_not_found and nothing is recorded. The agency's OIG attestations in review month order, newest first. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getOigAttestations", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/OigAttestation" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "OIG attestationPage", "type": "object" } } }, "description": "A page of OIG attestations" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code company_document_not_found: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List OIG attestations", "tags": [ "OIG attestations" ] }, "post": { "callbacks": {}, "operationId": "postOigAttestations", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OigAttestationInput" } } }, "description": "The OIG attestation's fields", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/OigAttestation" } }, "required": [ "data" ], "type": "object" } } }, "description": "The created OIG attestation" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a OIG attestation", "tags": [ "OIG attestations" ] } }, "/api/v1/oig-attestations/{id}": { "get": { "callbacks": {}, "description": "A screen the agency ran outside the app, attested monthly. company_document_id names a company document the agency already holds; another agency's or a deleted one answers 422 company_document_not_found and nothing is recorded.", "operationId": "getOigAttestationsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/OigAttestation" } }, "required": [ "data" ], "type": "object" } } }, "description": "The OIG attestation" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no OIG attestation with that id in this agency, including another agency's." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code company_document_not_found: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a OIG attestation", "tags": [ "OIG attestations" ] } }, "/api/v1/oig-checks/bulk": { "post": { "callbacks": {}, "description": "As the compliance dashboard's monthly sweep does: one clear attestation dated checked_on for each active caregiver. Clear only, as on the dashboard: an exclusion match is recorded on that caregiver. Needs caregivers.manage (403 forbidden otherwise). A date in the future, or more than a year old, is 422.", "operationId": "postOigChecksBulk", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "checked_on": { "description": "The day the LEIE was checked, YYYY-MM-DD.", "format": "date", "type": "string" } }, "required": [ "checked_on" ], "title": "OigExclusionBulk", "type": "object" } } }, "description": "The sweep", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "caregivers": { "description": "Active caregivers it covered.", "nullable": true, "type": "integer" }, "records": { "description": "Records written.", "nullable": true, "type": "integer" }, "replaced": { "description": "Existing dates it updated.", "nullable": true, "type": "integer" }, "skipped": { "description": "Records left as they were.", "nullable": true, "type": "integer" } }, "required": [ "caregivers", "records" ], "title": "CaregiverBulkResult", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "What was recorded" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Record a clear OIG check for every active caregiver", "tags": [ "Caregiver records" ] } }, "/api/v1/oig-screening-status": { "get": { "callbacks": {}, "description": "Each caregiver, whether the monthly screen covers them, and their latest exclusion check, as oig_screening_status returns them.", "operationId": "getOigScreeningStatus", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/OigCheck" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "OigCheckPage", "type": "object" } } }, "description": "A page of caregivers" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List each caregiver's latest OIG check", "tags": [ "Compliance" ] } }, "/api/v1/oig-screens": { "get": { "callbacks": {}, "description": "Monthly screens, newest first, with each one's still-open review count, as list_oig_screens returns them; include_single=true adds new-hire and single-caregiver screens.", "operationId": "getOigScreens", "parameters": [ { "description": "Include new-hire and single-caregiver screens. Default false.", "in": "query", "name": "include_single", "required": false, "schema": { "type": "boolean" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/OigScreen" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "OigScreenPage", "type": "object" } } }, "description": "A page of screens" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List the agency's OIG exclusion screens", "tags": [ "Compliance" ] }, "post": { "callbacks": {}, "description": "Queues a screen of the agency's roster, as the OIG Screening Log's button and run_oig_screen do: 202 with status queued, or already_queued when a screen is already waiting, running or retrying. The screen's row exists once the worker starts. A demo agency, or the Sandata certification tenant, is 422 demo_agency and nothing is queued.", "operationId": "postOigScreens", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/OigScreenQueued" } }, "required": [ "data" ], "type": "object" } } }, "description": "Queued" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code demo_agency: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Queue a roster OIG screen", "tags": [ "Compliance" ] } }, "/api/v1/open-shifts": { "get": { "callbacks": {}, "description": "The open shifts the caller may see, soonest first, undated last, as the open shifts screen lists them. filter: active (open or assigned, the default), assigned, completed, cancelled, all, with_responses (at least one live response) or no_responses (none); client_id narrows to one client. A caseload member sees their clients' shifts only. Needs open_shifts.view.", "operationId": "getOpenShifts", "parameters": [ { "description": "Which shifts; active by default.", "in": "query", "name": "filter", "required": false, "schema": { "enum": [ "active", "assigned", "completed", "cancelled", "all", "with_responses", "no_responses" ], "type": "string" } }, { "description": "Only this client's shifts.", "in": "query", "name": "client_id", "required": false, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 25, at most 100; a larger value is served as 100).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "care_type": { "enum": [ "personal", "homemaking", "both" ], "type": "string" }, "client": { "description": "The client, by name only: never the address or point.", "properties": { "first_name": { "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "type": "string" } }, "type": "object" }, "client_gender": { "enum": [ "female", "male", "unspecified" ], "type": "string" }, "cross_streets": { "type": "string" }, "date_mode": { "enum": [ "exact", "this_week", "next_week", "within_2_weeks", "tbd" ], "type": "string" }, "end_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "hours": { "description": "A one-time shift's hours.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was posted.", "format": "date-time", "type": "string" }, "kind": { "enum": [ "one_time", "ongoing" ], "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "note": { "nullable": true, "type": "string" }, "ongoing_times": { "description": "An ongoing shift's Shift Plan times on starts_on, and the ISO weekdays (1 Monday .. 7 Sunday) its slot runs on; null for a one-time shift.", "nullable": true, "properties": { "end": { "description": "HH:MM.", "nullable": true, "type": "string" }, "ends_next_day": { "description": "The end is past midnight.", "type": "boolean" }, "hours": { "description": "The hours that day.", "format": "decimal", "nullable": true, "type": "string" }, "run_days": { "items": { "type": "integer" }, "type": "array" }, "start": { "description": "HH:MM.", "nullable": true, "type": "string" } }, "type": "object" }, "rate_cents": { "description": "The hourly rate, in cents.", "nullable": true, "type": "integer" }, "service_area": { "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "shift_id": { "description": "An ongoing shift's slot.", "nullable": true, "type": "string" }, "start_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "starts_on": { "description": "The date for exact; the window's last day for this_week, next_week and within_2_weeks; null for tbd.", "format": "date", "nullable": true, "type": "string" }, "status": { "enum": [ "open", "assigned", "completed", "cancelled" ], "type": "string" }, "time_mode": { "enum": [ "exact", "am", "midday", "pm", "flexible" ], "nullable": true, "type": "string" }, "zip": { "nullable": true, "type": "string" } }, "title": "OpenShift", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "OpenShiftPage", "type": "object" } } }, "description": "A page of open shifts" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List the agency's open shifts", "tags": [ "Open shifts" ] }, "post": { "callbacks": {}, "description": "As the Post open shift screen's Publish does. An ongoing shift fills a Shift Plan slot and takes its days and times from the plan: a client with no Shift Plan holding the slot answers 422 no_shift_plan (details.shift_plan_path), an exact date the slot does not run on 422 not_a_run_day, and a slot already posted 409 slot_already_posted (details.open_shift_id). A note that looks like client information answers 422 client_info_found with details.finding; send it again with acknowledged: [details.finding.fingerprint] to post it anyway. An agency with open shifts off answers 409 open_shifts_off. A start sooner than the agency's post lead hours posts it with a warning. Another agency's client answers 404. Needs open_shifts.manage.", "operationId": "postOpenShifts", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "acknowledged": { "description": "The fingerprints of client_info_found refusals the sender confirmed are not client information.", "items": { "type": "string" }, "type": "array" }, "care_type": { "description": "The care the shift gives.", "enum": [ "personal", "homemaking", "both" ], "type": "string" }, "client_gender": { "description": "The client's gender, shown to responders.", "enum": [ "female", "male", "unspecified" ], "type": "string" }, "client_id": { "description": "The client the shift is for.", "format": "uuid", "type": "string" }, "cross_streets": { "description": "Two nearby major streets, as 'S Chambers Rd & E Hampden Ave'; never a house number.", "maxLength": 200, "type": "string", "x-untrusted": "text" }, "date_mode": { "description": "exact needs starts_on; this_week, next_week and within_2_weeks are windows; tbd has no date yet.", "enum": [ "exact", "this_week", "next_week", "within_2_weeks", "tbd" ], "type": "string" }, "end_time": { "description": "HH:MM, one-time exact only; earlier than start_time for an overnight shift.", "format": "time", "nullable": true, "type": "string" }, "hours": { "description": "One-time only, when time_mode is not exact: 0.5 to 24, in halves.", "format": "decimal", "nullable": true, "type": "string" }, "kind": { "description": "one_time for a single shift; ongoing to fill a Shift Plan slot, whose days and times are the Shift Plan's.", "enum": [ "one_time", "ongoing" ], "type": "string" }, "note": { "description": "Up to 500 characters for responders. Checked for client information: a match is refused unless acknowledged names its fingerprint.", "maxLength": 500, "nullable": true, "type": "string", "x-untrusted": "text" }, "rate_cents": { "description": "The hourly rate shown to responders, in cents.", "maximum": 99999, "minimum": 1, "type": "integer" }, "service_area_id": { "description": "The agency area the shift is shown at.", "format": "uuid", "type": "string" }, "shift_id": { "description": "Ongoing only: the Shift Plan slot the shift fills.", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "nullable": true, "type": "string" }, "start_time": { "description": "HH:MM, one-time exact only.", "format": "time", "nullable": true, "type": "string" }, "starts_on": { "description": "The date, for date_mode exact; ignored for a window.", "format": "date", "nullable": true, "type": "string" }, "time_mode": { "description": "One-time only: exact needs start_time and end_time; am, midday, pm and flexible need hours.", "enum": [ "exact", "am", "midday", "pm", "flexible" ], "nullable": true, "type": "string" }, "zip": { "description": "The client's 5-digit ZIP code, shown to responders.", "nullable": true, "pattern": "^[0-9]{5}$", "type": "string" } }, "required": [ "client_id", "kind", "service_area_id", "cross_streets", "date_mode", "care_type", "client_gender", "rate_cents" ], "title": "OpenShiftCreate", "type": "object" } } }, "description": "The shift", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "care_type": { "enum": [ "personal", "homemaking", "both" ], "type": "string" }, "client": { "description": "The client, by name only: never the address or point.", "properties": { "first_name": { "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "type": "string" } }, "type": "object" }, "client_gender": { "enum": [ "female", "male", "unspecified" ], "type": "string" }, "cross_streets": { "type": "string" }, "date_mode": { "enum": [ "exact", "this_week", "next_week", "within_2_weeks", "tbd" ], "type": "string" }, "end_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "hours": { "description": "A one-time shift's hours.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was posted.", "format": "date-time", "type": "string" }, "kind": { "enum": [ "one_time", "ongoing" ], "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "note": { "nullable": true, "type": "string" }, "ongoing_times": { "description": "An ongoing shift's Shift Plan times on starts_on, and the ISO weekdays (1 Monday .. 7 Sunday) its slot runs on; null for a one-time shift.", "nullable": true, "properties": { "end": { "description": "HH:MM.", "nullable": true, "type": "string" }, "ends_next_day": { "description": "The end is past midnight.", "type": "boolean" }, "hours": { "description": "The hours that day.", "format": "decimal", "nullable": true, "type": "string" }, "run_days": { "items": { "type": "integer" }, "type": "array" }, "start": { "description": "HH:MM.", "nullable": true, "type": "string" } }, "type": "object" }, "rate_cents": { "description": "The hourly rate, in cents.", "nullable": true, "type": "integer" }, "service_area": { "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "shift_id": { "description": "An ongoing shift's slot.", "nullable": true, "type": "string" }, "start_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "starts_on": { "description": "The date for exact; the window's last day for this_week, next_week and within_2_weeks; null for tbd.", "format": "date", "nullable": true, "type": "string" }, "status": { "enum": [ "open", "assigned", "completed", "cancelled" ], "type": "string" }, "time_mode": { "enum": [ "exact", "am", "midday", "pm", "flexible" ], "nullable": true, "type": "string" }, "zip": { "nullable": true, "type": "string" } }, "title": "OpenShift", "type": "object" }, "warnings": { "description": "What the act was done with that the agency may want to fix; usually empty. Never a refusal: the act was done.", "items": { "properties": { "fix": { "description": "Where it is fixed, when a page fixes it.", "nullable": true, "properties": { "label": { "description": "What the link says.", "type": "string" }, "path": { "description": "The app route that fixes it.", "type": "string" } }, "required": [ "path", "label" ], "type": "object" }, "id": { "description": "The rule that raised it, stable, e.g. client_care.medicaid_id_pending.", "type": "string" }, "message": { "description": "For a person to read.", "type": "string" } }, "required": [ "id", "message" ], "title": "Warning", "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The shift and its warnings" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes open_shifts_off, slot_already_posted: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes client_info_found, no_shift_plan, not_a_run_day: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Post an open shift", "tags": [ "Open shifts" ] } }, "/api/v1/open-shifts/cross-streets": { "post": { "callbacks": {}, "description": "Two nearby major streets for the client's stored point, as the Post open shift screen's Find cross streets does; the answer is a suggestion and nothing is saved. A client in the Address Confidentiality Program, one with no point, a lookup that fails or takes over 12 seconds, or no crossing nearby answers 422 cross_streets_not_found: type two nearby major streets. Another agency's client answers 404. Needs open_shifts.manage.", "operationId": "postOpenShiftsCrossStreets", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "client_id": { "description": "The client.", "format": "uuid", "type": "string" } }, "required": [ "client_id" ], "title": "OpenShiftCrossStreets", "type": "object" } } }, "description": "The client", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "cross_streets": { "description": " & ", "type": "string" } }, "required": [ "cross_streets" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The cross streets" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code cross_streets_not_found: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Suggest an open shift's cross streets", "tags": [ "Open shifts" ] } }, "/api/v1/open-shifts/dashboard": { "get": { "callbacks": {}, "description": "As the open shifts dashboard shows it. With no section: counts (open, open_no_responses, assigned_upcoming, paused) and coverage by area (open, no_responses, within_reach per area). With section: one list's page and total: not_responding (people alerted at least the agency's not_responding_alerts times in not_responding_days days who did not respond), onboarding (candidates and potential caregivers waiting for onboarding), pauses (caregivers paused from open shifts or holding unvoided strikes inside the agency's strike_window_days: each row's strikes, last_strike_kind, last_strike_at, and paused_until, null when not paused), activity (open-shift audit rows of the not_responding_days window, pay values redacted) or alerts_sent (every alert of a shift the caller may see; status narrows it). A caseload member reads only their clients' shifts, and no area, lead or caregiver rows. Another section answers 422 invalid_section, another status 422 invalid_status. Needs open_shifts.administer.", "operationId": "getOpenShiftsDashboard", "parameters": [ { "description": "Which list; the counts and coverage when left out.", "in": "query", "name": "section", "required": false, "schema": { "enum": [ "not_responding", "onboarding", "pauses", "activity", "alerts_sent" ], "type": "string" } }, { "description": "alerts_sent only: the alerts of this status.", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "pending", "sending", "sent", "failed", "unknown", "skipped" ], "type": "string" } }, { "description": "Rows per page (default 25, at most 100; a larger value is served as 100).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "counts": { "description": "No section: the four counts.", "type": "object" }, "coverage": { "description": "No section: one row per area holding an open shift.", "items": { "type": "object" }, "type": "array" }, "rows": { "items": { "type": "object" }, "type": "array" }, "section": { "type": "string" }, "total": { "type": "integer" } }, "title": "OpenShiftDashboard", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The dashboard, or one section's page" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes invalid_section, invalid_status: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read the open-shifts dashboard", "tags": [ "Open shifts" ] } }, "/api/v1/open-shifts/{id}": { "get": { "callbacks": {}, "description": "One shift as the list answers it. Another agency's shift, or one of a client off a caseload member's clients, answers 404. Needs open_shifts.view.", "operationId": "getOpenShiftsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "care_type": { "enum": [ "personal", "homemaking", "both" ], "type": "string" }, "client": { "description": "The client, by name only: never the address or point.", "properties": { "first_name": { "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "type": "string" } }, "type": "object" }, "client_gender": { "enum": [ "female", "male", "unspecified" ], "type": "string" }, "cross_streets": { "type": "string" }, "date_mode": { "enum": [ "exact", "this_week", "next_week", "within_2_weeks", "tbd" ], "type": "string" }, "end_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "hours": { "description": "A one-time shift's hours.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was posted.", "format": "date-time", "type": "string" }, "kind": { "enum": [ "one_time", "ongoing" ], "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "note": { "nullable": true, "type": "string" }, "ongoing_times": { "description": "An ongoing shift's Shift Plan times on starts_on, and the ISO weekdays (1 Monday .. 7 Sunday) its slot runs on; null for a one-time shift.", "nullable": true, "properties": { "end": { "description": "HH:MM.", "nullable": true, "type": "string" }, "ends_next_day": { "description": "The end is past midnight.", "type": "boolean" }, "hours": { "description": "The hours that day.", "format": "decimal", "nullable": true, "type": "string" }, "run_days": { "items": { "type": "integer" }, "type": "array" }, "start": { "description": "HH:MM.", "nullable": true, "type": "string" } }, "type": "object" }, "rate_cents": { "description": "The hourly rate, in cents.", "nullable": true, "type": "integer" }, "service_area": { "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "shift_id": { "description": "An ongoing shift's slot.", "nullable": true, "type": "string" }, "start_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "starts_on": { "description": "The date for exact; the window's last day for this_week, next_week and within_2_weeks; null for tbd.", "format": "date", "nullable": true, "type": "string" }, "status": { "enum": [ "open", "assigned", "completed", "cancelled" ], "type": "string" }, "time_mode": { "enum": [ "exact", "am", "midday", "pm", "flexible" ], "nullable": true, "type": "string" }, "zip": { "nullable": true, "type": "string" } }, "title": "OpenShift", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The shift" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read an open shift", "tags": [ "Open shifts" ] }, "patch": { "callbacks": {}, "description": "As the Edit screen's Save does: the fields sent change, the rest keep their values; lock_version is required. A lock_version other than the shift's answers 409 stale_record; a shift whose start has passed, or that is completed or cancelled, 409 open_shift_closed; a kind or slot change on an assigned ongoing shift 409 open_shift_assigned; a move onto a slot already posted 409 slot_already_posted. The note and the Shift Plan are judged as on create. Needs open_shifts.manage.", "operationId": "patchOpenShiftsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "acknowledged": { "description": "The fingerprints of client_info_found refusals the sender confirmed are not client information.", "items": { "type": "string" }, "type": "array" }, "care_type": { "description": "The care the shift gives.", "enum": [ "personal", "homemaking", "both" ], "type": "string" }, "client_gender": { "description": "The client's gender, shown to responders.", "enum": [ "female", "male", "unspecified" ], "type": "string" }, "cross_streets": { "description": "Two nearby major streets, as 'S Chambers Rd & E Hampden Ave'; never a house number.", "maxLength": 200, "type": "string", "x-untrusted": "text" }, "date_mode": { "description": "exact needs starts_on; this_week, next_week and within_2_weeks are windows; tbd has no date yet.", "enum": [ "exact", "this_week", "next_week", "within_2_weeks", "tbd" ], "type": "string" }, "end_time": { "description": "HH:MM, one-time exact only; earlier than start_time for an overnight shift.", "format": "time", "nullable": true, "type": "string" }, "hours": { "description": "One-time only, when time_mode is not exact: 0.5 to 24, in halves.", "format": "decimal", "nullable": true, "type": "string" }, "kind": { "description": "one_time for a single shift; ongoing to fill a Shift Plan slot, whose days and times are the Shift Plan's.", "enum": [ "one_time", "ongoing" ], "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "note": { "description": "Up to 500 characters for responders. Checked for client information: a match is refused unless acknowledged names its fingerprint.", "maxLength": 500, "nullable": true, "type": "string", "x-untrusted": "text" }, "rate_cents": { "description": "The hourly rate shown to responders, in cents.", "maximum": 99999, "minimum": 1, "type": "integer" }, "service_area_id": { "description": "The agency area the shift is shown at.", "format": "uuid", "type": "string" }, "shift_id": { "description": "Ongoing only: the Shift Plan slot the shift fills.", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "nullable": true, "type": "string" }, "start_time": { "description": "HH:MM, one-time exact only.", "format": "time", "nullable": true, "type": "string" }, "starts_on": { "description": "The date, for date_mode exact; ignored for a window.", "format": "date", "nullable": true, "type": "string" }, "time_mode": { "description": "One-time only: exact needs start_time and end_time; am, midday, pm and flexible need hours.", "enum": [ "exact", "am", "midday", "pm", "flexible" ], "nullable": true, "type": "string" }, "zip": { "description": "The client's 5-digit ZIP code, shown to responders.", "nullable": true, "pattern": "^[0-9]{5}$", "type": "string" } }, "required": [ "lock_version" ], "title": "OpenShiftUpdate", "type": "object" } } }, "description": "The fields that change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "care_type": { "enum": [ "personal", "homemaking", "both" ], "type": "string" }, "client": { "description": "The client, by name only: never the address or point.", "properties": { "first_name": { "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "type": "string" } }, "type": "object" }, "client_gender": { "enum": [ "female", "male", "unspecified" ], "type": "string" }, "cross_streets": { "type": "string" }, "date_mode": { "enum": [ "exact", "this_week", "next_week", "within_2_weeks", "tbd" ], "type": "string" }, "end_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "hours": { "description": "A one-time shift's hours.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was posted.", "format": "date-time", "type": "string" }, "kind": { "enum": [ "one_time", "ongoing" ], "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "note": { "nullable": true, "type": "string" }, "ongoing_times": { "description": "An ongoing shift's Shift Plan times on starts_on, and the ISO weekdays (1 Monday .. 7 Sunday) its slot runs on; null for a one-time shift.", "nullable": true, "properties": { "end": { "description": "HH:MM.", "nullable": true, "type": "string" }, "ends_next_day": { "description": "The end is past midnight.", "type": "boolean" }, "hours": { "description": "The hours that day.", "format": "decimal", "nullable": true, "type": "string" }, "run_days": { "items": { "type": "integer" }, "type": "array" }, "start": { "description": "HH:MM.", "nullable": true, "type": "string" } }, "type": "object" }, "rate_cents": { "description": "The hourly rate, in cents.", "nullable": true, "type": "integer" }, "service_area": { "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "shift_id": { "description": "An ongoing shift's slot.", "nullable": true, "type": "string" }, "start_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "starts_on": { "description": "The date for exact; the window's last day for this_week, next_week and within_2_weeks; null for tbd.", "format": "date", "nullable": true, "type": "string" }, "status": { "enum": [ "open", "assigned", "completed", "cancelled" ], "type": "string" }, "time_mode": { "enum": [ "exact", "am", "midday", "pm", "flexible" ], "nullable": true, "type": "string" }, "zip": { "nullable": true, "type": "string" } }, "title": "OpenShift", "type": "object" }, "warnings": { "description": "What the act was done with that the agency may want to fix; usually empty. Never a refusal: the act was done.", "items": { "properties": { "fix": { "description": "Where it is fixed, when a page fixes it.", "nullable": true, "properties": { "label": { "description": "What the link says.", "type": "string" }, "path": { "description": "The app route that fixes it.", "type": "string" } }, "required": [ "path", "label" ], "type": "object" }, "id": { "description": "The rule that raised it, stable, e.g. client_care.medicaid_id_pending.", "type": "string" }, "message": { "description": "For a person to read.", "type": "string" } }, "required": [ "id", "message" ], "title": "Warning", "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The shift and its warnings" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes open_shift_assigned, open_shift_closed, slot_already_posted, stale_record: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change an open shift", "tags": [ "Open shifts" ] } }, "/api/v1/open-shifts/{id}/assign": { "post": { "callbacks": {}, "description": "As the responder row's Assign does: the caregiver takes the shift, and an ongoing shift's caregiver is also picked on the client's Shift Plan slot (nothing is generated). A caregiver who did not respond is accepted when the agency's api_may_assign_non_responder is on; when it is off, 422 not_a_responder. An inactive or deleted caregiver answers 422 caregiver_not_active; a shift already assigned 409 open_shift_assigned (\"Already assigned to \"); a completed or cancelled one 409 open_shift_closed; a client with no Shift Plan 422 no_shift_plan (details.shift_plan_path), with the whole assign rolled back. A schedule clash, a posted rate that differs from the caregiver's pay rate, or a start that has passed is answered as a warning (open_shifts.schedule_clash, open_shifts.rate_differs, open_shifts.start_passed) and the shift is still assigned. Another agency's shift or caregiver answers 404. Needs open_shifts.manage.", "operationId": "postOpenShiftsByIdAssign", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "caregiver_id": { "description": "The caregiver to assign.", "format": "uuid", "type": "string" } }, "required": [ "caregiver_id" ], "title": "OpenShiftAssign", "type": "object" } } }, "description": "The caregiver", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "notes": { "description": "What the assign did to the Shift Plan, for an ongoing shift: who takes the slot from the next Generate and who keeps the current Work Order until then.", "items": { "type": "string" }, "type": "array" }, "open_shift": { "properties": { "care_type": { "enum": [ "personal", "homemaking", "both" ], "type": "string" }, "client": { "description": "The client, by name only: never the address or point.", "properties": { "first_name": { "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "type": "string" } }, "type": "object" }, "client_gender": { "enum": [ "female", "male", "unspecified" ], "type": "string" }, "cross_streets": { "type": "string" }, "date_mode": { "enum": [ "exact", "this_week", "next_week", "within_2_weeks", "tbd" ], "type": "string" }, "end_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "hours": { "description": "A one-time shift's hours.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was posted.", "format": "date-time", "type": "string" }, "kind": { "enum": [ "one_time", "ongoing" ], "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "note": { "nullable": true, "type": "string" }, "ongoing_times": { "description": "An ongoing shift's Shift Plan times on starts_on, and the ISO weekdays (1 Monday .. 7 Sunday) its slot runs on; null for a one-time shift.", "nullable": true, "properties": { "end": { "description": "HH:MM.", "nullable": true, "type": "string" }, "ends_next_day": { "description": "The end is past midnight.", "type": "boolean" }, "hours": { "description": "The hours that day.", "format": "decimal", "nullable": true, "type": "string" }, "run_days": { "items": { "type": "integer" }, "type": "array" }, "start": { "description": "HH:MM.", "nullable": true, "type": "string" } }, "type": "object" }, "rate_cents": { "description": "The hourly rate, in cents.", "nullable": true, "type": "integer" }, "service_area": { "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "shift_id": { "description": "An ongoing shift's slot.", "nullable": true, "type": "string" }, "start_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "starts_on": { "description": "The date for exact; the window's last day for this_week, next_week and within_2_weeks; null for tbd.", "format": "date", "nullable": true, "type": "string" }, "status": { "enum": [ "open", "assigned", "completed", "cancelled" ], "type": "string" }, "time_mode": { "enum": [ "exact", "am", "midday", "pm", "flexible" ], "nullable": true, "type": "string" }, "zip": { "nullable": true, "type": "string" } }, "title": "OpenShift", "type": "object" }, "shift_plan_path": { "description": "The client's Shift Plan, for an ongoing shift; null for a one-time one.", "nullable": true, "type": "string" } }, "type": "object" }, "warnings": { "description": "What the act was done with that the agency may want to fix; usually empty. Never a refusal: the act was done.", "items": { "properties": { "fix": { "description": "Where it is fixed, when a page fixes it.", "nullable": true, "properties": { "label": { "description": "What the link says.", "type": "string" }, "path": { "description": "The app route that fixes it.", "type": "string" } }, "required": [ "path", "label" ], "type": "object" }, "id": { "description": "The rule that raised it, stable, e.g. client_care.medicaid_id_pending.", "type": "string" }, "message": { "description": "For a person to read.", "type": "string" } }, "required": [ "id", "message" ], "title": "Warning", "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The assigned shift, its notes and its warnings" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes open_shift_assigned, open_shift_closed: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes caregiver_not_active, no_shift_plan, not_a_responder: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Assign a caregiver to an open shift", "tags": [ "Open shifts" ] } }, "/api/v1/open-shifts/{id}/cancel": { "post": { "callbacks": {}, "description": "As the card's Cancel shift does. A shift already completed or cancelled answers 409 open_shift_closed (\"This shift is already cancelled\"). Needs open_shifts.manage.", "operationId": "postOpenShiftsByIdCancel", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "care_type": { "enum": [ "personal", "homemaking", "both" ], "type": "string" }, "client": { "description": "The client, by name only: never the address or point.", "properties": { "first_name": { "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "type": "string" } }, "type": "object" }, "client_gender": { "enum": [ "female", "male", "unspecified" ], "type": "string" }, "cross_streets": { "type": "string" }, "date_mode": { "enum": [ "exact", "this_week", "next_week", "within_2_weeks", "tbd" ], "type": "string" }, "end_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "hours": { "description": "A one-time shift's hours.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was posted.", "format": "date-time", "type": "string" }, "kind": { "enum": [ "one_time", "ongoing" ], "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "note": { "nullable": true, "type": "string" }, "ongoing_times": { "description": "An ongoing shift's Shift Plan times on starts_on, and the ISO weekdays (1 Monday .. 7 Sunday) its slot runs on; null for a one-time shift.", "nullable": true, "properties": { "end": { "description": "HH:MM.", "nullable": true, "type": "string" }, "ends_next_day": { "description": "The end is past midnight.", "type": "boolean" }, "hours": { "description": "The hours that day.", "format": "decimal", "nullable": true, "type": "string" }, "run_days": { "items": { "type": "integer" }, "type": "array" }, "start": { "description": "HH:MM.", "nullable": true, "type": "string" } }, "type": "object" }, "rate_cents": { "description": "The hourly rate, in cents.", "nullable": true, "type": "integer" }, "service_area": { "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "shift_id": { "description": "An ongoing shift's slot.", "nullable": true, "type": "string" }, "start_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "starts_on": { "description": "The date for exact; the window's last day for this_week, next_week and within_2_weeks; null for tbd.", "format": "date", "nullable": true, "type": "string" }, "status": { "enum": [ "open", "assigned", "completed", "cancelled" ], "type": "string" }, "time_mode": { "enum": [ "exact", "am", "midday", "pm", "flexible" ], "nullable": true, "type": "string" }, "zip": { "nullable": true, "type": "string" } }, "title": "OpenShift", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The cancelled shift" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code open_shift_closed: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Cancel an open shift", "tags": [ "Open shifts" ] } }, "/api/v1/open-shifts/{id}/complete": { "post": { "callbacks": {}, "description": "As the card's Completed does: the shift moves to completed with outcome completed, and its Shift Plan pick and Visit stay as they are. Before the shift's start it answers 409 not_started while the agency's complete_before_start is off. A shift that is not assigned, a second complete included, answers 409 not_assigned. Another agency's shift, or one off a caseload member's clients, answers 404. Needs open_shifts.manage.", "operationId": "postOpenShiftsByIdComplete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "care_type": { "enum": [ "personal", "homemaking", "both" ], "type": "string" }, "client": { "description": "The client, by name only: never the address or point.", "properties": { "first_name": { "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "type": "string" } }, "type": "object" }, "client_gender": { "enum": [ "female", "male", "unspecified" ], "type": "string" }, "cross_streets": { "type": "string" }, "date_mode": { "enum": [ "exact", "this_week", "next_week", "within_2_weeks", "tbd" ], "type": "string" }, "end_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "hours": { "description": "A one-time shift's hours.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was posted.", "format": "date-time", "type": "string" }, "kind": { "enum": [ "one_time", "ongoing" ], "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "note": { "nullable": true, "type": "string" }, "ongoing_times": { "description": "An ongoing shift's Shift Plan times on starts_on, and the ISO weekdays (1 Monday .. 7 Sunday) its slot runs on; null for a one-time shift.", "nullable": true, "properties": { "end": { "description": "HH:MM.", "nullable": true, "type": "string" }, "ends_next_day": { "description": "The end is past midnight.", "type": "boolean" }, "hours": { "description": "The hours that day.", "format": "decimal", "nullable": true, "type": "string" }, "run_days": { "items": { "type": "integer" }, "type": "array" }, "start": { "description": "HH:MM.", "nullable": true, "type": "string" } }, "type": "object" }, "rate_cents": { "description": "The hourly rate, in cents.", "nullable": true, "type": "integer" }, "service_area": { "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "shift_id": { "description": "An ongoing shift's slot.", "nullable": true, "type": "string" }, "start_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "starts_on": { "description": "The date for exact; the window's last day for this_week, next_week and within_2_weeks; null for tbd.", "format": "date", "nullable": true, "type": "string" }, "status": { "enum": [ "open", "assigned", "completed", "cancelled" ], "type": "string" }, "time_mode": { "enum": [ "exact", "am", "midday", "pm", "flexible" ], "nullable": true, "type": "string" }, "zip": { "nullable": true, "type": "string" } }, "title": "OpenShift", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The completed shift" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes not_assigned, not_started: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Close an assigned open shift as completed", "tags": [ "Open shifts" ] } }, "/api/v1/open-shifts/{id}/no-show": { "post": { "callbacks": {}, "description": "As the card's No-show does, once the shift's start has passed: the assignment is undone as an unassign does it (a scheduled Visit is cancelled, reason caregiver_call_off; one under way is left for the office and answered as an open_shifts.needs_attention warning), the shift is cancelled with outcome no_show, its responders and the assignee are told it is cancelled, and the assignee is struck once. When the strikes in the agency's window reach its strikes_before_pause, the caregiver is paused from responding to open shifts. Before the start it answers 409 not_started (\"No-show can be marked once the shift has started\"); a shift that is not assigned, a second no-show included, 409 not_assigned; a shift assigned to someone else while the call ran 409 stale_record. Another agency's shift, or one off a caseload member's clients, answers 404. Needs open_shifts.manage.", "operationId": "postOpenShiftsByIdNoShow", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "care_type": { "enum": [ "personal", "homemaking", "both" ], "type": "string" }, "client": { "description": "The client, by name only: never the address or point.", "properties": { "first_name": { "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "type": "string" } }, "type": "object" }, "client_gender": { "enum": [ "female", "male", "unspecified" ], "type": "string" }, "cross_streets": { "type": "string" }, "date_mode": { "enum": [ "exact", "this_week", "next_week", "within_2_weeks", "tbd" ], "type": "string" }, "end_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "hours": { "description": "A one-time shift's hours.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was posted.", "format": "date-time", "type": "string" }, "kind": { "enum": [ "one_time", "ongoing" ], "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "note": { "nullable": true, "type": "string" }, "ongoing_times": { "description": "An ongoing shift's Shift Plan times on starts_on, and the ISO weekdays (1 Monday .. 7 Sunday) its slot runs on; null for a one-time shift.", "nullable": true, "properties": { "end": { "description": "HH:MM.", "nullable": true, "type": "string" }, "ends_next_day": { "description": "The end is past midnight.", "type": "boolean" }, "hours": { "description": "The hours that day.", "format": "decimal", "nullable": true, "type": "string" }, "run_days": { "items": { "type": "integer" }, "type": "array" }, "start": { "description": "HH:MM.", "nullable": true, "type": "string" } }, "type": "object" }, "rate_cents": { "description": "The hourly rate, in cents.", "nullable": true, "type": "integer" }, "service_area": { "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "shift_id": { "description": "An ongoing shift's slot.", "nullable": true, "type": "string" }, "start_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "starts_on": { "description": "The date for exact; the window's last day for this_week, next_week and within_2_weeks; null for tbd.", "format": "date", "nullable": true, "type": "string" }, "status": { "enum": [ "open", "assigned", "completed", "cancelled" ], "type": "string" }, "time_mode": { "enum": [ "exact", "am", "midday", "pm", "flexible" ], "nullable": true, "type": "string" }, "zip": { "nullable": true, "type": "string" } }, "title": "OpenShift", "type": "object" }, "warnings": { "description": "What the act was done with that the agency may want to fix; usually empty. Never a refusal: the act was done.", "items": { "properties": { "fix": { "description": "Where it is fixed, when a page fixes it.", "nullable": true, "properties": { "label": { "description": "What the link says.", "type": "string" }, "path": { "description": "The app route that fixes it.", "type": "string" } }, "required": [ "path", "label" ], "type": "object" }, "id": { "description": "The rule that raised it, stable, e.g. client_care.medicaid_id_pending.", "type": "string" }, "message": { "description": "For a person to read.", "type": "string" } }, "required": [ "id", "message" ], "title": "Warning", "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The cancelled shift and its warnings" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes not_assigned, not_started, stale_record: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Mark an assigned open shift a no-show", "tags": [ "Open shifts" ] } }, "/api/v1/open-shifts/{id}/responses": { "get": { "callbacks": {}, "description": "The shift's live responses (a withdrawn one is not listed), as the coordinator's card lists them: active caregivers first, then nearest to the shift's service area, then by when they responded. limit defaults to 50 (at most 100). home_area is answered only to a holder of open_shifts.administer. Another agency's shift, or one off a caseload member's clients, answers 404. Needs open_shifts.manage: a view-only credential answers 403.", "operationId": "getOpenShiftsByIdResponses", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 50, at most 100; a larger value is served as 100).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "description": "One live response to an open shift (a withdrawn one is not listed).", "properties": { "active": { "description": "The caregiver is active.", "type": "boolean" }, "caregiver_id": { "description": "The caregiver; null for a candidate.", "format": "uuid", "nullable": true, "type": "string" }, "completed": { "description": "Open shifts this caregiver has completed.", "nullable": true, "type": "integer" }, "home_area": { "description": "The caregiver's home service area. Present only for a holder of open_shifts.administer; null when none is set.", "nullable": true, "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "miles": { "description": "Whole miles from the caregiver's home area to the shift's service area; null when either has no known point.", "nullable": true, "type": "integer" }, "name": { "description": "Last, First.", "nullable": true, "type": "string" }, "open_shift_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "phone": { "nullable": true, "type": "string" }, "responded_at": { "description": "When they responded.", "format": "date-time", "type": "string" }, "role": { "enum": [ "Caregiver", "Candidate" ], "type": "string" } }, "title": "OpenShiftResponse", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "OpenShiftResponsePage", "type": "object" } } }, "description": "A page of responses" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List who responded to an open shift", "tags": [ "Open shifts" ] } }, "/api/v1/open-shifts/{id}/unassign": { "post": { "callbacks": {}, "description": "As the card's Remove assignment does: the shift is open again and its live responders, other than the caregiver who left, are told. A one-time cover's scheduled Visit is cancelled (reason schedule_change) and the temporary Assignment it made is closed; an ongoing shift's Shift Plan pick is cleared and the slot's Work Order archived while its start has not passed. A Visit already under way, or an ongoing shift whose start passed, is left for the office and answered as a warning (open_shifts.needs_attention). A shift that is not assigned answers 409 open_shift_not_assigned. Another agency's shift answers 404. Needs open_shifts.manage.", "operationId": "postOpenShiftsByIdUnassign", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "care_type": { "enum": [ "personal", "homemaking", "both" ], "type": "string" }, "client": { "description": "The client, by name only: never the address or point.", "properties": { "first_name": { "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "type": "string" } }, "type": "object" }, "client_gender": { "enum": [ "female", "male", "unspecified" ], "type": "string" }, "cross_streets": { "type": "string" }, "date_mode": { "enum": [ "exact", "this_week", "next_week", "within_2_weeks", "tbd" ], "type": "string" }, "end_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "hours": { "description": "A one-time shift's hours.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "inserted_at": { "description": "When it was posted.", "format": "date-time", "type": "string" }, "kind": { "enum": [ "one_time", "ongoing" ], "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "note": { "nullable": true, "type": "string" }, "ongoing_times": { "description": "An ongoing shift's Shift Plan times on starts_on, and the ISO weekdays (1 Monday .. 7 Sunday) its slot runs on; null for a one-time shift.", "nullable": true, "properties": { "end": { "description": "HH:MM.", "nullable": true, "type": "string" }, "ends_next_day": { "description": "The end is past midnight.", "type": "boolean" }, "hours": { "description": "The hours that day.", "format": "decimal", "nullable": true, "type": "string" }, "run_days": { "items": { "type": "integer" }, "type": "array" }, "start": { "description": "HH:MM.", "nullable": true, "type": "string" } }, "type": "object" }, "rate_cents": { "description": "The hourly rate, in cents.", "nullable": true, "type": "integer" }, "service_area": { "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "shift_id": { "description": "An ongoing shift's slot.", "nullable": true, "type": "string" }, "start_time": { "description": "HH:MM.", "nullable": true, "type": "string" }, "starts_on": { "description": "The date for exact; the window's last day for this_week, next_week and within_2_weeks; null for tbd.", "format": "date", "nullable": true, "type": "string" }, "status": { "enum": [ "open", "assigned", "completed", "cancelled" ], "type": "string" }, "time_mode": { "enum": [ "exact", "am", "midday", "pm", "flexible" ], "nullable": true, "type": "string" }, "zip": { "nullable": true, "type": "string" } }, "title": "OpenShift", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The reopened shift and its warnings" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code open_shift_not_assigned: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Remove the caregiver from an open shift", "tags": [ "Open shifts" ] } }, "/api/v1/openapi.json": { "get": { "callbacks": {}, "description": "This document. No credential is needed.", "operationId": "getOpenapiJson", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "The OpenAPI 3 document" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "security": [], "summary": "The OpenAPI document", "tags": [ "Documentation" ] } }, "/api/v1/paper-capture/applications/latest": { "get": { "callbacks": {}, "description": "The newest paper update to the record not undone, the data of its \"From paper\" badge, or data null; undoable says whether the badge offers Undo. Open without the paper-capture consent. 422 invalid_target_kind or invalid_id for a parameter it cannot read.", "operationId": "getPaperCaptureApplicationsLatest", "parameters": [ { "description": "", "in": "query", "name": "target_kind", "required": true, "schema": { "enum": [ "work_order", "timesheet", "plan_of_care", "supervisor_visit", "client" ], "type": "string" } }, { "description": "", "in": "query", "name": "target_id", "required": true, "schema": { "description": "The record.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The paper update" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code invalid_target_kind: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "A record's latest paper update", "tags": [ "Paper capture" ] } }, "/api/v1/paper-capture/applications/{id}/undo": { "post": { "callbacks": {}, "description": "Undo, as the record page's \"From paper\" badge does: every value the update wrote and nobody changed since is restored, rows it added are deleted, and lines names each field left alone; the form can then be applied again. Open without the paper-capture consent. Already undone answers 409 already_reverted; a record that is not editable 422 not_editable; an update that created its record (undoable false) 422 created_from_paper; answers the record now refuses (a question form) 422 invalid_answers with field_ids and errors, as apply does. Undo writes the record its apply wrote, so it needs what applying did: besides clients.manage, a Work Order work_orders.manage, a timesheet timesheets.manage, a Plan of Care or supervisory visit care_plans.manage, and a Time and Services Card timesheets.manage too; without it 403 forbidden names the permission and nothing is restored. Another agency's update answers 404.", "operationId": "postPaperCaptureApplicationsByIdUndo", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The paper update" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code already_reverted: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes created_from_paper, invalid_answers, not_editable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Undo a paper update", "tags": [ "Paper capture" ] } }, "/api/v1/paper-capture/forms": { "get": { "callbacks": {}, "description": "The Paper inbox's forms, newest first, each with its state, form type, target record, the sentence the inbox shows for a failure, the actions it offers (read, discard, choose_target, find_target for a form that matched no record of a kind it never creates, choose_client, choose_form_type with form_type_choices, review, view for an applied form), review_url (the page Review or View opens), unprinted (read from a layout HCB never printed), the scan it was read from (scan_id) and total_count. status narrows them (422 invalid_status for another); scan_id narrows them to one upload's forms, which appear once the scan is prepared. Without the agency's paper-capture consent (Settings > Data sharing) it answers 403 paper_capture_consent_required.", "operationId": "getPaperCaptureForms", "parameters": [ { "description": "Rows per page (default 50, at most 100; a larger value is served as 100).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "", "in": "query", "name": "status", "required": false, "schema": { "description": "One status.", "enum": [ "grouped", "extracting", "ready_for_review", "applying", "applied", "awaiting_form_type", "awaiting_consent", "awaiting_credit", "failed" ], "type": "string" } }, { "description": "Only the forms read from this scan, the id an upload answered (422 invalid_id for another value).", "in": "query", "name": "scan_id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "type": "object" }, "type": "array" }, "limit": { "description": "This page's size.", "nullable": true, "type": "integer" }, "offset": { "description": "Where it starts.", "nullable": true, "type": "integer" }, "total_count": { "description": "All of them, for status.", "nullable": true, "type": "integer" } }, "required": [ "data", "total_count" ], "type": "object" } } }, "description": "The forms" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code paper_capture_consent_required: Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code invalid_status: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List paper forms", "tags": [ "Paper capture" ] } }, "/api/v1/paper-capture/forms/{id}": { "delete": { "callbacks": {}, "description": "Discard, as the inbox does; an applied form cannot be discarded. A form whose state does not offer the action answers 422 with the inbox's sentence. Without the agency's paper-capture consent (Settings > Data sharing) it answers 403 paper_capture_consent_required. Another agency's form answers 404 and nothing is written.", "operationId": "deletePaperCaptureFormsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The form" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code paper_capture_consent_required: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Discard a paper form", "tags": [ "Paper capture" ] }, "get": { "callbacks": {}, "description": "The inbox's fields with the review's: mode, its rows (each field's current and read values, state, attention, the check's sentence, the decision it starts with, blank_allowed: false on a row naming who the client is, and kept, the sentence on a row the apply never writes, such as a stored Medicaid ID), notes (in review the unprinted-layout warning and the checks; once applied what the save said), the summary line (once applied, when and by whom), applied_rows once applied (each value written from paper as after_text beside the value it replaced as before_text, as the applied review shows them), its pages (images are GET /api/v1/paper-capture/pages/{id}/image), the records Choose record offers, and the draft a revised plan was replaced by. A Plan of Care or supervisory visit whose record is signed, revised or not editable says so in notes, and actions add revise_plan for a member with care_plans.manage (POST /api/v1/plans-of-care/{id}/revise on target.id), reopen_visit for a member with care_plans.manage (POST /api/v1/supervisory-visits/{id}/reopen with a reason, on target.id) or retarget_to_draft, as the review offers them; paper revises a signed record, never changes it in place. A PHI view. Without the agency's paper-capture consent (Settings > Data sharing) it answers 403 paper_capture_consent_required. Another agency's form answers 404 and nothing is written.", "operationId": "getPaperCaptureFormsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The form" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code paper_capture_consent_required: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "A paper form, as its review shows it", "tags": [ "Paper capture" ] } }, "/api/v1/paper-capture/forms/{id}/apply": { "post": { "callbacks": {}, "description": "Apply, as the review does, with one decision per row: accept, keep_current, blank or value. A row left out of decisions is not written, a New row included (the review screen preselects accept for one; this endpoint does not), and an apply that writes nothing puts no From paper on the record. A record changed since get answers 409 stale with the rows as they are now; a needs-attention row left undecided 422 needs_attention naming its field_ids; values the record refuses 422 validation_failed; any other refusal 422 with the review's sentence. A Work Order's Time and Services Card also writes each day as a paper_scan care log; care_log_warnings lists the office draft care logs that took the paper's values, the days the caregiver or an import already logged (kept as they are), the paper days no longer drafts, and each day's differences from the plan; for either card, it also lists each day whose delivery another source recorded, where the paper's times were not written and the recorded times stand (kind recorded; those fields are left out of what the apply wrote). None of these refuses the apply. Besides clients.manage, applying needs the target record's own permission: a Work Order work_orders.manage, a timesheet timesheets.manage, a Plan of Care or supervisory visit care_plans.manage, and a Time and Services Card timesheets.manage too, since it writes the month's timesheet and care logs; without it 403 forbidden names the permission. Without the agency's paper-capture consent (Settings > Data sharing) it answers 403 paper_capture_consent_required. Another agency's form answers 404 and nothing is written.", "operationId": "postPaperCaptureFormsByIdApply", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "decisions": { "items": { "properties": { "choice": { "description": "What to do with the row.", "enum": [ "accept", "keep_current", "blank", "value" ], "type": "string" }, "field": { "description": "The row's field_id.", "nullable": true, "type": "string" }, "shown_current": { "description": "The row's current, as GET /api/v1/paper-capture/forms/{id} answered it, sent back unchanged: a record changed since answers 409 stale.", "nullable": true, "type": "string" }, "value": { "description": "The value to write, for choice value.", "nullable": true, "type": "string" } }, "required": [ "field", "choice" ], "type": "object" }, "type": "array" } }, "required": [ "decisions" ], "type": "object" } } }, "description": "The decisions", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The paper update" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code paper_capture_consent_required: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes needs_attention, validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Apply a paper form to its record", "tags": [ "Paper capture" ] } }, "/api/v1/paper-capture/forms/{id}/client": { "post": { "callbacks": {}, "description": "The review's client picker for a client sheet that matched no client; until the sheet is applied, choosing another client points it there instead. A form whose state does not offer the action answers 422 with the inbox's sentence. Without the agency's paper-capture consent (Settings > Data sharing) it answers 403 paper_capture_consent_required. Another agency's form answers 404 and nothing is written.", "operationId": "postPaperCaptureFormsByIdClient", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "client_id": { "nullable": true, "type": "string" } }, "required": [ "client_id" ], "type": "object" } } }, "description": "The client", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The form" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code paper_capture_consent_required: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Choose the client of an unmatched client sheet", "tags": [ "Paper capture" ] } }, "/api/v1/paper-capture/forms/{id}/draft": { "post": { "callbacks": {}, "description": "For a plan of care revised, or a supervisory visit reopened for correction, since the page was printed: draft_id is get's draft_id. A form whose state does not offer the action answers 422 with the inbox's sentence. Without the agency's paper-capture consent (Settings > Data sharing) it answers 403 paper_capture_consent_required. Another agency's form answers 404 and nothing is written.", "operationId": "postPaperCaptureFormsByIdDraft", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "draft_id": { "description": "The draft.", "format": "uuid", "type": "string" } }, "required": [ "draft_id" ], "type": "object" } } }, "description": "The draft", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The form" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code paper_capture_consent_required: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Apply a paper form to the draft that replaced its plan or visit", "tags": [ "Paper capture" ] } }, "/api/v1/paper-capture/forms/{id}/form-type": { "post": { "callbacks": {}, "description": "The form-type picker: form_key is one of form_type_choices. The page is then read again, which sends it to Anthropic and spends reading credit. A form whose state does not offer the action answers 422 with the inbox's sentence. Without the agency's paper-capture consent (Settings > Data sharing) it answers 403 paper_capture_consent_required. Another agency's form answers 404 and nothing is written.", "operationId": "postPaperCaptureFormsByIdFormType", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "form_key": { "nullable": true, "type": "string" } }, "required": [ "form_key" ], "type": "object" } } }, "description": "The form type", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The form" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code paper_capture_consent_required: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Choose an unprinted page's form type", "tags": [ "Paper capture" ] } }, "/api/v1/paper-capture/forms/{id}/merge": { "post": { "callbacks": {}, "description": "Join with, as the inbox does: every page of from_form_id moves to this form, which waits for a Read; from_form_id is joined in and leaves the inbox. A read already done on either form is discarded, so a new Read is needed. Forms of two different form types or records answer 422 mismatch, a page both forms hold 422 duplicate_page, and a form that is being read, applied, discarded or joined already, or already holds every page, 422 not_mergeable, each with the inbox's sentence, as every inbox action refuses. Without the agency's paper-capture consent (Settings > Data sharing) it answers 403 paper_capture_consent_required. Another agency's form answers 404 and nothing is written.", "operationId": "postPaperCaptureFormsByIdMerge", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "from_form_id": { "description": "The form whose pages move to this one.", "format": "uuid", "type": "string" } }, "required": [ "from_form_id" ], "type": "object" } } }, "description": "The form to join in", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The form" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code paper_capture_consent_required: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes duplicate_page, not_mergeable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Join two paper forms' pages", "tags": [ "Paper capture" ] } }, "/api/v1/paper-capture/forms/{id}/read": { "post": { "callbacks": {}, "description": "Read, or Read again, as the inbox does: the page is sent to Anthropic and spends reading credit. A form waiting for its form type answers 422 awaiting_form_type: choose it first (POST /api/v1/paper-capture/forms/{id}/form-type). A form whose state does not offer the action answers 422 with the inbox's sentence. Without the agency's paper-capture consent (Settings > Data sharing) it answers 403 paper_capture_consent_required. Another agency's form answers 404 and nothing is written.", "operationId": "postPaperCaptureFormsByIdRead", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The form" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code paper_capture_consent_required: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code awaiting_form_type: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read a paper form", "tags": [ "Paper capture" ] } }, "/api/v1/paper-capture/forms/{id}/target": { "post": { "callbacks": {}, "description": "Choose record, as the inbox does: target_id is one of get's candidates or, when actions include find_target, the id of any of the agency's records of the form's kind (a Work Order for a Time and Services Card or Monthly Client Report, a supervisory visit for a Supervisory Visit form), as the review's record search finds them. A form whose state does not offer the action answers 422 with the inbox's sentence. Without the agency's paper-capture consent (Settings > Data sharing) it answers 403 paper_capture_consent_required. Another agency's form answers 404 and nothing is written.", "operationId": "postPaperCaptureFormsByIdTarget", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "target_id": { "nullable": true, "type": "string" } }, "required": [ "target_id" ], "type": "object" } } }, "description": "The record", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The form" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code paper_capture_consent_required: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Choose a paper form's record", "tags": [ "Paper capture" ] } }, "/api/v1/paper-capture/pages/{id}/image": { "get": { "callbacks": {}, "description": "A URL for the page's image, valid for 300 seconds, issued once the view is recorded. An image the 30-day purge removed answers 410 image_removed; the store not answering 503 storage_unavailable. Without the agency's paper-capture consent (Settings > Data sharing) it answers 403 paper_capture_consent_required. Another agency's page answers 404.", "operationId": "getPaperCapturePagesByIdImage", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The image's URL" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code paper_capture_consent_required: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code image_removed: Gone, as the operation's description says." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code storage_unavailable: Service Unavailable, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "A paper form page's image", "tags": [ "Paper capture" ] } }, "/api/v1/paper-capture/scans": { "post": { "callbacks": {}, "description": "Multipart field file (.jpg, .jpeg, .png, .heic, .pdf), up to 10 MB, as the upload control takes one: the agency's prepaid reading credit is checked against the pages first (422 insufficient_credit), then it is stored and read in the background, and its forms appear in GET /api/v1/paper-capture/forms. The same file uploaded again answers the scan already on file, existing true. A larger file, up to 25 MB, goes through POST /api/v1/paper-capture/scans/uploads. More than the agency's daily uploads answers 429 daily_upload_limit; a type it does not read 422 unsupported_file; over the limit 413 file_too_large. Without the agency's paper-capture consent (Settings > Data sharing) it answers 403 paper_capture_consent_required.", "operationId": "postPaperCaptureScans", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "description": "The photo or scan.", "format": "binary", "type": "string" }, "origin_target_id": { "description": "That record's id.", "format": "uuid", "type": "string" }, "origin_target_kind": { "description": "The kind of record the upload is made from, as a record page's upload control sends it; leave out for the Paper inbox's.", "enum": [ "work_order", "timesheet", "plan_of_care", "supervisor_visit", "client" ], "type": "string" } }, "required": [ "file" ], "type": "object" } } }, "description": "The file", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The scan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code paper_capture_consent_required: Forbidden, as the operation's description says." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code file_too_large: Request Entity Too Large, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes insufficient_credit, unsupported_file: Unprocessable Content, as the operation's description says." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code daily_upload_limit: Too Many Requests, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Upload a paper scan", "tags": [ "Paper capture" ] } }, "/api/v1/paper-capture/scans/uploads": { "post": { "callbacks": {}, "description": "For a file larger than 10 MB, up to 25 MB: answers upload_url, single-use, bound to this credential and this agency, valid for 30 minutes. PUT the file's bytes to it (PUT /api/v1/paper-capture/scans/uploads/{token}) with the same credential; the answer is the scan. The name and the origin record are checked now (422 unsupported_file, 422 origin_target_not_found), the credit and the bytes when they arrive. Without the agency's paper-capture consent (Settings > Data sharing) it answers 403 paper_capture_consent_required.", "operationId": "postPaperCaptureScansUploads", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "file_name": { "description": "The file's name, with its extension (.jpg, .jpeg, .png, .heic, .pdf).", "nullable": true, "type": "string" }, "origin_target_id": { "description": "That record's id.", "format": "uuid", "type": "string" }, "origin_target_kind": { "description": "The kind of record the upload is made from, as a record page's upload control sends it; leave out for the Paper inbox's.", "enum": [ "work_order", "timesheet", "plan_of_care", "supervisor_visit", "client" ], "type": "string" } }, "required": [ "file_name" ], "type": "object" } } }, "description": "The file's details", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "content_type": { "nullable": true, "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "file_name": { "nullable": true, "type": "string" }, "max_file_size": { "description": "The largest file the slot takes, in bytes.", "nullable": true, "type": "integer" }, "method": { "description": "PUT.", "nullable": true, "type": "string" }, "upload_url": { "description": "Where to PUT the file's bytes, once, with this credential.", "nullable": true, "type": "string" } }, "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The slot" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code paper_capture_consent_required: Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes origin_target_not_found, unsupported_file: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Request a slot to upload a large paper scan", "tags": [ "Paper capture" ] } }, "/api/v1/paper-capture/scans/uploads/{token}": { "put": { "callbacks": {}, "description": "The body is the file's bytes, nothing else (JSON, form or multipart answer 415), up to 25 MB; over it 413 file_too_large. Sent with the credential that requested the slot: another credential's or agency's slot answers 404, as an unknown one does. A slot stores one scan: used answers 409 upload_slot_used with the scan's id in details, one another PUT is still storing 409 upload_slot_in_progress, one past expires_at 410 upload_slot_expired. A file the upload refuses (422) leaves the slot usable until it expires. Without the agency's paper-capture consent (Settings > Data sharing) it answers 403 paper_capture_consent_required.", "operationId": "putPaperCaptureScansUploadsByToken", "parameters": [ { "description": "The slot's token, from its upload_url.", "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "The file's bytes", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The scan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code paper_capture_consent_required: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes upload_slot_in_progress, upload_slot_used: Conflict, as the operation's description says." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code upload_slot_expired: Gone, as the operation's description says." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code file_too_large: Request Entity Too Large, as the operation's description says." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unsupported Media Type, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Upload a paper scan's bytes to its slot", "tags": [ "Paper capture" ] } }, "/api/v1/payroll-exports": { "post": { "callbacks": {}, "description": "A pending export for billing_period_start to billing_period_end, with the agency's ADP company code, as Payroll does before it generates the file.", "operationId": "postPayrollExports", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "billing_period_end": { "description": "YYYY-MM-DD.", "format": "date", "type": "string" }, "billing_period_start": { "description": "YYYY-MM-DD.", "format": "date", "type": "string" } }, "required": [ "billing_period_start", "billing_period_end" ], "type": "object" } } }, "description": "The pay period", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "adp_co_code": { "nullable": true, "type": "string" }, "billing_period_end": { "format": "date", "nullable": true, "type": "string" }, "billing_period_start": { "format": "date", "nullable": true, "type": "string" }, "file_ready": { "description": "Whether GET .../file has a file to return.", "type": "boolean" }, "format": { "description": "adp (Workforce Now) or adp_run.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "status": { "description": "pending, generated or exported.", "nullable": true, "type": "string" } }, "title": "PayrollExport", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The export" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Start a payroll export for a pay period", "tags": [ "Payroll", "Payroll exports" ] } }, "/api/v1/payroll-exports/{id}/check": { "post": { "callbacks": {}, "description": "As Payroll exports > Check lists them: every line ADP would refuse and why, with the page where each is fixed, sorted unsendable, refusal, warning, then by caregiver last name. Changes nothing; any member at every access level, no Idempotency-Key. An id naming none of the agency's exports answers 404 not_found, whatever else holds; then 409 payroll_integration_off while the ADP payroll integration is off for the agency.", "operationId": "postPayrollExportsByIdCheck", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "caregiver_id": { "description": "The caregiver, or null for the export as a whole.", "format": "uuid", "nullable": true, "type": "string" }, "code": { "description": "Which rule found it.", "enum": [ "product_unknown", "no_company_code", "no_file_number", "hired_after_period", "hours_out_of_range", "rate_codes_assumed", "too_many_rates", "unmapped_kind", "basis_changed", "period_not_an_adp_pay_cycle", "pay_frequency_differs", "code_not_in_adp", "code_worker_type_mismatch", "adp_terminated", "adp_on_leave", "rate_differs" ], "type": "string" }, "fix_path": { "description": "The HomeCareBilling page where it is fixed.", "nullable": true, "type": "string" }, "message": { "description": "The sentence Payroll exports > Check shows.", "nullable": true, "type": "string" }, "severity": { "description": "unsendable (no line of the ADP file can be written), refusal (ADP refuses this line; the rest goes) or warning (sent as it is).", "enum": [ "unsendable", "refusal", "warning" ], "type": "string" } }, "required": [ "severity", "code", "caregiver_id", "message", "fix_path" ], "title": "PayrollCheckFinding", "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The findings" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code payroll_integration_off: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Check a payroll export before sending it to ADP", "tags": [ "Payroll", "Payroll exports" ] } }, "/api/v1/payroll-exports/{id}/file": { "get": { "callbacks": {}, "description": "The generated CSV, as Payroll exports > Download serves it. A pending export answers 409 not_generated; a file that is gone 410 file_missing. With format adp_import, the file ADP imports as it is, built from the timesheets and cash advances the export was generated from, as Download for ADP builds it: RUN's Time Sheet Import (file Monthly-03012026-03312026.csv and the like) or the Workforce Now paydata file (PR{co}EPI.csv), every line ADP would refuse left out (POST /payroll-exports/{id}/check names them). With entry_sheet, the RUN sheet the office types from, as Entry sheet (to type from) builds it. A format answers 409 payroll_integration_off while the ADP payroll integration is off for the agency, and adp_import answers 422 with the check's unsendable code (product_unknown, no_company_code) and message when no line can be written. Any member at every access level. Another agency's record answers 404 and nothing is written.", "operationId": "getPayrollExportsByIdFile", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "adp_import or entry_sheet builds that file (US-111.6); leave it out for the stored file.", "in": "query", "name": "format", "required": false, "schema": { "enum": [ "adp_import", "entry_sheet" ], "type": "string" } } ], "responses": { "200": { "content": { "text/csv": { "schema": { "type": "string" } } }, "description": "The CSV" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_generated (the export is pending) or payroll_integration_off (a format was asked while the ADP payroll integration is off)." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code file_missing: the record exists and its file does not. Nothing changed." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code unknown_file_format, or the pre-send check's unsendable code (product_unknown, no_company_code) with its message: no line of the ADP file can be written." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code internal_error: a failure on our side, which was logged. When its message says nothing changed (the file store refused the request, the virus scan could not be queued, the upload could not be read), nothing did, the same request fails the same way until it is fixed, and the Idempotency-Key stays free." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code storage_unavailable (the file store did not answer) or, on an upload, temporarily_unavailable (its uploaded file could not be read): nothing changed, and the same request can succeed later. Retry after the Retry-After seconds; a write retried with the same Idempotency-Key runs again.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (30).", "schema": { "type": "integer" }, "style": "simple" } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Download a payroll export's ADP file", "tags": [ "Payroll", "Payroll exports" ] } }, "/api/v1/payroll-exports/{id}/generate": { "post": { "callbacks": {}, "description": "Builds the ADP CSV (format adp for Workforce Now, adp_run for RUN) from the period's approved timesheets, overtime included, as Payroll does, and answers the export and its warnings. A generated export can be generated again; an exported one answers 422 export_already_finalized; no approved timesheets 422 no_approved_timesheets; no ADP company code 422 adp_settings_missing. 1099 contractors are left out of the file (a warning counts them and their hours); a period whose every caregiver is a contractor answers 422 all_caregivers_contractors. Another agency's record answers 404 and nothing is written.", "operationId": "postPayrollExportsByIdGenerate", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "", "in": "query", "name": "format", "required": true, "schema": { "enum": [ "adp", "adp_run" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "adp_co_code": { "nullable": true, "type": "string" }, "billing_period_end": { "format": "date", "nullable": true, "type": "string" }, "billing_period_start": { "format": "date", "nullable": true, "type": "string" }, "file_ready": { "description": "Whether GET .../file has a file to return.", "type": "boolean" }, "format": { "description": "adp (Workforce Now) or adp_run.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "status": { "description": "pending, generated or exported.", "nullable": true, "type": "string" } }, "title": "PayrollExport", "type": "object" }, "warnings": { "items": { "nullable": true, "type": "string" }, "type": "array" } }, "required": [ "data", "warnings" ], "type": "object" } } }, "description": "The export and its warnings" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes adp_settings_missing, all_caregivers_contractors, export_already_finalized, no_approved_timesheets: Unprocessable Content, as the operation's description says." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code internal_error: a failure on our side, which was logged. When its message says nothing changed (the file store refused the request, the virus scan could not be queued, the upload could not be read), nothing did, the same request fails the same way until it is fixed, and the Idempotency-Key stays free." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code storage_unavailable (the file store did not answer) or, on an upload, temporarily_unavailable (its uploaded file could not be read): nothing changed, and the same request can succeed later. Retry after the Retry-After seconds; a write retried with the same Idempotency-Key runs again.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (30).", "schema": { "type": "integer" }, "style": "simple" } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Generate a payroll export's ADP file", "tags": [ "Payroll", "Payroll exports" ] } }, "/api/v1/payroll-exports/{id}/mark-exported": { "post": { "callbacks": {}, "description": "As Payroll exports does once the file is uploaded to ADP. With record_repayments true, the cash advances the payroll deducts are then repaid in one transaction, and cash_advance_repayments_recorded counts them; if that fails, none is recorded, the export stays marked exported, and warnings says so. A caregiver the file deducted more from than was still owed is named in warnings, as the repayment is capped at the balance. Marking it again records no second repayment. Another agency's record answers 404 and nothing is written.", "operationId": "postPayrollExportsByIdMarkExported", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "record_repayments": { "description": "true also records, for the payroll that deducts the month's cash advances, a repayment of each advance for its remaining balance, dated the period end and naming the export, as Payroll exports' Mark Downloaded does with its box checked. Default false.", "type": "boolean" } }, "type": "object" } } }, "description": "Options", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cash_advance_repayments_recorded": { "description": "With record_repayments true, how many repayments were recorded.", "type": "integer" }, "data": { "properties": { "adp_co_code": { "nullable": true, "type": "string" }, "billing_period_end": { "format": "date", "nullable": true, "type": "string" }, "billing_period_start": { "format": "date", "nullable": true, "type": "string" }, "file_ready": { "description": "Whether GET .../file has a file to return.", "type": "boolean" }, "format": { "description": "adp (Workforce Now) or adp_run.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "status": { "description": "pending, generated or exported.", "nullable": true, "type": "string" } }, "title": "PayrollExport", "type": "object" }, "warnings": { "items": { "nullable": true, "type": "string" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The export" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Mark a payroll export sent to ADP", "tags": [ "Payroll", "Payroll exports" ] } }, "/api/v1/payroll-exports/{id}/submissions": { "post": { "callbacks": {}, "description": "As Payroll exports > Send to ADP does: checks the generated export, then queues one line per caregiver to post to ADP and answers the submission at once; poll GET /payroll-exports/{id}/submissions/{submission_id} for each line's result. A caregiver the check refuses, or with no linked ADP worker, is a refused line and the rest go. A press while a send of the export is a standing send answers that send; one ADP already has answers the last send with unchanged true. With resend true, as Fix and resend does: reads what ADP holds for the period, then replaces each line ADP accepted before by its item ids and adds the rest, superseding the earlier send. 409 needs_choice (details.lines, both figures per caregiver) when a line's hours in ADP are not what was sent; send again with choices. 409 resend_required when the hours changed after a send ADP holds lines of (use resend), 409 awaiting_confirmation while an earlier send is unconfirmed, 409 export_exported for an export marked downloaded, 502 read_back_failed when ADP did not answer the read-back. On an SFTP drop connection the send uploads the export's Workforce Now paydata file to the agency's ADP folder once: every caregiver in the file is a sent line, and the export is not marked exported; once ADP holds the file, resend answers 409 not_replaceable. 422 unsendable (with the findings' messages) when the check finds an export ADP cannot take, 422 not_sendable_status for an export that is not generated. Any member at full access, with a key or a grant holding hcb.submit; 403 submission_blocked while the agency's HomeCareBilling billing blocks submission (Download for ADP still works), 403 read_only for a read-only agency or key, 403 insufficient_scope for a grant without hcb.submit; 404 for an export or submission this agency does not have; 409 payroll_integration_off while the agency's ADP API connection is off; 409 not_api_connection while it sends payroll by file.", "operationId": "postPayrollExportsByIdSubmissions", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "choices": { "additionalProperties": { "enum": [ "replace", "keep" ], "type": "string" }, "description": "Per caregiver id, replace (HomeCareBilling's hours) or keep (ADP's), for each line a 409 needs_choice listed.", "type": "object" }, "resend": { "description": "true for Fix and resend: lines ADP accepted before are replaced by their ADP item ids, new ones added.", "type": "boolean" } }, "title": "PayrollSubmissionInput", "type": "object" } } }, "description": "Nothing to send; resend and choices for Fix and resend", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "attempt": { "description": "1 for the first send of the export, one more per resend.", "nullable": true, "type": "integer" }, "confirmed_at": { "description": "When every line was answered.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "line_count": { "description": "How many caregivers' lines the submission has.", "nullable": true, "type": "integer" }, "lines": { "items": { "properties": { "caregiver_id": { "description": "The caregiver the line pays.", "format": "uuid", "nullable": true, "type": "string" }, "error_code": { "description": "ADP's code, or HomeCareBilling's when it never reached ADP.", "nullable": true, "type": "string" }, "error_message": { "description": "Why the line was refused.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "label": { "description": "What Payroll exports shows for the line.", "nullable": true, "type": "string" }, "status": { "description": "pending and posting while it goes; accepted; refused by ADP, or before it was posted (error_code not_sent, not_linked or a check rule); unconfirmed while a post that may have been written is confirmed; sent when dropped as a file.", "enum": [ "pending", "posting", "accepted", "refused", "unconfirmed", "sent" ], "type": "string" } }, "required": [ "id", "status", "label" ], "title": "PayrollSubmissionLine", "type": "object" }, "type": "array" }, "message": { "description": "With unchanged: what Payroll exports shows.", "nullable": true, "type": "string" }, "payroll_export_id": { "description": "The payroll export sent.", "format": "uuid", "type": "string" }, "sent_at": { "description": "When posting began.", "format": "date-time", "nullable": true, "type": "string" }, "status": { "description": "queued and sending while it goes; sent when ADP accepted every line, partially_refused or refused when it refused some or all; unconfirmed when a post may have been written and is being confirmed; superseded once a resend replaced it.", "enum": [ "queued", "sending", "sent", "partially_refused", "refused", "unconfirmed", "superseded" ], "type": "string" }, "unchanged": { "description": "Present and true when ADP already had these hours: nothing was sent, and this is the last send that ADP accepted in full.", "type": "boolean" } }, "required": [ "id", "payroll_export_id", "status", "attempt", "line_count", "lines" ], "title": "PayrollSubmission", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The submission" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes insufficient_scope, read_only, submission_blocked: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes awaiting_confirmation, export_exported, needs_choice, not_api_connection, not_replaceable, payroll_integration_off, resend_required: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_sendable_status: Unprocessable Content, as the operation's description says." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code read_back_failed: Bad Gateway, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Send a payroll export to ADP", "tags": [ "Payroll", "Payroll exports" ] } }, "/api/v1/payroll-exports/{id}/submissions/{submission_id}": { "get": { "callbacks": {}, "description": "As Payroll exports shows a send's results: the submission's status and, per caregiver, the line's status, label and ADP's error, never the hours or rates posted. Changes nothing: any member at every access level. 404 for an export or submission this agency does not have; 409 payroll_integration_off while the agency's ADP API connection is off.", "operationId": "getPayrollExportsByIdSubmissionsBySubmissionId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The submission's id.", "in": "path", "name": "submission_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 50, at most 100; a larger value is served as 100).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "attempt": { "description": "1 for the first send of the export, one more per resend.", "nullable": true, "type": "integer" }, "confirmed_at": { "description": "When every line was answered.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "line_count": { "description": "How many caregivers' lines the submission has.", "nullable": true, "type": "integer" }, "lines": { "items": { "properties": { "caregiver_id": { "description": "The caregiver the line pays.", "format": "uuid", "nullable": true, "type": "string" }, "error_code": { "description": "ADP's code, or HomeCareBilling's when it never reached ADP.", "nullable": true, "type": "string" }, "error_message": { "description": "Why the line was refused.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "label": { "description": "What Payroll exports shows for the line.", "nullable": true, "type": "string" }, "status": { "description": "pending and posting while it goes; accepted; refused by ADP, or before it was posted (error_code not_sent, not_linked or a check rule); unconfirmed while a post that may have been written is confirmed; sent when dropped as a file.", "enum": [ "pending", "posting", "accepted", "refused", "unconfirmed", "sent" ], "type": "string" } }, "required": [ "id", "status", "label" ], "title": "PayrollSubmissionLine", "type": "object" }, "type": "array" }, "message": { "description": "With unchanged: what Payroll exports shows.", "nullable": true, "type": "string" }, "payroll_export_id": { "description": "The payroll export sent.", "format": "uuid", "type": "string" }, "sent_at": { "description": "When posting began.", "format": "date-time", "nullable": true, "type": "string" }, "status": { "description": "queued and sending while it goes; sent when ADP accepted every line, partially_refused or refused when it refused some or all; unconfirmed when a post may have been written and is being confirmed; superseded once a resend replaced it.", "enum": [ "queued", "sending", "sent", "partially_refused", "refused", "unconfirmed", "superseded" ], "type": "string" }, "unchanged": { "description": "Present and true when ADP already had these hours: nothing was sent, and this is the last send that ADP accepted in full.", "type": "boolean" } }, "required": [ "id", "payroll_export_id", "status", "attempt", "line_count", "lines" ], "title": "PayrollSubmission", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The submission" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code payroll_integration_off: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read a send to ADP and its lines", "tags": [ "Payroll", "Payroll exports" ] } }, "/api/v1/payroll-summary": { "get": { "callbacks": {}, "description": "US-102.37: each caregiver's hours, rates, pay and cash advance, as the Payroll Summary page computes them, sorted by name and paged; totals are over every row. period is \"month\" (or absent) for the whole month or a pay period's index (pay_periods lists them, from the agency's pay period frequency); anything else is the whole month, and period_start and period_end say which was read. A cash advance another payroll file holds is in the row's cash_advance_held, worded as the page words it, and is not in cash_advance or the totals.", "operationId": "getPayrollSummary", "parameters": [ { "description": "The payroll month's year.", "in": "query", "name": "year", "required": true, "schema": { "maximum": 2100, "minimum": 2000, "type": "integer" } }, { "description": "The payroll month, 1 to 12.", "in": "query", "name": "month", "required": true, "schema": { "maximum": 12, "minimum": 1, "type": "integer" } }, { "description": "\"month\" for the whole month, or a pay period's index (0, 1, ...).", "in": "query", "name": "period", "schema": { "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "adp_left_out": { "description": "The 1099 contractors the ADP files leave out over every row of the period, and their hours.", "properties": { "count": { "description": "How many contractors.", "nullable": true, "type": "integer" }, "hours": { "description": "Their hours, all regular.", "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "data": { "items": { "$ref": "#/components/schemas/PayrollSummaryRow" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "pay_periods": { "description": "The month's pay periods, from the agency's pay period frequency.", "items": { "properties": { "index": { "description": "The period's index, the period parameter that reads it.", "nullable": true, "type": "integer" }, "period_end": { "format": "date", "nullable": true, "type": "string" }, "period_start": { "format": "date", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "period_end": { "description": "The last day read.", "format": "date", "nullable": true, "type": "string" }, "period_start": { "description": "The first day read.", "format": "date", "nullable": true, "type": "string" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" }, "totals": { "description": "Over every row of the period, not this page; a row with no pay counts 0 in total_pay.", "properties": { "attendant_hours": { "format": "decimal", "nullable": true, "type": "string" }, "cash_advance": { "format": "decimal", "nullable": true, "type": "string" }, "daily_overtime_hours": { "format": "decimal", "nullable": true, "type": "string" }, "overtime_hours": { "format": "decimal", "nullable": true, "type": "string" }, "regular_hours": { "format": "decimal", "nullable": true, "type": "string" }, "total_pay": { "format": "decimal", "nullable": true, "type": "string" }, "travel_hours": { "format": "decimal", "nullable": true, "type": "string" } }, "type": "object" }, "warnings": { "description": "The page's attendant classification warnings.", "items": { "nullable": true, "type": "string" }, "type": "array" } }, "required": [ "period_start", "period_end", "pay_periods", "totals", "warnings", "data", "limit", "offset", "total" ], "title": "PayrollSummaryPage", "type": "object" } } }, "description": "A page of the Payroll Summary" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read the Payroll Summary of a month or one of its pay periods", "tags": [ "Payroll" ] } }, "/api/v1/payroll/connection": { "get": { "callbacks": {}, "description": "As Settings > Payroll shows it: which ADP the agency runs, how payroll reaches it, the methods offered, the file settings, and whether each secret is set (never its value). An agency with no connection yet gets one, sent as a file to an unknown ADP. Credentials whose member holds agency_settings.manage only (403 forbidden otherwise); 409 payroll_integration_off while the ADP payroll integration is off for the agency.", "operationId": "getPayrollConnection", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "certificate_expires_at": { "description": "When the ADP API certificate expires; null when there is none (own_api only).", "format": "date-time", "nullable": true, "type": "string" }, "enabled": { "description": "Whether the ADP payroll integration is on for the agency (Settings > Payroll's switch).", "type": "boolean" }, "health": { "properties": { "certificate_expires_at": { "description": "When the ADP API certificate expires.", "format": "date-time", "nullable": true, "type": "string" }, "consecutive_failures": { "description": "Failures since the last success.", "nullable": true, "type": "integer" }, "last_failure_at": { "description": "The last failed one.", "format": "date-time", "nullable": true, "type": "string" }, "last_success_at": { "description": "The last successful token request or call to ADP.", "format": "date-time", "nullable": true, "type": "string" }, "message": { "description": "The sentence the reconnect banner shows while the connection needs attention; null otherwise.", "nullable": true, "type": "string" }, "paused_until": { "description": "While ADP is not answering and HomeCareBilling has paused calls to it, when it tries again; null otherwise.", "format": "date-time", "nullable": true, "type": "string" }, "status": { "description": "The connection's state.", "enum": [ "pending_subscription", "pending_consent", "active", "needs_attention", "disconnected" ], "type": "string" }, "status_reason": { "description": "Why the connection needs attention: token_refused, circuit_open, certificate_expired, method_paused, or the code Test connection recorded; null otherwise.", "nullable": true, "type": "string" } }, "required": [ "status", "last_success_at", "last_failure_at", "consecutive_failures", "certificate_expires_at", "status_reason", "message", "paused_until" ], "title": "PayrollConnectionHealth", "type": "object" }, "method": { "description": "How payroll reaches ADP.", "enum": [ "file", "sftp_drop", "own_api", "marketplace" ], "type": "string" }, "methods_offered": { "description": "The sending methods Settings > Payroll offers for this product: built, fitting the product and switched on.", "items": { "type": "string" }, "type": "array" }, "notice": { "description": "On a change, \"Sending switched to the file, because that method is not offered for this ADP.\" when the method was not offered for the product and the file was stored instead (or, when the marketplace is kept for an ADP product other than the one the agency's ADP Marketplace subscription is for, a sentence naming both products: the connection waits for that product's order); otherwise null.", "nullable": true, "type": "string" }, "product": { "description": "Which ADP the agency runs: run, wfn or unknown.", "enum": [ "run", "wfn", "wfn_next_gen", "unknown" ], "type": "string" }, "secrets_set": { "properties": { "certificate_pem": { "description": "Whether certificate_pem is set. The value is never answered.", "type": "boolean" }, "client_id": { "description": "Whether client_id is set. The value is never answered.", "type": "boolean" }, "client_secret": { "description": "Whether client_secret is set. The value is never answered.", "type": "boolean" }, "private_key_pem": { "description": "Whether private_key_pem is set. The value is never answered.", "type": "boolean" }, "sftp_private_key": { "description": "Whether sftp_private_key is set. The value is never answered.", "type": "boolean" } }, "required": [ "client_id", "client_secret", "certificate_pem", "private_key_pem", "sftp_private_key" ], "title": "PayrollConnectionSecretsSet", "type": "object" }, "settings": { "properties": { "allow_hire_push": { "description": "Whether a caregiver may be added to ADP from HomeCareBilling (RUN's Add to ADP).", "type": "boolean" }, "employee_id_template": { "description": "Which RUN Time Sheet Import template keys each caregiver: payroll_assigned (ADP's Employee ID) or time_clock (the Time Clock ID).", "enum": [ "payroll_assigned", "time_clock" ], "type": "string" }, "mark_exported_on": { "description": "When a sent export is marked exported.", "enum": [ "all_accepted", "manual" ], "type": "string" }, "rate_mode": { "description": "How API methods send a pay rate.", "enum": [ "rate_value", "rate_code" ], "type": "string" }, "rate_tolerance": { "description": "How far ADP's rate may differ from HomeCareBilling's before a warning.", "format": "decimal", "nullable": true, "type": "string" }, "run_company_code": { "description": "RUN's company code or IID, 1 to 10 letters and numbers; null when unset.", "nullable": true, "type": "string" }, "run_file_version": { "description": "The RUN Time Sheet Import file version.", "enum": [ "V1.0", "V2.0" ], "type": "string" }, "send_contractors": { "description": "Whether 1099 contractors' hours go to ADP too.", "type": "boolean" }, "sftp_folder": { "description": "The SFTP drop's folder; null when unset.", "nullable": true, "type": "string" }, "sftp_host": { "description": "The SFTP drop's host; null when unset.", "nullable": true, "type": "string" }, "sftp_host_key_fingerprint": { "description": "The SHA-256 host key fingerprint the SFTP server presented at the first successful Test connection, trusted from then on; null until then.", "nullable": true, "type": "string" }, "sftp_port": { "description": "The SFTP drop's port, 1 to 65535; null when unset, which connects on 22.", "nullable": true, "type": "integer" }, "sftp_user": { "description": "The SFTP drop's user; null when unset.", "nullable": true, "type": "string" } }, "required": [ "run_company_code", "employee_id_template", "run_file_version", "rate_mode", "mark_exported_on", "send_contractors", "allow_hire_push", "rate_tolerance", "sftp_host", "sftp_user", "sftp_folder", "sftp_host_key_fingerprint", "sftp_port" ], "title": "PayrollConnectionSettings", "type": "object" }, "sftp_key_fingerprint": { "description": "The SHA-256 fingerprint (SHA256:..., as ssh-keygen -lf prints it) of the SFTP drop key's public half; null when no key is set. The key is never answered.", "nullable": true, "type": "string" }, "status": { "description": "The connection's state.", "enum": [ "pending_subscription", "pending_consent", "active", "needs_attention", "disconnected" ], "type": "string" } }, "required": [ "enabled", "product", "method", "status", "methods_offered", "settings", "certificate_expires_at", "secrets_set", "sftp_key_fingerprint", "health", "notice" ], "title": "PayrollConnection", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The connection" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code payroll_integration_off: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read the ADP payroll connection", "tags": [ "Payroll" ] }, "patch": { "callbacks": {}, "description": "As Settings > Payroll's Save and switch do, through the same checks; send only what changes. A RUN company code that is not 1 to 10 letters and numbers answers 422 naming run_company_code; a method not offered for the product stores file, and notice says so. A body turning enabled on is taken while the integration is off for the agency, when the platform and its plan allow it. Credentials whose member holds agency_settings.manage only (403 forbidden otherwise); 409 payroll_integration_off while the ADP payroll integration is off for the agency.", "operationId": "patchPayrollConnection", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "allow_hire_push": { "description": "RUN: let HomeCareBilling start new hires in RUN (Add to ADP on ADP workers), which sends the caregiver's SSN. Off by default.", "type": "boolean" }, "employee_id_template": { "description": "payroll_assigned (ADP's Employee ID, the default) or time_clock (the Time Clock ID).", "enum": [ "payroll_assigned", "time_clock" ], "type": "string" }, "enabled": { "description": "Turn the ADP payroll integration on or off for the agency. Off keeps the connection, its settings and earning codes.", "type": "boolean" }, "mark_exported_on": { "description": "API methods: all_accepted (the default) marks the export exported when ADP accepts every line; manual leaves it to Mark Downloaded.", "enum": [ "all_accepted", "manual" ], "type": "string" }, "method": { "description": "How payroll reaches ADP; one of methods_offered. Any other is stored as file, with notice saying so.", "enum": [ "file", "sftp_drop", "own_api", "marketplace" ], "type": "string" }, "product": { "description": "Which ADP the agency runs: run (signs in at runpayroll.adp.com), wfn (workforcenow.adp.com) or unknown.", "enum": [ "run", "wfn", "unknown" ], "type": "string" }, "run_company_code": { "description": "RUN's company code or IID, 1 to 10 letters and numbers; null or blank clears it.", "nullable": true, "type": "string" }, "run_file_version": { "description": "The RUN Time Sheet Import file version.", "enum": [ "V1.0", "V2.0" ], "type": "string" }, "send_contractors": { "description": "Send 1099 contractors' hours to ADP too.", "type": "boolean" } }, "title": "PayrollConnectionUpdate", "type": "object" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "certificate_expires_at": { "description": "When the ADP API certificate expires; null when there is none (own_api only).", "format": "date-time", "nullable": true, "type": "string" }, "enabled": { "description": "Whether the ADP payroll integration is on for the agency (Settings > Payroll's switch).", "type": "boolean" }, "health": { "properties": { "certificate_expires_at": { "description": "When the ADP API certificate expires.", "format": "date-time", "nullable": true, "type": "string" }, "consecutive_failures": { "description": "Failures since the last success.", "nullable": true, "type": "integer" }, "last_failure_at": { "description": "The last failed one.", "format": "date-time", "nullable": true, "type": "string" }, "last_success_at": { "description": "The last successful token request or call to ADP.", "format": "date-time", "nullable": true, "type": "string" }, "message": { "description": "The sentence the reconnect banner shows while the connection needs attention; null otherwise.", "nullable": true, "type": "string" }, "paused_until": { "description": "While ADP is not answering and HomeCareBilling has paused calls to it, when it tries again; null otherwise.", "format": "date-time", "nullable": true, "type": "string" }, "status": { "description": "The connection's state.", "enum": [ "pending_subscription", "pending_consent", "active", "needs_attention", "disconnected" ], "type": "string" }, "status_reason": { "description": "Why the connection needs attention: token_refused, circuit_open, certificate_expired, method_paused, or the code Test connection recorded; null otherwise.", "nullable": true, "type": "string" } }, "required": [ "status", "last_success_at", "last_failure_at", "consecutive_failures", "certificate_expires_at", "status_reason", "message", "paused_until" ], "title": "PayrollConnectionHealth", "type": "object" }, "method": { "description": "How payroll reaches ADP.", "enum": [ "file", "sftp_drop", "own_api", "marketplace" ], "type": "string" }, "methods_offered": { "description": "The sending methods Settings > Payroll offers for this product: built, fitting the product and switched on.", "items": { "type": "string" }, "type": "array" }, "notice": { "description": "On a change, \"Sending switched to the file, because that method is not offered for this ADP.\" when the method was not offered for the product and the file was stored instead (or, when the marketplace is kept for an ADP product other than the one the agency's ADP Marketplace subscription is for, a sentence naming both products: the connection waits for that product's order); otherwise null.", "nullable": true, "type": "string" }, "product": { "description": "Which ADP the agency runs: run, wfn or unknown.", "enum": [ "run", "wfn", "wfn_next_gen", "unknown" ], "type": "string" }, "secrets_set": { "properties": { "certificate_pem": { "description": "Whether certificate_pem is set. The value is never answered.", "type": "boolean" }, "client_id": { "description": "Whether client_id is set. The value is never answered.", "type": "boolean" }, "client_secret": { "description": "Whether client_secret is set. The value is never answered.", "type": "boolean" }, "private_key_pem": { "description": "Whether private_key_pem is set. The value is never answered.", "type": "boolean" }, "sftp_private_key": { "description": "Whether sftp_private_key is set. The value is never answered.", "type": "boolean" } }, "required": [ "client_id", "client_secret", "certificate_pem", "private_key_pem", "sftp_private_key" ], "title": "PayrollConnectionSecretsSet", "type": "object" }, "settings": { "properties": { "allow_hire_push": { "description": "Whether a caregiver may be added to ADP from HomeCareBilling (RUN's Add to ADP).", "type": "boolean" }, "employee_id_template": { "description": "Which RUN Time Sheet Import template keys each caregiver: payroll_assigned (ADP's Employee ID) or time_clock (the Time Clock ID).", "enum": [ "payroll_assigned", "time_clock" ], "type": "string" }, "mark_exported_on": { "description": "When a sent export is marked exported.", "enum": [ "all_accepted", "manual" ], "type": "string" }, "rate_mode": { "description": "How API methods send a pay rate.", "enum": [ "rate_value", "rate_code" ], "type": "string" }, "rate_tolerance": { "description": "How far ADP's rate may differ from HomeCareBilling's before a warning.", "format": "decimal", "nullable": true, "type": "string" }, "run_company_code": { "description": "RUN's company code or IID, 1 to 10 letters and numbers; null when unset.", "nullable": true, "type": "string" }, "run_file_version": { "description": "The RUN Time Sheet Import file version.", "enum": [ "V1.0", "V2.0" ], "type": "string" }, "send_contractors": { "description": "Whether 1099 contractors' hours go to ADP too.", "type": "boolean" }, "sftp_folder": { "description": "The SFTP drop's folder; null when unset.", "nullable": true, "type": "string" }, "sftp_host": { "description": "The SFTP drop's host; null when unset.", "nullable": true, "type": "string" }, "sftp_host_key_fingerprint": { "description": "The SHA-256 host key fingerprint the SFTP server presented at the first successful Test connection, trusted from then on; null until then.", "nullable": true, "type": "string" }, "sftp_port": { "description": "The SFTP drop's port, 1 to 65535; null when unset, which connects on 22.", "nullable": true, "type": "integer" }, "sftp_user": { "description": "The SFTP drop's user; null when unset.", "nullable": true, "type": "string" } }, "required": [ "run_company_code", "employee_id_template", "run_file_version", "rate_mode", "mark_exported_on", "send_contractors", "allow_hire_push", "rate_tolerance", "sftp_host", "sftp_user", "sftp_folder", "sftp_host_key_fingerprint", "sftp_port" ], "title": "PayrollConnectionSettings", "type": "object" }, "sftp_key_fingerprint": { "description": "The SHA-256 fingerprint (SHA256:..., as ssh-keygen -lf prints it) of the SFTP drop key's public half; null when no key is set. The key is never answered.", "nullable": true, "type": "string" }, "status": { "description": "The connection's state.", "enum": [ "pending_subscription", "pending_consent", "active", "needs_attention", "disconnected" ], "type": "string" } }, "required": [ "enabled", "product", "method", "status", "methods_offered", "settings", "certificate_expires_at", "secrets_set", "sftp_key_fingerprint", "health", "notice" ], "title": "PayrollConnection", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The connection as saved" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code payroll_integration_off: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change the ADP payroll connection", "tags": [ "Payroll" ] } }, "/api/v1/payroll/connection/connect-code": { "post": { "callbacks": {}, "description": "As Settings > Payroll's Connect in ADP Marketplace does: a new single-use code to paste into the ADP Marketplace checkout form when buying HomeCareBilling's connector, and when it expires (7 days). A new code replaces the old one, and the connection waits for its ADP Marketplace order. The code is answered once and never stored. Issued only where the tab offers one: 409 marketplace_not_offered unless the connection's ADP product is RUN and HomeCareBilling's ADP Marketplace listing is set; 409 already_connected while the connection is connected through ADP Marketplace, waiting for its ADP administrator's consent, or needs attention (a new code would stop its sending); nothing changes either way. Credentials whose member holds agency_settings.manage only (403 forbidden otherwise); 409 payroll_integration_off while connecting through ADP Marketplace is off for the agency.", "operationId": "postPayrollConnectionConnectCode", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "connect_code": { "description": "The single-use code to paste into the ADP Marketplace checkout form. Answered only here, never stored or shown again; a new code replaces the old.", "nullable": true, "type": "string" }, "expires_at": { "description": "When the code stops working, 7 days after it was made.", "format": "date-time", "type": "string" } }, "required": [ "connect_code", "expires_at" ], "title": "PayrollConnectCode", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The code" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_connected, marketplace_not_offered, payroll_integration_off: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get an ADP Marketplace connect code", "tags": [ "Payroll" ] } }, "/api/v1/payroll/connection/credentials": { "put": { "callbacks": {}, "description": "As Settings > Payroll's credentials do: the client ID and secret API Central issued and the certificate it signed for the request from POST /payroll/connection/csr; send only what changes. A certificate that is not one, fits neither HomeCareBilling's request nor its current key, or has expired answers 422 invalid_certificate with the tab's sentence, and nothing is saved. Answers the connection, never a secret. Credentials whose member holds agency_settings.manage only (403 forbidden otherwise); 409 payroll_integration_off while sending with the agency's own API credentials is off for it.", "operationId": "putPayrollConnectionCredentials", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "certificate_pem": { "description": "The certificate API Central signed for the request from POST /payroll/connection/csr, PEM; absent or blank keeps the saved one.", "nullable": true, "type": "string" }, "client_id": { "description": "The API Central project's client ID; absent or blank keeps the saved one.", "nullable": true, "type": "string" }, "client_secret": { "description": "The API Central project's client secret; absent or blank keeps the saved one. Never answered.", "nullable": true, "type": "string" } }, "title": "PayrollCredentialsUpdate", "type": "object" } } }, "description": "What API Central issued", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "certificate_expires_at": { "description": "When the ADP API certificate expires; null when there is none (own_api only).", "format": "date-time", "nullable": true, "type": "string" }, "enabled": { "description": "Whether the ADP payroll integration is on for the agency (Settings > Payroll's switch).", "type": "boolean" }, "health": { "properties": { "certificate_expires_at": { "description": "When the ADP API certificate expires.", "format": "date-time", "nullable": true, "type": "string" }, "consecutive_failures": { "description": "Failures since the last success.", "nullable": true, "type": "integer" }, "last_failure_at": { "description": "The last failed one.", "format": "date-time", "nullable": true, "type": "string" }, "last_success_at": { "description": "The last successful token request or call to ADP.", "format": "date-time", "nullable": true, "type": "string" }, "message": { "description": "The sentence the reconnect banner shows while the connection needs attention; null otherwise.", "nullable": true, "type": "string" }, "paused_until": { "description": "While ADP is not answering and HomeCareBilling has paused calls to it, when it tries again; null otherwise.", "format": "date-time", "nullable": true, "type": "string" }, "status": { "description": "The connection's state.", "enum": [ "pending_subscription", "pending_consent", "active", "needs_attention", "disconnected" ], "type": "string" }, "status_reason": { "description": "Why the connection needs attention: token_refused, circuit_open, certificate_expired, method_paused, or the code Test connection recorded; null otherwise.", "nullable": true, "type": "string" } }, "required": [ "status", "last_success_at", "last_failure_at", "consecutive_failures", "certificate_expires_at", "status_reason", "message", "paused_until" ], "title": "PayrollConnectionHealth", "type": "object" }, "method": { "description": "How payroll reaches ADP.", "enum": [ "file", "sftp_drop", "own_api", "marketplace" ], "type": "string" }, "methods_offered": { "description": "The sending methods Settings > Payroll offers for this product: built, fitting the product and switched on.", "items": { "type": "string" }, "type": "array" }, "notice": { "description": "On a change, \"Sending switched to the file, because that method is not offered for this ADP.\" when the method was not offered for the product and the file was stored instead (or, when the marketplace is kept for an ADP product other than the one the agency's ADP Marketplace subscription is for, a sentence naming both products: the connection waits for that product's order); otherwise null.", "nullable": true, "type": "string" }, "product": { "description": "Which ADP the agency runs: run, wfn or unknown.", "enum": [ "run", "wfn", "wfn_next_gen", "unknown" ], "type": "string" }, "secrets_set": { "properties": { "certificate_pem": { "description": "Whether certificate_pem is set. The value is never answered.", "type": "boolean" }, "client_id": { "description": "Whether client_id is set. The value is never answered.", "type": "boolean" }, "client_secret": { "description": "Whether client_secret is set. The value is never answered.", "type": "boolean" }, "private_key_pem": { "description": "Whether private_key_pem is set. The value is never answered.", "type": "boolean" }, "sftp_private_key": { "description": "Whether sftp_private_key is set. The value is never answered.", "type": "boolean" } }, "required": [ "client_id", "client_secret", "certificate_pem", "private_key_pem", "sftp_private_key" ], "title": "PayrollConnectionSecretsSet", "type": "object" }, "settings": { "properties": { "allow_hire_push": { "description": "Whether a caregiver may be added to ADP from HomeCareBilling (RUN's Add to ADP).", "type": "boolean" }, "employee_id_template": { "description": "Which RUN Time Sheet Import template keys each caregiver: payroll_assigned (ADP's Employee ID) or time_clock (the Time Clock ID).", "enum": [ "payroll_assigned", "time_clock" ], "type": "string" }, "mark_exported_on": { "description": "When a sent export is marked exported.", "enum": [ "all_accepted", "manual" ], "type": "string" }, "rate_mode": { "description": "How API methods send a pay rate.", "enum": [ "rate_value", "rate_code" ], "type": "string" }, "rate_tolerance": { "description": "How far ADP's rate may differ from HomeCareBilling's before a warning.", "format": "decimal", "nullable": true, "type": "string" }, "run_company_code": { "description": "RUN's company code or IID, 1 to 10 letters and numbers; null when unset.", "nullable": true, "type": "string" }, "run_file_version": { "description": "The RUN Time Sheet Import file version.", "enum": [ "V1.0", "V2.0" ], "type": "string" }, "send_contractors": { "description": "Whether 1099 contractors' hours go to ADP too.", "type": "boolean" }, "sftp_folder": { "description": "The SFTP drop's folder; null when unset.", "nullable": true, "type": "string" }, "sftp_host": { "description": "The SFTP drop's host; null when unset.", "nullable": true, "type": "string" }, "sftp_host_key_fingerprint": { "description": "The SHA-256 host key fingerprint the SFTP server presented at the first successful Test connection, trusted from then on; null until then.", "nullable": true, "type": "string" }, "sftp_port": { "description": "The SFTP drop's port, 1 to 65535; null when unset, which connects on 22.", "nullable": true, "type": "integer" }, "sftp_user": { "description": "The SFTP drop's user; null when unset.", "nullable": true, "type": "string" } }, "required": [ "run_company_code", "employee_id_template", "run_file_version", "rate_mode", "mark_exported_on", "send_contractors", "allow_hire_push", "rate_tolerance", "sftp_host", "sftp_user", "sftp_folder", "sftp_host_key_fingerprint", "sftp_port" ], "title": "PayrollConnectionSettings", "type": "object" }, "sftp_key_fingerprint": { "description": "The SHA-256 fingerprint (SHA256:..., as ssh-keygen -lf prints it) of the SFTP drop key's public half; null when no key is set. The key is never answered.", "nullable": true, "type": "string" }, "status": { "description": "The connection's state.", "enum": [ "pending_subscription", "pending_consent", "active", "needs_attention", "disconnected" ], "type": "string" } }, "required": [ "enabled", "product", "method", "status", "methods_offered", "settings", "certificate_expires_at", "secrets_set", "sftp_key_fingerprint", "health", "notice" ], "title": "PayrollConnection", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The connection as saved" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code payroll_integration_off: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code invalid_certificate: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Save the ADP API Central credentials", "tags": [ "Payroll" ] } }, "/api/v1/payroll/connection/csr": { "post": { "callbacks": {}, "description": "As Settings > Payroll's Create certificate request does: makes a new key pair, keeps its private key in HomeCareBilling, and answers the request to give API Central to sign. A live connection keeps its current key until the certificate signed for this request is saved. Credentials whose member holds agency_settings.manage only (403 forbidden otherwise); 409 payroll_integration_off while sending with the agency's own API credentials is off for it.", "operationId": "postPayrollConnectionCsr", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "csr_pem": { "description": "The certificate request to give API Central, PEM. HomeCareBilling keeps its private key; no answer carries it.", "nullable": true, "type": "string" } }, "required": [ "csr_pem" ], "title": "PayrollCsr", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The request" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code payroll_integration_off: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Make the ADP API Central certificate request", "tags": [ "Payroll" ] } }, "/api/v1/payroll/connection/sftp": { "put": { "callbacks": {}, "description": "As Settings > Payroll's SFTP form does: the host, port, user and folder ADP gave the agency for its Automated Paydata Integration, and the private key file; send only what changes. A key that is not an OpenSSH or PEM private key without a passphrase answers 422 invalid_private_key with the tab's sentence, a port that is not a whole number from 1 to 65535 answers 422 invalid_port, and nothing is saved. A new host or port forgets the trusted host key. Answers the connection: the key only as secrets_set.sftp_private_key and sftp_key_fingerprint, never its value. Credentials whose member holds agency_settings.manage only (403 forbidden otherwise); 409 payroll_integration_off while the SFTP drop is off for the agency.", "operationId": "putPayrollConnectionSftp", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "folder": { "description": "The folder ADP picks paydata files up from; absent, blank or null keeps the saved one.", "nullable": true, "type": "string" }, "host": { "description": "The SFTP server ADP gave the agency, a host name; absent, blank or null keeps the saved one. A new host trusts the next Test connection's host key.", "nullable": true, "type": "string" }, "port": { "description": "The SFTP server's port, 1 to 65535; absent or null keeps the saved one, an empty string clears it, and none saved connects on 22. A new port trusts the next Test connection's host key.", "nullable": true, "oneOf": [ { "maximum": 65535, "minimum": 1, "type": "integer" }, { "maxLength": 0, "type": "string" } ] }, "private_key": { "description": "The private key file ADP gave the agency (OpenSSH or PEM, no passphrase), as text; absent, blank or null keeps the saved one. Never answered.", "nullable": true, "type": "string" }, "user": { "description": "The SFTP user ADP gave the agency; absent, blank or null keeps the saved one.", "nullable": true, "type": "string" } }, "title": "PayrollSftpUpdate", "type": "object" } } }, "description": "The SFTP drop's settings", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "certificate_expires_at": { "description": "When the ADP API certificate expires; null when there is none (own_api only).", "format": "date-time", "nullable": true, "type": "string" }, "enabled": { "description": "Whether the ADP payroll integration is on for the agency (Settings > Payroll's switch).", "type": "boolean" }, "health": { "properties": { "certificate_expires_at": { "description": "When the ADP API certificate expires.", "format": "date-time", "nullable": true, "type": "string" }, "consecutive_failures": { "description": "Failures since the last success.", "nullable": true, "type": "integer" }, "last_failure_at": { "description": "The last failed one.", "format": "date-time", "nullable": true, "type": "string" }, "last_success_at": { "description": "The last successful token request or call to ADP.", "format": "date-time", "nullable": true, "type": "string" }, "message": { "description": "The sentence the reconnect banner shows while the connection needs attention; null otherwise.", "nullable": true, "type": "string" }, "paused_until": { "description": "While ADP is not answering and HomeCareBilling has paused calls to it, when it tries again; null otherwise.", "format": "date-time", "nullable": true, "type": "string" }, "status": { "description": "The connection's state.", "enum": [ "pending_subscription", "pending_consent", "active", "needs_attention", "disconnected" ], "type": "string" }, "status_reason": { "description": "Why the connection needs attention: token_refused, circuit_open, certificate_expired, method_paused, or the code Test connection recorded; null otherwise.", "nullable": true, "type": "string" } }, "required": [ "status", "last_success_at", "last_failure_at", "consecutive_failures", "certificate_expires_at", "status_reason", "message", "paused_until" ], "title": "PayrollConnectionHealth", "type": "object" }, "method": { "description": "How payroll reaches ADP.", "enum": [ "file", "sftp_drop", "own_api", "marketplace" ], "type": "string" }, "methods_offered": { "description": "The sending methods Settings > Payroll offers for this product: built, fitting the product and switched on.", "items": { "type": "string" }, "type": "array" }, "notice": { "description": "On a change, \"Sending switched to the file, because that method is not offered for this ADP.\" when the method was not offered for the product and the file was stored instead (or, when the marketplace is kept for an ADP product other than the one the agency's ADP Marketplace subscription is for, a sentence naming both products: the connection waits for that product's order); otherwise null.", "nullable": true, "type": "string" }, "product": { "description": "Which ADP the agency runs: run, wfn or unknown.", "enum": [ "run", "wfn", "wfn_next_gen", "unknown" ], "type": "string" }, "secrets_set": { "properties": { "certificate_pem": { "description": "Whether certificate_pem is set. The value is never answered.", "type": "boolean" }, "client_id": { "description": "Whether client_id is set. The value is never answered.", "type": "boolean" }, "client_secret": { "description": "Whether client_secret is set. The value is never answered.", "type": "boolean" }, "private_key_pem": { "description": "Whether private_key_pem is set. The value is never answered.", "type": "boolean" }, "sftp_private_key": { "description": "Whether sftp_private_key is set. The value is never answered.", "type": "boolean" } }, "required": [ "client_id", "client_secret", "certificate_pem", "private_key_pem", "sftp_private_key" ], "title": "PayrollConnectionSecretsSet", "type": "object" }, "settings": { "properties": { "allow_hire_push": { "description": "Whether a caregiver may be added to ADP from HomeCareBilling (RUN's Add to ADP).", "type": "boolean" }, "employee_id_template": { "description": "Which RUN Time Sheet Import template keys each caregiver: payroll_assigned (ADP's Employee ID) or time_clock (the Time Clock ID).", "enum": [ "payroll_assigned", "time_clock" ], "type": "string" }, "mark_exported_on": { "description": "When a sent export is marked exported.", "enum": [ "all_accepted", "manual" ], "type": "string" }, "rate_mode": { "description": "How API methods send a pay rate.", "enum": [ "rate_value", "rate_code" ], "type": "string" }, "rate_tolerance": { "description": "How far ADP's rate may differ from HomeCareBilling's before a warning.", "format": "decimal", "nullable": true, "type": "string" }, "run_company_code": { "description": "RUN's company code or IID, 1 to 10 letters and numbers; null when unset.", "nullable": true, "type": "string" }, "run_file_version": { "description": "The RUN Time Sheet Import file version.", "enum": [ "V1.0", "V2.0" ], "type": "string" }, "send_contractors": { "description": "Whether 1099 contractors' hours go to ADP too.", "type": "boolean" }, "sftp_folder": { "description": "The SFTP drop's folder; null when unset.", "nullable": true, "type": "string" }, "sftp_host": { "description": "The SFTP drop's host; null when unset.", "nullable": true, "type": "string" }, "sftp_host_key_fingerprint": { "description": "The SHA-256 host key fingerprint the SFTP server presented at the first successful Test connection, trusted from then on; null until then.", "nullable": true, "type": "string" }, "sftp_port": { "description": "The SFTP drop's port, 1 to 65535; null when unset, which connects on 22.", "nullable": true, "type": "integer" }, "sftp_user": { "description": "The SFTP drop's user; null when unset.", "nullable": true, "type": "string" } }, "required": [ "run_company_code", "employee_id_template", "run_file_version", "rate_mode", "mark_exported_on", "send_contractors", "allow_hire_push", "rate_tolerance", "sftp_host", "sftp_user", "sftp_folder", "sftp_host_key_fingerprint", "sftp_port" ], "title": "PayrollConnectionSettings", "type": "object" }, "sftp_key_fingerprint": { "description": "The SHA-256 fingerprint (SHA256:..., as ssh-keygen -lf prints it) of the SFTP drop key's public half; null when no key is set. The key is never answered.", "nullable": true, "type": "string" }, "status": { "description": "The connection's state.", "enum": [ "pending_subscription", "pending_consent", "active", "needs_attention", "disconnected" ], "type": "string" } }, "required": [ "enabled", "product", "method", "status", "methods_offered", "settings", "certificate_expires_at", "secrets_set", "sftp_key_fingerprint", "health", "notice" ], "title": "PayrollConnection", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The connection as saved" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code payroll_integration_off: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes invalid_port, invalid_private_key: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Save the ADP SFTP drop's settings and key", "tags": [ "Payroll" ] } }, "/api/v1/payroll/connection/test": { "post": { "callbacks": {}, "description": "As Settings > Payroll's Test connection does, for the connection's method. With the agency's own API Central credentials: one read at ADP with the saved credentials, recording the answer on the connection (active on success, needs_attention with the reason on a failure); connected false with the tab's sentence when ADP refused, did not answer, or a credential is missing. With the SFTP drop: signs in with the saved key and lists the folder, answering \"Connected. {folder} holds {count} files.\" or which step failed; the first success trusts the server's host key; nothing is written to the server. 409 not_api_connection, recording nothing, while the connection sends payroll by file. Credentials whose member holds agency_settings.manage only (403 forbidden otherwise); 409 payroll_integration_off while the connection's method is off for the agency.", "operationId": "postPayrollConnectionTest", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "connected": { "description": "Whether ADP answered with the saved credentials, or the SFTP drop signed in and listed its folder.", "type": "boolean" }, "message": { "description": "The sentence Settings > Payroll's Test connection shows.", "nullable": true, "type": "string" } }, "required": [ "connected", "message" ], "title": "PayrollConnectionTest", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "What ADP answered" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes not_api_connection, payroll_integration_off: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Test the ADP connection", "tags": [ "Payroll" ] } }, "/api/v1/payroll/earning-mappings": { "get": { "callbacks": {}, "description": "As /payroll/earnings shows them: all twelve slots, every hour kind for employees then contractors, each the saved code or else HomeCareBilling's proposal (saved false). A fixed set, so not paged. Credentials whose member holds payroll.view or agency_settings.view only (403 forbidden otherwise); 409 payroll_integration_off while the ADP payroll integration is off for the agency.", "operationId": "getPayrollEarningMappings", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "earning_code": { "description": "The ADP earning code carrying these hours; null when the slot is unmapped.", "nullable": true, "type": "string" }, "file_column": { "description": "The Workforce Now file's \"Hours N\" pair, 3 to 50, or null for the file's own column.", "nullable": true, "type": "integer" }, "hour_kind": { "description": "The kind of hours.", "enum": [ "regular", "weekly_overtime", "daily_overtime", "travel", "attendant", "cash_advance" ], "type": "string" }, "rate_code": { "description": "The ADP rate code, or null.", "nullable": true, "type": "string" }, "saved": { "description": "true for a saved code; false for HomeCareBilling's proposal, used until one is saved.", "type": "boolean" }, "source": { "description": "admin when a member saved it, adp_default when read from ADP; null on a proposal.", "enum": [ "adp_default", "admin" ], "nullable": true, "type": "string" }, "worker_type": { "description": "Employees or contractors.", "enum": [ "employee", "contractor" ], "type": "string" } }, "required": [ "hour_kind", "worker_type", "earning_code", "rate_code", "file_column", "source", "saved" ], "title": "PayrollEarningMapping", "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The slots" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code payroll_integration_off: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List the ADP earning mappings", "tags": [ "Payroll" ] }, "put": { "callbacks": {}, "description": "As a row's Save on /payroll/earnings does: sets the slot hour_kind and worker_type name, or clears it with a null or blank earning_code. A refused field answers 422 naming it. Credentials whose member holds agency_settings.manage only (403 forbidden otherwise); 409 payroll_integration_off while the ADP payroll integration is off for the agency.", "operationId": "putPayrollEarningMappings", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "earning_code": { "description": "The ADP earning code, 1 to 10 letters or digits as on your ADP Earnings Codes report (upcased and trimmed); null or blank clears the slot back to its proposal.", "nullable": true, "type": "string" }, "file_column": { "description": "The Workforce Now \"Hours N\" pair, 3 to 50, not used by another slot. Left out keeps it; null clears it.", "nullable": true, "type": "integer" }, "hour_kind": { "description": "The kind of hours to map.", "enum": [ "regular", "weekly_overtime", "daily_overtime", "travel", "attendant", "cash_advance" ], "type": "string" }, "rate_code": { "description": "On RUN, BASE, RATE_2 to RATE_5 or HRLY4SLRY1; elsewhere up to 10 letters, digits or underscores. Left out keeps it; null clears it.", "nullable": true, "type": "string" }, "worker_type": { "description": "employee or contractor.", "enum": [ "employee", "contractor" ], "type": "string" } }, "required": [ "hour_kind", "worker_type", "earning_code" ], "title": "PayrollEarningMappingUpdate", "type": "object" } } }, "description": "The slot and its codes", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "earning_code": { "description": "The ADP earning code carrying these hours; null when the slot is unmapped.", "nullable": true, "type": "string" }, "file_column": { "description": "The Workforce Now file's \"Hours N\" pair, 3 to 50, or null for the file's own column.", "nullable": true, "type": "integer" }, "hour_kind": { "description": "The kind of hours.", "enum": [ "regular", "weekly_overtime", "daily_overtime", "travel", "attendant", "cash_advance" ], "type": "string" }, "rate_code": { "description": "The ADP rate code, or null.", "nullable": true, "type": "string" }, "saved": { "description": "true for a saved code; false for HomeCareBilling's proposal, used until one is saved.", "type": "boolean" }, "source": { "description": "admin when a member saved it, adp_default when read from ADP; null on a proposal.", "enum": [ "adp_default", "admin" ], "nullable": true, "type": "string" }, "worker_type": { "description": "Employees or contractors.", "enum": [ "employee", "contractor" ], "type": "string" } }, "required": [ "hour_kind", "worker_type", "earning_code", "rate_code", "file_column", "source", "saved" ], "title": "PayrollEarningMapping", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The slot as saved" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code payroll_integration_off: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Save one ADP earning mapping", "tags": [ "Payroll" ] } }, "/api/v1/payroll/earning-mappings/sync": { "post": { "callbacks": {}, "description": "As /payroll/earnings' Sync from ADP does: queues a read of the agency's ADP earning codes, rate codes and pay cycles, which proposes the regular and overtime mappings ADP holds and lets Payroll exports > Check compare exports with them. One sync per agency waits at a time. Credentials whose member holds agency_settings.manage only (403 forbidden otherwise); 409 payroll_integration_off while the agency's ADP API connection is off; 409 not_api_connection while it sends payroll by file or SFTP.", "operationId": "postPayrollEarningMappingsSync", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "queued": { "description": "True: the sync is queued, or already waiting to run.", "type": "boolean" } }, "required": [ "queued" ], "title": "PayrollWorkerSync", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Queued" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes not_api_connection, payroll_integration_off: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Sync ADP's earning codes now", "tags": [ "Payroll" ] } }, "/api/v1/payroll/w4-changes": { "get": { "callbacks": {}, "description": "US-102.37: the Payroll Summary's W-4 panel, longest waiting first: each caregiver whose filing status or dependents changed since POST /caregivers/{id}/w4-sent-to-payroll last cleared it, with the values now on file.", "operationId": "getPayrollW4Changes", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/W4Change" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "W4ChangePage", "type": "object" } } }, "description": "A page of W-4 changes" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List the caregivers whose W-4 change payroll has not been sent", "tags": [ "Payroll" ] } }, "/api/v1/payroll/workers": { "get": { "callbacks": {}, "description": "As /payroll/workers lists them, by ADP name: each ADP worker of the agency's API connection with the caregiver it is linked to, how, and the row's warning. filter=no_adp_worker lists instead the caregivers no ADP worker is linked to. Credentials whose member holds payroll.view or agency_settings.view only (403 forbidden otherwise); 409 payroll_integration_off while the agency's ADP API connection is off; 409 not_api_connection while it sends payroll by file or SFTP.", "operationId": "getPayrollWorkers", "parameters": [ { "description": "all (default), needs_person (no caregiver yet), linked, or no_adp_worker (caregivers no ADP worker is linked to).", "in": "query", "name": "filter", "schema": { "enum": [ "all", "needs_person", "linked", "no_adp_worker" ], "type": "string" } }, { "description": "Rows per page (default 50, at most 100; a larger value is served as 100).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "adp_hire_date": { "description": "The hire date ADP holds.", "format": "date", "nullable": true, "type": "string" }, "adp_name": { "description": "The worker's name as ADP spells it.", "nullable": true, "type": "string" }, "adp_status": { "description": "The worker's status in ADP.", "enum": [ "active", "leave", "terminated" ], "nullable": true, "type": "string" }, "adp_status_date": { "description": "When that status began, in ADP.", "format": "date", "nullable": true, "type": "string" }, "adp_worker_id": { "description": "ADP's employee or file number for the worker.", "nullable": true, "type": "string" }, "associate_oid": { "description": "ADP's id for the worker.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The paired caregiver; null while the worker needs a person.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_name": { "description": "The paired caregiver's name.", "nullable": true, "type": "string" }, "id": { "description": "The worker link, the id POST /payroll/workers/{id}/link takes; null for a caregiver with no ADP worker.", "format": "uuid", "nullable": true, "type": "string" }, "linked_at": { "description": "When it was linked.", "format": "date-time", "nullable": true, "type": "string" }, "linked_by_name": { "description": "Who linked it, for a manual link.", "nullable": true, "type": "string" }, "match_method": { "description": "How the pairing was made: by ADP number, by name with birth or hire date, by a person (manual), or by HomeCareBilling adding the worker to ADP.", "enum": [ "file_number", "name_and_dob", "name_and_hire_date", "manual", "created_in_adp" ], "nullable": true, "type": "string" }, "missing_from_adp": { "description": "True when ADP's last complete worker list no longer held this worker; it then reads terminated.", "type": "boolean" }, "warning": { "description": "What /payroll/workers warns about the row: a different ADP number in HomeCareBilling, or another caregiver already holding this one.", "nullable": true, "type": "string" } }, "required": [ "id", "caregiver_id", "adp_status", "missing_from_adp" ], "title": "PayrollWorker", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "PayrollWorkerPage", "type": "object" } } }, "description": "A page of workers" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes not_api_connection, payroll_integration_off: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List the ADP workers and their caregivers", "tags": [ "Payroll" ] } }, "/api/v1/payroll/workers/sync": { "post": { "callbacks": {}, "description": "As /payroll/workers' Sync from ADP does: queues a read of every ADP worker, which updates the rows and links the ones the evidence leaves no doubt about. One sync per agency waits at a time. Credentials whose member holds agency_settings.manage only (403 forbidden otherwise); 409 payroll_integration_off while the agency's ADP API connection is off; 409 not_api_connection while it sends payroll by file or SFTP.", "operationId": "postPayrollWorkersSync", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "queued": { "description": "True: the sync is queued, or already waiting to run.", "type": "boolean" } }, "required": [ "queued" ], "title": "PayrollWorkerSync", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Queued" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes not_api_connection, payroll_integration_off: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Sync the ADP workers now", "tags": [ "Payroll" ] } }, "/api/v1/payroll/workers/{id}/link": { "delete": { "callbacks": {}, "description": "As a /payroll/workers row's Unlink does: the worker needs a person again, and no sync links it on its own. The caregiver's ADP number is left as it is. A worker with no caregiver answers itself. Credentials whose member holds agency_settings.manage only (403 forbidden otherwise); 409 payroll_integration_off while the agency's ADP API connection is off; 409 not_api_connection while it sends payroll by file or SFTP.", "operationId": "deletePayrollWorkersByIdLink", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "adp_hire_date": { "description": "The hire date ADP holds.", "format": "date", "nullable": true, "type": "string" }, "adp_name": { "description": "The worker's name as ADP spells it.", "nullable": true, "type": "string" }, "adp_status": { "description": "The worker's status in ADP.", "enum": [ "active", "leave", "terminated" ], "nullable": true, "type": "string" }, "adp_status_date": { "description": "When that status began, in ADP.", "format": "date", "nullable": true, "type": "string" }, "adp_worker_id": { "description": "ADP's employee or file number for the worker.", "nullable": true, "type": "string" }, "associate_oid": { "description": "ADP's id for the worker.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The paired caregiver; null while the worker needs a person.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_name": { "description": "The paired caregiver's name.", "nullable": true, "type": "string" }, "id": { "description": "The worker link, the id POST /payroll/workers/{id}/link takes; null for a caregiver with no ADP worker.", "format": "uuid", "nullable": true, "type": "string" }, "linked_at": { "description": "When it was linked.", "format": "date-time", "nullable": true, "type": "string" }, "linked_by_name": { "description": "Who linked it, for a manual link.", "nullable": true, "type": "string" }, "match_method": { "description": "How the pairing was made: by ADP number, by name with birth or hire date, by a person (manual), or by HomeCareBilling adding the worker to ADP.", "enum": [ "file_number", "name_and_dob", "name_and_hire_date", "manual", "created_in_adp" ], "nullable": true, "type": "string" }, "missing_from_adp": { "description": "True when ADP's last complete worker list no longer held this worker; it then reads terminated.", "type": "boolean" }, "warning": { "description": "What /payroll/workers warns about the row: a different ADP number in HomeCareBilling, or another caregiver already holding this one.", "nullable": true, "type": "string" } }, "required": [ "id", "caregiver_id", "adp_status", "missing_from_adp" ], "title": "PayrollWorker", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The row as unlinked" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes not_api_connection, payroll_integration_off: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Unlink an ADP worker", "tags": [ "Payroll" ] }, "post": { "callbacks": {}, "description": "As a /payroll/workers row's Link does: pairs the worker with the caregiver, and writes the worker's ADP number to the caregiver when the caregiver has none and no other caregiver holds it. 409 already_linked when the worker already has a caregiver; 409 caregiver_already_linked when the caregiver is on another worker; 404 for a worker or caregiver not the agency's. Credentials whose member holds agency_settings.manage only (403 forbidden otherwise); 409 payroll_integration_off while the agency's ADP API connection is off; 409 not_api_connection while it sends payroll by file or SFTP.", "operationId": "postPayrollWorkersByIdLink", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "caregiver_id": { "description": "The caregiver this ADP worker is.", "format": "uuid", "type": "string" } }, "required": [ "caregiver_id" ], "title": "PayrollWorkerLinkInput", "type": "object" } } }, "description": "The caregiver", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "adp_hire_date": { "description": "The hire date ADP holds.", "format": "date", "nullable": true, "type": "string" }, "adp_name": { "description": "The worker's name as ADP spells it.", "nullable": true, "type": "string" }, "adp_status": { "description": "The worker's status in ADP.", "enum": [ "active", "leave", "terminated" ], "nullable": true, "type": "string" }, "adp_status_date": { "description": "When that status began, in ADP.", "format": "date", "nullable": true, "type": "string" }, "adp_worker_id": { "description": "ADP's employee or file number for the worker.", "nullable": true, "type": "string" }, "associate_oid": { "description": "ADP's id for the worker.", "nullable": true, "type": "string" }, "caregiver_id": { "description": "The paired caregiver; null while the worker needs a person.", "format": "uuid", "nullable": true, "type": "string" }, "caregiver_name": { "description": "The paired caregiver's name.", "nullable": true, "type": "string" }, "id": { "description": "The worker link, the id POST /payroll/workers/{id}/link takes; null for a caregiver with no ADP worker.", "format": "uuid", "nullable": true, "type": "string" }, "linked_at": { "description": "When it was linked.", "format": "date-time", "nullable": true, "type": "string" }, "linked_by_name": { "description": "Who linked it, for a manual link.", "nullable": true, "type": "string" }, "match_method": { "description": "How the pairing was made: by ADP number, by name with birth or hire date, by a person (manual), or by HomeCareBilling adding the worker to ADP.", "enum": [ "file_number", "name_and_dob", "name_and_hire_date", "manual", "created_in_adp" ], "nullable": true, "type": "string" }, "missing_from_adp": { "description": "True when ADP's last complete worker list no longer held this worker; it then reads terminated.", "type": "boolean" }, "warning": { "description": "What /payroll/workers warns about the row: a different ADP number in HomeCareBilling, or another caregiver already holding this one.", "nullable": true, "type": "string" } }, "required": [ "id", "caregiver_id", "adp_status", "missing_from_adp" ], "title": "PayrollWorker", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The row as linked" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_linked, caregiver_already_linked, not_api_connection, payroll_integration_off: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Link an ADP worker to a caregiver", "tags": [ "Payroll" ] } }, "/api/v1/phone-care-logs/exceptions": { "get": { "callbacks": {}, "description": "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.", "operationId": "getPhoneCareLogsExceptions", "parameters": [ { "description": "Rows per page (default 25, at most 100; a larger value is served as 100).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only the logs listed for this reason.", "in": "query", "name": "reason", "schema": { "enum": [ "no_tasks", "call_ended_early", "attestation_missing", "attestation_interrupted", "attestation_empty", "attestation_unverified", "attestation_not_saved" ], "type": "string" } }, { "description": "Service dates on or after, YYYY-MM-DD.", "in": "query", "name": "from", "schema": { "format": "date", "type": "string" } }, { "description": "Service dates on or before, YYYY-MM-DD.", "in": "query", "name": "to", "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/PhoneCareLogException" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "PhoneCareLogExceptionPage", "type": "object" } } }, "description": "A page of incomplete phone care logs" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List incomplete phone care logs", "tags": [ "Care logs" ] } }, "/api/v1/phone-care-logs/{id}/dismiss": { "post": { "callbacks": {}, "description": "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.", "operationId": "postPhoneCareLogsByIdDismiss", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Why it can be dismissed, 3 to 500 characters, as the screen asks.", "type": "string" } }, "title": "PhoneCareLogDismiss", "type": "object" } } }, "description": "The reason", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/EvidenceDismissal" } }, "required": [ "data" ], "type": "object" } } }, "description": "Already dismissed" }, "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/EvidenceDismissal" } }, "required": [ "data" ], "type": "object" } } }, "description": "The dismissal" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Dismiss an incomplete phone care log", "tags": [ "Care logs" ] } }, "/api/v1/plans-of-care": { "get": { "callbacks": {}, "description": "A client's Plan of Care for one service, with its tasks (task, frequency, minutes). The current plan for a service is the one in force; creating a new one makes it past. The agency's plans of care in effective date, newest first. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getPlansOfCare", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records with this status.", "in": "query", "name": "status", "schema": { "enum": [ "current", "past" ], "type": "string" } }, { "description": "Only records of this client.", "in": "query", "name": "client_id", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/PlanOfCare" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Plan of carePage", "type": "object" } } }, "description": "A page of plans of care" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List plans of care", "tags": [ "Plans of care" ] }, "post": { "callbacks": {}, "operationId": "postPlansOfCare", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanOfCareCreate" } } }, "description": "The plan of care's fields", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/PlanOfCare" } }, "required": [ "data" ], "type": "object" } } }, "description": "The created plan of care" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a plan of care", "tags": [ "Plans of care" ] } }, "/api/v1/plans-of-care/{id}": { "delete": { "callbacks": {}, "description": "Soft-deletes the plan, as the client's Plans of Care tab does: it leaves every list, print, Work Order, Shift Plan and calculator read, and the audit trail keeps it. A draft or a voided plan can be deleted; a signed plan answers 422 plan_signed (void it first, with POST /plans-of-care/{id}/revise or on its page), and one already deleted 422 already_deleted. Deleting a current plan leaves its service with no current plan; no earlier plan takes its place. Work Orders, standing Work Orders and PARs that reference the plan keep their own copies and do not stop the delete. Plans carry no lock_version.", "operationId": "deletePlansOfCareById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "deleted_at": { "description": "When it was deleted (UTC).", "format": "date-time", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "required": [ "id", "deleted_at" ], "title": "DeletedPlanOfCare", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted plan" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_deleted, plan_signed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a Plan of Care entered in error", "tags": [ "Deletes and restores" ] }, "get": { "callbacks": {}, "description": "A client's Plan of Care for one service, with its tasks (task, frequency, minutes). The current plan for a service is the one in force; creating a new one makes it past.", "operationId": "getPlansOfCareById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/PlanOfCare" } }, "required": [ "data" ], "type": "object" } } }, "description": "The plan of care" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no plan of care with that id in this agency, including another agency's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a plan of care", "tags": [ "Plans of care" ] }, "patch": { "callbacks": {}, "description": "Changes the fields sent. A tasks list replaces the plan's tasks; leave it out to keep them. Plans have no lock_version and, as on the web, the last save wins. Lowering a task below what the client's Work Orders schedule is saved, with an over_authorized warning in warnings; tasks adding up to more hours a week than the plan authorizes are saved too, with a care_planning.task_hours_over_authorization warning after it.", "operationId": "patchPlansOfCareById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanOfCareUpdate" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/PlanOfCare" } }, "required": [ "data" ], "type": "object" } } }, "description": "The updated plan of care" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no plan of care with that id in this agency, including another agency's." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: the plan of care changed since the lock_version sent was read, or while this request ran. Nothing was saved; read it again and retry." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a plan of care", "tags": [ "Plans of care" ] } }, "/api/v1/plans-of-care/{id}/resolve-over-authorization": { "post": { "callbacks": {}, "description": "For each task the client's Work Orders schedule over the plan in that month, takes visits off the largest contributor first until the total equals the authorization, as the plan page's Resolve does. target, optional, names the Work Order to trim per task (its key or plan task id); a target that cannot absorb the whole overage answers 422 residual_over_authorization and trims nothing. Answers each change; an empty list when nothing was over.", "operationId": "postPlansOfCareByIdResolveOverAuthorization", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "month": { "description": "The month, 1 to 12.", "maximum": 12, "minimum": 1, "type": "integer" }, "target": { "additionalProperties": { "format": "uuid", "type": "string" }, "description": "Optional: task key or plan task id => the Work Order id to trim it from.", "type": "object" }, "year": { "description": "The year.", "maximum": 2100, "minimum": 2020, "type": "integer" } }, "required": [ "month", "year" ], "title": "OverAuthorizationResolve", "type": "object" } } }, "description": "The month and an optional target", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "caregiver_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "from": { "description": "Visits a week before the trim.", "nullable": true, "type": "integer" }, "task": { "description": "The task's key on the plan.", "nullable": true, "type": "string" }, "task_definition_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "task_label": { "description": "The task as the plan names it.", "nullable": true, "type": "string" }, "to": { "description": "Visits a week after it; 0 means the task was taken off.", "nullable": true, "type": "integer" }, "work_order_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "title": "OverAuthorizationAdjustment", "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The trims made" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code residual_over_authorization: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Trim a month's Work Orders back to a Plan of Care's authorization", "tags": [ "Work orders" ] } }, "/api/v1/plans-of-care/{id}/revise": { "post": { "callbacks": {}, "description": "As the plan page's Revise does: the signed current plan is voided with the reason given and kept as signed, and a copy becomes the client's current plan as a new draft, which is the answer (its replaces_id names the original). Needs care_plans.manage (403 forbidden otherwise). Without a reason it answers 422 reason_required; a draft 422 not_signed, a plan no longer current 422 not_current, a voided plan 409 voided.", "operationId": "postPlansOfCareByIdRevise", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Why the signed plan is revised, 3 to 1000 characters. It is kept with the voided original.", "nullable": true, "type": "string" } }, "required": [ "reason" ], "title": "PlanOfCareRevision", "type": "object" } } }, "description": "Why it is revised", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/PlanOfCare" } }, "required": [ "data" ], "type": "object" } } }, "description": "The new draft" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes not_current, not_signed, reason_required: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Revise a signed Plan of Care", "tags": [ "Plans of care" ] } }, "/api/v1/plans-of-care/{id}/signatures": { "post": { "callbacks": {}, "description": "Records the plan's supervisor line as a typed signature by the credential's user, as the plan page's typed office signature does. The plan's first signature keeps its consent wording with it and locks it. The client's line is signed on a device, on the plan page. A line already signed answers 422 already_signed, a voided plan 409 voided, a plan changed since its first signature 409 content_changed. 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.", "operationId": "postPlansOfCareByIdSignatures", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "signer_name": { "description": "The supervisor's name as the signature records it; the credential's user is the signer.", "nullable": true, "type": "string" } }, "required": [ "signer_name" ], "title": "PlanOfCareSupervisorSignature", "type": "object" } } }, "description": "The signature", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/PlanOfCare" } }, "required": [ "data" ], "type": "object" } } }, "description": "The plan" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code signature_requires_person: Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code content_changed: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code already_signed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Sign a Plan of Care as its supervisor", "tags": [ "Plans of care" ] } }, "/api/v1/plans-of-care/{id}/work-orders/distribute": { "post": { "callbacks": {}, "description": "Makes one Work Order per caregiver from the plan, each carrying the visits a week given for it, as /care-plans/:id/generate-work-orders does. frequencies maps each caregiver id to plan task ids (from GET /plans-of-care/{id}) and visits a week; a caregiver whose counts are all 0 gets none. A split over the authorization is saved, with a warning. A plan task id the plan no longer carries answers 409 plan_changed and writes nothing.", "operationId": "postPlansOfCareByIdWorkOrdersDistribute", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "month": { "description": "The month, 1 to 12.", "maximum": 12, "minimum": 1, "type": "integer" }, "selections": { "description": "One per service and shift being generated.", "items": { "properties": { "frequencies": { "additionalProperties": { "additionalProperties": { "minimum": 0, "type": "integer" }, "type": "object" }, "description": "caregiver id => plan task id => visits a week. A caregiver whose counts are all 0 gets no Work Order.", "type": "object" }, "service_type": { "description": "The service.", "enum": [ "homemaker", "personal_care" ], "type": "string" }, "shift_number": { "description": "Optional: the shift, 1 to 4; default 1.", "maximum": 4, "minimum": 1, "type": "integer" } }, "required": [ "service_type", "frequencies" ], "type": "object" }, "type": "array" }, "year": { "description": "The year.", "maximum": 2100, "minimum": 2020, "type": "integer" } }, "required": [ "month", "year", "selections" ], "title": "WorkOrderDistribute", "type": "object" } } }, "description": "The month and the split", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WorkOrder" }, "type": "array" }, "services": { "description": "Per service the plan authorizes, as the Generate Work Orders page's totals show it: authorized_minutes and task_minutes a week, and rounding, quarter_hour when the tasks come to less than the authorization by under 15 minutes (the calculator rounds them up to the next quarter hour), under when by 15 minutes or more, else null.", "items": { "properties": { "authorized_minutes": { "type": "integer" }, "rounding": { "enum": [ "quarter_hour", "under" ], "nullable": true, "type": "string" }, "service": { "type": "string" }, "task_minutes": { "type": "integer" } }, "required": [ "service", "authorized_minutes", "task_minutes", "rounding" ], "title": "PlanServiceMinutes", "type": "object" }, "type": "array" }, "shift_plan_work_orders": { "description": "The Work Orders the client's Shift Plan made that are in force in the month, each with its shift_id, so a month made here as well as there shows; empty when the client has no Shift Plan. Never a refusal.", "items": { "properties": { "caregiver": { "description": "The Work Order's caregiver; null when it has none.", "nullable": true, "properties": { "first_name": { "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_name": { "nullable": true, "type": "string" } }, "type": "object" }, "closing_date": { "description": "Its Closing Date; null while it stays open.", "format": "date", "nullable": true, "type": "string" }, "effective_date": { "description": "Its Effective Date.", "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "number": { "description": "The Work Order's WO #.", "nullable": true, "type": "integer" }, "service": { "description": "The Work Order's service.", "enum": [ "personal_care", "homemaker", "hma" ], "type": "string" }, "shift_id": { "description": "The Shift Plan's shift that made it; only on a Work Order the plan made.", "enum": [ "PC1", "PC2", "PC3", "PC4", "HM1", "HM2", "HM3", "HM4" ], "type": "string" } }, "required": [ "id", "number", "service", "caregiver", "effective_date", "closing_date" ], "title": "ShiftPlanWorkOrderLine", "type": "object" }, "type": "array" }, "warnings": { "description": "What the distribution found, each with a code: over_authorized (tasks this split puts over the plan), already_over_authorized (tasks over before it), plan_outside_month (the plan's dates do not reach the month, naming a plan that does), existing_work_orders (caregivers skipped because they already have the month's Work Order, named), not_on_work_orders (plan tasks no Work Order could carry). The Work Orders are made regardless.", "items": { "additionalProperties": true, "properties": { "code": { "type": "string" } }, "required": [ "code" ], "type": "object" }, "type": "array" } }, "required": [ "data", "warnings", "services", "shift_plan_work_orders" ], "type": "object" } } }, "description": "The Work Orders made and the warnings" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code plan_changed: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Split a Plan of Care across caregivers for a month", "tags": [ "Work orders" ] } }, "/api/v1/print/{form}": { "get": { "callbacks": {}, "description": "The form as its print page renders it for this agency: the same HTML, with the print layout, as the web prints, or that page as a PDF with format=pdf. Every other query parameter is the print route's own, by its name there: the record ids its path takes, an earlier revision's id, and a list print's filters, as the page's own Print link carries them. A parameter the form does not read answers 400 naming the ones it reads. A record of another agency, or an id that names none, answers 404. The forms, with the ids each takes: client_list (The client list; reads status, temporary, client_type, search, sort_by, show_archived); client_report (A client report; reads cols, status, client_type, search, page); client_birthdays (The client birthday list; reads month); caregiver_list (The caregiver list; reads status, search, show_archived); caregiver_report (A caregiver report; reads cols, status, search, page); caregiver_envelopes (Envelopes for every caregiver flagged for one; reads address); caregiver_envelope (An envelope addressed to a caregiver: caregiver_id; reads address); oig_screening (An OIG screening's proof: id); oig_attestation (An OIG monthly attestation: id); plan_of_care (A plan of care: plan_id; reads addenda_through); care_log (A care log's day: id; reads addenda_through); half_month_summary (A caregiver's half of a month for one client, as signed: id); client_care_plans (Every service plan of a client: client_id); phone_task_card (A client's phone task card, the codes a caregiver keys on the phone line: client_id); provider_care_plan_template (The blank provider care plan); provider_care_plan (A provider care plan: id); provider_care_plan_revision (An earlier revision of a provider care plan: id, revision_id); client_information_sheet (A client information sheet: client_id); client_information_sheet_employee (A client information sheet, the caregiver's copy: client_id); client_emergency_information (A client's emergency information: client_id; reads blank, addenda_through); client_emergency_wallet_card (A client's emergency wallet card: client_id); client_emergency_information_revision (An earlier revision of a client's emergency information: client_id, id; reads blank, addenda_through); client_envelope (An envelope addressed to a client: client_id); health_summary (A client's health summary: client_id); missed_visit (A missed visit form: client_id); attempted_visit (An attempted visit form: client_id); client_communication_report (A client's communication report: client_id; reads from, to, sort); satisfaction_survey (A satisfaction survey: client_id, id); caregiver_communication_report (A caregiver's communication notes: caregiver_id; reads from, to, contact_type, search, sort); caregiver_communication_note (One caregiver communication note: id); compliance_report (A caregiver's compliance report: caregiver_id); file_checklist (A caregiver's employee file checklist: caregiver_id); reference_check (A caregiver's reference check form: caregiver_id); caregiver_new_hire (A caregiver's new-hire sheet: caregiver_id); client_consent_form (A client's intake notice (disclosure notice or rights acknowledgement): client_id, id; reads addenda_through); complaint (A complaint: id; reads addenda_through); meeting_minutes (Meeting minutes: id); meeting_minutes_template (The blank meeting minutes); incident (A critical incident: id; reads addenda_through); supervisory_visit (A supervisory visit: id; reads blank, addenda_through); supervisory_visits_planned (A month's planned supervisory visits; reads month, page); work_order (A Work Order: id; reads month); shift_plan (A client's Shift Plan, every shift's Work Order: client_id); client_work_orders (Every Work Order of a client for a month (month=YYYY-MM): client_id; reads month); work_order_blank (The blank Work Order); work_order_blank_card (The empty Time and Services Card; reads service, half, month); work_order_report (A Work Order's monthly client report: id; reads blank, month, report, addenda_through); work_order_card (A Work Order's Time and Services Card: id; reads blank, month, half); work_order_batch (Time and Services Cards in a batch, or with form=report the Monthly Client Reports; reads month, form, blank, half, stacks, monthly_print, service_type, status, wo_type, completeness, caregiver_id, client_id, shift_number, exclude_completed, part, include_ids, page_half); work_order_month (The month-start print of every Time and Services Card; reads month, form, blank, half, stacks, monthly_print, service_type, status, wo_type, completeness, caregiver_id, client_id, shift_number, exclude_completed, part, include_ids, page_half); work_order_schedule (Every Work Order in force with its daily times and hours; reads page); timesheet (A timesheet: id; reads blank); cash_advances (A month's cash advances, or with month=all&status=owed every advance still owed; reads month, status, search); expiring_authorizations (The authorizations (PARs) ending within 30, 60 or 90 days, soonest first; reads days, renewed); evv_issues (The EVV issue log by caregiver (caregiver_id and status filter it); reads caregiver_id, status); evaluations_due (The caregivers whose annual evaluation falls due in a month (month=1..12); reads month); hospital_stays (A month's client hospital stays and the care recorded on those days (month=YYYY-MM); reads month, page).", "operationId": "getPrintByForm", "parameters": [ { "description": "The printed form.", "in": "path", "name": "form", "required": true, "schema": { "enum": [ "client_list", "client_report", "client_birthdays", "caregiver_list", "caregiver_report", "caregiver_envelopes", "caregiver_envelope", "oig_screening", "oig_attestation", "plan_of_care", "care_log", "half_month_summary", "client_care_plans", "phone_task_card", "provider_care_plan_template", "provider_care_plan", "provider_care_plan_revision", "client_information_sheet", "client_information_sheet_employee", "client_emergency_information", "client_emergency_wallet_card", "client_emergency_information_revision", "client_envelope", "health_summary", "missed_visit", "attempted_visit", "client_communication_report", "satisfaction_survey", "caregiver_communication_report", "caregiver_communication_note", "compliance_report", "file_checklist", "reference_check", "caregiver_new_hire", "client_consent_form", "complaint", "meeting_minutes", "meeting_minutes_template", "incident", "supervisory_visit", "supervisory_visits_planned", "work_order", "shift_plan", "client_work_orders", "work_order_blank", "work_order_blank_card", "work_order_report", "work_order_card", "work_order_batch", "work_order_month", "work_order_schedule", "timesheet", "cash_advances", "expiring_authorizations", "evv_issues", "evaluations_due", "hospital_stays" ], "type": "string" } }, { "description": "html (the default) or pdf.", "in": "query", "name": "format", "required": false, "schema": { "enum": [ "html", "pdf" ], "type": "string" } } ], "responses": { "200": { "content": { "application/pdf": { "schema": { "format": "binary", "type": "string" } }, "text/html": { "schema": { "description": "The printed page's HTML.", "type": "string" } } }, "description": "The printed form" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a query parameter the form does not read (the message names the ones it reads), a record id or required path parameter missing, or a format other than html or pdf." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code print_refused: the print page itself refused, as it does on the web (a Work Order month outside its dates), and the message is the page's; or the print could not be made from the parameters sent, and the message names them and what the form takes." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code temporarily_unavailable: the page or its PDF could not be rendered in time, or the PDF renderer failed. Nothing changed; try again." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Print a form", "tags": [ "Printed forms" ] } }, "/api/v1/print/{form}/{id}": { "get": { "callbacks": {}, "description": "The form for one record as a PDF: {id} is the record id followed by .pdf, the id the form's route names first by id (a plan of care's plan_id, a client form's client_id, a revision form's own id), and the query carries the rest of the route's parameters, as GET /api/v1/print/{form} takes them. A parameter the form does not read answers 400 naming the ones it reads. A form that names no record (a list, a blank template, a batch) is read with format=pdf there instead.", "operationId": "getPrintByFormById", "parameters": [ { "description": "The printed form.", "in": "path", "name": "form", "required": true, "schema": { "enum": [ "client_list", "client_report", "client_birthdays", "caregiver_list", "caregiver_report", "caregiver_envelopes", "caregiver_envelope", "oig_screening", "oig_attestation", "plan_of_care", "care_log", "half_month_summary", "client_care_plans", "phone_task_card", "provider_care_plan_template", "provider_care_plan", "provider_care_plan_revision", "client_information_sheet", "client_information_sheet_employee", "client_emergency_information", "client_emergency_wallet_card", "client_emergency_information_revision", "client_envelope", "health_summary", "missed_visit", "attempted_visit", "client_communication_report", "satisfaction_survey", "caregiver_communication_report", "caregiver_communication_note", "compliance_report", "file_checklist", "reference_check", "caregiver_new_hire", "client_consent_form", "complaint", "meeting_minutes", "meeting_minutes_template", "incident", "supervisory_visit", "supervisory_visits_planned", "work_order", "shift_plan", "client_work_orders", "work_order_blank", "work_order_blank_card", "work_order_report", "work_order_card", "work_order_batch", "work_order_month", "work_order_schedule", "timesheet", "cash_advances", "expiring_authorizations", "evv_issues", "evaluations_due", "hospital_stays" ], "type": "string" } }, { "description": "The record id, then .pdf.", "in": "path", "name": "id", "required": true, "schema": { "pattern": "\\.pdf$", "type": "string" } } ], "responses": { "200": { "content": { "application/pdf": { "schema": { "format": "binary", "type": "string" } } }, "description": "The printed form" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a query parameter the form does not read (the message names the ones it reads), a record id or required path parameter missing, or a format other than html or pdf." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code print_refused: the print page itself refused, as it does on the web (a Work Order month outside its dates), and the message is the page's; or the print could not be made from the parameters sent, and the message names them and what the form takes." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code temporarily_unavailable: the page or its PDF could not be rendered in time, or the PDF renderer failed. Nothing changed; try again." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Print a form's record as a PDF", "tags": [ "Printed forms" ] } }, "/api/v1/prospects": { "get": { "callbacks": {}, "description": "Someone the agency is following up as a possible client or caregiver, from the Pipeline pages. A status moves only along the pipeline; converting one is POST /api/v1/prospects/{id}/convert. The agency's prospects in newest first. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getProspects", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records with this status.", "in": "query", "name": "status", "schema": { "enum": [ "new", "contacted", "interested", "interviewing", "onboarding", "converted", "declined", "archived" ], "type": "string" } }, { "description": "Every word must match a returned name or identifier, case-insensitively. At most 100 characters and 8 words.", "in": "query", "name": "search", "schema": { "maxLength": 100, "type": "string" } }, { "description": "Only potential clients or employees.", "in": "query", "name": "prospect_type", "schema": { "enum": [ "potential_client", "potential_employee" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Prospect" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ProspectPage", "type": "object" } } }, "description": "A page of prospects" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List prospects", "tags": [ "Pipeline" ] }, "post": { "callbacks": {}, "operationId": "postProspects", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProspectCreate" } } }, "description": "The prospect's fields", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Prospect" } }, "required": [ "data" ], "type": "object" } } }, "description": "The created prospect" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a prospect", "tags": [ "Pipeline" ] } }, "/api/v1/prospects/{id}": { "delete": { "callbacks": {}, "description": "Deletes the prospect, as the Pipeline page does. A converted prospect answers 422 cannot_delete_converted: its client or caregiver points back to it.", "operationId": "deleteProspectsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Prospect" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted prospect" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code cannot_delete_converted: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a prospect", "tags": [ "Pipeline" ] }, "get": { "callbacks": {}, "description": "Someone the agency is following up as a possible client or caregiver, from the Pipeline pages. A status moves only along the pipeline; converting one is POST /api/v1/prospects/{id}/convert.", "operationId": "getProspectsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Prospect" } }, "required": [ "data" ], "type": "object" } } }, "description": "The prospect" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no prospect with that id in this agency, including another agency's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a prospect", "tags": [ "Pipeline" ] }, "patch": { "callbacks": {}, "description": "Sets only the fields sent. lock_version is required: send the value you read, and a record changed since answers 409 stale_record.", "operationId": "patchProspectsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProspectInput" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Prospect" } }, "required": [ "data" ], "type": "object" } } }, "description": "The updated prospect" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no prospect with that id in this agency, including another agency's." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: the prospect changed since the lock_version sent was read, or while this request ran. Nothing was saved; read it again and retry." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a prospect", "tags": [ "Pipeline" ] } }, "/api/v1/prospects/{id}/convert": { "post": { "callbacks": {}, "description": "Makes the client (for a potential client) or the caregiver (for a potential employee) from the prospect and marks it converted, as the Pipeline page's Convert does. A potential client's type follows its insurance (private makes a private-insurance client, anything else a Medicaid one), and its Medicaid ID, contact person and address are carried over; a Medicaid ID another client already holds is left off and named in warnings. The person is looked for first, as a create is: a client already on file with the same Medicaid ID and name is linked rather than made twice (converted_to_id is that client), and namesakes on file are counted; both are named in warnings, never refused. Only a prospect at onboarding converts; any other answers 422 invalid_status_for_conversion. A prospect carries no date of birth, so when the agency already has a client or caregiver of the same name that nothing tells apart, nothing is written and the answer is 409 possible_match, whose details list the matches; send the request again with same_person_id (one of the matches, which is linked) or create_new (a new record is made): the list of the matches' ids passes over only those (and, with hidden_seen, as many on cards the caller cannot open as the 409 counted in hidden), so a namesake filed meanwhile is asked about, and true passes over every namesake on file, seen or not. Warn, never block: either answer converts.", "operationId": "postProspectsByIdConvert", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "as": { "description": "Start onboarding (US-122.23), as the Pipeline page's Start onboarding does: an open caregiver lead at any stage (new to onboarding) is moved to onboarding and becomes a caregiver with status potential, its open-shift responses, alerts and portal devices moving with it; a former employee's re-hire lead sets that caregiver card back to potential instead of making one. A closed lead answers 422 lead_not_open, a client lead 422 not_employee_lead. Send it again with the possible-match answer. Absent: convert at onboarding into an active caregiver or a client.", "enum": [ "potential" ], "type": "string" }, "create_new": { "description": "The answer to a 409 possible_match when the prospect is someone else: a new record is made, and warnings counts the namesakes passed over. A list of record ids names the namesakes the caller was shown, and makes the record only if it names every namesake on file now that the caller can open, and, with hidden_seen, no more than that many on cards it cannot; one filed since (or one the 409 counted in more and did not list) answers 409 possible_match again. true is an explicit \"create regardless\": the record is made, passing over every namesake on file, including any the caller never saw. false or absent makes nothing.", "oneOf": [ { "type": "boolean" }, { "items": { "format": "uuid", "type": "string" }, "type": "array" } ] }, "hidden_seen": { "description": "With a create_new list: the hidden count of the 409 possible_match it answers, the namesakes on cards the caller cannot open, which are never named. The list then also passes over up to that many of them, as the Pipeline page's \"Someone else\" does; one more than that (filed since) answers 409 possible_match again. Absent or 0 passes over none.", "minimum": 0, "type": "integer" }, "same_person_id": { "description": "The answer to a 409 possible_match: the id of one of its matches, which is the same person. The prospect is linked to that record and nothing is made. An id that is no longer one of the prospect's namesakes answers 409 possible_match again.", "format": "uuid", "type": "string" } }, "title": "ProspectConversionInput", "type": "object" } } }, "description": "The answer to a possible match (empty on the first call)", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "converted_to_id": { "description": "The client or caregiver the prospect became: a new record, or the client already on file it was linked to.", "format": "uuid", "type": "string" }, "converted_to_type": { "description": "What was made.", "enum": [ "client", "caregiver" ], "type": "string" }, "prospect": { "$ref": "#/components/schemas/Prospect" }, "warnings": { "description": "What the conversion did not do as asked: a Medicaid ID left off, an existing client linked, namesakes on file. Usually empty.", "items": { "type": "string" }, "type": "array" } }, "required": [ "prospect", "converted_to_type", "converted_to_id", "warnings" ], "title": "ProspectConversion", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The converted prospect and what it became" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code possible_match: someone of this name is already on file and nothing tells them apart. Nothing was written. The shared envelope's details is {type, matches, more, hidden, warnings}: type is client or caregiver (what would be made); matches lists the namesakes on file with nothing to tell them from the prospect, oldest first, each {id, name}, at most 20; more counts the ones past those 20, never named (a create_new list cannot name them, so with more above 0 the answer is same_person_id or create_new true); hidden counts namesakes on cards the caller cannot open, never named (0 while every member reaches every client and caregiver); the message then says how many, as the Pipeline page does, and a create_new list passes them over when it carries hidden_seen set to that count; warnings are the warnings the conversion would carry. Answer with same_person_id or create_new. Code stale_record: the prospect, or the clients and caregivers it is matched against, changed while it converted (a card of this name or Medicaid ID was filed meanwhile, twice). Nothing was written; send the same request again." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code invalid_status_for_conversion: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Convert a prospect to a client or caregiver", "tags": [ "Pipeline" ] } }, "/api/v1/provider-care-plans": { "get": { "callbacks": {}, "description": "Newest first, as the client's Provider care plans tab lists them. Another agency's client answers 404.", "operationId": "getProviderCarePlans", "parameters": [ { "description": "The client whose plans to list.", "in": "query", "name": "client_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "authorizations_reconciled_at": { "description": "When its authorisations were last fully reconciled.", "format": "date-time", "nullable": true, "type": "string" }, "certification_end_date": { "description": "The certification period's end.", "format": "date", "nullable": true, "type": "string" }, "certification_start_date": { "description": "The certification period's start.", "format": "date", "nullable": true, "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "created_at": { "description": "When it was created.", "format": "date-time", "type": "string" }, "current_revision_id": { "description": "Its current revision.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "source_document_id": { "description": "The PCSP it was imported from.", "format": "uuid", "nullable": true, "type": "string" }, "status": { "description": "Whether it is the client's current plan.", "enum": [ "current", "past" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "client_id", "status" ], "title": "ProviderCarePlan", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ProviderCarePlanPage", "type": "object" } } }, "description": "A page of plans" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a client's provider care plans", "tags": [ "Provider care plans" ] }, "post": { "callbacks": {}, "description": "Creates the client's plan, born current, as the plan form does. The certification period is decided as the form decides it: the PCSP's period wins where the client's active certification is silent; where both speak and disagree, the request must send certification_choice (422 certification_disagreement names both periods otherwise).", "operationId": "postProviderCarePlans", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "certification_choice": { "description": "Which period wins when the PCSP's and the client's certification disagree.", "enum": [ "document", "client_certification" ], "type": "string" }, "certification_end_date": { "description": "The PCSP's certification end, YYYY-MM-DD.", "format": "date", "nullable": true, "type": "string" }, "certification_start_date": { "description": "The PCSP's certification start, YYYY-MM-DD.", "format": "date", "nullable": true, "type": "string" }, "change_note": { "description": "Why this revision.", "nullable": true, "type": "string" }, "client_id": { "description": "For a new plan: the client.", "format": "uuid", "type": "string" }, "content": { "description": "The plan's fields, by key, as get_provider_care_plan shows them.", "type": "object" }, "source_document_id": { "description": "The PCSP stored for the client, with store_pcsp; a new plan only, where null means none.", "format": "uuid", "nullable": true, "type": "string" } }, "title": "ProviderCarePlanSave", "type": "object" } } }, "description": "The plan", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "authorizations_reconciled_at": { "description": "When its authorisations were last fully reconciled.", "format": "date-time", "nullable": true, "type": "string" }, "certification_end_date": { "description": "The certification period's end.", "format": "date", "nullable": true, "type": "string" }, "certification_start_date": { "description": "The certification period's start.", "format": "date", "nullable": true, "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "content": { "description": "The current revision's fields, by key.", "type": "object" }, "created_at": { "description": "When it was created.", "format": "date-time", "type": "string" }, "current_revision_id": { "description": "Its current revision.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reconciliation_outcome": { "description": "The last reconciliation's rows.", "nullable": true, "type": "object" }, "source_document_id": { "description": "The PCSP it was imported from.", "format": "uuid", "nullable": true, "type": "string" }, "status": { "description": "Whether it is the client's current plan.", "enum": [ "current", "past" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "client_id", "status", "content" ], "title": "ProviderCarePlanDetail", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The plan" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code certification_disagreement: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a provider care plan", "tags": [ "Provider care plans" ] } }, "/api/v1/provider-care-plans/{id}": { "get": { "callbacks": {}, "description": "The plan and its current revision's content.", "operationId": "getProviderCarePlansById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "authorizations_reconciled_at": { "description": "When its authorisations were last fully reconciled.", "format": "date-time", "nullable": true, "type": "string" }, "certification_end_date": { "description": "The certification period's end.", "format": "date", "nullable": true, "type": "string" }, "certification_start_date": { "description": "The certification period's start.", "format": "date", "nullable": true, "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "content": { "description": "The current revision's fields, by key.", "type": "object" }, "created_at": { "description": "When it was created.", "format": "date-time", "type": "string" }, "current_revision_id": { "description": "Its current revision.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reconciliation_outcome": { "description": "The last reconciliation's rows.", "nullable": true, "type": "object" }, "source_document_id": { "description": "The PCSP it was imported from.", "format": "uuid", "nullable": true, "type": "string" }, "status": { "description": "Whether it is the client's current plan.", "enum": [ "current", "past" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "client_id", "status", "content" ], "title": "ProviderCarePlanDetail", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The plan" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read a provider care plan", "tags": [ "Provider care plans" ] }, "patch": { "callbacks": {}, "description": "Saves a new revision, as the plan form's Save does; earlier revisions are kept. client_id and source_document_id are a new plan's only: sending either, null included, is 422 create_only. The certification period is decided as the form decides it: the PCSP's period wins where the client's active certification is silent; where both speak and disagree, the request must send certification_choice (422 certification_disagreement names both periods otherwise).", "operationId": "patchProviderCarePlansById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "certification_choice": { "description": "Which period wins when the PCSP's and the client's certification disagree.", "enum": [ "document", "client_certification" ], "type": "string" }, "certification_end_date": { "description": "The PCSP's certification end, YYYY-MM-DD.", "format": "date", "nullable": true, "type": "string" }, "certification_start_date": { "description": "The PCSP's certification start, YYYY-MM-DD.", "format": "date", "nullable": true, "type": "string" }, "change_note": { "description": "Why this revision.", "nullable": true, "type": "string" }, "client_id": { "description": "For a new plan: the client.", "format": "uuid", "type": "string" }, "content": { "description": "The plan's fields, by key, as get_provider_care_plan shows them.", "type": "object" }, "source_document_id": { "description": "The PCSP stored for the client, with store_pcsp; a new plan only, where null means none.", "format": "uuid", "nullable": true, "type": "string" } }, "title": "ProviderCarePlanSave", "type": "object" } } }, "description": "The revision", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "authorizations_reconciled_at": { "description": "When its authorisations were last fully reconciled.", "format": "date-time", "nullable": true, "type": "string" }, "certification_end_date": { "description": "The certification period's end.", "format": "date", "nullable": true, "type": "string" }, "certification_start_date": { "description": "The certification period's start.", "format": "date", "nullable": true, "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "content": { "description": "The current revision's fields, by key.", "type": "object" }, "created_at": { "description": "When it was created.", "format": "date-time", "type": "string" }, "current_revision_id": { "description": "Its current revision.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reconciliation_outcome": { "description": "The last reconciliation's rows.", "nullable": true, "type": "object" }, "source_document_id": { "description": "The PCSP it was imported from.", "format": "uuid", "nullable": true, "type": "string" }, "status": { "description": "Whether it is the client's current plan.", "enum": [ "current", "past" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "client_id", "status", "content" ], "title": "ProviderCarePlanDetail", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The plan" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes certification_disagreement, create_only: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Revise a provider care plan", "tags": [ "Provider care plans" ] } }, "/api/v1/provider-care-plans/{id}/mark-current": { "post": { "callbacks": {}, "description": "As the plan page's Mark current does; the client's other current plan becomes past.", "operationId": "postProviderCarePlansByIdMarkCurrent", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "authorizations_reconciled_at": { "description": "When its authorisations were last fully reconciled.", "format": "date-time", "nullable": true, "type": "string" }, "certification_end_date": { "description": "The certification period's end.", "format": "date", "nullable": true, "type": "string" }, "certification_start_date": { "description": "The certification period's start.", "format": "date", "nullable": true, "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "content": { "description": "The current revision's fields, by key.", "type": "object" }, "created_at": { "description": "When it was created.", "format": "date-time", "type": "string" }, "current_revision_id": { "description": "Its current revision.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reconciliation_outcome": { "description": "The last reconciliation's rows.", "nullable": true, "type": "object" }, "source_document_id": { "description": "The PCSP it was imported from.", "format": "uuid", "nullable": true, "type": "string" }, "status": { "description": "Whether it is the client's current plan.", "enum": [ "current", "past" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "client_id", "status", "content" ], "title": "ProviderCarePlanDetail", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The plan" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Make a provider care plan the client's current one", "tags": [ "Provider care plans" ] } }, "/api/v1/provider-care-plans/{id}/reconciliation": { "post": { "callbacks": {}, "description": "Records the rows of a reconciliation done without an apply, and whether nothing is left outstanding (which clears the not-yet-reconciled banner).", "operationId": "postProviderCarePlansByIdReconciliation", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "complete": { "description": "Whether nothing is left outstanding.", "type": "boolean" }, "rows": { "description": "One per service row.", "items": { "type": "object" }, "type": "array" } }, "title": "ProviderCarePlanReconciliation", "type": "object" } } }, "description": "The outcome", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "authorizations_reconciled_at": { "description": "When its authorisations were last fully reconciled.", "format": "date-time", "nullable": true, "type": "string" }, "certification_end_date": { "description": "The certification period's end.", "format": "date", "nullable": true, "type": "string" }, "certification_start_date": { "description": "The certification period's start.", "format": "date", "nullable": true, "type": "string" }, "client_id": { "description": "The client.", "format": "uuid", "type": "string" }, "content": { "description": "The current revision's fields, by key.", "type": "object" }, "created_at": { "description": "When it was created.", "format": "date-time", "type": "string" }, "current_revision_id": { "description": "Its current revision.", "format": "uuid", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reconciliation_outcome": { "description": "The last reconciliation's rows.", "nullable": true, "type": "object" }, "source_document_id": { "description": "The PCSP it was imported from.", "format": "uuid", "nullable": true, "type": "string" }, "status": { "description": "Whether it is the client's current plan.", "enum": [ "current", "past" ], "type": "string" }, "updated_at": { "description": "When it last changed.", "format": "date-time", "type": "string" } }, "required": [ "id", "client_id", "status", "content" ], "title": "ProviderCarePlanDetail", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The plan" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Record a reconciliation outcome", "tags": [ "Provider care plans" ] } }, "/api/v1/provider-care-plans/{id}/reconciliation/apply": { "post": { "callbacks": {}, "description": "Applies the preview the token was minted for, with the decisions, as the reconcile page's Apply does; each row's outcome is answered, and a refused row is a result, not an error. A token already spent answers 409 already_applied, a stale one 409 expired, and another member's PCSP 422 identity_mismatch.", "operationId": "postProviderCarePlansByIdReconciliationApply", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "decisions": { "description": "excluded, choices and supersessions.", "properties": { "choices": { "description": "Row index => the authorization id it updates.", "type": "object" }, "excluded": { "description": "Row indexes to leave out.", "items": { "type": "integer" }, "type": "array" }, "supersessions": { "description": "Authorization id => end_date or leave.", "type": "object" } }, "title": "PcspReconciliationDecisions", "type": "object" }, "token": { "description": "The token the preview answered.", "format": "uuid", "type": "string" } }, "required": [ "token" ], "title": "PcspReconciliationApply", "type": "object" } } }, "description": "The token and decisions", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "complete": { "description": "Whether nothing is left outstanding.", "type": "boolean" }, "results": { "items": { "type": "object" }, "type": "array" } }, "required": [ "results", "complete" ], "title": "PcspReconciliationResult", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Each row's outcome" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code already_applied: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code identity_mismatch: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Apply a previewed PCSP's authorisations", "tags": [ "Provider care plans" ] } }, "/api/v1/provider-care-plans/{id}/reconciliation/preview": { "post": { "callbacks": {}, "description": "Reads the plan's PCSP and proposes its authorisations, as the reconcile page does, numbering each row. When something can be applied it answers a single-use token, good for expires_in_seconds, that POST .../reconciliation/apply takes with the decisions; the preview it applies is this one. A plan with no PCSP answers 422 no_source_document; an unreadable one 422 unreadable_document.", "operationId": "postProviderCarePlansByIdReconciliationPreview", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "candidates": { "description": "Each proposed authorisation, with its index.", "items": { "type": "object" }, "type": "array" }, "expires_in_seconds": { "description": "How long the token is good for.", "nullable": true, "type": "integer" }, "identity_mismatch": { "description": "Set when the PCSP names another member; nothing can be applied.", "items": { "type": "object" }, "type": "array" }, "service_plan_type": { "description": "initial, csr or revision.", "nullable": true, "type": "string" }, "supersessions": { "items": { "type": "object" }, "type": "array" }, "token": { "description": "The apply token, or null when nothing can be applied.", "format": "uuid", "nullable": true, "type": "string" } }, "required": [ "candidates" ], "title": "PcspReconciliationPreview", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The preview" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code file_missing: the record exists and its file does not. Nothing changed." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes no_source_document, unreadable_document: Unprocessable Content, as the operation's description says." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code internal_error: a failure on our side, which was logged. When its message says nothing changed (the file store refused the request, the virus scan could not be queued, the upload could not be read), nothing did, the same request fails the same way until it is fixed, and the Idempotency-Key stays free." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code storage_unavailable (the file store did not answer) or, on an upload, temporarily_unavailable (its uploaded file could not be read): nothing changed, and the same request can succeed later. Retry after the Retry-After seconds; a write retried with the same Idempotency-Key runs again.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (30).", "schema": { "type": "integer" }, "style": "simple" } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Preview a PCSP's authorisations", "tags": [ "Provider care plans" ] } }, "/api/v1/provider-revalidations": { "get": { "callbacks": {}, "description": "The Medicaid revalidation due date for an NPI the agency bills under, as the Provider Web Portal shows it. Reading one needs compliance.view; adding, changing and deleting one needs compliance.manage (403 forbidden otherwise). The agency's provider revalidations in due date order, the nearest first. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getProviderRevalidations", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ProviderRevalidation" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Provider revalidationPage", "type": "object" } } }, "description": "A page of provider revalidations" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List provider revalidations", "tags": [ "Compliance" ] }, "post": { "callbacks": {}, "operationId": "postProviderRevalidations", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderRevalidationInput" } } }, "description": "The provider revalidation's fields", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ProviderRevalidation" } }, "required": [ "data" ], "type": "object" } } }, "description": "The created provider revalidation" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a provider revalidation", "tags": [ "Compliance" ] } }, "/api/v1/provider-revalidations/{id}": { "delete": { "callbacks": {}, "description": "Removes the date and its reminders. Needs compliance.manage.", "operationId": "deleteProviderRevalidationsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ProviderRevalidation" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted revalidation date" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a provider revalidation", "tags": [ "Compliance" ] }, "patch": { "callbacks": {}, "description": "Sets only the fields sent; a changed due date is reminded again at 90, 60 and 30 days. Needs compliance.manage.", "operationId": "patchProviderRevalidationsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderRevalidationInput" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ProviderRevalidation" } }, "required": [ "data" ], "type": "object" } } }, "description": "The updated revalidation date" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a provider revalidation", "tags": [ "Compliance" ] } }, "/api/v1/provider-type-modifiers": { "get": { "callbacks": {}, "description": "Every provider type the agency bills, with its billing code and modifiers: the agency's own set where it changed one, the system default otherwise.", "operationId": "getProviderTypeModifiers", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "agency_owned": { "description": "Whether the agency has its own copy of the template. Its first certification save on a system template makes that copy; modifier changes write the agency's offering and make no copy.", "type": "boolean" }, "billing_code": { "description": "The HCPCS code it bills.", "nullable": true, "type": "string" }, "certification_text": { "description": "The certification its cards print, in English.", "nullable": true, "type": "string" }, "certification_translations": { "additionalProperties": { "type": "string" }, "description": "Its translations, by language code.", "type": "object" }, "certification_version": { "description": "What a certification save sends back, to refuse one saved since.", "nullable": true, "type": "string" }, "code": { "description": "The provider type's code, as the path takes it.", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "modifiers": { "description": "The modifiers it bills, and the batch validation expects.", "items": { "type": "string" }, "type": "array" }, "name": { "description": "The provider type's name.", "nullable": true, "type": "string" } }, "required": [ "code", "modifiers" ], "title": "ProviderTypeModifiers", "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The provider types" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List provider types and their modifiers", "tags": [ "Provider type modifiers" ] } }, "/api/v1/provider-type-modifiers/{code}": { "put": { "callbacks": {}, "description": "Sets the modifiers a provider type bills and the rule the batch validation checks, together, as Settings does. It writes the agency's offering for that set and makes no copy of a system template (agency_owned stays as it was). expected_modifiers is the set the caller read: a set changed since answers 409 stale_modifiers and writes nothing. A value that is not a two-character modifier, more than four, or two programs answers 422 validation_failed; a well-formed modifier no fee schedule prices is saved and named in warnings. Needs billing.manage (403 forbidden otherwise).", "operationId": "putProviderTypeModifiersByCode", "parameters": [ { "description": "The provider type's code.", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "expected_modifiers": { "description": "The modifiers as they were read (find_provider_type_modifiers).", "items": { "type": "string" }, "type": "array" }, "modifiers": { "description": "The modifiers to bill, at most four.", "items": { "type": "string" }, "type": "array" } }, "required": [ "modifiers", "expected_modifiers" ], "type": "object" } } }, "description": "The new set and the one read", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "agency_owned": { "description": "Whether the agency has its own copy of the template. Its first certification save on a system template makes that copy; modifier changes write the agency's offering and make no copy.", "type": "boolean" }, "billing_code": { "description": "The HCPCS code it bills.", "nullable": true, "type": "string" }, "certification_text": { "description": "The certification its cards print, in English.", "nullable": true, "type": "string" }, "certification_translations": { "additionalProperties": { "type": "string" }, "description": "Its translations, by language code.", "type": "object" }, "certification_version": { "description": "What a certification save sends back, to refuse one saved since.", "nullable": true, "type": "string" }, "code": { "description": "The provider type's code, as the path takes it.", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "modifiers": { "description": "The modifiers it bills, and the batch validation expects.", "items": { "type": "string" }, "type": "array" }, "name": { "description": "The provider type's name.", "nullable": true, "type": "string" }, "warnings": { "description": "What the saved set warns of; usually empty. Never a refusal: the set is saved. Each names its rule (catalog.unpriced_modifier: a modifier no fee schedule in force today or later prices on the billing code; it bills as entered) and the message.", "items": { "properties": { "message": { "description": "What the admin is warned of.", "type": "string" }, "rule_id": { "description": "The rule that raised it.", "type": "string" } }, "required": [ "rule_id", "message" ], "title": "ProviderTypeModifierWarning", "type": "object" }, "type": "array" } }, "required": [ "code", "modifiers", "warnings" ], "title": "SavedProviderTypeModifiers", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The provider type" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_modifiers: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Set a provider type's modifiers", "tags": [ "Provider type modifiers" ] } }, "/api/v1/provider-type-templates/{id}/certification": { "patch": { "callbacks": {}, "description": "Saves the English certification its cards print and its translation into the agency's card language, as Settings > Provider Type Templates does. certification_version is the one GET /api/v1/provider-type-modifiers returned: one saved since answers 409 stale_record. The first save on a system default makes the agency's own copy, which answers with its own id. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "patchProviderTypeTemplatesByIdCertification", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "certification_text": { "description": "English; empty for the standard wording.", "nullable": true, "type": "string" }, "certification_version": { "description": "As GET /api/v1/provider-type-modifiers (find_provider_type_modifiers) returned it.", "type": "string" }, "translation": { "description": "Optional: into the agency's card language.", "nullable": true, "type": "string" } }, "required": [ "certification_version" ], "title": "ProviderTypeCertificationUpdate", "type": "object" } } }, "description": "The wording and the version read", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "certification_text": { "nullable": true, "type": "string" }, "certification_translations": { "additionalProperties": { "type": "string" }, "type": "object" }, "certification_version": { "nullable": true, "type": "string" }, "code": { "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "title": "ProviderTypeCertification", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The certification" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a provider type's certification", "tags": [ "Work orders" ] } }, "/api/v1/query": { "post": { "callbacks": {}, "description": "The aggregate the AI assistant and the query_data tool answer: a count (the default query_type), a per-status breakdown, a count within a date range, or the records missing required fields, for one kind of record. Answers counts only, never a record. An entity and query_type pair the assistant cannot answer is 422 unsupported_query; a malformed date or an unknown status is 422 invalid_filters. Stores nothing, so it needs no Idempotency-Key and is allowed with a read-only key.", "operationId": "postQuery", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "entity": { "enum": [ "clients", "caregivers", "timesheets", "batches", "claims", "assignments", "service_rates", "visits" ], "type": "string" }, "filters": { "properties": { "date_from": { "format": "date", "type": "string" }, "date_to": { "format": "date", "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "query_type": { "enum": [ "count", "count_by_status", "date_range_summary", "missing_data_check" ], "type": "string" } }, "required": [ "entity" ], "type": "object" } } }, "description": "The question", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "additionalProperties": true, "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The answer" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes invalid_filters, unsupported_query: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Count the agency's records", "tags": [ "Reports" ] } }, "/api/v1/recertifications": { "get": { "callbacks": {}, "description": "The open renewals of the agency's service authorizations: requested or in progress. The agency's recertifications in requested date, oldest first. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getRecertifications", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Recertification" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "RecertificationPage", "type": "object" } } }, "description": "A page of recertifications" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List recertifications", "tags": [ "Service authorizations" ] } }, "/api/v1/recertifications/{id}/complete": { "post": { "callbacks": {}, "description": "Creates the renewing PAR from authorization, as the web's renewal form does, for the renewed PAR's client and linked back to it. A renewed recertification answers 422 already_renewed.", "operationId": "postRecertificationsByIdComplete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "authorization": { "$ref": "#/components/schemas/ServiceAuthorizationRenewal" } }, "required": [ "authorization" ], "type": "object" } } }, "description": "The renewing PAR", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Recertification" } }, "required": [ "data" ], "type": "object" } } }, "description": "The recertification, renewed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code already_renewed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Complete a recertification with its renewing PAR", "tags": [ "Service authorizations" ] } }, "/api/v1/recertifications/{id}/in-progress": { "post": { "callbacks": {}, "operationId": "postRecertificationsByIdInProgress", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Recertification" } }, "required": [ "data" ], "type": "object" } } }, "description": "The recertification" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Mark a recertification in progress", "tags": [ "Service authorizations" ] } }, "/api/v1/recurring-runs/{id}/hold": { "post": { "callbacks": {}, "description": "As the run banner's Hold: a created run is held, so it is not sent until someone submits its batch (POST /api/v1/batches/{id}/submit). A run already held answers it unchanged; a run in any other state 409 run_status, with the banner's words. Needs a credential holding hcb.submit and an agency at full access, as Submit does: 403 insufficient_scope for a credential without hcb.write or hcb.submit, 403 read_only for a read-only agency, 403 submission_blocked while the agency's billing blocks submission; nothing is written. Another agency's run answers 404 not_found and nothing is written.", "operationId": "postRecurringRunsByIdHold", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/RecurringRun" } }, "required": [ "data" ], "type": "object" } } }, "description": "The run" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes insufficient_scope, read_only, submission_blocked: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code run_status: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Hold a recurring run", "tags": [ "Recurring batches" ] } }, "/api/v1/recurring-runs/{id}/rerun": { "post": { "callbacks": {}, "description": "As the schedule page's Send again: a cancelled, failed or skipped run's period gets a fresh batch from the schedule's current lines, and the run is created again with a new notice and send time. Its old batch is cancelled first: 422 batch_in_progress while it is still being prepared (changed within the hour). Refused, writing nothing: 409 run_status for a run that has not left (created, held or submitted); 422 schedule_ended; 422 nothing_to_bill when every line is already billed by another batch; 422 no_submission_access when the schedule's owner may not submit; 422 patient_limit_exceeded over the plan's client limit; 422 too_many_claims when the period has more claims than HCPF accepts in one batch, so the schedule must be split. Needs a credential holding hcb.submit and an agency at full access, as Submit does: 403 insufficient_scope for a credential without hcb.write or hcb.submit, 403 read_only for a read-only agency, 403 submission_blocked while the agency's billing blocks submission; nothing is written. Another agency's run answers 404 not_found and nothing is written.", "operationId": "postRecurringRunsByIdRerun", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/RecurringRun" } }, "required": [ "data" ], "type": "object" } } }, "description": "The run" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes insufficient_scope, read_only, submission_blocked: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code run_status: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes batch_in_progress, no_submission_access, nothing_to_bill, patient_limit_exceeded, schedule_ended, too_many_claims: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Re-run a recurring period", "tags": [ "Recurring batches" ] } }, "/api/v1/recurring-schedules": { "get": { "callbacks": {}, "description": "The agency's recurring schedules, newest first, as the schedule list shows them, each with next_period.", "operationId": "getRecurringSchedules", "parameters": [ { "description": "Rows per page (default 50, at most 100; a larger value is served as 100).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "allOf": [ { "$ref": "#/components/schemas/RecurringSchedule" }, { "properties": { "next_period": { "description": "The period the schedule bills next, the one Skip acts on; null once it has none.", "nullable": true, "properties": { "period_end": { "description": "The last day billed.", "format": "date", "nullable": true, "type": "string" }, "period_start": { "description": "The first day billed.", "format": "date", "nullable": true, "type": "string" } }, "required": [ "period_start", "period_end" ], "title": "RecurringPeriod", "type": "object" } }, "type": "object" } ] }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "RecurringSchedulePage", "type": "object" } } }, "description": "A page of schedules" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List recurring schedules", "tags": [ "Recurring batches" ] }, "post": { "callbacks": {}, "description": "As Make recurring's confirm: a schedule from the proposal, with any of name, submit_mode, submit_weekday, submit_time and end_date over it, and one line per claim copied field for field (a line whose claim HCPF denied starts paused). 409 schedule_exists, naming it, when the batch already has a live schedule; 422 not_upload_source and 422 not_proposable as the proposal refuses; 404 not_found for a batch this agency does not have; 400 bad_request without batch_id. Line warnings (not paid last period, an EVV visit each week, a PAR ending, more hours a week than the PAR allows) never stop the write: warnings lists each with its line_id. Every write needs a credential holding hcb.submit and an agency at full access, as Submit does: 403 insufficient_scope for a credential without hcb.write or hcb.submit, 403 read_only for a read-only agency, 403 submission_blocked while the agency's billing blocks submission; nothing is written.", "operationId": "postRecurringSchedules", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "batch_id": { "description": "The uploaded batch to make recurring.", "format": "uuid", "type": "string" }, "end_date": { "description": "No run is made for a period starting after it, YYYY-MM-DD.", "format": "date", "type": "string" }, "name": { "description": "The schedule's name.", "maxLength": 120, "type": "string" }, "submit_mode": { "description": "auto sends each run at its send time unless held; approval waits for a Submit.", "enum": [ "auto", "approval" ], "type": "string" }, "submit_time": { "description": "The time a run is sent, HH:MM or HH:MM:SS, Mountain time.", "format": "time", "type": "string" }, "submit_weekday": { "description": "The day a run is sent, Monday 1 to Sunday 7, in Mountain time.", "maximum": 7, "minimum": 1, "type": "integer" } }, "required": [ "batch_id" ], "title": "RecurringScheduleCreate", "type": "object" } } }, "description": "The batch and settings", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/RecurringSchedule" }, { "properties": { "next_period": { "description": "The period the schedule bills next, the one Skip acts on; null once it has none.", "nullable": true, "properties": { "period_end": { "description": "The last day billed.", "format": "date", "nullable": true, "type": "string" }, "period_start": { "description": "The first day billed.", "format": "date", "nullable": true, "type": "string" } }, "required": [ "period_start", "period_end" ], "title": "RecurringPeriod", "type": "object" } }, "type": "object" } ] }, "warnings": { "items": { "properties": { "authorization_id": { "description": "The PAR an over_weekly_allowance warning was judged against; null for every other code.", "format": "uuid", "nullable": true, "type": "string" }, "code": { "description": "What to check.", "enum": [ "not_paid", "recouped", "evv", "par_ends", "over_weekly_allowance" ], "type": "string" }, "line_id": { "description": "The line it is about.", "format": "uuid", "type": "string" }, "message": { "description": "The words the schedule page shows.", "type": "string" } }, "required": [ "code", "message" ], "title": "RecurringLineWarning", "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "type": "object" } } }, "description": "The schedule and its line warnings" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: Bad Request, as the operation's description says." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes insufficient_scope, read_only, submission_blocked: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code schedule_exists: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes not_proposable, not_upload_source: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Make a batch recurring", "tags": [ "Recurring batches" ] } }, "/api/v1/recurring-schedules/{id}": { "get": { "callbacks": {}, "description": "As the schedule page shows it: the schedule, next_period (the run Skip acts on), one page of its lines (limit and offset page them, lines_total counts them) each with its warnings, and its newest 20 runs with runs_total. Another agency's schedule answers 404 not_found.", "operationId": "getRecurringSchedulesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 50, at most 100; a larger value is served as 100).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/RecurringSchedule" }, { "properties": { "next_period": { "description": "The period the schedule bills next, the one Skip acts on; null once it has none.", "nullable": true, "properties": { "period_end": { "description": "The last day billed.", "format": "date", "nullable": true, "type": "string" }, "period_start": { "description": "The first day billed.", "format": "date", "nullable": true, "type": "string" } }, "required": [ "period_start", "period_end" ], "title": "RecurringPeriod", "type": "object" } }, "type": "object" } ] }, { "properties": { "lines": { "items": { "$ref": "#/components/schemas/RecurringScheduleLine" }, "type": "array" }, "lines_total": { "type": "integer" }, "runs": { "items": { "$ref": "#/components/schemas/RecurringRun" }, "type": "array" }, "runs_total": { "type": "integer" } }, "type": "object" } ] } }, "required": [ "data" ], "type": "object" } } }, "description": "The schedule" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a recurring schedule", "tags": [ "Recurring batches" ] }, "patch": { "callbacks": {}, "description": "As the schedule page's settings form and its Pause, Resume and End: the settings sent are saved (with the lock_version read; 409 stale_record when it changed since, 400 bad_request without one), then status moves the schedule. A switch to approval clears the scheduled send of the schedule's runs not yet sent; a send-setting change moves their send time. 422 schedule_ended for an ended schedule; 422 invalid_status for a status that is none. Line warnings (not paid last period, an EVV visit each week, a PAR ending, more hours a week than the PAR allows) never stop the write: warnings lists each with its line_id. Every write needs a credential holding hcb.submit and an agency at full access, as Submit does: 403 insufficient_scope for a credential without hcb.write or hcb.submit, 403 read_only for a read-only agency, 403 submission_blocked while the agency's billing blocks submission; nothing is written. Another agency's schedule, line or run answers 404 not_found and nothing is written.", "operationId": "patchRecurringSchedulesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "end_date": { "description": "YYYY-MM-DD; null clears it.", "format": "date", "nullable": true, "type": "string" }, "lock_version": { "description": "The lock_version the schedule was read with; required when a setting (name, submit_mode, submit_weekday, submit_time, end_date) is sent. A schedule changed since answers 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "name": { "description": "The schedule's name.", "maxLength": 120, "type": "string" }, "status": { "description": "Pause (paused), resume (active) or end (ended, final) the schedule.", "enum": [ "active", "paused", "ended" ], "type": "string" }, "submit_mode": { "description": "auto sends each run at its send time unless held; approval waits for a Submit.", "enum": [ "auto", "approval" ], "type": "string" }, "submit_time": { "description": "The time a run is sent, HH:MM or HH:MM:SS, Mountain time.", "format": "time", "type": "string" }, "submit_weekday": { "description": "The day a run is sent, Monday 1 to Sunday 7, in Mountain time.", "maximum": 7, "minimum": 1, "type": "integer" } }, "title": "RecurringScheduleUpdate", "type": "object" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/RecurringSchedule" }, { "properties": { "next_period": { "description": "The period the schedule bills next, the one Skip acts on; null once it has none.", "nullable": true, "properties": { "period_end": { "description": "The last day billed.", "format": "date", "nullable": true, "type": "string" }, "period_start": { "description": "The first day billed.", "format": "date", "nullable": true, "type": "string" } }, "required": [ "period_start", "period_end" ], "title": "RecurringPeriod", "type": "object" } }, "type": "object" } ] }, "warnings": { "items": { "properties": { "authorization_id": { "description": "The PAR an over_weekly_allowance warning was judged against; null for every other code.", "format": "uuid", "nullable": true, "type": "string" }, "code": { "description": "What to check.", "enum": [ "not_paid", "recouped", "evv", "par_ends", "over_weekly_allowance" ], "type": "string" }, "line_id": { "description": "The line it is about.", "format": "uuid", "type": "string" }, "message": { "description": "The words the schedule page shows.", "type": "string" } }, "required": [ "code", "message" ], "title": "RecurringLineWarning", "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "type": "object" } } }, "description": "The schedule and its line warnings" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: Bad Request, as the operation's description says." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes insufficient_scope, read_only, submission_blocked: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes invalid_status, schedule_ended: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a recurring schedule", "tags": [ "Recurring batches" ] } }, "/api/v1/recurring-schedules/{id}/lines": { "post": { "callbacks": {}, "description": "As the schedule page's Add line: a line billed from the next run on, after the last. 422 validation_failed names a missing member_id, procedure_code, units or charge_amount; 422 schedule_ended for an ended schedule. Line warnings (not paid last period, an EVV visit each week, a PAR ending, more hours a week than the PAR allows) never stop the write: warnings lists each with its line_id. Every write needs a credential holding hcb.submit and an agency at full access, as Submit does: 403 insufficient_scope for a credential without hcb.write or hcb.submit, 403 read_only for a read-only agency, 403 submission_blocked while the agency's billing blocks submission; nothing is written. Another agency's schedule, line or run answers 404 not_found and nothing is written.", "operationId": "postRecurringSchedulesByIdLines", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "charge_amount": { "description": "Amount billed each period.", "format": "decimal", "type": "string" }, "diagnosis_code_1": { "description": "A diagnosis code.", "type": "string" }, "diagnosis_code_2": { "description": "A diagnosis code.", "type": "string" }, "diagnosis_code_3": { "description": "A diagnosis code.", "type": "string" }, "diagnosis_code_4": { "description": "A diagnosis code.", "type": "string" }, "member_id": { "description": "The Medicaid member id.", "type": "string" }, "modifier_1": { "description": "A modifier.", "type": "string" }, "modifier_2": { "description": "A modifier.", "type": "string" }, "modifier_3": { "description": "A modifier.", "type": "string" }, "modifier_4": { "description": "A modifier.", "type": "string" }, "par_number": { "description": "The prior authorization request number.", "type": "string" }, "patient_dob": { "description": "The member's date of birth, YYYY-MM-DD. Written only; never answered.", "format": "date", "type": "string" }, "patient_first_name": { "description": "The member's first name.", "type": "string" }, "patient_last_name": { "description": "The member's last name.", "type": "string" }, "place_of_service": { "description": "The place of service code, e.g. 99.", "type": "string" }, "procedure_code": { "description": "The procedure code, e.g. T1019.", "type": "string" }, "rendering_npi": { "description": "The rendering provider's NPI.", "type": "string" }, "units": { "description": "Units billed each period.", "format": "decimal", "type": "string" } }, "required": [ "member_id", "procedure_code", "units", "charge_amount" ], "title": "RecurringLineCreate", "type": "object" } } }, "description": "The line", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/RecurringScheduleLine" }, "warnings": { "items": { "properties": { "authorization_id": { "description": "The PAR an over_weekly_allowance warning was judged against; null for every other code.", "format": "uuid", "nullable": true, "type": "string" }, "code": { "description": "What to check.", "enum": [ "not_paid", "recouped", "evv", "par_ends", "over_weekly_allowance" ], "type": "string" }, "line_id": { "description": "The line it is about.", "format": "uuid", "type": "string" }, "message": { "description": "The words the schedule page shows.", "type": "string" } }, "required": [ "code", "message" ], "title": "RecurringLineWarning", "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "type": "object" } } }, "description": "The line and its warnings" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes insufficient_scope, read_only, submission_blocked: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes schedule_ended, validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Add a line to a recurring schedule", "tags": [ "Recurring batches" ] } }, "/api/v1/recurring-schedules/{id}/lines/{line_id}": { "delete": { "callbacks": {}, "description": "As the schedule page's Delete: the line is removed; the claims runs made from it keep their data. 422 schedule_ended for an ended schedule. Every write needs a credential holding hcb.submit and an agency at full access, as Submit does: 403 insufficient_scope for a credential without hcb.write or hcb.submit, 403 read_only for a read-only agency, 403 submission_blocked while the agency's billing blocks submission; nothing is written. Another agency's schedule, line or run answers 404 not_found and nothing is written.", "operationId": "deleteRecurringSchedulesByIdLinesByLineId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The line's id.", "in": "path", "name": "line_id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/RecurringScheduleLine" }, "warnings": { "items": { "properties": { "authorization_id": { "description": "The PAR an over_weekly_allowance warning was judged against; null for every other code.", "format": "uuid", "nullable": true, "type": "string" }, "code": { "description": "What to check.", "enum": [ "not_paid", "recouped", "evv", "par_ends", "over_weekly_allowance" ], "type": "string" }, "line_id": { "description": "The line it is about.", "format": "uuid", "type": "string" }, "message": { "description": "The words the schedule page shows.", "type": "string" } }, "required": [ "code", "message" ], "title": "RecurringLineWarning", "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "type": "object" } } }, "description": "The deleted line" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes insufficient_scope, read_only, submission_blocked: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code schedule_ended: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a recurring line", "tags": [ "Recurring batches" ] }, "patch": { "callbacks": {}, "description": "As the schedule page's line editor and its Pause and Resume: the fields sent are saved (runs already made keep their claims), then status pauses or resumes the line. 422 schedule_ended for an ended schedule. Line warnings (not paid last period, an EVV visit each week, a PAR ending, more hours a week than the PAR allows) never stop the write: warnings lists each with its line_id. Every write needs a credential holding hcb.submit and an agency at full access, as Submit does: 403 insufficient_scope for a credential without hcb.write or hcb.submit, 403 read_only for a read-only agency, 403 submission_blocked while the agency's billing blocks submission; nothing is written. Another agency's schedule, line or run answers 404 not_found and nothing is written.", "operationId": "patchRecurringSchedulesByIdLinesByLineId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The line's id.", "in": "path", "name": "line_id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "charge_amount": { "description": "Amount billed each period.", "format": "decimal", "type": "string" }, "diagnosis_code_1": { "description": "A diagnosis code. Null clears it.", "nullable": true, "type": "string" }, "diagnosis_code_2": { "description": "A diagnosis code. Null clears it.", "nullable": true, "type": "string" }, "diagnosis_code_3": { "description": "A diagnosis code. Null clears it.", "nullable": true, "type": "string" }, "diagnosis_code_4": { "description": "A diagnosis code. Null clears it.", "nullable": true, "type": "string" }, "member_id": { "description": "The Medicaid member id.", "type": "string" }, "modifier_1": { "description": "A modifier. Null clears it.", "nullable": true, "type": "string" }, "modifier_2": { "description": "A modifier. Null clears it.", "nullable": true, "type": "string" }, "modifier_3": { "description": "A modifier. Null clears it.", "nullable": true, "type": "string" }, "modifier_4": { "description": "A modifier. Null clears it.", "nullable": true, "type": "string" }, "par_number": { "description": "The prior authorization request number. Null clears it.", "nullable": true, "type": "string" }, "patient_dob": { "description": "The member's date of birth, YYYY-MM-DD. Written only; never answered. Null clears it.", "format": "date", "nullable": true, "type": "string" }, "patient_first_name": { "description": "The member's first name. Null clears it.", "nullable": true, "type": "string" }, "patient_last_name": { "description": "The member's last name. Null clears it.", "nullable": true, "type": "string" }, "place_of_service": { "description": "The place of service code, e.g. 99.", "type": "string" }, "procedure_code": { "description": "The procedure code, e.g. T1019.", "type": "string" }, "rendering_npi": { "description": "The rendering provider's NPI. Null clears it.", "nullable": true, "type": "string" }, "status": { "description": "paused leaves the line out of runs until it is set active again, whatever paused it.", "enum": [ "active", "paused" ], "type": "string" }, "units": { "description": "Units billed each period.", "format": "decimal", "type": "string" } }, "title": "RecurringLineUpdate", "type": "object" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/RecurringScheduleLine" }, "warnings": { "items": { "properties": { "authorization_id": { "description": "The PAR an over_weekly_allowance warning was judged against; null for every other code.", "format": "uuid", "nullable": true, "type": "string" }, "code": { "description": "What to check.", "enum": [ "not_paid", "recouped", "evv", "par_ends", "over_weekly_allowance" ], "type": "string" }, "line_id": { "description": "The line it is about.", "format": "uuid", "type": "string" }, "message": { "description": "The words the schedule page shows.", "type": "string" } }, "required": [ "code", "message" ], "title": "RecurringLineWarning", "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "type": "object" } } }, "description": "The line and its warnings" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes insufficient_scope, read_only, submission_blocked: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code schedule_ended: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change, pause or resume a recurring line", "tags": [ "Recurring batches" ] } }, "/api/v1/recurring-schedules/{id}/skip-next": { "post": { "callbacks": {}, "description": "As Skip next week: the period next_period names is skipped, its run (made already or not) recorded skipped with no batch sent. period_start must be that period's start: any other answers 409 period_moved with the next_period as it stands now, so a retried skip never reaches a second period (a repeated Idempotency-Key replays the first answer). 409 run_status when that period's run has already left (sent, skipped or cancelled); 409 already_delivered when its batch was already handed to HCPF; 422 schedule_ended when the schedule has no next period; 400 bad_request without period_start. Every write needs a credential holding hcb.submit and an agency at full access, as Submit does: 403 insufficient_scope for a credential without hcb.write or hcb.submit, 403 read_only for a read-only agency, 403 submission_blocked while the agency's billing blocks submission; nothing is written. Another agency's schedule, line or run answers 404 not_found and nothing is written.", "operationId": "postRecurringSchedulesByIdSkipNext", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "period_start": { "description": "The next_period.period_start this schedule was read with. Any other answers 409 period_moved, so a repeated skip never skips a second period.", "format": "date", "type": "string" } }, "required": [ "period_start" ], "title": "RecurringSkip", "type": "object" } } }, "description": "The period seen", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/RecurringRun" } }, "required": [ "data" ], "type": "object" } } }, "description": "The skipped run" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: Bad Request, as the operation's description says." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes insufficient_scope, read_only, submission_blocked: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_delivered, period_moved, run_status: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code schedule_ended: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Skip a recurring schedule's next run", "tags": [ "Recurring batches" ] } }, "/api/v1/refused-clocks": { "get": { "callbacks": {}, "description": "The clocks a cancelled, completed or verified visit refused, which the server kept for the office: nothing on the visit records them, so the office enters the time itself, then marks each reviewed. Only those not yet reviewed, on visits not deleted, newest first; total counts what remains under the same after. An unknown after id is 400.", "operationId": "getRefusedClocks", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "The id of the last clock you read: the page starts after it, so clocks you reviewed meanwhile never make you skip any. Use it instead of offset to work through the list.", "in": "query", "name": "after", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/RefusedClock" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "RefusedClockPage", "type": "object" } } }, "description": "A page of refused clocks" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Bad Request, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List refused clocks", "tags": [ "Refused clocks" ] } }, "/api/v1/refused-clocks/{id}/review": { "post": { "callbacks": {}, "description": "Marks an open refused clock reviewed by the credential's user, with an audit row, once the office has acted on it; it leaves the list. Idempotent: one already reviewed answers as it is, with no second audit row. One on a deleted visit, or not this agency's, is 404; 500 review_failed means nothing was saved, so retry.", "operationId": "postRefusedClocksByIdReview", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/RefusedClock" } }, "required": [ "data" ], "type": "object" } } }, "description": "The reviewed clock" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code review_failed: Internal Server Error, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Mark a refused clock reviewed", "tags": [ "Refused clocks" ] } }, "/api/v1/reminders/{id}/complete": { "post": { "callbacks": {}, "description": "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.", "operationId": "postRemindersByIdComplete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ReminderClosed" } }, "required": [ "data" ], "type": "object" } } }, "description": "The reminder" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code already_closed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Mark a reminder done", "tags": [ "Agenda" ] } }, "/api/v1/reminders/{id}/dismiss": { "post": { "callbacks": {}, "description": "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.", "operationId": "postRemindersByIdDismiss", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ReminderClosed" } }, "required": [ "data" ], "type": "object" } } }, "description": "The reminder" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code already_closed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Dismiss a reminder", "tags": [ "Agenda" ] } }, "/api/v1/remittances": { "get": { "callbacks": {}, "description": "HCPF's 835 remittances: what it paid, denied and reversed. The agency's remittances in receipt order, newest first. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getRemittances", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records changed at or after this instant (ISO 8601, with an offset), compared to the second. The list is then in change order: updated_at, then id.", "in": "query", "name": "updated_since", "schema": { "format": "date-time", "type": "string" } }, { "description": "With updated_since, a cursor: send the last record's updated_at as updated_since and its id as after_id to get the next page. Use this, not offset, to sync: an offset skips a record when an earlier one changes between two requests. The sync is at least once: timestamps are whole seconds and set before commit, so a record changed in the cursor's second, or committed late, can fall behind the cursor. Start each sync pass a minute before the newest updated_at you saw, and treat every record returned as current: apply it over what you hold. A record can change twice within one second, and not every change moves lock_version, so the same updated_at and lock_version do not mean the same content.", "in": "query", "name": "after_id", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Remittance" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "RemittancePage", "type": "object" } } }, "description": "A page of remittances" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List remittances", "tags": [ "Remittances" ] } }, "/api/v1/remittances/{id}": { "get": { "callbacks": {}, "description": "What HCPF paid, denied and reversed on one remittance, claim by claim, with each reason in plain English. lines is paged by limit and offset; lines_total counts them all, and a client wanting every line reads until offset reaches it.", "operationId": "getRemittancesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 500, at most 1000; a larger value is served as 1000).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/RemittanceDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The remittance" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a remittance", "tags": [ "Remittances" ] } }, "/api/v1/report-questions/{id}": { "patch": { "callbacks": {}, "description": "Its wording and its type's settings, as the page's Edit does. Past reports keep the old wording. Needs agency_settings.manage (403 forbidden otherwise). A change the page confirms first answers 409 confirmation_required unless confirm is true.", "operationId": "patchReportQuestionsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "confirm": { "description": "Confirm a change the page would ask about.", "type": "boolean" }, "describes": { "description": "text: the key of the question it explains; null or an empty string clears it.", "nullable": true, "type": "string" }, "heading": { "description": "consent_text: its heading.", "type": "string" }, "item_type": { "description": "Its kind, which never changes: the type it has is accepted, any other is refused.", "enum": [ "yes_no", "consent_text", "text", "phone", "choice", "multi_choice", "date", "section" ], "type": "string" }, "label_en": { "description": "The English text.", "type": "string" }, "label_secondary": { "description": "The text in the agency's print language; null or an empty string removes it.", "nullable": true, "type": "string" }, "multiline": { "description": "text: whether the answer is a paragraph.", "type": "boolean" }, "option_labels": { "additionalProperties": { "type": "string" }, "description": "choice and multi_choice: a caption for each code, keyed by code. It replaces the stored captions. A code it names must be in the options, or be one this same write removes from them, whose caption is dropped with it. Sent without it, an options change keeps the captions of the codes still listed.", "type": "object" }, "options": { "description": "choice and multi_choice: the option codes, in print order.", "items": { "type": "string" }, "type": "array" }, "print_region": { "description": "yes_no on the supervisory sheet: where it prints. A new one prints in the table unless told otherwise. The sheet's own band questions print below both tables and take none.", "enum": [ "top_list", "table" ], "type": "string" } }, "required": [ "label_en" ], "title": "ReportQuestionUpdate", "type": "object" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "active": { "description": "Whether new reports ask it.", "type": "boolean" }, "advisory": { "description": "Whether a statute or the agency's paper asks for it.", "type": "boolean" }, "config": { "description": "Its type's settings.", "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_type": { "description": "What kind of question it is.", "nullable": true, "type": "string" }, "labels": { "description": "Its text by language code (en, and the print language).", "type": "object" }, "position": { "description": "Its place on the form.", "type": "integer" }, "printed": { "description": "Whether it prints.", "type": "boolean" }, "question_key": { "description": "Its frozen key; answers are kept under it.", "nullable": true, "type": "string" }, "report_type": { "description": "Its report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "required_to_sign": { "description": "Whether it must be answered before signing.", "type": "boolean" }, "seeded": { "description": "Whether it ships with the form.", "type": "boolean" }, "translated": { "description": "Whether it prints in the second language.", "type": "boolean" } }, "required": [ "id", "report_type", "question_key", "labels" ], "title": "ReportQuestion", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The question" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code confirmation_required: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Edit a report question", "tags": [ "Report templates" ] } }, "/api/v1/report-questions/{id}/deactivate": { "post": { "callbacks": {}, "description": "New reports stop asking it; past reports keep it. Needs agency_settings.manage (403 forbidden otherwise). A change the page confirms first answers 409 confirmation_required unless confirm is true.", "operationId": "postReportQuestionsByIdDeactivate", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "confirm": { "description": "Confirm a change the page would ask about first.", "type": "boolean" } }, "title": "ReportQuestionHide", "type": "object" } } }, "description": "Confirmation", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "active": { "description": "Whether new reports ask it.", "type": "boolean" }, "advisory": { "description": "Whether a statute or the agency's paper asks for it.", "type": "boolean" }, "config": { "description": "Its type's settings.", "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_type": { "description": "What kind of question it is.", "nullable": true, "type": "string" }, "labels": { "description": "Its text by language code (en, and the print language).", "type": "object" }, "position": { "description": "Its place on the form.", "type": "integer" }, "printed": { "description": "Whether it prints.", "type": "boolean" }, "question_key": { "description": "Its frozen key; answers are kept under it.", "nullable": true, "type": "string" }, "report_type": { "description": "Its report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "required_to_sign": { "description": "Whether it must be answered before signing.", "type": "boolean" }, "seeded": { "description": "Whether it ships with the form.", "type": "boolean" }, "translated": { "description": "Whether it prints in the second language.", "type": "boolean" } }, "required": [ "id", "report_type", "question_key", "labels" ], "title": "ReportQuestion", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The question" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code confirmation_required: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Hide a report question", "tags": [ "Report templates" ] } }, "/api/v1/report-questions/{id}/flag": { "post": { "callbacks": {}, "description": "translated, required_to_sign or printed, to the value sent, as the page's toggles set them. Setting a flag to what it already is changes nothing. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "postReportQuestionsByIdFlag", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "flag": { "description": "The flag to set.", "enum": [ "printed", "required_to_sign", "translated" ], "type": "string" }, "value": { "description": "What to set it to.", "type": "boolean" } }, "required": [ "flag", "value" ], "title": "ReportQuestionFlag", "type": "object" } } }, "description": "The flag and its value", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "active": { "description": "Whether new reports ask it.", "type": "boolean" }, "advisory": { "description": "Whether a statute or the agency's paper asks for it.", "type": "boolean" }, "config": { "description": "Its type's settings.", "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_type": { "description": "What kind of question it is.", "nullable": true, "type": "string" }, "labels": { "description": "Its text by language code (en, and the print language).", "type": "object" }, "position": { "description": "Its place on the form.", "type": "integer" }, "printed": { "description": "Whether it prints.", "type": "boolean" }, "question_key": { "description": "Its frozen key; answers are kept under it.", "nullable": true, "type": "string" }, "report_type": { "description": "Its report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "required_to_sign": { "description": "Whether it must be answered before signing.", "type": "boolean" }, "seeded": { "description": "Whether it ships with the form.", "type": "boolean" }, "translated": { "description": "Whether it prints in the second language.", "type": "boolean" } }, "required": [ "id", "report_type", "question_key", "labels" ], "title": "ReportQuestion", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The question" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Set a report question's flag", "tags": [ "Report templates" ] } }, "/api/v1/report-questions/{id}/move": { "post": { "callbacks": {}, "description": "One place, as the page's arrows do; answers the template's questions in their new order. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "postReportQuestionsByIdMove", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "direction": { "description": "Which way.", "enum": [ "up", "down" ], "type": "string" } }, "required": [ "direction" ], "title": "ReportQuestionMove", "type": "object" } } }, "description": "Which way", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "active": { "description": "Whether new reports ask it.", "type": "boolean" }, "advisory": { "description": "Whether a statute or the agency's paper asks for it.", "type": "boolean" }, "config": { "description": "Its type's settings.", "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_type": { "description": "What kind of question it is.", "nullable": true, "type": "string" }, "labels": { "description": "Its text by language code (en, and the print language).", "type": "object" }, "position": { "description": "Its place on the form.", "type": "integer" }, "printed": { "description": "Whether it prints.", "type": "boolean" }, "question_key": { "description": "Its frozen key; answers are kept under it.", "nullable": true, "type": "string" }, "report_type": { "description": "Its report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "required_to_sign": { "description": "Whether it must be answered before signing.", "type": "boolean" }, "seeded": { "description": "Whether it ships with the form.", "type": "boolean" }, "translated": { "description": "Whether it prints in the second language.", "type": "boolean" } }, "required": [ "id", "report_type", "question_key", "labels" ], "title": "ReportQuestion", "type": "object" }, "title": "ReportQuestionsMoved", "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The questions" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Move a report question up or down", "tags": [ "Report templates" ] } }, "/api/v1/report-questions/{id}/reactivate": { "post": { "callbacks": {}, "description": "As the page's Restore does. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "postReportQuestionsByIdReactivate", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "active": { "description": "Whether new reports ask it.", "type": "boolean" }, "advisory": { "description": "Whether a statute or the agency's paper asks for it.", "type": "boolean" }, "config": { "description": "Its type's settings.", "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_type": { "description": "What kind of question it is.", "nullable": true, "type": "string" }, "labels": { "description": "Its text by language code (en, and the print language).", "type": "object" }, "position": { "description": "Its place on the form.", "type": "integer" }, "printed": { "description": "Whether it prints.", "type": "boolean" }, "question_key": { "description": "Its frozen key; answers are kept under it.", "nullable": true, "type": "string" }, "report_type": { "description": "Its report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "required_to_sign": { "description": "Whether it must be answered before signing.", "type": "boolean" }, "seeded": { "description": "Whether it ships with the form.", "type": "boolean" }, "translated": { "description": "Whether it prints in the second language.", "type": "boolean" } }, "required": [ "id", "report_type", "question_key", "labels" ], "title": "ReportQuestion", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The question" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Show a hidden report question", "tags": [ "Report templates" ] } }, "/api/v1/report-templates/{report_type}": { "get": { "callbacks": {}, "description": "The report type's questions, hidden ones included, in order, and its printed form settings, as Settings > Report templates shows them. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "getReportTemplatesByReportType", "parameters": [ { "description": "The report type.", "in": "path", "name": "report_type", "required": true, "schema": { "description": "The report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "form": { "properties": { "orientation": { "description": "How it prints.", "enum": [ "portrait", "landscape" ], "type": "string" }, "report_type": { "description": "The report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "title": { "description": "The printed title; null prints the default.", "nullable": true, "type": "string" }, "version": { "description": "How many times it has been saved.", "type": "integer" } }, "required": [ "report_type", "orientation" ], "title": "ReportTemplateForm", "type": "object" }, "questions": { "items": { "properties": { "active": { "description": "Whether new reports ask it.", "type": "boolean" }, "advisory": { "description": "Whether a statute or the agency's paper asks for it.", "type": "boolean" }, "config": { "description": "Its type's settings.", "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_type": { "description": "What kind of question it is.", "nullable": true, "type": "string" }, "labels": { "description": "Its text by language code (en, and the print language).", "type": "object" }, "position": { "description": "Its place on the form.", "type": "integer" }, "printed": { "description": "Whether it prints.", "type": "boolean" }, "question_key": { "description": "Its frozen key; answers are kept under it.", "nullable": true, "type": "string" }, "report_type": { "description": "Its report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "required_to_sign": { "description": "Whether it must be answered before signing.", "type": "boolean" }, "seeded": { "description": "Whether it ships with the form.", "type": "boolean" }, "translated": { "description": "Whether it prints in the second language.", "type": "boolean" } }, "required": [ "id", "report_type", "question_key", "labels" ], "title": "ReportQuestion", "type": "object" }, "type": "array" } }, "required": [ "form", "questions" ], "title": "ReportTemplate", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The template" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read a report template", "tags": [ "Report templates" ] } }, "/api/v1/report-templates/{report_type}/apply-preset": { "post": { "callbacks": {}, "description": "Replaces the questions with the preset's, as the page's presets do; every question stays editable. An unknown preset answers 422 unknown_preset. Needs agency_settings.manage (403 forbidden otherwise). A change the page confirms first answers 409 confirmation_required unless confirm is true.", "operationId": "postReportTemplatesByReportTypeApplyPreset", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "description": "The report type.", "in": "path", "name": "report_type", "required": true, "schema": { "description": "The report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "confirm": { "description": "Confirm a change the page would ask about first.", "type": "boolean" }, "preset": { "description": "The preset's name.", "type": "string" } }, "required": [ "preset" ], "title": "ReportPresetApply", "type": "object" } } }, "description": "The preset", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "active": { "description": "Whether new reports ask it.", "type": "boolean" }, "advisory": { "description": "Whether a statute or the agency's paper asks for it.", "type": "boolean" }, "config": { "description": "Its type's settings.", "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_type": { "description": "What kind of question it is.", "nullable": true, "type": "string" }, "labels": { "description": "Its text by language code (en, and the print language).", "type": "object" }, "position": { "description": "Its place on the form.", "type": "integer" }, "printed": { "description": "Whether it prints.", "type": "boolean" }, "question_key": { "description": "Its frozen key; answers are kept under it.", "nullable": true, "type": "string" }, "report_type": { "description": "Its report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "required_to_sign": { "description": "Whether it must be answered before signing.", "type": "boolean" }, "seeded": { "description": "Whether it ships with the form.", "type": "boolean" }, "translated": { "description": "Whether it prints in the second language.", "type": "boolean" } }, "required": [ "id", "report_type", "question_key", "labels" ], "title": "ReportQuestion", "type": "object" }, "title": "ReportQuestionsPreset", "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The questions" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code confirmation_required: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code unknown_preset: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Apply a shipped preset to a report template", "tags": [ "Report templates" ] } }, "/api/v1/report-templates/{report_type}/form": { "patch": { "callbacks": {}, "description": "Its title (null, blank or left out prints the default) and orientation, written whole. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "patchReportTemplatesByReportTypeForm", "parameters": [ { "description": "The report type.", "in": "path", "name": "report_type", "required": true, "schema": { "description": "The report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "orientation": { "description": "How it prints.", "enum": [ "portrait", "landscape" ], "type": "string" }, "title": { "description": "The printed title; null, blank or left out prints the default.", "nullable": true, "type": "string" } }, "required": [ "orientation" ], "title": "ReportTemplateFormUpdate", "type": "object" } } }, "description": "The form", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "orientation": { "description": "How it prints.", "enum": [ "portrait", "landscape" ], "type": "string" }, "report_type": { "description": "The report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "title": { "description": "The printed title; null prints the default.", "nullable": true, "type": "string" }, "version": { "description": "How many times it has been saved.", "type": "integer" } }, "required": [ "report_type", "orientation" ], "title": "ReportTemplateForm", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The form" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Save a report template's printed form", "tags": [ "Report templates" ] } }, "/api/v1/report-templates/{report_type}/questions": { "post": { "callbacks": {}, "description": "At the end, as the page's Add does; its key is made from the English text and never changes. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "postReportTemplatesByReportTypeQuestions", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "description": "The report type.", "in": "path", "name": "report_type", "required": true, "schema": { "description": "The report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "describes": { "description": "text: the key of the question it explains; null or an empty string clears it.", "nullable": true, "type": "string" }, "heading": { "description": "consent_text: its heading.", "type": "string" }, "item_type": { "description": "What kind of question it is; the report type's first kind when omitted.", "enum": [ "yes_no", "consent_text", "text", "phone", "choice", "multi_choice", "date", "section" ], "type": "string" }, "label_en": { "description": "The English text.", "type": "string" }, "label_secondary": { "description": "The text in the agency's print language; null or an empty string removes it.", "nullable": true, "type": "string" }, "multiline": { "description": "text: whether the answer is a paragraph.", "type": "boolean" }, "option_labels": { "additionalProperties": { "type": "string" }, "description": "choice and multi_choice: a caption for each code, keyed by code. It replaces the stored captions. A code it names must be in the options, or be one this same write removes from them, whose caption is dropped with it. Sent without it, an options change keeps the captions of the codes still listed.", "type": "object" }, "options": { "description": "choice and multi_choice: the option codes, in print order.", "items": { "type": "string" }, "type": "array" }, "print_region": { "description": "yes_no on the supervisory sheet: where it prints. A new one prints in the table unless told otherwise. The sheet's own band questions print below both tables and take none.", "enum": [ "top_list", "table" ], "type": "string" } }, "required": [ "label_en" ], "title": "ReportQuestionCreate", "type": "object" } } }, "description": "The question", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "active": { "description": "Whether new reports ask it.", "type": "boolean" }, "advisory": { "description": "Whether a statute or the agency's paper asks for it.", "type": "boolean" }, "config": { "description": "Its type's settings.", "type": "object" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "item_type": { "description": "What kind of question it is.", "nullable": true, "type": "string" }, "labels": { "description": "Its text by language code (en, and the print language).", "type": "object" }, "position": { "description": "Its place on the form.", "type": "integer" }, "printed": { "description": "Whether it prints.", "type": "boolean" }, "question_key": { "description": "Its frozen key; answers are kept under it.", "nullable": true, "type": "string" }, "report_type": { "description": "Its report type.", "enum": [ "monthly_client_report", "supervisory_home_visit", "plan_of_care_consent", "client_emergency_information", "complaint_grievance", "agency_disclosure_notice", "client_rights_acknowledgement" ], "type": "string" }, "required_to_sign": { "description": "Whether it must be answered before signing.", "type": "boolean" }, "seeded": { "description": "Whether it ships with the form.", "type": "boolean" }, "translated": { "description": "Whether it prints in the second language.", "type": "boolean" } }, "required": [ "id", "report_type", "question_key", "labels" ], "title": "ReportQuestion", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The question" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Add a question to a report template", "tags": [ "Report templates" ] } }, "/api/v1/reports/electronic-evidence": { "get": { "callbacks": {}, "description": "US-101.12: the share of worked client-days with electronic visit evidence (the caregiver app, the phone line, Sandata or another EVV vendor), for the 12 months ending with month, and for month itself per caregiver and per client, lowest share first and paged (limit and offset apply to both tables). A worked client-day is a client, caregiver and date with a worked visit or timesheet hours. Figures are computed nightly, for live agencies only (the nightly run skips demo agencies, whose months all answer computed false): a month with no snapshot answers computed false, never 0%. Work Order days are not counted. month defaults to the latest computed month.", "operationId": "getReportsElectronicEvidence", "parameters": [ { "description": "The month, YYYY-MM.", "in": "query", "name": "month", "required": false, "schema": { "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } }, { "description": "Rows per page (default 25, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "caregivers": { "properties": { "data": { "items": { "properties": { "client_days": { "description": "The caregiver's worked client-days in the month.", "nullable": true, "type": "integer" }, "electronic_days": { "description": "Of those, the days with electronic evidence.", "nullable": true, "type": "integer" }, "id": { "description": "The caregiver; null once the caregiver is removed.", "format": "uuid", "nullable": true, "type": "string" }, "name": { "description": "The caregiver's \"Last, First\".", "nullable": true, "type": "string", "x-untrusted": "text" }, "share": { "description": "electronic_days / client_days, 0 to 1; null with no worked day.", "nullable": true, "type": "number" } }, "required": [ "client_days", "electronic_days" ], "title": "ElectronicEvidenceCaregiversRow", "type": "object" }, "type": "array" }, "total": { "description": "How many rows the month has.", "nullable": true, "type": "integer" } }, "required": [ "data", "total" ], "title": "ElectronicEvidenceCaregivers", "type": "object" }, "clients": { "properties": { "data": { "items": { "properties": { "client_days": { "description": "The client's worked client-days in the month.", "nullable": true, "type": "integer" }, "electronic_days": { "description": "Of those, the days with electronic evidence.", "nullable": true, "type": "integer" }, "id": { "description": "The client; null once the client is removed.", "format": "uuid", "nullable": true, "type": "string" }, "name": { "description": "The client's \"Last, First\".", "nullable": true, "type": "string", "x-untrusted": "text" }, "share": { "description": "electronic_days / client_days, 0 to 1; null with no worked day.", "nullable": true, "type": "number" } }, "required": [ "client_days", "electronic_days" ], "title": "ElectronicEvidenceClientsRow", "type": "object" }, "type": "array" }, "total": { "description": "How many rows the month has.", "nullable": true, "type": "integer" } }, "required": [ "data", "total" ], "title": "ElectronicEvidenceClients", "type": "object" }, "computed": { "description": "Whether the month has a snapshot.", "type": "boolean" }, "limit": { "description": "The page size of both tables.", "nullable": true, "type": "integer" }, "month": { "description": "YYYY-MM.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" }, "offset": { "description": "The rows skipped in both tables.", "nullable": true, "type": "integer" }, "trend": { "description": "The 12 months ending with month, newest first.", "items": { "properties": { "client_days": { "description": "Worked client-days; null when not computed.", "nullable": true, "type": "integer" }, "computed": { "description": "False when the month has no snapshot yet: not 0%.", "type": "boolean" }, "electronic_days": { "description": "Of those, the days with electronic evidence; null when not computed.", "nullable": true, "type": "integer" }, "month": { "description": "YYYY-MM.", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" }, "share": { "description": "electronic_days / client_days, 0 to 1; null with no worked day.", "nullable": true, "type": "number" } }, "required": [ "month", "computed" ], "title": "ElectronicEvidenceTrendMonth", "type": "object" }, "type": "array" } }, "required": [ "month", "computed", "trend", "caregivers", "clients", "limit", "offset" ], "title": "ElectronicEvidenceReport", "type": "object" } } }, "description": "The electronic evidence report" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read the electronic evidence (adoption) report of a month", "tags": [ "Visits" ] } }, "/api/v1/reports/workforce": { "get": { "callbacks": {}, "description": "US-74.8: for HCPF's Base Wage Attestation and Workforce Reporting, each Direct Care Worker's hours, lowest wage in force, four-week average hours, members served and counties per primary service, from the period's worked EVV visits and approved or exported timesheets (a day with a worked visit is counted from the visit only), ordered by the caregiver's name and paged. A row with missing data is kept: missing names the blank cells. from and to are required, at most a year apart.", "operationId": "getReportsWorkforce", "parameters": [ { "description": "The period's first day, YYYY-MM-DD.", "in": "query", "name": "from", "required": true, "schema": { "format": "date", "type": "string" } }, { "description": "The period's last day, YYYY-MM-DD.", "in": "query", "name": "to", "required": true, "schema": { "format": "date", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/WorkforceReportRow" }, "type": "array" }, "from": { "description": "The period's first day.", "format": "date", "nullable": true, "type": "string" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "to": { "description": "The period's last day.", "format": "date", "nullable": true, "type": "string" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "from", "to", "data", "limit", "offset", "total" ], "title": "WorkforceReportPage", "type": "object" } } }, "description": "A page of the DCW Workforce Report" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read the DCW Workforce Report of a period", "tags": [ "Workforce" ] } }, "/api/v1/responses": { "get": { "callbacks": {}, "description": "The files HCPF sent back: acknowledgments of the agency's batches, and remittances. The agency's responses in receipt order, newest first. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getResponses", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only responses of this kind: ta1 acknowledges an interchange, x999 a file, era835 is a remittance; the remaining value is a claim-level acknowledgment HCPF does not send in practice.", "in": "query", "name": "response_type", "schema": { "enum": [ "ta1", "x999", "x277ca", "era835" ], "type": "string" } }, { "description": "Only records changed at or after this instant (ISO 8601, with an offset), compared to the second. The list is then in change order: updated_at, then id.", "in": "query", "name": "updated_since", "schema": { "format": "date-time", "type": "string" } }, { "description": "With updated_since, a cursor: send the last record's updated_at as updated_since and its id as after_id to get the next page. Use this, not offset, to sync: an offset skips a record when an earlier one changes between two requests. The sync is at least once: timestamps are whole seconds and set before commit, so a record changed in the cursor's second, or committed late, can fall behind the cursor. Start each sync pass a minute before the newest updated_at you saw, and treat every record returned as current: apply it over what you hold. A record can change twice within one second, and not every change moves lock_version, so the same updated_at and lock_version do not mean the same content.", "in": "query", "name": "after_id", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Response" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ResponsePage", "type": "object" } } }, "description": "A page of responses" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List responses", "tags": [ "Responses" ] } }, "/api/v1/responses/{id}": { "get": { "callbacks": {}, "description": "The files HCPF sent back: acknowledgments of the agency's batches, and remittances.", "operationId": "getResponsesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Response" } }, "required": [ "data" ], "type": "object" } } }, "description": "The response" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no response with that id in this agency, including another agency's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a response", "tags": [ "Responses" ] } }, "/api/v1/resubmission-deadlines": { "get": { "callbacks": {}, "description": "Denied and unpaid claims, the soonest resubmit-by date first, each with the date and what it counts from. A line whose date passed more than 30 days ago is no longer listed. Dismissed lines are left out unless include_dismissed is true.", "operationId": "getResubmissionDeadlines", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only lines due on or before today plus this many days (passed ones included).", "in": "query", "name": "within_days", "schema": { "maximum": 366, "minimum": 0, "type": "integer" } }, { "description": "true to list dismissed lines too, each with dismissed: true.", "in": "query", "name": "include_dismissed", "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ResubmissionDeadline" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ResubmissionDeadlinePage", "type": "object" } } }, "description": "The deadlines" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List resubmission deadlines", "tags": [ "Claims" ] } }, "/api/v1/revenue-at-risk": { "get": { "callbacks": {}, "description": "The dollars of billable care at risk in the next 14 or 30 days: the unused value of active PARs that end inside the window with no renewal on file, plus scheduled visits inside the window that no active or pending PAR covers, at HCPF's published rates in whole dollars. The rows are the PARs and visits behind the total, the largest first, unpriced ones last. Scheduled visits count only as far ahead as the schedule has made them. Nothing here blocks a claim.", "operationId": "getRevenueAtRisk", "parameters": [ { "description": "14 or 30 (default 30).", "in": "query", "name": "within_days", "schema": { "enum": [ 14, 30 ], "type": "integer" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/RevenueAtRisk" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "summary": { "properties": { "total": { "description": "unused.value plus uncovered.value, in whole dollars.", "format": "decimal", "nullable": true, "type": "string" }, "truncated": { "description": "True when the window held more PARs or visits than one read values; the total is then a floor.", "type": "boolean" }, "uncovered": { "description": "Scheduled care with no PAR.", "properties": { "count": { "description": "Rows, priced or not.", "minimum": 0, "type": "integer" }, "value": { "description": "Whole dollars, the priced rows only.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "value", "count" ], "title": "RevenueAtRiskPart", "type": "object" }, "unpriced_count": { "description": "Rows with no published rate, left out of the total.", "minimum": 0, "type": "integer" }, "unused": { "description": "Authorized care ending unused.", "properties": { "count": { "description": "Rows, priced or not.", "minimum": 0, "type": "integer" }, "value": { "description": "Whole dollars, the priced rows only.", "format": "decimal", "nullable": true, "type": "string" } }, "required": [ "value", "count" ], "title": "RevenueAtRiskPart", "type": "object" }, "within_days": { "description": "The window read.", "enum": [ 14, 30 ], "type": "integer" } }, "required": [ "within_days", "total", "unused", "uncovered", "unpriced_count", "truncated" ], "title": "RevenueAtRiskSummary", "type": "object" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total", "summary" ], "title": "RevenueAtRiskPage", "type": "object" } } }, "description": "The revenue at risk" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Revenue at risk", "tags": [ "Service authorizations" ] } }, "/api/v1/revenue-warnings/dismissals": { "delete": { "callbacks": {}, "description": "As the batch page's Show again button: ends the dismissal, so the warning is listed as not dismissed; the dismissal is kept as history. No dismissal of that warning in this agency is 404.", "operationId": "deleteRevenueWarningsDismissals", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "fingerprint": { "description": "The warning's fingerprint, as it was listed.", "maxLength": 200, "type": "string" }, "kind": { "description": "The warning's kind, as the warning names it.", "type": "string" }, "subject_id": { "description": "The claim the warning is about: the warning's claim_id.", "format": "uuid", "type": "string" } }, "required": [ "kind", "subject_id", "fingerprint" ], "type": "object" } } }, "description": "The warning to show again", "required": true }, "responses": { "204": { "description": "Shown again" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Show a dismissed revenue warning again", "tags": [ "Claims" ] }, "post": { "callbacks": {}, "description": "As the batch page's Dismiss button: the warning is listed as dismissed until its figures change. Dismissing one already dismissed answers the existing dismissal. A kind no warning has is 422 unknown_kind. A fingerprint that is not the warning's current one (its figures changed since it was listed) is 409 stale_finding, and nothing is written. Another agency's claim answers 404 and nothing is written.", "operationId": "postRevenueWarningsDismissals", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "fingerprint": { "description": "The warning's fingerprint, as it was listed.", "maxLength": 200, "type": "string" }, "kind": { "description": "The warning's kind, as the warning names it.", "type": "string" }, "subject_id": { "description": "The claim the warning is about: the warning's claim_id.", "format": "uuid", "type": "string" } }, "required": [ "kind", "subject_id", "fingerprint" ], "type": "object" } } }, "description": "The warning to dismiss", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/RevenueWarningDismissal" } }, "required": [ "data" ], "type": "object" } } }, "description": "The dismissal" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_finding: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code unknown_kind: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Dismiss a revenue warning", "tags": [ "Claims" ] } }, "/api/v1/satisfaction-surveys/{id}": { "delete": { "callbacks": {}, "description": "Soft-deletes the survey, as the client's surveys list does. The answer is the survey's id and deleted_at. A survey changed since it was read answers 409 stale_record.", "operationId": "deleteSatisfactionSurveysById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The lock_version the record was read with: missing answers 400, changed since 409 stale_record.", "in": "query", "name": "lock_version", "required": true, "schema": { "description": "The value the record was read with; a record changed since answers 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "deleted_at": { "description": "When it was deleted (UTC).", "format": "date-time", "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "required": [ "id", "deleted_at" ], "title": "DeletedSatisfactionSurvey", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted survey" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a satisfaction survey", "tags": [ "Deletes and restores" ] }, "patch": { "callbacks": {}, "description": "Send only what changes, with the lock_version read; a stale one answers 409.", "operationId": "patchSatisfactionSurveysById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SatisfactionSurveyInput" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SatisfactionSurvey" } }, "required": [ "data" ], "type": "object" } } }, "description": "The survey" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a satisfaction survey", "tags": [ "Client records" ] } }, "/api/v1/satisfaction-surveys/{id}/complete": { "post": { "callbacks": {}, "description": "Saves any final answers and marks it completed, as the Surveys tab's Complete does. Send the lock_version read.", "operationId": "postSatisfactionSurveysByIdComplete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SatisfactionSurveyInput" } } }, "description": "Final answers", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SatisfactionSurvey" } }, "required": [ "data" ], "type": "object" } } }, "description": "The survey" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Complete a satisfaction survey", "tags": [ "Client records" ] } }, "/api/v1/saved-reports": { "get": { "callbacks": {}, "description": "The saved client or caregiver reports (kind) the credential's user can see: their own and the agency's shared ones. Filters are never returned (they can name a client); filter_count says how many a report has.", "operationId": "getSavedReports", "parameters": [ { "description": "", "in": "query", "name": "kind", "required": true, "schema": { "enum": [ "client", "caregiver" ], "type": "string" } }, { "description": "", "in": "query", "name": "limit", "required": false, "schema": { "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "", "in": "query", "name": "offset", "required": false, "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "type": "object" }, "type": "array" }, "total_count": { "description": "All of them.", "nullable": true, "type": "integer" } }, "required": [ "data" ], "type": "object" } } }, "description": "The records" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List saved reports", "tags": [ "Company documents", "Saved reports" ] }, "post": { "callbacks": {}, "description": "A saved client or caregiver report (kind), with its columns and filters, as Save on the report page does.", "operationId": "postSavedReports", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "columns": { "items": { "type": "string" }, "type": "array" }, "description": { "description": "What it shows; null or blank clears it.", "nullable": true, "type": "string" }, "filters": { "description": "The report's filters, as the report page saves them. Never returned.", "type": "object" }, "kind": { "enum": [ "client", "caregiver" ], "type": "string" }, "name": { "type": "string" }, "visibility": { "description": "private or tenant (the agency's).", "enum": [ "private", "tenant" ], "type": "string" } }, "type": "object" } } }, "description": "The report", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The record" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Save a report", "tags": [ "Company documents", "Saved reports" ] } }, "/api/v1/saved-reports/{id}": { "delete": { "callbacks": {}, "description": "One the credential's user may edit, as above. Another agency's record answers 404 and nothing is written.", "operationId": "deleteSavedReportsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "", "in": "query", "name": "kind", "required": true, "schema": { "enum": [ "client", "caregiver" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The record" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a saved report", "tags": [ "Company documents", "Saved reports" ] }, "patch": { "callbacks": {}, "description": "The fields sent, on a report the credential's user may edit: their own, or another member's with clients.manage (client reports) or caregivers.manage (caregiver reports), as the pages allow. Another's answers 404. Another agency's record answers 404 and nothing is written.", "operationId": "patchSavedReportsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "", "in": "query", "name": "kind", "required": true, "schema": { "enum": [ "client", "caregiver" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "columns": { "items": { "type": "string" }, "type": "array" }, "description": { "description": "What it shows; null or blank clears it.", "nullable": true, "type": "string" }, "filters": { "description": "The report's filters, as the report page saves them. Never returned.", "type": "object" }, "kind": { "enum": [ "client", "caregiver" ], "type": "string" }, "name": { "type": "string" }, "visibility": { "description": "private or tenant (the agency's).", "enum": [ "private", "tenant" ], "type": "string" } }, "type": "object" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The record" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a saved report", "tags": [ "Company documents", "Saved reports" ] } }, "/api/v1/service-areas": { "get": { "callbacks": {}, "description": "The areas open shifts are posted at, by their place in the list, as the areas page lists them; include_archived adds the archived ones after the rest, by name. Needs open_shifts.view.", "operationId": "getServiceAreas", "parameters": [ { "description": "Add the archived areas.", "in": "query", "name": "include_archived", "required": false, "schema": { "description": "Add the archived areas.", "type": "boolean" } }, { "description": "Rows per page (default 100, at most 500; a larger value is served as 500).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "archived": { "description": "Archived: kept for the shifts that name it, offered for none.", "type": "boolean" }, "county": { "description": "A Colorado county.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "latitude": { "description": "The latitude of the area's centre.", "format": "decimal", "nullable": true, "type": "string" }, "longitude": { "description": "The longitude of the area's centre.", "format": "decimal", "nullable": true, "type": "string" }, "name": { "description": "The area's name.", "type": "string" }, "position": { "description": "Its place in the agency's list, 1 first; an archived area keeps its last.", "nullable": true, "type": "integer" } }, "required": [ "id", "name", "latitude", "longitude", "position", "archived" ], "title": "ServiceArea", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "ServiceAreaPage", "type": "object" } } }, "description": "A page of areas" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List the agency's service areas", "tags": [ "Open shifts" ] }, "post": { "callbacks": {}, "description": "As the areas page's Add does: last in the list, or at position, the others moving to make room. A name the agency already holds, archived included, answers 422 validation_failed naming name. Needs agency_settings.manage.", "operationId": "postServiceAreas", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "county": { "description": "A Colorado county (Douglas), or null for none.", "nullable": true, "type": "string" }, "latitude": { "description": "The latitude of the area's centre.", "maximum": 90, "minimum": -90, "type": "number" }, "longitude": { "description": "The longitude of the area's centre.", "maximum": 180, "minimum": -180, "type": "number" }, "name": { "description": "The area's name, as the agency writes it (Denver — Downtown, Parker).", "maxLength": 80, "minLength": 1, "type": "string", "x-untrusted": "text" }, "position": { "description": "Optional; last when left out. Its place in the agency's list, 1 first; the other areas move to make room, and a place past the end puts it last.", "minimum": 1, "type": "integer" } }, "required": [ "name", "latitude", "longitude" ], "title": "ServiceAreaCreate", "type": "object" } } }, "description": "The area", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "archived": { "description": "Archived: kept for the shifts that name it, offered for none.", "type": "boolean" }, "county": { "description": "A Colorado county.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "latitude": { "description": "The latitude of the area's centre.", "format": "decimal", "nullable": true, "type": "string" }, "longitude": { "description": "The longitude of the area's centre.", "format": "decimal", "nullable": true, "type": "string" }, "name": { "description": "The area's name.", "type": "string" }, "position": { "description": "Its place in the agency's list, 1 first; an archived area keeps its last.", "nullable": true, "type": "integer" } }, "required": [ "id", "name", "latitude", "longitude", "position", "archived" ], "title": "ServiceArea", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The area" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Add a service area", "tags": [ "Open shifts" ] } }, "/api/v1/service-areas/import-starter": { "post": { "callbacks": {}, "description": "Adds each area of the starter list whose name the agency does not hold, archived included, after its last area, as the areas page's Use the starter list does. A second call adds none and answers inserted 0. Needs agency_settings.manage.", "operationId": "postServiceAreasImportStarter", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "inserted": { "description": "The areas added.", "nullable": true, "type": "integer" } }, "required": [ "inserted" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "How many were added" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Add the Denver-metro starter areas", "tags": [ "Open shifts" ] } }, "/api/v1/service-areas/{id}": { "patch": { "callbacks": {}, "description": "Renames it, moves it (position, clamped to the list), changes its county or point, archives it (archived true, closing the gap it leaves) or restores it (archived false, last unless a position is sent). A field left out keeps its value. Another agency's area answers 404. Needs agency_settings.manage.", "operationId": "patchServiceAreasById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "archived": { "description": "true archives the area: it keeps its id and stays on what names it, and is offered for nothing new; false restores it, last in the list unless a position is sent.", "type": "boolean" }, "county": { "description": "A Colorado county (Douglas), or null for none.", "nullable": true, "type": "string" }, "latitude": { "description": "The latitude of the area's centre.", "maximum": 90, "minimum": -90, "type": "number" }, "longitude": { "description": "The longitude of the area's centre.", "maximum": 180, "minimum": -180, "type": "number" }, "name": { "description": "The area's name, as the agency writes it (Denver — Downtown, Parker).", "maxLength": 80, "minLength": 1, "type": "string", "x-untrusted": "text" }, "position": { "description": "Its place in the agency's list, 1 first; the other areas move to make room, and a place past the end puts it last.", "minimum": 1, "type": "integer" } }, "title": "ServiceAreaUpdate", "type": "object" } } }, "description": "The fields that change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "archived": { "description": "Archived: kept for the shifts that name it, offered for none.", "type": "boolean" }, "county": { "description": "A Colorado county.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "latitude": { "description": "The latitude of the area's centre.", "format": "decimal", "nullable": true, "type": "string" }, "longitude": { "description": "The longitude of the area's centre.", "format": "decimal", "nullable": true, "type": "string" }, "name": { "description": "The area's name.", "type": "string" }, "position": { "description": "Its place in the agency's list, 1 first; an archived area keeps its last.", "nullable": true, "type": "integer" } }, "required": [ "id", "name", "latitude", "longitude", "position", "archived" ], "title": "ServiceArea", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The area" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a service area", "tags": [ "Open shifts" ] } }, "/api/v1/service-rates": { "get": { "callbacks": {}, "description": "What the agency is paid per unit for a billing code and modifiers. The agency's service rates in billing-code order, newest rate first per code. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getServiceRates", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records with this status.", "in": "query", "name": "status", "schema": { "enum": [ "active", "expired" ], "type": "string" } }, { "description": "Only records changed at or after this instant (ISO 8601, with an offset), compared to the second. The list is then in change order: updated_at, then id.", "in": "query", "name": "updated_since", "schema": { "format": "date-time", "type": "string" } }, { "description": "With updated_since, a cursor: send the last record's updated_at as updated_since and its id as after_id to get the next page. Use this, not offset, to sync: an offset skips a record when an earlier one changes between two requests. The sync is at least once: timestamps are whole seconds and set before commit, so a record changed in the cursor's second, or committed late, can fall behind the cursor. Start each sync pass a minute before the newest updated_at you saw, and treat every record returned as current: apply it over what you hold. A record can change twice within one second, and not every change moves lock_version, so the same updated_at and lock_version do not mean the same content.", "in": "query", "name": "after_id", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/ServiceRate" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Service ratePage", "type": "object" } } }, "description": "A page of service rates" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List service rates", "tags": [ "Service rates" ] }, "post": { "callbacks": {}, "operationId": "postServiceRates", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceRateCreate" } } }, "description": "The service rate's fields", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ServiceRate" } }, "required": [ "data" ], "type": "object" } } }, "description": "The created service rate" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a service rate", "tags": [ "Service rates" ] } }, "/api/v1/service-rates/import": { "post": { "callbacks": {}, "description": "Reads the file as Service rates > Import reads it (at most 5,000 rows; columns matched by name), with effective_date for its rows (today when absent). A rate cell with more than two places is rounded half-up to cents rather than refused. preview true answers the first rows checked and writes nothing: each row's rate_per_unit as it would be stored (null for a cell that is no rate, refused in errors) and its notes, which name any rounding (\"6.9575 rounded to 6.96\"); otherwise every new rate is created and duplicates skipped, and the counts answered.", "operationId": "postServiceRatesImport", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "csv": { "description": "The file as CSV text, header row first.", "type": "string" }, "csv_base64": { "description": "Or the file's bytes, base64.", "type": "string" }, "effective_date": { "description": "YYYY-MM-DD, for the file's rows; today when left out.", "format": "date", "type": "string" }, "preview": { "description": "Check the rows and write nothing.", "type": "boolean" } }, "type": "object" } } }, "description": "The file", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The preview or the import's counts" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Import the agency's rates from a CSV file", "tags": [ "Payroll", "Service rates" ] } }, "/api/v1/service-rates/schedule-source": { "put": { "callbacks": {}, "description": "use_system_fee_schedule true bills against the system's published schedule, false against the agency's own rates, as the service rates page's switch sets it. Nothing stored is changed; the setting changes which rate is used. Sending the current value changes nothing.", "operationId": "putServiceRatesScheduleSource", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "use_system_fee_schedule": { "description": "true bills against the system's schedule, false the agency's own rates.", "type": "boolean" } }, "required": [ "use_system_fee_schedule" ], "type": "object" } } }, "description": "The choice", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The choice as saved" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Choose the fee schedule the agency bills against", "tags": [ "Payroll", "Service rates" ] } }, "/api/v1/service-rates/{id}": { "delete": { "callbacks": {}, "description": "As the service rates page deletes one. Another agency's record answers 404 and nothing is written.", "operationId": "deleteServiceRatesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The rate" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete one of the agency's own rates", "tags": [ "Payroll", "Service rates" ] }, "get": { "callbacks": {}, "description": "What the agency is paid per unit for a billing code and modifiers.", "operationId": "getServiceRatesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ServiceRate" } }, "required": [ "data" ], "type": "object" } } }, "description": "The service rate" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no service rate with that id in this agency, including another agency's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a service rate", "tags": [ "Service rates" ] }, "patch": { "callbacks": {}, "description": "Sets only the fields sent. lock_version is required: send the value you read, and a record changed since answers 409 stale_record.", "operationId": "patchServiceRatesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceRateUpdate" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ServiceRate" } }, "required": [ "data" ], "type": "object" } } }, "description": "The updated service rate" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no service rate with that id in this agency, including another agency's." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: the service rate changed since the lock_version sent was read, or while this request ran. Nothing was saved; read it again and retry." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a service rate", "tags": [ "Service rates" ] } }, "/api/v1/service-rates/{id}/transition": { "post": { "callbacks": {}, "description": "Closes the rate the day before effective_date and opens its successor at rate_per_unit from that day, as the rate list's Change Rate does. Only rate_per_unit and effective_date are read: the successor keeps the rate's code, modifiers and description. A closed rate answers 422 rate_already_closed, before any date is looked at, so a retried transition never opens a second successor. An effective_date that is missing or not YYYY-MM-DD answers 422 missing_effective_date; one not after the current one 422 effective_date_must_be_after_current; either one carries any other refused field's error in details. A rate_per_unit that is not a number, or a start date another rate of the same code and modifiers already has, answers 422 with the field's error in details. Another agency's record answers 404 and nothing is written.", "operationId": "postServiceRatesByIdTransition", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "effective_date": { "description": "YYYY-MM-DD.", "format": "date", "type": "string" }, "rate_per_unit": { "description": "The new rate, a decimal, as text (a leading $ is allowed) or a JSON number.", "oneOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": [ "rate_per_unit", "effective_date" ], "type": "object" } } }, "description": "The new rate and its first day", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The rate" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes effective_date_must_be_after_current, missing_effective_date, rate_already_closed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a rate from a date", "tags": [ "Payroll", "Service rates" ] } }, "/api/v1/settings/adp": { "get": { "callbacks": {}, "description": "As Settings > Payroll shows them: company code, batch description, overtime, pay rates, pay period and earning codes. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "getSettingsAdp", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "adp_batch_description": { "description": "The batch description; null clears it.", "nullable": true, "type": "string" }, "adp_co_code": { "description": "The ADP company code; null clears it.", "nullable": true, "type": "string" }, "adp_earning_code_map": { "additionalProperties": true, "description": "Attendant hours to an ADP Hours column, as the tab's JSON; an empty object leaves the column out.", "type": "object" }, "biweekly_anchor_date": { "description": "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.", "format": "date", "nullable": true, "type": "string" }, "cash_advance_in_adp_run": { "description": "Whether the ADP Run file deducts each caregiver's cash advance as a negative Misc Amount.", "type": "boolean" }, "daily_overtime_enabled": { "description": "Whether daily overtime is reported.", "type": "boolean" }, "default_attendant_pay_rate": { "description": "The attendant hourly rate, such as 18.50: above zero, two decimals; null clears it.", "format": "decimal", "nullable": true, "type": "string" }, "holiday_pay_rate": { "description": "The holiday hourly rate: above zero, two decimals; null clears it.", "format": "decimal", "nullable": true, "type": "string" }, "mileage_pay_rate": { "description": "The rate per mile, such as 0.67: above zero, two decimals; null clears it.", "format": "decimal", "nullable": true, "type": "string" }, "pay_period_frequency": { "description": "The pay period.", "enum": [ "weekly", "biweekly", "semi_monthly", "monthly" ], "type": "string" } }, "required": [ "adp_batch_description", "adp_co_code", "adp_earning_code_map", "biweekly_anchor_date", "cash_advance_in_adp_run", "daily_overtime_enabled", "default_attendant_pay_rate", "holiday_pay_rate", "mileage_pay_rate", "pay_period_frequency" ], "title": "AdpSettings", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The settings" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read the ADP settings", "tags": [ "Agency settings" ] }, "patch": { "callbacks": {}, "description": "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).", "operationId": "patchSettingsAdp", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "adp_batch_description": { "description": "The batch description; null clears it.", "nullable": true, "type": "string" }, "adp_co_code": { "description": "The ADP company code; null clears it.", "nullable": true, "type": "string" }, "adp_earning_code_map": { "additionalProperties": true, "description": "Attendant hours to an ADP Hours column, as the tab's JSON; an empty object leaves the column out.", "type": "object" }, "biweekly_anchor_date": { "description": "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.", "format": "date", "nullable": true, "type": "string" }, "cash_advance_in_adp_run": { "description": "Whether the ADP Run file deducts each caregiver's cash advance as a negative Misc Amount.", "type": "boolean" }, "daily_overtime_enabled": { "description": "Whether daily overtime is reported.", "type": "boolean" }, "default_attendant_pay_rate": { "description": "The attendant hourly rate, such as 18.50: above zero, two decimals; null clears it.", "format": "decimal", "nullable": true, "type": "string" }, "holiday_pay_rate": { "description": "The holiday hourly rate: above zero, two decimals; null clears it.", "format": "decimal", "nullable": true, "type": "string" }, "mileage_pay_rate": { "description": "The rate per mile, such as 0.67: above zero, two decimals; null clears it.", "format": "decimal", "nullable": true, "type": "string" }, "pay_period_frequency": { "description": "The pay period.", "enum": [ "weekly", "biweekly", "semi_monthly", "monthly" ], "type": "string" } }, "title": "AdpSettingsUpdate", "type": "object" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "adp_batch_description": { "description": "The batch description; null clears it.", "nullable": true, "type": "string" }, "adp_co_code": { "description": "The ADP company code; null clears it.", "nullable": true, "type": "string" }, "adp_earning_code_map": { "additionalProperties": true, "description": "Attendant hours to an ADP Hours column, as the tab's JSON; an empty object leaves the column out.", "type": "object" }, "biweekly_anchor_date": { "description": "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.", "format": "date", "nullable": true, "type": "string" }, "cash_advance_in_adp_run": { "description": "Whether the ADP Run file deducts each caregiver's cash advance as a negative Misc Amount.", "type": "boolean" }, "daily_overtime_enabled": { "description": "Whether daily overtime is reported.", "type": "boolean" }, "default_attendant_pay_rate": { "description": "The attendant hourly rate, such as 18.50: above zero, two decimals; null clears it.", "format": "decimal", "nullable": true, "type": "string" }, "holiday_pay_rate": { "description": "The holiday hourly rate: above zero, two decimals; null clears it.", "format": "decimal", "nullable": true, "type": "string" }, "mileage_pay_rate": { "description": "The rate per mile, such as 0.67: above zero, two decimals; null clears it.", "format": "decimal", "nullable": true, "type": "string" }, "pay_period_frequency": { "description": "The pay period.", "enum": [ "weekly", "biweekly", "semi_monthly", "monthly" ], "type": "string" } }, "required": [ "adp_batch_description", "adp_co_code", "adp_earning_code_map", "biweekly_anchor_date", "cash_advance_in_adp_run", "daily_overtime_enabled", "default_attendant_pay_rate", "holiday_pay_rate", "mileage_pay_rate", "pay_period_frequency" ], "title": "AdpSettings", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The settings" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Save the ADP settings", "tags": [ "Agency settings" ] } }, "/api/v1/settings/csv-mapping": { "get": { "callbacks": {}, "description": "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).", "operationId": "getSettingsCsvMapping", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "mapping": { "additionalProperties": { "type": "string" }, "description": "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.", "type": "object" }, "optional_fields": { "description": "The claim fields an upload may carry.", "items": { "type": "string" }, "type": "array" }, "required_fields": { "description": "The claim fields an upload must carry.", "items": { "type": "string" }, "type": "array" } }, "required": [ "mapping", "required_fields", "optional_fields" ], "title": "CsvMapping", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The mapping" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read the CSV column mapping", "tags": [ "Agency settings" ] }, "put": { "callbacks": {}, "description": "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).", "operationId": "putSettingsCsvMapping", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "mapping": { "additionalProperties": { "type": "string" }, "description": "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.", "type": "object" } }, "required": [ "mapping" ], "title": "CsvMappingUpdate", "type": "object" } } }, "description": "The mapping", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "mapping": { "additionalProperties": { "type": "string" }, "description": "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.", "type": "object" }, "optional_fields": { "description": "The claim fields an upload may carry.", "items": { "type": "string" }, "type": "array" }, "required_fields": { "description": "The claim fields an upload must carry.", "items": { "type": "string" }, "type": "array" } }, "required": [ "mapping", "required_fields", "optional_fields" ], "title": "CsvMapping", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The mapping" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Replace the CSV column mapping", "tags": [ "Agency settings" ] } }, "/api/v1/settings/docusign": { "delete": { "callbacks": {}, "description": "As the page's Disconnect does: the agency's tokens and Connect HMAC key are cleared and an audit row written. Envelopes already sent stay at DocuSign. Nothing to disconnect answers the same body and writes nothing. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "deleteSettingsDocusign", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "account_kind": { "description": "The account a send goes through: the agency's own, HomeCareBilling's (paid from prepaid credit), or null when neither is available.", "enum": [ "agency", "platform" ], "nullable": true, "type": "string" }, "agency_connection": { "description": "The agency's own DocuSign connection, null when it never connected. A disconnected one stays here for its history; account_kind says which account a send goes through.", "nullable": true, "properties": { "account_name": { "description": "The DocuSign account's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "connect_hmac_key_set": { "description": "Whether a Connect HMAC key is stored. The key itself is never shown.", "type": "boolean" }, "connect_hmac_key_set_at": { "description": "When the Connect HMAC key was stored.", "format": "date-time", "nullable": true, "type": "string" }, "connected_at": { "description": "When it was connected.", "format": "date-time", "nullable": true, "type": "string" }, "connected_by": { "description": "Who connected it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "disconnected_at": { "description": "When it was disconnected.", "format": "date-time", "nullable": true, "type": "string" }, "docusign_account_id": { "description": "The DocuSign account id.", "nullable": true, "type": "string" }, "docusign_user_email": { "description": "The DocuSign user who connected it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "The agency's own DocuSign connection.", "enum": [ "active", "needs_reconnect", "disconnected" ], "type": "string" } }, "required": [ "status", "connect_hmac_key_set" ], "title": "DocuSignAgencyConnection", "type": "object" }, "own_key_set": { "description": "Whether the agency has saved its own DocuSign integration key, which Connect and every token refresh then run under. The key and its secret are never shown.", "type": "boolean" }, "own_key_set_at": { "description": "When the agency's own key was saved.", "format": "date-time", "nullable": true, "type": "string" }, "platform_price_microdollars": { "description": "What one envelope costs in prepaid credit, in millionths of a dollar, when sends go through HomeCareBilling's account.", "nullable": true, "type": "integer" }, "status": { "description": "The agency's own DocuSign connection: agency_connection.status, or none when it never connected.", "enum": [ "active", "needs_reconnect", "disconnected", "none" ], "type": "string" } }, "required": [ "status", "account_kind", "agency_connection", "own_key_set" ], "title": "DocuSignSettings", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The settings" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Disconnect DocuSign", "tags": [ "DocuSign" ] }, "get": { "callbacks": {}, "description": "As Settings > DocuSign shows them: the agency's connection, the account a send goes through, and whether a Connect HMAC key is stored. No token and no key is ever shown. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "getSettingsDocusign", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "account_kind": { "description": "The account a send goes through: the agency's own, HomeCareBilling's (paid from prepaid credit), or null when neither is available.", "enum": [ "agency", "platform" ], "nullable": true, "type": "string" }, "agency_connection": { "description": "The agency's own DocuSign connection, null when it never connected. A disconnected one stays here for its history; account_kind says which account a send goes through.", "nullable": true, "properties": { "account_name": { "description": "The DocuSign account's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "connect_hmac_key_set": { "description": "Whether a Connect HMAC key is stored. The key itself is never shown.", "type": "boolean" }, "connect_hmac_key_set_at": { "description": "When the Connect HMAC key was stored.", "format": "date-time", "nullable": true, "type": "string" }, "connected_at": { "description": "When it was connected.", "format": "date-time", "nullable": true, "type": "string" }, "connected_by": { "description": "Who connected it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "disconnected_at": { "description": "When it was disconnected.", "format": "date-time", "nullable": true, "type": "string" }, "docusign_account_id": { "description": "The DocuSign account id.", "nullable": true, "type": "string" }, "docusign_user_email": { "description": "The DocuSign user who connected it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "The agency's own DocuSign connection.", "enum": [ "active", "needs_reconnect", "disconnected" ], "type": "string" } }, "required": [ "status", "connect_hmac_key_set" ], "title": "DocuSignAgencyConnection", "type": "object" }, "own_key_set": { "description": "Whether the agency has saved its own DocuSign integration key, which Connect and every token refresh then run under. The key and its secret are never shown.", "type": "boolean" }, "own_key_set_at": { "description": "When the agency's own key was saved.", "format": "date-time", "nullable": true, "type": "string" }, "platform_price_microdollars": { "description": "What one envelope costs in prepaid credit, in millionths of a dollar, when sends go through HomeCareBilling's account.", "nullable": true, "type": "integer" }, "status": { "description": "The agency's own DocuSign connection: agency_connection.status, or none when it never connected.", "enum": [ "active", "needs_reconnect", "disconnected", "none" ], "type": "string" } }, "required": [ "status", "account_kind", "agency_connection", "own_key_set" ], "title": "DocuSignSettings", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The settings" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read the DocuSign settings", "tags": [ "DocuSign" ] } }, "/api/v1/settings/docusign/connect-hmac-key": { "delete": { "callbacks": {}, "description": "Removes the stored key, so Connect deliveries are no longer checked against one. Nothing stored answers the same body and writes nothing. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "deleteSettingsDocusignConnectHmacKey", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "account_kind": { "description": "The account a send goes through: the agency's own, HomeCareBilling's (paid from prepaid credit), or null when neither is available.", "enum": [ "agency", "platform" ], "nullable": true, "type": "string" }, "agency_connection": { "description": "The agency's own DocuSign connection, null when it never connected. A disconnected one stays here for its history; account_kind says which account a send goes through.", "nullable": true, "properties": { "account_name": { "description": "The DocuSign account's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "connect_hmac_key_set": { "description": "Whether a Connect HMAC key is stored. The key itself is never shown.", "type": "boolean" }, "connect_hmac_key_set_at": { "description": "When the Connect HMAC key was stored.", "format": "date-time", "nullable": true, "type": "string" }, "connected_at": { "description": "When it was connected.", "format": "date-time", "nullable": true, "type": "string" }, "connected_by": { "description": "Who connected it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "disconnected_at": { "description": "When it was disconnected.", "format": "date-time", "nullable": true, "type": "string" }, "docusign_account_id": { "description": "The DocuSign account id.", "nullable": true, "type": "string" }, "docusign_user_email": { "description": "The DocuSign user who connected it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "The agency's own DocuSign connection.", "enum": [ "active", "needs_reconnect", "disconnected" ], "type": "string" } }, "required": [ "status", "connect_hmac_key_set" ], "title": "DocuSignAgencyConnection", "type": "object" }, "own_key_set": { "description": "Whether the agency has saved its own DocuSign integration key, which Connect and every token refresh then run under. The key and its secret are never shown.", "type": "boolean" }, "own_key_set_at": { "description": "When the agency's own key was saved.", "format": "date-time", "nullable": true, "type": "string" }, "platform_price_microdollars": { "description": "What one envelope costs in prepaid credit, in millionths of a dollar, when sends go through HomeCareBilling's account.", "nullable": true, "type": "integer" }, "status": { "description": "The agency's own DocuSign connection: agency_connection.status, or none when it never connected.", "enum": [ "active", "needs_reconnect", "disconnected", "none" ], "type": "string" } }, "required": [ "status", "account_kind", "agency_connection", "own_key_set" ], "title": "DocuSignSettings", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The settings" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Remove the DocuSign Connect HMAC key", "tags": [ "DocuSign" ] }, "put": { "callbacks": {}, "description": "Stores, or replaces, the HMAC key of the agency's DocuSign Connect configuration. From then on a Connect delivery for the agency's envelopes is accepted only when a signature matches it. The key is never shown again. With no current connection it answers 422 not_connected; a key that breaks the rule answers 422 validation_failed. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "putSettingsDocusignConnectHmacKey", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "hmac_key": { "description": "The HMAC key from the agency's DocuSign Connect configuration, which must be 16 to 256 characters with no spaces. It is stored encrypted and never shown again.", "nullable": true, "type": "string" } }, "required": [ "hmac_key" ], "title": "DocuSignConnectHmacKey", "type": "object" } } }, "description": "The key", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "account_kind": { "description": "The account a send goes through: the agency's own, HomeCareBilling's (paid from prepaid credit), or null when neither is available.", "enum": [ "agency", "platform" ], "nullable": true, "type": "string" }, "agency_connection": { "description": "The agency's own DocuSign connection, null when it never connected. A disconnected one stays here for its history; account_kind says which account a send goes through.", "nullable": true, "properties": { "account_name": { "description": "The DocuSign account's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "connect_hmac_key_set": { "description": "Whether a Connect HMAC key is stored. The key itself is never shown.", "type": "boolean" }, "connect_hmac_key_set_at": { "description": "When the Connect HMAC key was stored.", "format": "date-time", "nullable": true, "type": "string" }, "connected_at": { "description": "When it was connected.", "format": "date-time", "nullable": true, "type": "string" }, "connected_by": { "description": "Who connected it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "disconnected_at": { "description": "When it was disconnected.", "format": "date-time", "nullable": true, "type": "string" }, "docusign_account_id": { "description": "The DocuSign account id.", "nullable": true, "type": "string" }, "docusign_user_email": { "description": "The DocuSign user who connected it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "The agency's own DocuSign connection.", "enum": [ "active", "needs_reconnect", "disconnected" ], "type": "string" } }, "required": [ "status", "connect_hmac_key_set" ], "title": "DocuSignAgencyConnection", "type": "object" }, "own_key_set": { "description": "Whether the agency has saved its own DocuSign integration key, which Connect and every token refresh then run under. The key and its secret are never shown.", "type": "boolean" }, "own_key_set_at": { "description": "When the agency's own key was saved.", "format": "date-time", "nullable": true, "type": "string" }, "platform_price_microdollars": { "description": "What one envelope costs in prepaid credit, in millionths of a dollar, when sends go through HomeCareBilling's account.", "nullable": true, "type": "integer" }, "status": { "description": "The agency's own DocuSign connection: agency_connection.status, or none when it never connected.", "enum": [ "active", "needs_reconnect", "disconnected", "none" ], "type": "string" } }, "required": [ "status", "account_kind", "agency_connection", "own_key_set" ], "title": "DocuSignSettings", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The settings" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes not_connected, validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Store the DocuSign Connect HMAC key", "tags": [ "DocuSign" ] } }, "/api/v1/settings/docusign/own-key": { "delete": { "callbacks": {}, "description": "Removes the stored key, so Connect and token refreshes run under the app-wide key again, and marks an active connection as needing a reconnect. Nothing stored answers the same body and writes nothing. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "deleteSettingsDocusignOwnKey", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "account_kind": { "description": "The account a send goes through: the agency's own, HomeCareBilling's (paid from prepaid credit), or null when neither is available.", "enum": [ "agency", "platform" ], "nullable": true, "type": "string" }, "agency_connection": { "description": "The agency's own DocuSign connection, null when it never connected. A disconnected one stays here for its history; account_kind says which account a send goes through.", "nullable": true, "properties": { "account_name": { "description": "The DocuSign account's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "connect_hmac_key_set": { "description": "Whether a Connect HMAC key is stored. The key itself is never shown.", "type": "boolean" }, "connect_hmac_key_set_at": { "description": "When the Connect HMAC key was stored.", "format": "date-time", "nullable": true, "type": "string" }, "connected_at": { "description": "When it was connected.", "format": "date-time", "nullable": true, "type": "string" }, "connected_by": { "description": "Who connected it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "disconnected_at": { "description": "When it was disconnected.", "format": "date-time", "nullable": true, "type": "string" }, "docusign_account_id": { "description": "The DocuSign account id.", "nullable": true, "type": "string" }, "docusign_user_email": { "description": "The DocuSign user who connected it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "The agency's own DocuSign connection.", "enum": [ "active", "needs_reconnect", "disconnected" ], "type": "string" } }, "required": [ "status", "connect_hmac_key_set" ], "title": "DocuSignAgencyConnection", "type": "object" }, "own_key_set": { "description": "Whether the agency has saved its own DocuSign integration key, which Connect and every token refresh then run under. The key and its secret are never shown.", "type": "boolean" }, "own_key_set_at": { "description": "When the agency's own key was saved.", "format": "date-time", "nullable": true, "type": "string" }, "platform_price_microdollars": { "description": "What one envelope costs in prepaid credit, in millionths of a dollar, when sends go through HomeCareBilling's account.", "nullable": true, "type": "integer" }, "status": { "description": "The agency's own DocuSign connection: agency_connection.status, or none when it never connected.", "enum": [ "active", "needs_reconnect", "disconnected", "none" ], "type": "string" } }, "required": [ "status", "account_kind", "agency_connection", "own_key_set" ], "title": "DocuSignSettings", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The settings" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Remove the agency's own DocuSign key", "tags": [ "DocuSign" ] }, "put": { "callbacks": {}, "description": "Stores, or replaces, the integration key and secret of a Private custom integration the agency made in its own DocuSign account. Connect and every token refresh then run under it instead of HomeCareBilling's app-wide key, and the agency must register the redirect URI of Settings > DocuSign on it. The pair is stored encrypted and never shown again, and the agency's active connection, which was issued under the old key, must be connected again. A pair that breaks a rule answers 422 validation_failed, naming the rule and never the value. The pair is not checked with DocuSign until Connect. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "putSettingsDocusignOwnKey", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "integration_key": { "description": "The integration key of a Private custom integration in the agency's own DocuSign account: must be a UUID, as DocuSign shows it. It is stored encrypted and never shown again.", "nullable": true, "type": "string" }, "secret_key": { "description": "The secret of that integration key, which must be 8 to 256 characters with no spaces. It is stored encrypted and never shown again.", "nullable": true, "type": "string" } }, "required": [ "integration_key", "secret_key" ], "title": "DocuSignOwnKey", "type": "object" } } }, "description": "The key and secret", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "account_kind": { "description": "The account a send goes through: the agency's own, HomeCareBilling's (paid from prepaid credit), or null when neither is available.", "enum": [ "agency", "platform" ], "nullable": true, "type": "string" }, "agency_connection": { "description": "The agency's own DocuSign connection, null when it never connected. A disconnected one stays here for its history; account_kind says which account a send goes through.", "nullable": true, "properties": { "account_name": { "description": "The DocuSign account's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "connect_hmac_key_set": { "description": "Whether a Connect HMAC key is stored. The key itself is never shown.", "type": "boolean" }, "connect_hmac_key_set_at": { "description": "When the Connect HMAC key was stored.", "format": "date-time", "nullable": true, "type": "string" }, "connected_at": { "description": "When it was connected.", "format": "date-time", "nullable": true, "type": "string" }, "connected_by": { "description": "Who connected it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "disconnected_at": { "description": "When it was disconnected.", "format": "date-time", "nullable": true, "type": "string" }, "docusign_account_id": { "description": "The DocuSign account id.", "nullable": true, "type": "string" }, "docusign_user_email": { "description": "The DocuSign user who connected it.", "nullable": true, "type": "string", "x-untrusted": "text" }, "status": { "description": "The agency's own DocuSign connection.", "enum": [ "active", "needs_reconnect", "disconnected" ], "type": "string" } }, "required": [ "status", "connect_hmac_key_set" ], "title": "DocuSignAgencyConnection", "type": "object" }, "own_key_set": { "description": "Whether the agency has saved its own DocuSign integration key, which Connect and every token refresh then run under. The key and its secret are never shown.", "type": "boolean" }, "own_key_set_at": { "description": "When the agency's own key was saved.", "format": "date-time", "nullable": true, "type": "string" }, "platform_price_microdollars": { "description": "What one envelope costs in prepaid credit, in millionths of a dollar, when sends go through HomeCareBilling's account.", "nullable": true, "type": "integer" }, "status": { "description": "The agency's own DocuSign connection: agency_connection.status, or none when it never connected.", "enum": [ "active", "needs_reconnect", "disconnected", "none" ], "type": "string" } }, "required": [ "status", "account_kind", "agency_connection", "own_key_set" ], "title": "DocuSignSettings", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The settings" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Store the agency's own DocuSign key", "tags": [ "DocuSign" ] } }, "/api/v1/settings/evv-collection": { "get": { "callbacks": {}, "description": "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).", "operationId": "getSettingsEvvCollection", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "enrolled_caregivers": { "description": "How many caregivers are enrolled in the EVV pilot.", "nullable": true, "type": "integer" }, "evv_collected_from": { "description": "The agency's calendar day HCB starts collecting EVV; null for no start day.", "format": "date", "nullable": true, "type": "string" }, "evv_rollout": { "description": "Who HCB collects EVV for: off (alerts start with the agency's first clock-in), pilot (enrolled caregivers only) or all.", "enum": [ "off", "pilot", "all" ], "type": "string" } }, "required": [ "evv_rollout", "evv_collected_from", "enrolled_caregivers" ], "title": "EvvCollection", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The rollout" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read the EVV rollout", "tags": [ "Agency settings" ] }, "patch": { "callbacks": {}, "description": "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).", "operationId": "patchSettingsEvvCollection", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "evv_collected_from": { "description": "The agency's calendar day HCB starts collecting EVV; null for no start day.", "format": "date", "nullable": true, "type": "string" }, "evv_rollout": { "description": "Who HCB collects EVV for: off (alerts start with the agency's first clock-in), pilot (enrolled caregivers only) or all.", "enum": [ "off", "pilot", "all" ], "type": "string" } }, "title": "EvvCollectionUpdate", "type": "object" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "enrolled_caregivers": { "description": "How many caregivers are enrolled in the EVV pilot.", "nullable": true, "type": "integer" }, "evv_collected_from": { "description": "The agency's calendar day HCB starts collecting EVV; null for no start day.", "format": "date", "nullable": true, "type": "string" }, "evv_rollout": { "description": "Who HCB collects EVV for: off (alerts start with the agency's first clock-in), pilot (enrolled caregivers only) or all.", "enum": [ "off", "pilot", "all" ], "type": "string" } }, "required": [ "evv_rollout", "evv_collected_from", "enrolled_caregivers" ], "title": "EvvCollection", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The rollout" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Save the EVV rollout", "tags": [ "Agency settings" ] } }, "/api/v1/settings/notifications": { "get": { "callbacks": {}, "description": "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).", "operationId": "getSettingsNotifications", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "notify_on_277ca": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_835": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_999": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_submission": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_ta1": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "remittance_review_email": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "text_caregivers_before_expiry": { "description": "Whether each caregiver is texted a month, and again a week, before a dated credential of theirs expires.", "type": "boolean" } }, "required": [ "notify_on_submission", "notify_on_ta1", "notify_on_999", "notify_on_277ca", "notify_on_835", "remittance_review_email", "text_caregivers_before_expiry" ], "title": "NotificationSettings", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The settings" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read the notification settings", "tags": [ "Agency settings" ] }, "patch": { "callbacks": {}, "description": "As the tab's checkboxes do; send only what changes. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "patchSettingsNotifications", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "notify_on_277ca": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_835": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_999": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_submission": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_ta1": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "remittance_review_email": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "text_caregivers_before_expiry": { "description": "Whether each caregiver is texted a month, and again a week, before a dated credential of theirs expires.", "type": "boolean" } }, "title": "NotificationSettingsUpdate", "type": "object" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "notify_on_277ca": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_835": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_999": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_submission": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "notify_on_ta1": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "remittance_review_email": { "description": "Whether the agency is emailed for this event.", "type": "boolean" }, "text_caregivers_before_expiry": { "description": "Whether each caregiver is texted a month, and again a week, before a dated credential of theirs expires.", "type": "boolean" } }, "required": [ "notify_on_submission", "notify_on_ta1", "notify_on_999", "notify_on_277ca", "notify_on_835", "remittance_review_email", "text_caregivers_before_expiry" ], "title": "NotificationSettings", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The settings" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Save the notification settings", "tags": [ "Agency settings" ] } }, "/api/v1/settings/sandata": { "get": { "callbacks": {}, "description": "As Settings > Sandata shows them; the username and password say only whether each is saved. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "getSettingsSandata", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "sandata_agency_id": { "description": "The Sandata Account.", "nullable": true, "type": "string" }, "sandata_api_url": { "description": "The Sandata API URL (https).", "nullable": true, "type": "string" }, "sandata_batch_size": { "description": "Visits per send, 1 to 5000.", "nullable": true, "type": "integer" }, "sandata_custom_cron": { "description": "A five-field cron expression, for a custom schedule.", "nullable": true, "type": "string" }, "sandata_default_timezone": { "description": "The timezone visits are sent in.", "nullable": true, "type": "string" }, "sandata_enabled": { "description": "Whether visits are sent to Sandata.", "enum": [ "true", "false" ], "nullable": true, "type": "string" }, "sandata_entity_guid": { "description": "The EntityGuid header, sent when set.", "nullable": true, "type": "string" }, "sandata_password": { "properties": { "set": { "description": "Whether a value is saved; read it with the secrets operation.", "type": "boolean" } }, "required": [ "set" ], "title": "SecretSet", "type": "object" }, "sandata_provider_id": { "description": "The agency's Medicaid provider id (8 to 10 digits).", "nullable": true, "type": "string" }, "sandata_send_visit_memo": { "description": "Whether the visit memo is sent.", "enum": [ "true", "false" ], "nullable": true, "type": "string" }, "sandata_submission_schedule": { "description": "When visits are sent: a preset or custom.", "nullable": true, "type": "string" }, "sandata_username": { "properties": { "set": { "description": "Whether a value is saved; read it with the secrets operation.", "type": "boolean" } }, "required": [ "set" ], "title": "SecretSet", "type": "object" } }, "required": [ "sandata_username", "sandata_password" ], "title": "SandataSettings", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The settings" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read the Sandata settings", "tags": [ "Integration settings" ] }, "patch": { "callbacks": {}, "description": "As the tab's Save does, in one transaction with an audit row; send only what changes. A blank username or password keeps the saved one, and a value the tab refuses answers 422 naming the field. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "patchSettingsSandata", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "sandata_agency_id": { "description": "The Sandata Account.", "nullable": false, "type": "string" }, "sandata_api_url": { "description": "The Sandata API URL (https).", "nullable": true, "type": "string" }, "sandata_batch_size": { "description": "Visits per send, 1 to 5000.", "type": "integer" }, "sandata_custom_cron": { "description": "A five-field cron expression, for a custom schedule.", "nullable": true, "type": "string" }, "sandata_default_timezone": { "description": "The timezone visits are sent in.", "nullable": true, "type": "string" }, "sandata_enabled": { "description": "Whether visits are sent to Sandata.", "enum": [ "true", "false" ], "type": "string" }, "sandata_entity_guid": { "description": "The EntityGuid header, sent when set.", "nullable": true, "type": "string" }, "sandata_password": { "description": "The password; null or blank keeps the saved one.", "nullable": true, "type": "string" }, "sandata_provider_id": { "description": "The agency's Medicaid provider id (8 to 10 digits).", "nullable": false, "type": "string" }, "sandata_send_visit_memo": { "description": "Whether the visit memo is sent.", "enum": [ "true", "false" ], "type": "string" }, "sandata_submission_schedule": { "description": "When visits are sent: a preset or custom.", "nullable": true, "type": "string" }, "sandata_username": { "description": "The username; null or blank keeps the saved one.", "nullable": true, "type": "string" } }, "title": "SandataSettingsUpdate", "type": "object" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "sandata_agency_id": { "description": "The Sandata Account.", "nullable": true, "type": "string" }, "sandata_api_url": { "description": "The Sandata API URL (https).", "nullable": true, "type": "string" }, "sandata_batch_size": { "description": "Visits per send, 1 to 5000.", "nullable": true, "type": "integer" }, "sandata_custom_cron": { "description": "A five-field cron expression, for a custom schedule.", "nullable": true, "type": "string" }, "sandata_default_timezone": { "description": "The timezone visits are sent in.", "nullable": true, "type": "string" }, "sandata_enabled": { "description": "Whether visits are sent to Sandata.", "enum": [ "true", "false" ], "nullable": true, "type": "string" }, "sandata_entity_guid": { "description": "The EntityGuid header, sent when set.", "nullable": true, "type": "string" }, "sandata_password": { "properties": { "set": { "description": "Whether a value is saved; read it with the secrets operation.", "type": "boolean" } }, "required": [ "set" ], "title": "SecretSet", "type": "object" }, "sandata_provider_id": { "description": "The agency's Medicaid provider id (8 to 10 digits).", "nullable": true, "type": "string" }, "sandata_send_visit_memo": { "description": "Whether the visit memo is sent.", "enum": [ "true", "false" ], "nullable": true, "type": "string" }, "sandata_submission_schedule": { "description": "When visits are sent: a preset or custom.", "nullable": true, "type": "string" }, "sandata_username": { "properties": { "set": { "description": "Whether a value is saved; read it with the secrets operation.", "type": "boolean" } }, "required": [ "set" ], "title": "SecretSet", "type": "object" } }, "required": [ "sandata_username", "sandata_password" ], "title": "SandataSettings", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The settings" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Save the Sandata settings", "tags": [ "Integration settings" ] } }, "/api/v1/settings/sandata/certification": { "get": { "callbacks": {}, "description": "As Settings > Sandata > Certification shows it: the checklist, progress, why each action is refused, and where each sample client and employee stands with Sandata. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "getSettingsSandataCertification", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "cases": { "description": "Sandata's certification test cases, in order, each sent on its own.", "items": { "properties": { "applied": { "description": "Round 2: whether the case's change was made. Null in round 1.", "nullable": true, "type": "boolean" }, "blocked": { "description": "Why a send is refused now; null when it is not.", "nullable": true, "type": "string" }, "id": { "description": "The case's id, as POST /settings/sandata/certification/cases/{id} takes it.", "nullable": true, "type": "string" }, "records": { "description": "How many records it sends.", "type": "integer" }, "round": { "description": "1: the sample records as created. 2: changes to records Sandata accepted.", "type": "integer" }, "scenario": { "description": "The Sandata scenario it covers.", "nullable": true, "type": "string" }, "state": { "additionalProperties": { "type": "integer" }, "description": "Of those records, how many Sandata holds as they are now (accepted), are waiting for Sandata's answer (waiting), were refused as they are now and go again on a send (refused), were refused too often to go again until they change (parked), cannot be sent as they are (held_back), and are left to send (to_send); each record is in exactly one. Null while Sandata is paused or not set up.", "nullable": true, "type": "object" }, "title": { "description": "What the page calls it.", "nullable": true, "type": "string" } }, "required": [ "id", "round", "title", "scenario", "records" ], "title": "CertificationCase", "type": "object" }, "type": "array" }, "cleanup_refusal": { "description": "Why sample records cannot be removed; null when they can.", "nullable": true, "type": "string" }, "completed_count": { "description": "Steps done.", "type": "integer" }, "dry_run": { "description": "Whether sends are a dry run: written to the server log, nothing sent to Sandata. Only the certification tenant has one.", "type": "boolean" }, "environment": { "description": "The Sandata environment the sends reach.", "nullable": true, "type": "string" }, "generate_refusal": { "description": "Why sample records cannot be created; null when they can.", "nullable": true, "type": "string" }, "globally_enabled": { "description": "The platform switch: whether Sandata is turned on for agencies. It never pauses the certification tenant; see sandata_open.", "type": "boolean" }, "parties": { "description": "Each sample client and employee, and where it stands with Sandata.", "items": { "properties": { "batch": { "description": "Its latest batch's status; null when never sent.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "kind": { "description": "Client or employee.", "enum": [ "client", "employee" ], "type": "string" }, "name": { "description": "Its name.", "nullable": true, "type": "string" }, "state": { "description": "Where it stands with Sandata.", "enum": [ "accepted", "refused", "waiting", "unanswered", "not_sent" ], "type": "string" } }, "required": [ "kind", "id", "name", "state" ], "title": "CertificationParty", "type": "object" }, "type": "array" }, "percentage": { "description": "Steps done, in percent.", "type": "number" }, "sandata_open": { "description": "False while Sandata is paused for this agency: the platform switch is off and this is not the certification tenant.", "type": "boolean" }, "send_refusal": { "description": "Why sample records cannot be sent; null when they can.", "nullable": true, "type": "string" }, "steps": { "description": "The checklist, in order.", "items": { "properties": { "category": { "description": "Its section on the page.", "nullable": true, "type": "string" }, "completed": { "description": "Whether it is done.", "type": "boolean" }, "date": { "description": "The day it was marked done; null when not done.", "format": "date", "nullable": true, "type": "string" }, "key": { "description": "The step's key.", "nullable": true, "type": "string" }, "notes": { "description": "Its notes; null when none.", "nullable": true, "type": "string" }, "text": { "description": "What the page calls it.", "nullable": true, "type": "string" } }, "required": [ "key", "text", "category", "completed" ], "title": "CertificationStep", "type": "object" }, "type": "array" }, "test_data_exists": { "description": "Whether sample records exist.", "type": "boolean" }, "total_count": { "description": "Steps in all.", "type": "integer" } }, "required": [ "steps", "completed_count", "total_count", "percentage", "parties" ], "title": "SandataCertification", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The page" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read the Sandata certification page", "tags": [ "Integration settings" ] } }, "/api/v1/settings/sandata/certification/cases/{case}": { "post": { "callbacks": {}, "description": "The page's Send on one test case, with its audit row. Live, it makes a round 2 case's change and queues the case's records for Sandata, nothing else. In a dry run it writes the records to the server log and keeps nothing, a round 2 change included. The platform switch never pauses the certification tenant, so both go while it is off; elsewhere a paused Sandata answers 409 sandata_paused. 404 not_found for an unknown case; 422 no_records when there are no sample records for it; 409 not_ready while Sandata has not accepted what the case needs; 409 nothing_to_send when Sandata holds or is answering for every record of it; 500 case_incomplete when its change failed, which changed nothing. Needs agency_settings.manage (403 forbidden otherwise). Refused outside the Sandata certification tenant (422 not_certification_tenant).", "operationId": "postSettingsSandataCertificationCasesByCase", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "description": "The case's id, as the page read lists it under cases.", "in": "path", "name": "case", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "case": { "description": "The case's id.", "nullable": true, "type": "string" }, "dry_run": { "description": "True: written to the server log, nothing sent to Sandata and nothing changed.", "type": "boolean" }, "records": { "description": "How many records the case holds.", "type": "integer" }, "refused": { "description": "POST /settings/sandata/certification/send only: present when this case was refused while the other went; it changed nothing.", "properties": { "code": { "description": "The refusal's code, as an error carries it.", "nullable": true, "type": "string" }, "message": { "description": "Why the case was not sent.", "nullable": true, "type": "string" } }, "required": [ "code", "message" ], "title": "CertificationCaseRefusal", "type": "object" }, "sending": { "description": "Live: how many of them were queued, those Sandata does not hold as they are now, a record it refused included until it is parked. Dry run: how many were written to the server log.", "type": "integer" } }, "required": [ "case", "records", "sending", "dry_run" ], "title": "CertificationCaseResult", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Sent or logged" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes not_ready, nothing_to_send, sandata_paused: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes no_records, not_certification_tenant: Unprocessable Content, as the operation's description says." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code case_incomplete: Internal Server Error, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Send one Sandata certification test case", "tags": [ "Integration settings" ] } }, "/api/v1/settings/sandata/certification/dry-run": { "patch": { "callbacks": {}, "description": "The page's dry-run switch, with its audit row. On, sending a test case writes its records to the server log and nothing goes to Sandata; off, a test case goes to Sandata's test environment. The switch itself sends nothing. Allowed while Sandata is paused. Refused outside the Sandata certification tenant (422 not_certification_tenant). Answers the whole page. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "patchSettingsSandataCertificationDryRun", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "dry_run": { "description": "True writes what would be sent to the server log and sends nothing; false sends to Sandata.", "type": "boolean" } }, "required": [ "dry_run" ], "title": "CertificationDryRunUpdate", "type": "object" } } }, "description": "The switch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "cases": { "description": "Sandata's certification test cases, in order, each sent on its own.", "items": { "properties": { "applied": { "description": "Round 2: whether the case's change was made. Null in round 1.", "nullable": true, "type": "boolean" }, "blocked": { "description": "Why a send is refused now; null when it is not.", "nullable": true, "type": "string" }, "id": { "description": "The case's id, as POST /settings/sandata/certification/cases/{id} takes it.", "nullable": true, "type": "string" }, "records": { "description": "How many records it sends.", "type": "integer" }, "round": { "description": "1: the sample records as created. 2: changes to records Sandata accepted.", "type": "integer" }, "scenario": { "description": "The Sandata scenario it covers.", "nullable": true, "type": "string" }, "state": { "additionalProperties": { "type": "integer" }, "description": "Of those records, how many Sandata holds as they are now (accepted), are waiting for Sandata's answer (waiting), were refused as they are now and go again on a send (refused), were refused too often to go again until they change (parked), cannot be sent as they are (held_back), and are left to send (to_send); each record is in exactly one. Null while Sandata is paused or not set up.", "nullable": true, "type": "object" }, "title": { "description": "What the page calls it.", "nullable": true, "type": "string" } }, "required": [ "id", "round", "title", "scenario", "records" ], "title": "CertificationCase", "type": "object" }, "type": "array" }, "cleanup_refusal": { "description": "Why sample records cannot be removed; null when they can.", "nullable": true, "type": "string" }, "completed_count": { "description": "Steps done.", "type": "integer" }, "dry_run": { "description": "Whether sends are a dry run: written to the server log, nothing sent to Sandata. Only the certification tenant has one.", "type": "boolean" }, "environment": { "description": "The Sandata environment the sends reach.", "nullable": true, "type": "string" }, "generate_refusal": { "description": "Why sample records cannot be created; null when they can.", "nullable": true, "type": "string" }, "globally_enabled": { "description": "The platform switch: whether Sandata is turned on for agencies. It never pauses the certification tenant; see sandata_open.", "type": "boolean" }, "parties": { "description": "Each sample client and employee, and where it stands with Sandata.", "items": { "properties": { "batch": { "description": "Its latest batch's status; null when never sent.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "kind": { "description": "Client or employee.", "enum": [ "client", "employee" ], "type": "string" }, "name": { "description": "Its name.", "nullable": true, "type": "string" }, "state": { "description": "Where it stands with Sandata.", "enum": [ "accepted", "refused", "waiting", "unanswered", "not_sent" ], "type": "string" } }, "required": [ "kind", "id", "name", "state" ], "title": "CertificationParty", "type": "object" }, "type": "array" }, "percentage": { "description": "Steps done, in percent.", "type": "number" }, "sandata_open": { "description": "False while Sandata is paused for this agency: the platform switch is off and this is not the certification tenant.", "type": "boolean" }, "send_refusal": { "description": "Why sample records cannot be sent; null when they can.", "nullable": true, "type": "string" }, "steps": { "description": "The checklist, in order.", "items": { "properties": { "category": { "description": "Its section on the page.", "nullable": true, "type": "string" }, "completed": { "description": "Whether it is done.", "type": "boolean" }, "date": { "description": "The day it was marked done; null when not done.", "format": "date", "nullable": true, "type": "string" }, "key": { "description": "The step's key.", "nullable": true, "type": "string" }, "notes": { "description": "Its notes; null when none.", "nullable": true, "type": "string" }, "text": { "description": "What the page calls it.", "nullable": true, "type": "string" } }, "required": [ "key", "text", "category", "completed" ], "title": "CertificationStep", "type": "object" }, "type": "array" }, "test_data_exists": { "description": "Whether sample records exist.", "type": "boolean" }, "total_count": { "description": "Steps in all.", "type": "integer" } }, "required": [ "steps", "completed_count", "total_count", "percentage", "parties" ], "title": "SandataCertification", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The page" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_certification_tenant: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Turn the certification dry run on or off", "tags": [ "Integration settings" ] } }, "/api/v1/settings/sandata/certification/sample-records": { "delete": { "callbacks": {}, "description": "The page's Remove Sample Data, with its audit row. Refused outside the Sandata certification tenant (422 not_certification_tenant). Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "deleteSettingsSandataCertificationSampleRecords", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "clients": { "description": "Sample clients.", "type": "integer" }, "employees": { "description": "Sample employees.", "type": "integer" }, "visits": { "description": "Sample visits.", "type": "integer" } }, "required": [ "clients", "employees", "visits" ], "title": "SampleRecordCounts", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Removed" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_certification_tenant: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Remove the certification sample records", "tags": [ "Integration settings" ] }, "post": { "callbacks": {}, "description": "The page's Create Sample Records, with its audit row: sample clients, employees and visits in the certification tenant. Refused once Sandata submission is off in Sandata settings (422 not_opted_in) and while sample records exist (409 test_data_exists). Needs agency_settings.manage (403 forbidden otherwise). Refused outside the certification tenant (422 not_certification_tenant).", "operationId": "postSettingsSandataCertificationSampleRecords", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "clients": { "description": "Sample clients.", "type": "integer" }, "employees": { "description": "Sample employees.", "type": "integer" }, "visits": { "description": "Sample visits.", "type": "integer" } }, "required": [ "clients", "employees", "visits" ], "title": "SampleRecordCounts", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Created" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code test_data_exists: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes not_certification_tenant, not_opted_in: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create the certification sample records", "tags": [ "Integration settings" ] } }, "/api/v1/settings/sandata/certification/send": { "post": { "callbacks": {}, "description": "The Employees test case and the Clients one, each sent on its own (POST /settings/sandata/certification/cases/{id}), so one refused does not stop the other: a refused case carries refused. Live, they are queued for Sandata; in a dry run they are written to the server log and nothing is sent. When neither went, the error says why, as for one case. Needs agency_settings.manage (403 forbidden otherwise). Refused while Sandata is paused for the agency (409 sandata_paused), which the platform switch never does to the certification tenant. Refused outside the certification tenant (422 not_certification_tenant).", "operationId": "postSettingsSandataCertificationSend", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "cases": { "description": "Each case's result.", "items": { "properties": { "case": { "description": "The case's id.", "nullable": true, "type": "string" }, "dry_run": { "description": "True: written to the server log, nothing sent to Sandata and nothing changed.", "type": "boolean" }, "records": { "description": "How many records the case holds.", "type": "integer" }, "refused": { "description": "POST /settings/sandata/certification/send only: present when this case was refused while the other went; it changed nothing.", "properties": { "code": { "description": "The refusal's code, as an error carries it.", "nullable": true, "type": "string" }, "message": { "description": "Why the case was not sent.", "nullable": true, "type": "string" } }, "required": [ "code", "message" ], "title": "CertificationCaseRefusal", "type": "object" }, "sending": { "description": "Live: how many of them were queued, those Sandata does not hold as they are now, a record it refused included until it is parked. Dry run: how many were written to the server log.", "type": "integer" } }, "required": [ "case", "records", "sending", "dry_run" ], "title": "CertificationCaseResult", "type": "object" }, "type": "array" }, "dry_run": { "description": "Whether this was a dry run.", "type": "boolean" }, "queued": { "description": "True when they were queued for Sandata; false in a dry run.", "type": "boolean" } }, "required": [ "queued" ], "title": "SampleRecordsQueued", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Sent" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code sandata_paused: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_certification_tenant: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Send the sample employees and clients to Sandata", "tags": [ "Integration settings" ] } }, "/api/v1/settings/sandata/certification/send-visits": { "post": { "callbacks": {}, "description": "Sends the first visit test case whose visits Sandata does not hold yet (POST /settings/sandata/certification/cases/{id}), one case per call. 409 not_ready until Sandata has accepted that case's clients and employees; 422 no_sample_visits when no visit is left to send; 409 dry_run while the dry run is on (a case's own operation dry-runs it). Needs agency_settings.manage (403 forbidden otherwise). Refused while Sandata is paused for the agency (409 sandata_paused), which the platform switch never does to the certification tenant. Refused outside the certification tenant (422 not_certification_tenant).", "operationId": "postSettingsSandataCertificationSendVisits", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "case": { "description": "The test case sent.", "nullable": true, "type": "string" }, "queued_visits": { "description": "Sample visits queued.", "type": "integer" } }, "required": [ "queued_visits" ], "title": "SampleVisitsQueued", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Queued" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes dry_run, not_ready, sandata_paused: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes no_sample_visits, not_certification_tenant: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Send the next sample visit test case to Sandata", "tags": [ "Integration settings" ] } }, "/api/v1/settings/sandata/certification/steps/{key}": { "patch": { "callbacks": {}, "description": "As the page's checkbox and notes do, with the same audit row: completed marks the step done today or not done, keeping its notes; notes replaces them (trimmed, 500 characters at most; null or blank empties them). Answers the whole page. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "patchSettingsSandataCertificationStepsByKey", "parameters": [ { "description": "The step's key, as the page read lists it.", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "completed": { "description": "Done or not done.", "type": "boolean" }, "notes": { "description": "The notes; null or blank empties them.", "nullable": true, "type": "string" } }, "title": "CertificationStepUpdate", "type": "object" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "cases": { "description": "Sandata's certification test cases, in order, each sent on its own.", "items": { "properties": { "applied": { "description": "Round 2: whether the case's change was made. Null in round 1.", "nullable": true, "type": "boolean" }, "blocked": { "description": "Why a send is refused now; null when it is not.", "nullable": true, "type": "string" }, "id": { "description": "The case's id, as POST /settings/sandata/certification/cases/{id} takes it.", "nullable": true, "type": "string" }, "records": { "description": "How many records it sends.", "type": "integer" }, "round": { "description": "1: the sample records as created. 2: changes to records Sandata accepted.", "type": "integer" }, "scenario": { "description": "The Sandata scenario it covers.", "nullable": true, "type": "string" }, "state": { "additionalProperties": { "type": "integer" }, "description": "Of those records, how many Sandata holds as they are now (accepted), are waiting for Sandata's answer (waiting), were refused as they are now and go again on a send (refused), were refused too often to go again until they change (parked), cannot be sent as they are (held_back), and are left to send (to_send); each record is in exactly one. Null while Sandata is paused or not set up.", "nullable": true, "type": "object" }, "title": { "description": "What the page calls it.", "nullable": true, "type": "string" } }, "required": [ "id", "round", "title", "scenario", "records" ], "title": "CertificationCase", "type": "object" }, "type": "array" }, "cleanup_refusal": { "description": "Why sample records cannot be removed; null when they can.", "nullable": true, "type": "string" }, "completed_count": { "description": "Steps done.", "type": "integer" }, "dry_run": { "description": "Whether sends are a dry run: written to the server log, nothing sent to Sandata. Only the certification tenant has one.", "type": "boolean" }, "environment": { "description": "The Sandata environment the sends reach.", "nullable": true, "type": "string" }, "generate_refusal": { "description": "Why sample records cannot be created; null when they can.", "nullable": true, "type": "string" }, "globally_enabled": { "description": "The platform switch: whether Sandata is turned on for agencies. It never pauses the certification tenant; see sandata_open.", "type": "boolean" }, "parties": { "description": "Each sample client and employee, and where it stands with Sandata.", "items": { "properties": { "batch": { "description": "Its latest batch's status; null when never sent.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "kind": { "description": "Client or employee.", "enum": [ "client", "employee" ], "type": "string" }, "name": { "description": "Its name.", "nullable": true, "type": "string" }, "state": { "description": "Where it stands with Sandata.", "enum": [ "accepted", "refused", "waiting", "unanswered", "not_sent" ], "type": "string" } }, "required": [ "kind", "id", "name", "state" ], "title": "CertificationParty", "type": "object" }, "type": "array" }, "percentage": { "description": "Steps done, in percent.", "type": "number" }, "sandata_open": { "description": "False while Sandata is paused for this agency: the platform switch is off and this is not the certification tenant.", "type": "boolean" }, "send_refusal": { "description": "Why sample records cannot be sent; null when they can.", "nullable": true, "type": "string" }, "steps": { "description": "The checklist, in order.", "items": { "properties": { "category": { "description": "Its section on the page.", "nullable": true, "type": "string" }, "completed": { "description": "Whether it is done.", "type": "boolean" }, "date": { "description": "The day it was marked done; null when not done.", "format": "date", "nullable": true, "type": "string" }, "key": { "description": "The step's key.", "nullable": true, "type": "string" }, "notes": { "description": "Its notes; null when none.", "nullable": true, "type": "string" }, "text": { "description": "What the page calls it.", "nullable": true, "type": "string" } }, "required": [ "key", "text", "category", "completed" ], "title": "CertificationStep", "type": "object" }, "type": "array" }, "test_data_exists": { "description": "Whether sample records exist.", "type": "boolean" }, "total_count": { "description": "Steps in all.", "type": "integer" } }, "required": [ "steps", "completed_count", "total_count", "percentage", "parties" ], "title": "SandataCertification", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The page" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a certification checklist step", "tags": [ "Integration settings" ] } }, "/api/v1/settings/sandata/certification/validate": { "post": { "callbacks": {}, "description": "The page's Check Data Format: every sample record through the Sandata mappers; nothing is sent or saved. Refused while Sandata is paused for the agency (409 sandata_paused), which the platform switch never does to the certification tenant. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "postSettingsSandataCertificationValidate", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "clients": { "properties": { "errors": { "description": "One per failed record.", "items": { "properties": { "error": { "description": "What the mapper refused.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "description": "The sample record's name.", "nullable": true, "type": "string" } }, "required": [ "name", "id", "error" ], "title": "CertificationRecordError", "type": "object" }, "type": "array" }, "failed": { "description": "Those that did not.", "type": "integer" }, "passed": { "description": "Those that mapped cleanly.", "type": "integer" }, "total": { "description": "Sample records checked.", "type": "integer" } }, "required": [ "total", "passed", "failed", "errors" ], "title": "CertificationDomainReport", "type": "object" }, "credential_error": { "description": "Set when the Sandata settings are incomplete; null otherwise.", "nullable": true, "type": "string" }, "employees": { "properties": { "errors": { "description": "One per failed record.", "items": { "properties": { "error": { "description": "What the mapper refused.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "description": "The sample record's name.", "nullable": true, "type": "string" } }, "required": [ "name", "id", "error" ], "title": "CertificationRecordError", "type": "object" }, "type": "array" }, "failed": { "description": "Those that did not.", "type": "integer" }, "passed": { "description": "Those that mapped cleanly.", "type": "integer" }, "total": { "description": "Sample records checked.", "type": "integer" } }, "required": [ "total", "passed", "failed", "errors" ], "title": "CertificationDomainReport", "type": "object" }, "overall_pass": { "description": "Every sample record mapped cleanly.", "type": "boolean" }, "visits": { "properties": { "errors": { "description": "One per failed record.", "items": { "properties": { "error": { "description": "What the mapper refused.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "name": { "description": "The sample record's name.", "nullable": true, "type": "string" } }, "required": [ "name", "id", "error" ], "title": "CertificationRecordError", "type": "object" }, "type": "array" }, "failed": { "description": "Those that did not.", "type": "integer" }, "passed": { "description": "Those that mapped cleanly.", "type": "integer" }, "total": { "description": "Sample records checked.", "type": "integer" } }, "required": [ "total", "passed", "failed", "errors" ], "title": "CertificationDomainReport", "type": "object" } }, "required": [ "clients", "employees", "visits", "overall_pass" ], "title": "CertificationReport", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The report" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code sandata_paused: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Check the sample records' data format", "tags": [ "Integration settings" ] } }, "/api/v1/settings/sandata/test": { "post": { "callbacks": {}, "description": "The tab's Test Connection, with the saved settings or the values sent in their place; nothing is saved. A failure answers 422 connection_failed with the reason. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "postSettingsSandataTest", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "sandata_agency_id": { "description": "The Sandata Account.", "nullable": true, "type": "string" }, "sandata_api_url": { "description": "The Sandata API URL (https).", "nullable": true, "type": "string" }, "sandata_entity_guid": { "description": "The EntityGuid header, sent when set.", "nullable": true, "type": "string" }, "sandata_password": { "description": "The password; null or blank tests the saved one.", "nullable": true, "type": "string" }, "sandata_username": { "description": "The username; null or blank tests the saved one.", "nullable": true, "type": "string" } }, "title": "SandataConnectionTest", "type": "object" } } }, "description": "Values to test instead of the saved ones", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "connected": { "description": "Always true.", "type": "boolean" } }, "required": [ "connected" ], "title": "SandataConnected", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Connected" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code connection_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Test the Sandata connection", "tags": [ "Integration settings" ] } }, "/api/v1/settings/security": { "get": { "callbacks": {}, "description": "As Settings > Security shows them: whether two-factor is required, and the session timeout. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "getSettingsSecurity", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "require_two_factor": { "description": "Whether every member must sign in with two-factor.", "type": "boolean" }, "session_timeout_minutes": { "description": "Minutes idle before sign-out.", "enum": [ 5, 15, 30, 60 ], "type": "integer" } }, "required": [ "require_two_factor", "session_timeout_minutes" ], "title": "SecuritySettings", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The settings" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read the security settings", "tags": [ "Agency settings" ] }, "put": { "callbacks": {}, "description": "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).", "operationId": "putSettingsSecurity", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "code": { "deprecated": true, "description": "Deprecated: send otp_code. Read when otp_code is absent, until April 30, 2027.", "type": "string" }, "otp_code": { "description": "A current 6-digit code from your authenticator app; needed to turn the requirement off.", "type": "string" }, "require_two_factor": { "description": "Require two-factor sign-in of every member (true), or stop (false). Requiring it needs your own two-factor on first.", "type": "boolean" }, "session_timeout_minutes": { "description": "Minutes idle before sign-out: 5, 15, 30 or 60.", "type": "integer" } }, "title": "SecuritySettingsUpdate", "type": "object" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "require_two_factor": { "description": "Whether every member must sign in with two-factor.", "type": "boolean" }, "session_timeout_minutes": { "description": "Minutes idle before sign-out.", "enum": [ 5, 15, 30, 60 ], "type": "integer" } }, "required": [ "require_two_factor", "session_timeout_minutes" ], "title": "SecuritySettings", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The settings" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes enable_yours_first, invalid_code: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Save the security settings", "tags": [ "Agency settings" ] } }, "/api/v1/settings/telephony": { "delete": { "callbacks": {}, "description": "Back to the shared system number, as the tab's Clear does: the number's webhook is reset first, then every key is removed. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "deleteSettingsTelephony", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "settings": { "properties": { "telephony_match_window_minutes": { "description": "Minutes a call may be from its visit, 1 to 480.", "nullable": true, "type": "string" }, "telephony_send_sms_confirmation": { "description": "SMS confirmation; unavailable for now.", "nullable": true, "type": "string" }, "twilio_account_sid": { "properties": { "masked": { "description": "Its last four characters, as ****1234; empty when none.", "nullable": true, "type": "string" }, "set": { "description": "Whether an Account SID is saved.", "type": "boolean" } }, "required": [ "set", "masked" ], "title": "AccountSidSet", "type": "object" }, "twilio_auth_token": { "properties": { "set": { "description": "Whether a value is saved; read it with the secrets operation.", "type": "boolean" } }, "required": [ "set" ], "title": "SecretSet", "type": "object" }, "twilio_phone_number": { "description": "The agency's own Twilio number, 10 digits.", "nullable": true, "type": "string" }, "twilio_record_calls": { "description": "Whether calls are recorded.", "enum": [ "true", "false" ], "nullable": true, "type": "string" } }, "required": [ "twilio_account_sid", "twilio_auth_token" ], "title": "TelephonySettings", "type": "object" }, "warnings": { "description": "Set when the old number's webhook could not be reset.", "items": { "type": "string" }, "type": "array" } }, "required": [ "settings", "warnings" ], "title": "TelephonyCleared", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Cleared" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Clear the telephony settings", "tags": [ "Integration settings" ] }, "get": { "callbacks": {}, "description": "As Settings > Telephony shows them: the Account SID masked, the Auth Token as whether it is saved. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "getSettingsTelephony", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "telephony_match_window_minutes": { "description": "Minutes a call may be from its visit, 1 to 480.", "nullable": true, "type": "string" }, "telephony_send_sms_confirmation": { "description": "SMS confirmation; unavailable for now.", "nullable": true, "type": "string" }, "twilio_account_sid": { "properties": { "masked": { "description": "Its last four characters, as ****1234; empty when none.", "nullable": true, "type": "string" }, "set": { "description": "Whether an Account SID is saved.", "type": "boolean" } }, "required": [ "set", "masked" ], "title": "AccountSidSet", "type": "object" }, "twilio_auth_token": { "properties": { "set": { "description": "Whether a value is saved; read it with the secrets operation.", "type": "boolean" } }, "required": [ "set" ], "title": "SecretSet", "type": "object" }, "twilio_phone_number": { "description": "The agency's own Twilio number, 10 digits.", "nullable": true, "type": "string" }, "twilio_record_calls": { "description": "Whether calls are recorded.", "enum": [ "true", "false" ], "nullable": true, "type": "string" } }, "required": [ "twilio_account_sid", "twilio_auth_token" ], "title": "TelephonySettings", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The settings" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read the telephony settings", "tags": [ "Integration settings" ] }, "patch": { "callbacks": {}, "description": "The tab's Test then Save in one call: changed credentials or a new number are tested with Twilio (the account must own the number) and saved only on a pass, then the number's webhook is set. Blank credentials keep the saved ones; all three blank clears the configuration. Moving a number while telephony visits are open goes through with a warning. A failed test answers 422 test_failed. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "patchSettingsTelephony", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "telephony_match_window_minutes": { "description": "Minutes, 1 to 480.", "nullable": true, "type": "string" }, "twilio_account_sid": { "description": "The Account SID; null or blank keeps the saved one.", "nullable": true, "type": "string" }, "twilio_auth_token": { "description": "The Auth Token; null or blank keeps the saved one.", "nullable": true, "type": "string" }, "twilio_phone_number": { "description": "The agency's Twilio number.", "nullable": true, "type": "string" }, "twilio_record_calls": { "description": "Whether calls are recorded.", "enum": [ "true", "false" ], "type": "string" } }, "title": "TelephonySettingsUpdate", "type": "object" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "cleared": { "description": "True when every credential was blank, so it was cleared.", "type": "boolean" }, "settings": { "properties": { "telephony_match_window_minutes": { "description": "Minutes a call may be from its visit, 1 to 480.", "nullable": true, "type": "string" }, "telephony_send_sms_confirmation": { "description": "SMS confirmation; unavailable for now.", "nullable": true, "type": "string" }, "twilio_account_sid": { "properties": { "masked": { "description": "Its last four characters, as ****1234; empty when none.", "nullable": true, "type": "string" }, "set": { "description": "Whether an Account SID is saved.", "type": "boolean" } }, "required": [ "set", "masked" ], "title": "AccountSidSet", "type": "object" }, "twilio_auth_token": { "properties": { "set": { "description": "Whether a value is saved; read it with the secrets operation.", "type": "boolean" } }, "required": [ "set" ], "title": "SecretSet", "type": "object" }, "twilio_phone_number": { "description": "The agency's own Twilio number, 10 digits.", "nullable": true, "type": "string" }, "twilio_record_calls": { "description": "Whether calls are recorded.", "enum": [ "true", "false" ], "nullable": true, "type": "string" } }, "required": [ "twilio_account_sid", "twilio_auth_token" ], "title": "TelephonySettings", "type": "object" }, "warnings": { "description": "What went through but needs attention.", "items": { "type": "string" }, "type": "array" } }, "required": [ "settings", "warnings" ], "title": "TelephonySave", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Saved" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code test_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Save the telephony settings", "tags": [ "Integration settings" ] } }, "/api/v1/settings/telephony/test": { "post": { "callbacks": {}, "description": "The tab's Test Configuration: the credentials authenticate and the account owns the number. Values sent replace the saved ones; nothing is saved. 20 tests a minute per agency (429 rate_limited). Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "postSettingsTelephonyTest", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "twilio_account_sid": { "description": "The Account SID; null or blank keeps the saved one.", "nullable": true, "type": "string" }, "twilio_auth_token": { "description": "The Auth Token; null or blank keeps the saved one.", "nullable": true, "type": "string" }, "twilio_phone_number": { "description": "The agency's Twilio number.", "nullable": true, "type": "string" } }, "title": "TelephonyTest", "type": "object" } } }, "description": "Values to test instead of the saved ones", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "owns_number": { "description": "Always true.", "type": "boolean" } }, "required": [ "owns_number" ], "title": "TelephonyTested", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The account owns the number" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code rate_limited: Too Many Requests, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Test the telephony settings", "tags": [ "Integration settings" ] } }, "/api/v1/settings/tpid-authorized": { "get": { "callbacks": {}, "description": "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).", "operationId": "getSettingsTpidAuthorized", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "tpid_authorized": { "description": "Whether the agency confirmed its Trading Partner authorization.", "type": "boolean" } }, "required": [ "tpid_authorized" ], "title": "TpidAuthorization", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The authorization" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read the Trading Partner authorization", "tags": [ "Agency settings" ] }, "put": { "callbacks": {}, "description": "As the Agency tab's toggle does. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "putSettingsTpidAuthorized", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "authorized": { "description": "Whether the agency authorized HomeCareBilling as its Trading Partner: confirmed (true) or not (false).", "type": "boolean" } }, "required": [ "authorized" ], "title": "TpidAuthorizationUpdate", "type": "object" } } }, "description": "The authorization", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "tpid_authorized": { "description": "Whether the agency confirmed its Trading Partner authorization.", "type": "boolean" } }, "required": [ "tpid_authorized" ], "title": "TpidAuthorization", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The authorization" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Set the Trading Partner authorization", "tags": [ "Agency settings" ] } }, "/api/v1/settings/{tab}/secrets/{key}": { "get": { "callbacks": {}, "description": "One saved credential, as the tab's eye icon shows it, with the same audit row; when the audit row cannot be written nothing is returned. null when none is saved. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "getSettingsByTabSecretsByKey", "parameters": [ { "description": "sandata or telephony.", "in": "path", "name": "tab", "required": true, "schema": { "description": "The settings tab.", "enum": [ "sandata", "telephony" ], "type": "string" } }, { "description": "sandata_username or sandata_password (sandata); twilio_account_sid or twilio_auth_token (telephony).", "in": "path", "name": "key", "required": true, "schema": { "description": "The credential.", "enum": [ "sandata_password", "sandata_username", "twilio_account_sid", "twilio_auth_token" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "key": { "description": "The credential's key.", "nullable": true, "type": "string" }, "value": { "description": "Its value; null when none is saved.", "nullable": true, "type": "string" } }, "required": [ "key", "value" ], "title": "SettingSecret", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The credential" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Reveal a saved credential", "tags": [ "Integration settings" ] } }, "/api/v1/signed-records/{record_type}/{id}/addenda": { "post": { "callbacks": {}, "description": "As the record page's Add addendum does: the addendum is created and signed, as a typed signature by the credential's user, in one step, and the record reads amended; the signed record, its signatures and its true copy never change, and the addendum gets a true copy of its own. The same body and reason sent again by the same user within 60 seconds answers the addendum already made. A draft answers 422 not_signed, a voided record 409 voided, a missing body or reason 422 validation_failed, an unknown record_type 404 not_found. 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.", "operationId": "postSignedRecordsByRecordTypeByIdAddenda", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "description": "The record's type: supervisor_visit, plan_of_care, monthly_client_report, complaint, critical_incident, client_consent_form, client_emergency_info, care_log or half_month_summary; half_month_summary takes no addendum.", "in": "path", "name": "record_type", "required": true, "schema": { "enum": [ "supervisor_visit", "plan_of_care", "monthly_client_report", "complaint", "critical_incident", "client_consent_form", "client_emergency_info", "care_log", "half_month_summary" ], "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "body": { "description": "What to add, up to 5000 characters. The signed record itself never changes.", "nullable": true, "type": "string" }, "reason": { "description": "Why it is added, 3 to 1000 characters.", "nullable": true, "type": "string" }, "signer_name": { "description": "The name the addendum is signed under, a typed signature by the credential's user; the user's own name when left out.", "nullable": true, "type": "string" } }, "required": [ "body", "reason" ], "title": "RecordAddendumInput", "type": "object" } } }, "description": "The addendum", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/RecordAddendum" } }, "required": [ "data" ], "type": "object" } } }, "description": "The addendum" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code signature_requires_person: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes not_signed, validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Add an addendum to a signed record", "tags": [ "Signed records" ] } }, "/api/v1/signed-records/{record_type}/{id}/docusign-envelopes": { "get": { "callbacks": {}, "description": "Newest first, as the record page's DocuSign panel shows the latest: each envelope's status, its signers' names, roles and emails, when it was sent and completed, and the account it went through.", "operationId": "getSignedRecordsByRecordTypeByIdDocusignEnvelopes", "parameters": [ { "description": "The record's type: client_consent_form, client_emergency_info, monthly_client_report, plan_of_care or supervisor_visit.", "in": "path", "name": "record_type", "required": true, "schema": { "enum": [ "client_consent_form", "client_emergency_info", "monthly_client_report", "plan_of_care", "supervisor_visit" ], "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 20, at most 100; a larger value is served as 100).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "account_kind": { "description": "The DocuSign account it was sent through.", "enum": [ "agency", "platform" ], "type": "string" }, "completed_at": { "description": "When every signer had signed.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The envelope's id.", "format": "uuid", "type": "string" }, "recipients": { "description": "Its signers.", "items": { "properties": { "email": { "description": "Where DocuSign sent the signing link.", "nullable": true, "type": "string", "x-untrusted": "text" }, "name": { "description": "The signer's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "role": { "description": "Who signs.", "enum": [ "client", "representative" ], "type": "string" } }, "required": [ "name", "role", "email" ], "title": "DocuSignEnvelopeRecipient", "type": "object" }, "type": "array" }, "record_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "record_type": { "description": "The record's type.", "nullable": true, "type": "string" }, "sent_at": { "description": "When DocuSign accepted it.", "format": "date-time", "nullable": true, "type": "string" }, "status": { "description": "Where the envelope is.", "enum": [ "sending", "sent", "delivered", "completed", "declined", "voided", "failed", "superseded" ], "type": "string" } }, "required": [ "id", "status", "account_kind", "recipients" ], "title": "DocuSignEnvelope", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "DocuSignEnvelopePage", "type": "object" } } }, "description": "A page of envelopes" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List a record's DocuSign envelopes", "tags": [ "DocuSign" ] }, "post": { "callbacks": {}, "description": "As the record page's Send with DocuSign does: DocuSign emails each signer a link, and their signatures land on the record when they have signed. The envelope is created in the background, so it answers 202 with the envelope sending. Through HomeCareBilling's account the price is held on the agency's prepaid credit first, and too little credit answers 402 insufficient_credit with nothing written. A record that is not a draft, one already out for signature, no account to send through, or a signer the record does not take answers 422 with its code; an Idempotency-Key replay answers the first send.", "operationId": "postSignedRecordsByRecordTypeByIdDocusignEnvelopes", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "description": "The record's type: client_consent_form, client_emergency_info, monthly_client_report, plan_of_care or supervisor_visit.", "in": "path", "name": "record_type", "required": true, "schema": { "enum": [ "client_consent_form", "client_emergency_info", "monthly_client_report", "plan_of_care", "supervisor_visit" ], "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "recipients": { "description": "Who signs. Left out, the record's client and its designated representative, where the record has a representative's line, each with an email on file, as the page's Send dialog offers them.", "items": { "properties": { "email": { "description": "Where DocuSign sends the signing link.", "nullable": true, "type": "string" }, "name": { "description": "The signer's name, as it prints.", "nullable": true, "type": "string" }, "role": { "description": "Who signs.", "enum": [ "client", "representative" ], "type": "string" } }, "required": [ "role", "name", "email" ], "title": "DocuSignRecipientInput", "type": "object" }, "type": "array" } }, "title": "DocuSignSend", "type": "object" } } }, "description": "Who signs", "required": false }, "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "account_kind": { "description": "The DocuSign account it was sent through.", "enum": [ "agency", "platform" ], "type": "string" }, "available_balance_microdollars": { "description": "A send through HomeCareBilling's account: the prepaid credit left after the hold.", "nullable": true, "type": "integer" }, "completed_at": { "description": "When every signer had signed.", "format": "date-time", "nullable": true, "type": "string" }, "id": { "description": "The envelope's id.", "format": "uuid", "type": "string" }, "price_microdollars": { "description": "A send through HomeCareBilling's account: the prepaid credit held for it, in millionths of a dollar.", "nullable": true, "type": "integer" }, "recipients": { "description": "Its signers.", "items": { "properties": { "email": { "description": "Where DocuSign sent the signing link.", "nullable": true, "type": "string", "x-untrusted": "text" }, "name": { "description": "The signer's name.", "nullable": true, "type": "string", "x-untrusted": "text" }, "role": { "description": "Who signs.", "enum": [ "client", "representative" ], "type": "string" } }, "required": [ "name", "role", "email" ], "title": "DocuSignEnvelopeRecipient", "type": "object" }, "type": "array" }, "record_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "record_type": { "description": "The record's type.", "nullable": true, "type": "string" }, "sent_at": { "description": "When DocuSign accepted it.", "format": "date-time", "nullable": true, "type": "string" }, "status": { "description": "Where the envelope is.", "enum": [ "sending", "sent", "delivered", "completed", "declined", "voided", "failed", "superseded" ], "type": "string" } }, "required": [ "id", "status", "account_kind", "recipients" ], "title": "DocuSignEnvelopeSent", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The envelope, sending" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Send a draft record for signature with DocuSign", "tags": [ "DocuSign" ] } }, "/api/v1/signed-records/{record_type}/{id}/history": { "get": { "callbacks": {}, "description": "The record's events, oldest first, as its page lists them: each signature (live or voided), each signature voided, its true copy stored, each signed addendum in full, the record voided, and the record it replaces or that replaced it.", "operationId": "getSignedRecordsByRecordTypeByIdHistory", "parameters": [ { "description": "The record's type: supervisor_visit, plan_of_care, monthly_client_report, complaint, critical_incident, client_consent_form, client_emergency_info, care_log or half_month_summary; half_month_summary takes no addendum.", "in": "path", "name": "record_type", "required": true, "schema": { "enum": [ "supervisor_visit", "plan_of_care", "monthly_client_report", "complaint", "critical_incident", "client_consent_form", "client_emergency_info", "care_log", "half_month_summary" ], "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/SignedRecordEvent" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "SignedRecordEventPage", "type": "object" } } }, "description": "A page of events" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read a signed record's history", "tags": [ "Signed records" ] } }, "/api/v1/signed-records/{record_type}/{id}/void": { "post": { "callbacks": {}, "description": "As the record page's Void does: the record is marked voided with the reason given and kept as signed, with its signatures and true copy; it takes no further signatures or addenda. A voided Plan of Care that was the client's current plan becomes past; Work Orders made from it are not changed. Needs signed_records.void (403 forbidden otherwise). Without a reason it answers 422 reason_required; a draft 422 not_signed, a voided record 409 voided.", "operationId": "postSignedRecordsByRecordTypeByIdVoid", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "description": "The record's type: supervisor_visit, plan_of_care, monthly_client_report, complaint, critical_incident, client_consent_form, client_emergency_info, care_log or half_month_summary; half_month_summary takes no addendum.", "in": "path", "name": "record_type", "required": true, "schema": { "enum": [ "supervisor_visit", "plan_of_care", "monthly_client_report", "complaint", "critical_incident", "client_consent_form", "client_emergency_info", "care_log", "half_month_summary" ], "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Why the record is voided, 3 to 1000 characters. It is kept with the voided record.", "nullable": true, "type": "string" } }, "required": [ "reason" ], "title": "SignedRecordVoid", "type": "object" } } }, "description": "Why it is voided", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SignedRecordState" } }, "required": [ "data" ], "type": "object" } } }, "description": "The record" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes not_signed, reason_required: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Void a signed record", "tags": [ "Signed records" ] } }, "/api/v1/supervisory-visits": { "get": { "callbacks": {}, "description": "Each with its checklist questions and answers. A draft is edited here; a completed or signed visit, or a draft already carrying a signature, is changed only on the visit page. The agency's supervisory visits in visit date order, newest first. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getSupervisoryVisits", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records with this status.", "in": "query", "name": "status", "schema": { "enum": [ "draft", "completed", "signed" ], "type": "string" } }, { "description": "Only this client's visits.", "in": "query", "name": "client_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only visits observing this caregiver.", "in": "query", "name": "caregiver_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Visits on or between these days. on or after this date (YYYY-MM-DD, Colorado).", "in": "query", "name": "visit_date_from", "schema": { "format": "date", "type": "string" } }, { "description": "Visits on or between these days. on or before this date (YYYY-MM-DD, Colorado).", "in": "query", "name": "visit_date_to", "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/SupervisoryVisit" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Supervisory visitPage", "type": "object" } } }, "description": "A page of supervisory visits" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List supervisory visits", "tags": [ "Supervisory visits" ] }, "post": { "callbacks": {}, "operationId": "postSupervisoryVisits", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupervisoryVisitCreate" } } }, "description": "The supervisory visit's fields", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SupervisoryVisit" } }, "required": [ "data" ], "type": "object" } } }, "description": "The created supervisory visit" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a supervisory visit", "tags": [ "Supervisory visits" ] } }, "/api/v1/supervisory-visits/due": { "get": { "callbacks": {}, "description": "The agency's clients by how urgent their next supervisory visit is, most urgent first, with the last visit's date and planned day. With planned_for (US-102.37), only the clients whose planned supervisory month of the quarter is that month, by planned day, as the planned supervisory list shows them; due_status is the same rolling-cadence status either way.", "operationId": "getSupervisoryVisitsDue", "parameters": [ { "description": "YYYY-MM: the month whose planned supervisory visits to list (January, April, July and October are month 1 of their quarter).", "in": "query", "name": "planned_for", "schema": { "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/SupervisoryVisitDue" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "SupervisoryVisitDuePage", "type": "object" } } }, "description": "A page of clients" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List the clients a supervisory visit is due for", "tags": [ "Supervisory visits" ] } }, "/api/v1/supervisory-visits/{id}": { "delete": { "callbacks": {}, "description": "Soft-deletes the visit, as the client's visit list does: the same care_plans.manage for a draft or a finalized visit (403 forbidden otherwise). A visit changed since it was read answers 409 stale_record.", "operationId": "deleteSupervisoryVisitsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The lock_version the record was read with: missing answers 400, changed since 409 stale_record.", "in": "query", "name": "lock_version", "required": true, "schema": { "description": "The value the record was read with; a record changed since answers 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SupervisoryVisit" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted visit" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a supervisory visit", "tags": [ "Deletes and restores" ] }, "get": { "callbacks": {}, "description": "Each with its checklist questions and answers. A draft is edited here; a completed or signed visit, or a draft already carrying a signature, is changed only on the visit page.", "operationId": "getSupervisoryVisitsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SupervisoryVisit" } }, "required": [ "data" ], "type": "object" } } }, "description": "The supervisory visit" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no supervisory visit with that id in this agency, including another agency's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a supervisory visit", "tags": [ "Supervisory visits" ] }, "patch": { "callbacks": {}, "description": "Sets only the fields sent. lock_version is required: send the value you read, and a record changed since answers 409 stale_record.", "operationId": "patchSupervisoryVisitsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupervisoryVisitInput" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SupervisoryVisit" } }, "required": [ "data" ], "type": "object" } } }, "description": "The updated supervisory visit" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no supervisory visit with that id in this agency, including another agency's." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: the supervisory visit changed since the lock_version sent was read, or while this request ran. Nothing was saved; read it again and retry." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a supervisory visit", "tags": [ "Supervisory visits" ] } }, "/api/v1/supervisory-visits/{id}/complete": { "post": { "callbacks": {}, "description": "Marks it completed and schedules the next visit when the client has a cadence, as the visit page's Complete does. Needs care_plans.manage (403 forbidden otherwise). Unanswered required questions answer 422 naming them; a later step that failed (the next visit, the completing user's reminder cadence) answers 500 internal_error, nothing saved. A visit another request changed while this one ran answers 409 stale_record; send it again.", "operationId": "postSupervisoryVisitsByIdComplete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SupervisoryVisit" } }, "required": [ "data" ], "type": "object" } } }, "description": "The visit" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code internal_error: Internal Server Error, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Complete a supervisory visit", "tags": [ "Supervisory visits" ] } }, "/api/v1/supervisory-visits/{id}/date": { "post": { "callbacks": {}, "description": "As the visit page's date field does; a blank or null date clears it. Every change is recorded with the old and new value. A visit another request changed while this one ran answers 409 stale_record; send it again.", "operationId": "postSupervisoryVisitsByIdDate", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "date": { "description": "The visit's date, YYYY-MM-DD, or null to clear it; empty clears it too.", "format": "date", "nullable": true, "type": "string" } }, "title": "SupervisoryVisitDate", "type": "object" } } }, "description": "The date", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SupervisoryVisit" } }, "required": [ "data" ], "type": "object" } } }, "description": "The visit" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Set a supervisory visit's date", "tags": [ "Supervisory visits" ] } }, "/api/v1/supervisory-visits/{id}/reopen": { "post": { "callbacks": {}, "description": "As the visit page's Reopen does. A visit with a signature recorded since signatures became records (record_state signed or amended) is voided with the reason given and copied into a new draft, which is the answer (its replaces_id names the original); without a reason it answers 422 reason_required, and a voided visit 409 voided. Any other completed or signed visit has its signatures cleared and returns to draft in place. Reopening needs care_plans.manage (403 forbidden otherwise); a draft with nothing to undo answers 422 already_draft. A visit another request changed while this one ran answers 409 stale_record; send it again.", "operationId": "postSupervisoryVisitsByIdReopen", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Why the visit is being corrected, 3 to 1000 characters; required once any line is signed, when the visit is voided and copied into a new draft.", "nullable": true, "type": "string" } }, "title": "SupervisoryVisitReopen", "type": "object" } } }, "description": "Why it is reopened", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SupervisoryVisit" } }, "required": [ "data" ], "type": "object" } } }, "description": "The visit, or the new draft" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_draft, reason_required: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Reopen a supervisory visit for correction", "tags": [ "Supervisory visits" ] } }, "/api/v1/supervisory-visits/{id}/signatures": { "post": { "callbacks": {}, "description": "Records one signature line, as the visit page does: supervisor (signed as the credential's user, under name or the visit's supervisor), client and pcp (by name, required), caregiver (the visit's caregiver). A line already signed answers 422 already_signed; unanswered required questions answer 422 naming them. A visit another request changed while this one ran answers 409 stale_record; send it again. 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.", "operationId": "postSupervisoryVisitsByIdSignatures", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "The signer's name; required for client and pcp.", "nullable": true, "type": "string" }, "signer": { "description": "Whose line to sign.", "enum": [ "supervisor", "client", "caregiver", "pcp" ], "type": "string" } }, "required": [ "signer" ], "title": "SupervisoryVisitSignature", "type": "object" } } }, "description": "The signature", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SupervisoryVisit" } }, "required": [ "data" ], "type": "object" } } }, "description": "The visit" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code signature_requires_person: Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code already_signed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Sign a supervisory visit", "tags": [ "Supervisory visits" ] } }, "/api/v1/support-tickets": { "get": { "callbacks": {}, "description": "The support tickets the API key's user raised, newest first, with where each has got to. Tickets other members raised are not listed.", "operationId": "getSupportTickets", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only tickets in this state.", "in": "query", "name": "status", "schema": { "enum": [ "open", "in_progress", "waiting_on_user", "resolved", "closed" ], "type": "string" } }, { "description": "Only tickets at this priority.", "in": "query", "name": "priority", "schema": { "enum": [ "low", "normal", "high", "urgent" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/SupportTicket" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "SupportTicketPage", "type": "object" } } }, "description": "A page of support tickets" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List your support tickets", "tags": [ "Support tickets" ] }, "post": { "callbacks": {}, "description": "Sends a request to the HomeCareBilling support team. Send it ONCE per problem: a second call files a second ticket. A bug report the server cannot complete from the user's recent activity is 422 needs_more_info and files nothing: its details carry the questions (missing, questions) and a follow_up_id; ask the user, then send the request again with the answers and that follow_up_id, which files it once however often it is sent. The description needs at least 20 characters; a field that is missing, too long or not one of its values is 422 naming it. A screenshot is not accepted. Requests share the in-app assistant's ceiling: past it the answer is 429 support_ticket_limit. Support replies by email, quoting the reference.", "operationId": "postSupportTickets", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportTicketInput" } } }, "description": "The request", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SupportTicket" } }, "required": [ "data" ], "type": "object" } } }, "description": "The ticket" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code needs_more_info: Unprocessable Content, as the operation's description says." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code support_ticket_limit: Too Many Requests, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Open a support ticket", "tags": [ "Support tickets" ] } }, "/api/v1/support-tickets/{id}": { "get": { "callbacks": {}, "description": "One ticket the API key's user raised. A ticket another member raised, or another agency's, is 404.", "operationId": "getSupportTicketsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SupportTicket" } }, "required": [ "data" ], "type": "object" } } }, "description": "The support ticket" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get one of your support tickets", "tags": [ "Support tickets" ] } }, "/api/v1/task-set-templates": { "get": { "callbacks": {}, "description": "A reusable set of tasks with default minutes and visits a week, from Settings > Task templates. Creating, changing and deleting one is an admin's (403 forbidden otherwise). The agency's task set templates in the default template first, then name order. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getTaskSetTemplates", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only templates for this service.", "in": "query", "name": "service_type", "schema": { "enum": [ "personal_care", "homemaker", "legacy" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/TaskSetTemplate" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Task set templatePage", "type": "object" } } }, "description": "A page of task set templates" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List task set templates", "tags": [ "Task set templates" ] }, "post": { "callbacks": {}, "operationId": "postTaskSetTemplates", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskSetTemplateInput" } } }, "description": "The task set template's fields", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/TaskSetTemplate" } }, "required": [ "data" ], "type": "object" } } }, "description": "The created task set template" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a task set template", "tags": [ "Task set templates" ] } }, "/api/v1/task-set-templates/{id}": { "delete": { "callbacks": {}, "description": "Deletes it, as the settings page does; Work Orders made from it keep their tasks. The agency's default template answers 422 cannot_delete_default. Needs agency_settings.manage (403 forbidden otherwise).", "operationId": "deleteTaskSetTemplatesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/TaskSetTemplate" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted template" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code cannot_delete_default: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a task set template", "tags": [ "Task set templates" ] }, "get": { "callbacks": {}, "description": "A reusable set of tasks with default minutes and visits a week, from Settings > Task templates. Creating, changing and deleting one is an admin's (403 forbidden otherwise).", "operationId": "getTaskSetTemplatesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/TaskSetTemplate" } }, "required": [ "data" ], "type": "object" } } }, "description": "The task set template" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no task set template with that id in this agency, including another agency's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a task set template", "tags": [ "Task set templates" ] }, "patch": { "callbacks": {}, "description": "Sets only the fields sent. lock_version is required: send the value you read, and a record changed since answers 409 stale_record.", "operationId": "patchTaskSetTemplatesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskSetTemplateInput" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/TaskSetTemplate" } }, "required": [ "data" ], "type": "object" } } }, "description": "The updated task set template" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no task set template with that id in this agency, including another agency's." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: the task set template changed since the lock_version sent was read, or while this request ran. Nothing was saved; read it again and retry." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a task set template", "tags": [ "Task set templates" ] } }, "/api/v1/telephony-pins/bulk": { "post": { "callbacks": {}, "description": "As the caregiver list's Assign PINs does. The PINs are never returned (PRD 5.8); the caregiver list exports them. When a draw fails part way, the PINs already assigned stay and incomplete names why; run it again for the rest.", "operationId": "postTelephonyPinsBulk", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "assigned": { "description": "Caregivers given a PIN.", "nullable": true, "type": "integer" }, "incomplete": { "description": "Whether it stopped part way.", "type": "boolean" }, "reason": { "description": "Why it stopped: no free PIN left (exhausted), a refused audit row rolled back the next assignment (audit_log_failed; the ones before it were kept), or a caregiver changed during the run (stale).", "enum": [ "exhausted", "audit_log_failed", "stale" ], "nullable": true, "type": "string" } }, "required": [ "assigned" ], "title": "TelephonyPinsAssigned", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "How many were assigned" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Give every active caregiver without one a telephony PIN", "tags": [ "Caregiver records" ] } }, "/api/v1/timesheet-entries/{id}": { "patch": { "callbacks": {}, "description": "Changes the fields sent, as the entries page does, and recalculates the hours. A timesheet that is not a draft answers 422 not_editable.", "operationId": "patchTimesheetEntriesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "date": { "description": "The date, YYYY-MM-DD.", "format": "date", "type": "string" }, "deviation_explanation": { "description": "Why the times deviate from the plan; null or blank clears it.", "nullable": true, "type": "string" }, "time_in": { "description": "HH:MM:SS; null or blank clears it.", "nullable": true, "type": "string" }, "time_out": { "description": "HH:MM:SS; null or blank clears it.", "nullable": true, "type": "string" }, "travel_time": { "description": "Whether the entry is travel time.", "type": "boolean" } }, "title": "TimesheetEntryUpdate", "type": "object" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "date": { "format": "date", "nullable": true, "type": "string" }, "day_of_week": { "nullable": true, "type": "string" }, "deviation_explanation": { "nullable": true, "type": "string" }, "evv_clock_in": { "description": "The EVV clock-in pulled from the matched visit.", "format": "date-time", "type": "string" }, "evv_clock_out": { "description": "The EVV clock-out pulled from the matched visit.", "format": "date-time", "type": "string" }, "evv_source": { "nullable": true, "type": "string" }, "hours_worked": { "description": "Hours that day.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "time_in": { "description": "HH:MM:SS.", "nullable": true, "type": "string" }, "time_out": { "description": "HH:MM:SS.", "nullable": true, "type": "string" }, "timesheet_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "travel_time": { "type": "boolean" }, "visit_id": { "description": "The EVV visit the times were pulled from.", "format": "uuid", "type": "string" } }, "title": "TimesheetEntry", "type": "object" }, "warnings": { "description": "The findings the day's delivery raised on this write (care_logs.over_weekly_limit and the like), and the entry's own (timesheets.time_out_before_time_in: the Time Out is before the Time In, so the day counts as an overnight shift): warnings, never refusals.", "items": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "type": "object" } } }, "description": "The entry" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_editable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a time entry", "tags": [ "Timesheets" ] } }, "/api/v1/timesheet-entries/{id}/pull-evv": { "post": { "callbacks": {}, "description": "Copies the clock-in and clock-out of the EVV visit matching the entry's client, caregiver and date onto the entry and links the visit, as the entries page's Pull EVV does. The visit is matched by the server, never named by the client. A flagged visit (an EVV exception, or one not verified) answers 422 evv_flagged naming the flag; no matching visit 422 no_evv_match; a timesheet that is not a draft 422 not_editable. An entry of another agency's timesheet answers 404 and nothing is written.", "operationId": "postTimesheetEntriesByIdPullEvv", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "date": { "format": "date", "nullable": true, "type": "string" }, "day_of_week": { "nullable": true, "type": "string" }, "deviation_explanation": { "nullable": true, "type": "string" }, "evv_clock_in": { "description": "The EVV clock-in pulled from the matched visit.", "format": "date-time", "type": "string" }, "evv_clock_out": { "description": "The EVV clock-out pulled from the matched visit.", "format": "date-time", "type": "string" }, "evv_source": { "nullable": true, "type": "string" }, "hours_worked": { "description": "Hours that day.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "time_in": { "description": "HH:MM:SS.", "nullable": true, "type": "string" }, "time_out": { "description": "HH:MM:SS.", "nullable": true, "type": "string" }, "timesheet_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "travel_time": { "type": "boolean" }, "visit_id": { "description": "The EVV visit the times were pulled from.", "format": "uuid", "type": "string" } }, "title": "TimesheetEntry", "type": "object" }, "warnings": { "description": "The findings the day's delivery raised on this write (care_logs.over_weekly_limit and the like), and the entry's own (timesheets.time_out_before_time_in: the Time Out is before the Time In, so the day counts as an overnight shift): warnings, never refusals.", "items": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "type": "object" } } }, "description": "The entry" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes evv_flagged, no_evv_match, not_editable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Pull an entry's EVV clock times from its matched visit", "tags": [ "Timesheets" ] } }, "/api/v1/timesheet-tasks/{id}": { "patch": { "callbacks": {}, "description": "Changes the fields sent, as the entries page marks a task done or not.", "operationId": "patchTimesheetTasksById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "completed": { "description": "Whether the task was done.", "type": "boolean" }, "frequency": { "description": "Times done.", "nullable": true, "type": "integer" }, "notes": { "description": "Notes on the task; null or blank clears them.", "nullable": true, "type": "string" }, "time_minutes": { "description": "Minutes spent.", "nullable": true, "type": "integer" } }, "title": "TimesheetTaskUpdate", "type": "object" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "completed": { "type": "boolean" }, "frequency": { "description": "Times done.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "notes": { "nullable": true, "type": "string" }, "task_category": { "nullable": true, "type": "string" }, "task_name": { "nullable": true, "type": "string" }, "time_minutes": { "description": "Minutes spent.", "nullable": true, "type": "integer" }, "timesheet_entry_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "title": "TimesheetTask", "type": "object" }, "warnings": { "description": "The findings the day's delivery raised on this write (care_logs.over_weekly_limit and the like), and the entry's own (timesheets.time_out_before_time_in: the Time Out is before the Time In, so the day counts as an overnight shift): warnings, never refusals.", "items": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "type": "object" } } }, "description": "The task" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a task", "tags": [ "Timesheets" ] } }, "/api/v1/timesheets": { "get": { "callbacks": {}, "description": "The hours worked for one client and caregiver in one billing period. The agency's timesheets in billing-period order, newest first, deleted ones left out unless include_deleted=true. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getTimesheets", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records with this status.", "in": "query", "name": "status", "schema": { "enum": [ "draft", "submitted", "approved", "rejected", "exported" ], "type": "string" } }, { "description": "Only records of this client.", "in": "query", "name": "client_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only records of this caregiver.", "in": "query", "name": "caregiver_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only records changed at or after this instant (ISO 8601, with an offset), compared to the second. The list is then in change order: updated_at, then id.", "in": "query", "name": "updated_since", "schema": { "format": "date-time", "type": "string" } }, { "description": "With updated_since, a cursor: send the last record's updated_at as updated_since and its id as after_id to get the next page. Use this, not offset, to sync: an offset skips a record when an earlier one changes between two requests. The sync is at least once: timestamps are whole seconds and set before commit, so a record changed in the cursor's second, or committed late, can fall behind the cursor. Start each sync pass a minute before the newest updated_at you saw, and treat every record returned as current: apply it over what you hold. A record can change twice within one second, and not every change moves lock_version, so the same updated_at and lock_version do not mean the same content.", "in": "query", "name": "after_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "true also lists deleted records, with deleted_at set, so a sync learns of deletions.", "in": "query", "name": "include_deleted", "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Timesheet" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "TimesheetPage", "type": "object" } } }, "description": "A page of timesheets" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List timesheets", "tags": [ "Timesheets" ] } }, "/api/v1/timesheets/{id}": { "delete": { "callbacks": {}, "description": "Deletes the timesheet, as the timesheet list does. Only a draft deletes: any other status answers 422 not_draft. A timesheet of another agency, or a deleted one, answers 404 and nothing is written.", "operationId": "deleteTimesheetsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Timesheet" } }, "required": [ "data" ], "type": "object" } } }, "description": "The timesheet" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_draft: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a draft timesheet", "tags": [ "Timesheets" ] }, "get": { "callbacks": {}, "description": "The hours worked for one client and caregiver in one billing period.", "operationId": "getTimesheetsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Timesheet" } }, "required": [ "data" ], "type": "object" } } }, "description": "The timesheet" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no timesheet with that id in this agency, including another agency's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a timesheet", "tags": [ "Timesheets" ] } }, "/api/v1/timesheets/{id}/approve": { "post": { "callbacks": {}, "description": "Approves it, as the returned timesheet bar does. warnings names hours stored on the timesheet that differ from what its entries add up to; the stored hours bill. A timesheet not awaiting approval answers 422 not_submitted. A timesheet of another agency, or a deleted one, answers 404 and nothing is written.", "operationId": "postTimesheetsByIdApprove", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Timesheet" }, "warnings": { "items": { "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "type": "object" } } }, "description": "The timesheet and its warnings" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_submitted: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Approve a submitted timesheet", "tags": [ "Timesheets" ] } }, "/api/v1/timesheets/{id}/billing-data": { "get": { "callbacks": {}, "description": "Builds the claim lines from an approved timesheet, as the billing summary does, each with the fields a claim returns (the patient's date of birth, address and gender, which the 837P carries, are not returned; charge_amount only for a credential holding Billing & claims → View). Nothing is written. A timesheet that cannot bill answers 422 billing_refusal with the billing summary's reason. A timesheet of another agency, or a deleted one, answers 404 and nothing is written.", "operationId": "getTimesheetsByIdBillingData", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The claim lines" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code billing_refusal: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "The claim lines an approved timesheet bills", "tags": [ "Timesheets" ] } }, "/api/v1/timesheets/{id}/entries": { "post": { "callbacks": {}, "description": "Adds an entry for a date in the billing period and recalculates the hours. A timesheet that is not a draft answers 422 not_editable. A timesheet of another agency, or a deleted one, answers 404 and nothing is written.", "operationId": "postTimesheetsByIdEntries", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "date": { "description": "The date, YYYY-MM-DD.", "format": "date", "type": "string" }, "deviation_explanation": { "description": "Why the times deviate from the plan; null or blank clears it.", "nullable": true, "type": "string" }, "time_in": { "description": "HH:MM:SS; null or blank clears it.", "nullable": true, "type": "string" }, "time_out": { "description": "HH:MM:SS; null or blank clears it.", "nullable": true, "type": "string" }, "travel_time": { "description": "Whether the entry is travel time.", "type": "boolean" } }, "required": [ "date" ], "title": "TimesheetEntryCreate", "type": "object" } } }, "description": "The entry", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "date": { "format": "date", "nullable": true, "type": "string" }, "day_of_week": { "nullable": true, "type": "string" }, "deviation_explanation": { "nullable": true, "type": "string" }, "evv_clock_in": { "description": "The EVV clock-in pulled from the matched visit.", "format": "date-time", "type": "string" }, "evv_clock_out": { "description": "The EVV clock-out pulled from the matched visit.", "format": "date-time", "type": "string" }, "evv_source": { "nullable": true, "type": "string" }, "hours_worked": { "description": "Hours that day.", "format": "decimal", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "time_in": { "description": "HH:MM:SS.", "nullable": true, "type": "string" }, "time_out": { "description": "HH:MM:SS.", "nullable": true, "type": "string" }, "timesheet_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "travel_time": { "type": "boolean" }, "visit_id": { "description": "The EVV visit the times were pulled from.", "format": "uuid", "type": "string" } }, "title": "TimesheetEntry", "type": "object" }, "warnings": { "description": "The findings the day's delivery raised on this write (care_logs.over_weekly_limit and the like), and the entry's own (timesheets.time_out_before_time_in: the Time Out is before the Time In, so the day counts as an overnight shift): warnings, never refusals.", "items": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "type": "object" } } }, "description": "The entry" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_editable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Add a time entry to a draft timesheet", "tags": [ "Timesheets" ] } }, "/api/v1/timesheets/{id}/export": { "post": { "callbacks": {}, "description": "Exports it, as the returned timesheet bar's Export does; exported is final. A timesheet that is not approved answers 422 not_exportable. A timesheet of another agency, or a deleted one, answers 404 and nothing is written.", "operationId": "postTimesheetsByIdExport", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Timesheet" } }, "required": [ "data" ], "type": "object" } } }, "description": "The timesheet" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_exportable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Export an approved timesheet for billing", "tags": [ "Timesheets" ] } }, "/api/v1/timesheets/{id}/reject": { "post": { "callbacks": {}, "description": "Returns it to draft with the reason, clearing its signatures and voiding the half-month summaries that covered it, as the returned timesheet bar does. No reason answers 422 reason_required, a null or blank one 422 null_not_allowed; a timesheet not awaiting approval 422 not_submitted; a covering summary voided meanwhile 409 voided. A timesheet of another agency, or a deleted one, answers 404 and nothing is written.", "operationId": "postTimesheetsByIdReject", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Why it is rejected.", "type": "string" } }, "required": [ "reason" ], "title": "TimesheetReject", "type": "object" } } }, "description": "The reason", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Timesheet" } }, "required": [ "data" ], "type": "object" } } }, "description": "The timesheet" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes not_submitted, null_not_allowed, reason_required: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Reject a submitted timesheet back to draft", "tags": [ "Timesheets" ] } }, "/api/v1/timesheets/{id}/reopen": { "post": { "callbacks": {}, "description": "Returns an approved timesheet a denied claim sent back for correction to draft, clearing its signatures and voiding the half-month summaries that covered it, as the release panel does. Without a release it answers 422 no_release; a covering summary voided meanwhile 409 voided. A timesheet of another agency, or a deleted one, answers 404 and nothing is written.", "operationId": "postTimesheetsByIdReopen", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Timesheet" } }, "required": [ "data" ], "type": "object" } } }, "description": "The timesheet" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code no_release: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Move a released timesheet back to draft for correction", "tags": [ "Timesheets" ] } }, "/api/v1/timesheets/{id}/signatures": { "post": { "callbacks": {}, "description": "Signing needs signed_records.sign and timesheets.view, not timesheets.manage (403 forbidden naming the permission otherwise). A caregiver slot is recorded as the caregiver's paper signature on file (the office never signs in the caregiver's name), with the credential's user as who recorded it; a client slot needs client_name matching the client's name (422 client_name_required when it is blank, 422 client_name_mismatch when it is not the client's). A signed slot answers 409 already_signed unless resign is true, which needs signed_records.void (403 forbidden otherwise). A re-sign voids the half-month summary holding the half with every signature on it, the other role's included, drafts a fresh one from the hours as they now stand, writes a paper signature on file in the other line again on it, and signs the slot on it; another timesheet of the same service that relied on the voided summary must be signed again. The same re-sign retried changes nothing. The signature is written on the half-month summary of the client, caregiver and the timesheet's service, and nothing is written on the timesheet; a half whose client line was skipped with a reason answers 409 half_complete, resign or not; a role held by the paper card of another Work Order of the client and caregiver answers 409 paper_card_on_file, resign or not. When the half's hours changed after a line was signed on its summary, a paper signature on file is redrawn onto a fresh summary of the hours as they now stand and the slot signs that one; a line someone signed for the earlier hours answers 409 signed_hours_changed, and that line is re-signed first. A half not yet ended answers 422 signature_period_not_reached. A timesheet of another agency, or a deleted one, answers 404 and nothing is written. 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.", "operationId": "postTimesheetsByIdSignatures", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "client_name": { "description": "The client's name, for a client slot.", "nullable": true, "type": "string" }, "resign": { "description": "Re-sign a signed slot (needs signed_records.void).", "type": "boolean" }, "signature_type": { "description": "The slot to sign.", "enum": [ "caregiver_first_half", "client_first_half", "caregiver_second_half", "client_second_half" ], "type": "string" } }, "required": [ "signature_type" ], "title": "TimesheetSign", "type": "object" } } }, "description": "The slot", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Timesheet" } }, "required": [ "data" ], "type": "object" } } }, "description": "The timesheet" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code signature_requires_person: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_signed, half_complete, paper_card_on_file, signed_hours_changed: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes client_name_mismatch, client_name_required, signature_period_not_reached: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Sign one of a draft timesheet's four slots", "tags": [ "Timesheets" ] } }, "/api/v1/timesheets/{id}/submit": { "post": { "callbacks": {}, "description": "Submits it, as the returned timesheet bar does. A half counts as signed when the pair's half-month summary for it is signed by the caregiver and the client (in the app, in the office, or on the Timesheet's own paper card) for the hours the Timesheet bills. Missing signatures answer 422 signatures_required unless acknowledge_missing_signatures is true (the page's Submit anyway); no hours answers 422 no_hours_logged. A timesheet of another agency, or a deleted one, answers 404 and nothing is written.", "operationId": "postTimesheetsByIdSubmit", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "acknowledge_missing_signatures": { "description": "Submit with signatures missing.", "type": "boolean" } }, "title": "TimesheetSubmit", "type": "object" } } }, "description": "Options", "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Timesheet" } }, "required": [ "data" ], "type": "object" } } }, "description": "The timesheet" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes no_hours_logged, signatures_required: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Submit a draft timesheet for approval", "tags": [ "Timesheets" ] } }, "/api/v1/timesheets/{id}/tasks": { "post": { "callbacks": {}, "description": "Records a task done on one of the timesheet's entries, as the entries page does. task_name is one of HCPF's task names. An entry of another timesheet answers 422 entry_not_in_timesheet. A timesheet of another agency, or a deleted one, answers 404 and nothing is written.", "operationId": "postTimesheetsByIdTasks", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "completed": { "description": "Whether the task was done.", "type": "boolean" }, "frequency": { "description": "Times done.", "nullable": true, "type": "integer" }, "notes": { "description": "Notes on the task; null or blank clears them.", "nullable": true, "type": "string" }, "task_name": { "description": "HCPF's task name.", "type": "string" }, "time_minutes": { "description": "Minutes spent.", "nullable": true, "type": "integer" }, "timesheet_entry_id": { "description": "The entry the task was done on.", "format": "uuid", "type": "string" } }, "required": [ "timesheet_entry_id", "task_name" ], "title": "TimesheetTaskCreate", "type": "object" } } }, "description": "The task", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "completed": { "type": "boolean" }, "frequency": { "description": "Times done.", "nullable": true, "type": "integer" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "notes": { "nullable": true, "type": "string" }, "task_category": { "nullable": true, "type": "string" }, "task_name": { "nullable": true, "type": "string" }, "time_minutes": { "description": "Minutes spent.", "nullable": true, "type": "integer" }, "timesheet_entry_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "title": "TimesheetTask", "type": "object" }, "warnings": { "description": "The findings the day's delivery raised on this write (care_logs.over_weekly_limit and the like), and the entry's own (timesheets.time_out_before_time_in: the Time Out is before the Time In, so the day counts as an overnight shift): warnings, never refusals.", "items": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "data", "warnings" ], "type": "object" } } }, "description": "The task" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code entry_not_in_timesheet: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Add a task to an entry of a draft timesheet", "tags": [ "Timesheets" ] } }, "/api/v1/trainings/bulk-annual-completion": { "post": { "callbacks": {}, "description": "As the compliance dashboard's bulk annual training does, for completed_date's year: by default only courses not yet recorded; replace true also moves dates already recorded. Needs caregivers.manage (403 forbidden otherwise). A year outside 2000 to next year is 422.", "operationId": "postTrainingsBulkAnnualCompletion", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "completed_date": { "description": "The completion date, YYYY-MM-DD; its year is the training year.", "format": "date", "type": "string" }, "replace": { "description": "Also move dates already recorded.", "type": "boolean" } }, "required": [ "completed_date" ], "title": "TrainingBulkCompletion", "type": "object" } } }, "description": "The completion", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "caregivers": { "description": "Active caregivers it covered.", "nullable": true, "type": "integer" }, "records": { "description": "Records written.", "nullable": true, "type": "integer" }, "replaced": { "description": "Existing dates it updated.", "nullable": true, "type": "integer" }, "skipped": { "description": "Records left as they were.", "nullable": true, "type": "integer" } }, "required": [ "caregivers", "records" ], "title": "CaregiverBulkResult", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "What was written" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Set annual training complete for every active caregiver", "tags": [ "Caregiver records" ] } }, "/api/v1/trainings/{id}": { "delete": { "callbacks": {}, "description": "Deletes the record, as the caregiver's Training tab does; the audit trail keeps what it was. Training records carry no lock_version.", "operationId": "deleteTrainingsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CaregiverTraining" } }, "required": [ "data" ], "type": "object" } } }, "description": "The deleted record" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a caregiver's training record", "tags": [ "Deletes and restores" ] }, "patch": { "callbacks": {}, "description": "Sets only the fields sent; a body that changes nothing is 422 nothing_to_change. Another agency's record is 404.", "operationId": "patchTrainingsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaregiverTrainingInput" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CaregiverTraining" } }, "required": [ "data" ], "type": "object" } } }, "description": "The training record" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code nothing_to_change: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a training record", "tags": [ "Caregiver records" ] } }, "/api/v1/underpayments": { "get": { "callbacks": {}, "description": "Paid claims HCPF paid less than its published rate for the dates of service says, after the adjustments that lawfully explain short pay, the largest gap first, then the newest paid. Paid dates default to the last 90 days; a range over 366 days is 400. Dismissed rows are left out unless include_dismissed is true. Nothing here blocks a claim.", "operationId": "getUnderpayments", "parameters": [ { "description": "First paid date (YYYY-MM-DD). Default 90 days before paid_to.", "in": "query", "name": "paid_from", "schema": { "format": "date", "type": "string" } }, { "description": "Last paid date (YYYY-MM-DD). Default today.", "in": "query", "name": "paid_to", "schema": { "format": "date", "type": "string" } }, { "description": "true also lists dismissed rows, with dismissed true.", "in": "query", "name": "include_dismissed", "schema": { "type": "boolean" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Underpayment" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "paid_from": { "description": "The first paid date read.", "format": "date", "nullable": true, "type": "string" }, "paid_to": { "description": "The last paid date read.", "format": "date", "nullable": true, "type": "string" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" }, "total_gap": { "description": "The sum of every listed row's gap, not just this page's.", "format": "decimal", "nullable": true, "type": "string" }, "truncated": { "description": "True when the period held more paid claims than one read judges (5000): only the newest-paid were judged. Narrow the dates to see the rest.", "type": "boolean" } }, "required": [ "data", "limit", "offset", "total", "total_gap", "truncated", "paid_from", "paid_to" ], "title": "UnderpaymentPage", "type": "object" } } }, "description": "The underpaid claims" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Bad Request, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List underpaid claims", "tags": [ "Claims" ] } }, "/api/v1/university/videos": { "get": { "callbacks": {}, "description": "The narrated training videos of jobs in the app, in the order /university shows them: by section, then by title. The same for every agency.", "operationId": "getUniversityVideos", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/UniversityVideo" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "UniversityVideoPage", "type": "object" } } }, "description": "A page of videos" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List HCB University videos", "tags": [ "HCB University" ] } }, "/api/v1/university/videos/{slug}": { "get": { "callbacks": {}, "description": "One video with the pages it shows, its chapters, and for each rendered language the video, captions and poster as storage URLs signed for 6 hours. A URL that could not be signed is null. 404 for a slug the catalog does not list.", "operationId": "getUniversityVideosBySlug", "parameters": [ { "description": "The video's slug.", "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/UniversityVideoDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The video" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get an HCB University video", "tags": [ "HCB University" ] } }, "/api/v1/unmatched-calls": { "get": { "callbacks": {}, "description": "Telephony clock calls that matched no visit, newest first, each with the calling number masked to its last four digits. Filter by status and by the Colorado day the call came in.", "operationId": "getUnmatchedCalls", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records with this status.", "in": "query", "name": "status", "schema": { "enum": [ "pending", "matched", "dismissed" ], "type": "string" } }, { "description": "Only calls received (Colorado days) on or after this date (YYYY-MM-DD, Colorado).", "in": "query", "name": "call_date_from", "schema": { "format": "date", "type": "string" } }, { "description": "Only calls received (Colorado days) on or before this date (YYYY-MM-DD, Colorado).", "in": "query", "name": "call_date_to", "schema": { "format": "date", "type": "string" } }, { "description": "The id of the last call you read: the page starts after it, so calls you resolved meanwhile never make you skip any (offset would). total counts what remains after it.", "in": "query", "name": "after", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/UnmatchedCall" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "UnmatchedCallPage", "type": "object" } } }, "description": "A page of unmatched calls" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List unmatched calls", "tags": [ "Unmatched calls" ] } }, "/api/v1/unmatched-calls/{id}/dismiss": { "post": { "callbacks": {}, "description": "Dismisses a pending call with a reason, as the screen does; it can be undone within 24 hours. The reason is trimmed, then must be 10 to 500 characters (422 invalid_reason); a call no longer pending is 422 naming status.", "operationId": "postUnmatchedCallsByIdDismiss", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Why it is dismissed: 10 to 500 characters, as on the screen.", "maxLength": 500, "minLength": 10, "type": "string" } }, "required": [ "reason" ], "title": "UnmatchedCallDismiss", "type": "object" } } }, "description": "The reason", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/UnmatchedCall" } }, "required": [ "data" ], "type": "object" } } }, "description": "The dismissed call" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code invalid_reason: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Dismiss an unmatched call", "tags": [ "Unmatched calls" ] } }, "/api/v1/unmatched-calls/{id}/match": { "post": { "callbacks": {}, "description": "Records the call as the visit's clock-in or clock-out, as the unmatched-calls screen does. The visit must be this agency's and the call's caregiver's, in a status that takes that clock: 422 names visit_id or the rule. A call no longer pending is 422 naming status. A call kept without its caller's number (originating_phone_number empty) cannot be recorded as a phone clock: 422 no_caller_number; dismiss it and enter the time on the visit.", "operationId": "postUnmatchedCallsByIdMatch", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "visit_id": { "description": "The visit the call clocked.", "format": "uuid", "type": "string" } }, "required": [ "visit_id" ], "title": "UnmatchedCallMatch", "type": "object" } } }, "description": "The visit", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/UnmatchedCall" } }, "required": [ "data" ], "type": "object" } } }, "description": "The matched call" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code no_caller_number: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Match an unmatched call to a visit", "tags": [ "Unmatched calls" ] } }, "/api/v1/unmatched-calls/{id}/undo-dismiss": { "post": { "callbacks": {}, "description": "Returns a dismissed call to pending within 24 hours of its dismissal, as the screen does. A call not dismissed is 422 naming status; past the window, 422 undo_window_expired.", "operationId": "postUnmatchedCallsByIdUndoDismiss", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/UnmatchedCall" } }, "required": [ "data" ], "type": "object" } } }, "description": "The call, pending again" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code undo_window_expired: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Undo a dismissal", "tags": [ "Unmatched calls" ] } }, "/api/v1/users": { "get": { "callbacks": {}, "description": "Every member, by email, as the Settings Team screen lists them. Needs Team → View (403 forbidden otherwise).", "operationId": "getUsers", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "email": { "description": "Their sign-in email.", "nullable": true, "type": "string" }, "id": { "description": "The member's user id.", "format": "uuid", "type": "string" }, "joined_at": { "description": "When they joined (UTC).", "format": "date-time", "type": "string" }, "last_seen_at": { "description": "When they last signed in here (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "name": { "description": "Their display name; null shows the email.", "nullable": true, "type": "string" }, "role": { "description": "Their role in this agency.", "enum": [ "admin", "billing_staff" ], "type": "string" }, "status": { "description": "Whether they may sign in here.", "enum": [ "active", "deactivated" ], "type": "string" } }, "required": [ "id", "email", "role", "status" ], "title": "AgencyMember", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "AgencyMemberPage", "type": "object" } } }, "description": "A page of members" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List the agency's members", "tags": [ "Agency administration" ] } }, "/api/v1/users/{id}": { "delete": { "callbacks": {}, "description": "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).", "operationId": "deleteUsersById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "email": { "description": "Their sign-in email.", "nullable": true, "type": "string" }, "id": { "description": "The member's user id.", "format": "uuid", "type": "string" }, "joined_at": { "description": "When they joined (UTC).", "format": "date-time", "type": "string" }, "last_seen_at": { "description": "When they last signed in here (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "name": { "description": "Their display name; null shows the email.", "nullable": true, "type": "string" }, "role": { "description": "Their role in this agency.", "enum": [ "admin", "billing_staff" ], "type": "string" }, "status": { "description": "Whether they may sign in here.", "enum": [ "active", "deactivated" ], "type": "string" } }, "required": [ "id", "email", "role", "status" ], "title": "AgencyMember", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The member" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes cannot_deactivate_self, last_admin: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Deactivate a member", "tags": [ "Agency administration" ] }, "patch": { "callbacks": {}, "description": "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).", "operationId": "patchUsersById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "Their display name; null or blank clears it, showing the email.", "nullable": true, "type": "string" }, "role": { "description": "Their role.", "enum": [ "admin", "billing_staff" ], "type": "string" } }, "title": "AgencyMemberUpdate", "type": "object" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "email": { "description": "Their sign-in email.", "nullable": true, "type": "string" }, "id": { "description": "The member's user id.", "format": "uuid", "type": "string" }, "joined_at": { "description": "When they joined (UTC).", "format": "date-time", "type": "string" }, "last_seen_at": { "description": "When they last signed in here (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "name": { "description": "Their display name; null shows the email.", "nullable": true, "type": "string" }, "role": { "description": "Their role in this agency.", "enum": [ "admin", "billing_staff" ], "type": "string" }, "status": { "description": "Whether they may sign in here.", "enum": [ "active", "deactivated" ], "type": "string" } }, "required": [ "id", "email", "role", "status" ], "title": "AgencyMember", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The member" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes cannot_change_own_role, last_admin, role_held_by_custom_role, role_unavailable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Rename a member or change their role", "tags": [ "Agency administration" ] } }, "/api/v1/users/{id}/reactivate": { "post": { "callbacks": {}, "description": "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).", "operationId": "postUsersByIdReactivate", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "email": { "description": "Their sign-in email.", "nullable": true, "type": "string" }, "id": { "description": "The member's user id.", "format": "uuid", "type": "string" }, "joined_at": { "description": "When they joined (UTC).", "format": "date-time", "type": "string" }, "last_seen_at": { "description": "When they last signed in here (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "name": { "description": "Their display name; null shows the email.", "nullable": true, "type": "string" }, "role": { "description": "Their role in this agency.", "enum": [ "admin", "billing_staff" ], "type": "string" }, "status": { "description": "Whether they may sign in here.", "enum": [ "active", "deactivated" ], "type": "string" } }, "required": [ "id", "email", "role", "status" ], "title": "AgencyMember", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The member" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Reactivate a member", "tags": [ "Agency administration" ] } }, "/api/v1/users/{id}/two-factor/reset": { "post": { "callbacks": {}, "description": "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).", "operationId": "postUsersByIdTwoFactorReset", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "two_factor_enabled": { "description": "Always false once reset.", "type": "boolean" }, "user_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "required": [ "user_id", "two_factor_enabled" ], "title": "TwoFactorReset", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Reset" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_allowed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Reset a member's two-factor", "tags": [ "Agency settings" ] } }, "/api/v1/vaccinations/bulk": { "post": { "callbacks": {}, "description": "As the bulk vaccination page's Save all does: one status per caregiver for the year, all or none. An unknown caregiver is 404 naming it; an invalid entry is 422.", "operationId": "postVaccinationsBulk", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "updates": { "description": "One per caregiver: {caregiver_id, status, vaccination_date, notes}.", "items": { "properties": { "caregiver_id": { "description": "The caregiver.", "format": "uuid", "type": "string" }, "notes": { "description": "Notes.", "nullable": true, "type": "string" }, "status": { "enum": [ "vaccinated", "declined_medical", "declined_other", "unknown" ], "type": "string" }, "vaccination_date": { "description": "When vaccinated.", "format": "date", "nullable": true, "type": "string" } }, "required": [ "caregiver_id", "status" ], "title": "VaccinationBulkEntry", "type": "object" }, "type": "array" }, "year": { "description": "The flu season's year.", "type": "integer" } }, "required": [ "year", "updates" ], "title": "VaccinationBulkUpdate", "type": "object" } } }, "description": "The updates", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "updated": { "description": "Vaccination records written.", "nullable": true, "type": "integer" } }, "required": [ "updated" ], "title": "VaccinationBulkResult", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "How many were updated" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update many caregivers' flu vaccinations for a year", "tags": [ "Caregiver records" ] } }, "/api/v1/visit-exceptions": { "get": { "callbacks": {}, "description": "An EVV exception: a rule a visit broke, or (sandata_raised) an exception Sandata raised on it as the office recorded it; its resolution; and its Sandata acknowledgement state. A deleted visit's exceptions are kept as they are, as the exception queue keeps them. Exceptions are not deleted; only resetting a demo agency removes its records, all of them. The agency's visit exceptions in severity order, errors first, then newest detected. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getVisitExceptions", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records with this status.", "in": "query", "name": "status", "schema": { "enum": [ "open", "acknowledged", "corrected", "dismissed", "withdrawn" ], "type": "string" } }, { "description": "Only exceptions of this type.", "in": "query", "name": "exception_type", "schema": { "enum": [ "late_clock_in", "location_mismatch", "time_discrepancy", "missing_clock_in", "missing_clock_out", "overlapping_visits", "manual_entry", "suspicious_regularity", "phone_mismatch", "sandata_raised" ], "type": "string" } }, { "description": "Only exceptions of this severity.", "in": "query", "name": "severity", "schema": { "enum": [ "warning", "error" ], "type": "string" } }, { "description": "Only exceptions on this visit.", "in": "query", "name": "visit_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only records of this client.", "in": "query", "name": "client_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only records of this caregiver.", "in": "query", "name": "caregiver_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only exceptions detected on or after this date (YYYY-MM-DD, Colorado).", "in": "query", "name": "detected_from", "schema": { "format": "date", "type": "string" } }, { "description": "Only exceptions detected on or before this date (YYYY-MM-DD, Colorado).", "in": "query", "name": "detected_to", "schema": { "format": "date", "type": "string" } }, { "description": "Only records changed at or after this instant (ISO 8601, with an offset), compared to the second. The list is then in change order: updated_at, then id.", "in": "query", "name": "updated_since", "schema": { "format": "date-time", "type": "string" } }, { "description": "With updated_since, a cursor: send the last record's updated_at as updated_since and its id as after_id to get the next page. Use this, not offset, to sync: an offset skips a record when an earlier one changes between two requests. The sync is at least once: timestamps are whole seconds and set before commit, so a record changed in the cursor's second, or committed late, can fall behind the cursor. Start each sync pass a minute before the newest updated_at you saw, and treat every record returned as current: apply it over what you hold. A record can change twice within one second, and not every change moves lock_version, so the same updated_at and lock_version do not mean the same content.", "in": "query", "name": "after_id", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/VisitException" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Visit exceptionPage", "type": "object" } } }, "description": "A page of visit exceptions" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List visit exceptions", "tags": [ "Visit exceptions" ] } }, "/api/v1/visit-exceptions/reason-codes": { "get": { "callbacks": {}, "description": "The resolution codes a resolve takes, and the Colorado reason code (Addendum Appendix 3) that describes each exception type, as reference data.", "operationId": "getVisitExceptionsReasonCodes", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/VisitExceptionReasonCodes" } }, "required": [ "data" ], "type": "object" } } }, "description": "The codes" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Resolution and reason codes", "tags": [ "Visit exceptions" ] } }, "/api/v1/visit-exceptions/resolve": { "post": { "callbacks": {}, "description": "Acknowledges or dismisses up to 100 exceptions with one reason, each on its own, so one failing never undoes another. Only open exceptions of this agency are resolved; the rest, including one resolved elsewhere meanwhile, are skipped.", "operationId": "postVisitExceptionsResolve", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitExceptionBulkResolve" } } }, "description": "The exceptions and the resolution", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "failed_ids": { "description": "Not resolved because the write failed; retrying them is safe.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "type": "array" }, "resolved_ids": { "description": "Resolved now.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "type": "array" }, "skipped_ids": { "description": "Not open, or not this agency's: nothing was done to them.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "type": "array" } }, "required": [ "resolved_ids", "failed_ids", "skipped_ids" ], "title": "VisitExceptionBulkResult", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "What was resolved" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Resolve visit exceptions in bulk", "tags": [ "Visit exceptions" ] } }, "/api/v1/visit-exceptions/{id}": { "get": { "callbacks": {}, "description": "An EVV exception: a rule a visit broke, or (sandata_raised) an exception Sandata raised on it as the office recorded it; its resolution; and its Sandata acknowledgement state. A deleted visit's exceptions are kept as they are, as the exception queue keeps them. Exceptions are not deleted; only resetting a demo agency removes its records, all of them. ", "operationId": "getVisitExceptionsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/VisitException" } }, "required": [ "data" ], "type": "object" } } }, "description": "The visit exception" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no visit exception with that id in this agency, including another agency's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a visit exception", "tags": [ "Visit exceptions" ] } }, "/api/v1/visit-exceptions/{id}/assignment": { "post": { "callbacks": {}, "description": "Assigns the exception to a user of this agency, or unassigns it with null, as the exception page does (US-94.24). The last assignment wins; it takes no lock_version. A user of another agency answers 422 assignee_not_found; an exception of another agency 404. One changed by another write while this request ran answers 409 stale_record, and nothing is saved.", "operationId": "postVisitExceptionsByIdAssignment", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitExceptionAssignment" } } }, "description": "Who it is assigned to", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/VisitException" } }, "required": [ "data" ], "type": "object" } } }, "description": "The exception" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code assignee_not_found: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Assign a visit exception", "tags": [ "Visit exceptions" ] } }, "/api/v1/visit-exceptions/{id}/resolve": { "post": { "callbacks": {}, "description": "Resolves an open exception. Its acknowledgement is queued to Sandata only when it carries an ACK exception code Sandata raised (15 or 21); Sandata takes none for any other. An exception that is not open is 422 naming status; dismiss without resolution_notes is 422 naming resolution_notes; correct without both adjusted times is 422; correcting one whose visit was deleted is 422 visit_deleted. One changed by another write while this request ran answers 409 stale_record, and nothing is saved.", "operationId": "postVisitExceptionsByIdResolve", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitExceptionResolve" } } }, "description": "The resolution", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/VisitException" } }, "required": [ "data" ], "type": "object" } } }, "description": "The resolved exception" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code visit_deleted: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Resolve a visit exception", "tags": [ "Visit exceptions" ] } }, "/api/v1/visit-imports": { "post": { "callbacks": {}, "description": "Imports each row of a Sandata Detail Visit Status export as a read-only visit beside the agency's own (source import, import_system sandata), as Import Sandata visits does. A re-import of the same file adds nothing, and a row whose visit Sandata changed updates its imported visit; HCB's own visits are never changed. A row naming no client or caregiver of this agency, or several, or no call times, is not written and is listed by row number and reason; the rest of the file still imports. With dry_run true the answer is 200 with what the import would do, writing nothing; a file that cannot be read is 422 with the refusal's code (missing_columns, csv_parse_error, empty_file, too_many_rows, file_too_large). Without it the answer is 202 with the run, queued; GET /api/v1/visit-imports/{id} until it has ended, when such a file ends it failed.", "operationId": "postVisitImports", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "dry_run": { "description": "true: answer what the import would do (counts and unresolved rows) and write nothing. Left out or false: import.", "type": "boolean" }, "file": { "format": "binary", "type": "string" } }, "required": [ "file" ], "type": "object" } } }, "description": "A multipart form with Sandata's Detail Visit Status export (Reports, Detail Visit Status, exported as CSV) in the field `file`, at most 10 MB and 5000 rows, and optionally dry_run.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/VisitImportPreview" } }, "required": [ "data" ], "type": "object" } } }, "description": "dry_run true: what the import would do" }, "202": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/VisitImport" } }, "required": [ "data" ], "type": "object" } } }, "description": "The run, queued; GET /api/v1/visit-imports/{id} until it has ended" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Import Sandata's record of visits", "tags": [ "Visits" ] } }, "/api/v1/visit-imports/{id}": { "get": { "callbacks": {}, "description": "A run POST /api/v1/visit-imports started: pending or processing until its worker ends it, then completed, partial (some rows unresolved) or failed, with its counts and unresolved rows.", "operationId": "getVisitImportsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/VisitImport" } }, "required": [ "data" ], "type": "object" } } }, "description": "The run" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Read a Sandata visit import", "tags": [ "Visits" ] } }, "/api/v1/visits": { "get": { "callbacks": {}, "description": "An EVV visit: one caregiver's service to one client on one day, with its clocked, scheduled and adjusted times, its EVV attributes and its Sandata state. The agency's visits in service-date order, newest first, then scheduled start; deleted ones left out unless include_deleted=true. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getVisits", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records with this status.", "in": "query", "name": "status", "schema": { "enum": [ "scheduled", "in_progress", "completed", "verified", "submitted", "matched", "rejected", "cancelled" ], "type": "string" } }, { "description": "Only visits of this type.", "in": "query", "name": "visit_type", "schema": { "enum": [ "standard", "group", "live_in", "respite", "companion", "travel" ], "type": "string" } }, { "description": "Only visits in this Sandata queue state; not_queued is a visit not in the queue (never queued, or pulled before it was sent).", "in": "query", "name": "sandata_submission_status", "schema": { "enum": [ "pending", "submitted", "accepted", "rejected", "resubmitted", "not_queued" ], "type": "string" } }, { "description": "Only records of this client.", "in": "query", "name": "client_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only records of this caregiver.", "in": "query", "name": "caregiver_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only visits whose service date is on or after this date (YYYY-MM-DD).", "in": "query", "name": "service_date_from", "schema": { "format": "date", "type": "string" } }, { "description": "Only visits whose service date is on or before this date (YYYY-MM-DD).", "in": "query", "name": "service_date_to", "schema": { "format": "date", "type": "string" } }, { "description": "Only records changed at or after this instant (ISO 8601, with an offset), compared to the second. The list is then in change order: updated_at, then id.", "in": "query", "name": "updated_since", "schema": { "format": "date-time", "type": "string" } }, { "description": "With updated_since, a cursor: send the last record's updated_at as updated_since and its id as after_id to get the next page. Use this, not offset, to sync: an offset skips a record when an earlier one changes between two requests. The sync is at least once: timestamps are whole seconds and set before commit, so a record changed in the cursor's second, or committed late, can fall behind the cursor. Start each sync pass a minute before the newest updated_at you saw, and treat every record returned as current: apply it over what you hold. A record can change twice within one second, and not every change moves lock_version, so the same updated_at and lock_version do not mean the same content.", "in": "query", "name": "after_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "true also lists deleted records, with deleted_at set, so a sync learns of deletions.", "in": "query", "name": "include_deleted", "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/Visit" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "VisitPage", "type": "object" } } }, "description": "A page of visits" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List visits", "tags": [ "Visits" ] }, "post": { "callbacks": {}, "description": "Schedules a visit, as the web's visit form does, with source api. The client, caregiver and assignment must be this agency's (422 naming the field). A visit overlapping the caregiver's others is created, and warnings says so.", "operationId": "postVisits", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitCreate" } } }, "description": "The visit's fields", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitWriteResult" } } }, "description": "The created visit and its warnings" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a visit", "tags": [ "Visits" ] } }, "/api/v1/visits/bulk-cancel": { "post": { "callbacks": {}, "description": "Cancels up to 100 of the agency's visits, each on its own, so one failing never undoes another, as the visit list's bulk action does (US-94.24). An id that is not this agency's visit is failed as not_found; a visit imported from another EVV system (US-101.9) is read-only here and is failed as imported_visit. Visits carry a lock_version, but a bulk action takes none: each visit is moved as it is when the action reaches it. A cancel dismisses the visit's open exceptions; one it cannot dismiss is failed as exception_not_dismissed. cancellation_reason and cancellation_note, if sent, are kept on every visit cancelled (a note needs a reason: 422 validation_failed).", "operationId": "postVisitsBulkCancel", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitBulkTransition" } } }, "description": "The visits", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "failed": { "description": "Not moved: not_found (not this agency's visit), invalid_transition (its status cannot move there), exception_not_dismissed (a cancel whose open exception could not be dismissed), imported_visit (a visit imported from another EVV system, US-101.9, which is read-only here) or error (the write failed; retrying is safe).", "items": { "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reason": { "description": "Why.", "enum": [ "not_found", "invalid_transition", "exception_not_dismissed", "imported_visit", "error" ], "type": "string" } }, "required": [ "id", "reason" ], "type": "object" }, "type": "array" }, "succeeded_ids": { "description": "Moved now.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "type": "array" } }, "required": [ "succeeded_ids", "failed" ], "title": "VisitBulkTransitionResult", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "What was cancelled" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Cancel visits in bulk", "tags": [ "Visits" ] } }, "/api/v1/visits/bulk-verify": { "post": { "callbacks": {}, "description": "Verifies up to 100 of the agency's visits, each on its own, so one failing never undoes another, as the visit list's bulk action does (US-94.24). An id that is not this agency's visit is failed as not_found; a visit imported from another EVV system (US-101.9) is read-only here and is failed as imported_visit. Visits carry a lock_version, but a bulk action takes none: each visit is moved as it is when the action reaches it. Only a completed visit can be verified; one in another status is failed as invalid_transition.", "operationId": "postVisitsBulkVerify", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitBulkTransition" } } }, "description": "The visits", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "failed": { "description": "Not moved: not_found (not this agency's visit), invalid_transition (its status cannot move there), exception_not_dismissed (a cancel whose open exception could not be dismissed), imported_visit (a visit imported from another EVV system, US-101.9, which is read-only here) or error (the write failed; retrying is safe).", "items": { "properties": { "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "reason": { "description": "Why.", "enum": [ "not_found", "invalid_transition", "exception_not_dismissed", "imported_visit", "error" ], "type": "string" } }, "required": [ "id", "reason" ], "type": "object" }, "type": "array" }, "succeeded_ids": { "description": "Moved now.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "type": "array" } }, "required": [ "succeeded_ids", "failed" ], "title": "VisitBulkTransitionResult", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "What was verified" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Verify visits in bulk", "tags": [ "Visits" ] } }, "/api/v1/visits/{id}": { "delete": { "callbacks": {}, "description": "Soft-deletes the visit, as the web does (US-98.20): its open exceptions are dismissed and their Sandata acknowledgements queued (one that cannot be dismissed answers 422 exception_not_updated and nothing changes), and a visit Sandata holds is queued to go to Sandata as cancelled. lock_version is the one the visit was read with: a visit changed since answers 409 stale_record. A deleted visit answers 404. meta.exceptions_dismissed counts the open exceptions the delete dismissed. meta.links names what rested on the visit, which the delete leaves in place (warn, never block, US-98.32): timesheet_entries whose EVV times were pulled from it (the first 50 by date, with timesheet_entries_total) and unfrozen_months, the Work Order months its signature alone froze, read under the delete's lock. warnings says the same in words (US-116.18): visits.delete_keeps_entry_times and visits.delete_reopens_month.", "operationId": "deleteVisitsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "The lock_version the record was read with: missing answers 400, changed since 409 stale_record.", "in": "query", "name": "lock_version", "required": true, "schema": { "description": "The value the record was read with; a record changed since answers 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Visit" }, "meta": { "properties": { "exceptions_dismissed": { "minimum": 0, "type": "integer" }, "links": { "$ref": "#/components/schemas/VisitDeleteLinks" } }, "required": [ "exceptions_dismissed", "links" ], "type": "object" }, "warnings": { "description": "What the delete left resting on the visit, in words (US-116.18), beside meta.links; usually empty. Never a refusal: the visit is deleted. Each id is one of visits.delete_keeps_entry_times (one item for the timesheet entries whose EVV times came from it) and visits.delete_reopens_month (one per Work Order month its signature alone froze, open to edits again).", "items": { "properties": { "fix": { "description": "Where it is fixed, when a page fixes it.", "nullable": true, "properties": { "label": { "description": "What the link says.", "type": "string" }, "path": { "description": "The app route that fixes it.", "type": "string" } }, "required": [ "path", "label" ], "type": "object" }, "id": { "description": "The rule that raised it, stable, e.g. client_care.medicaid_id_pending.", "type": "string" }, "message": { "description": "For a person to read.", "type": "string" } }, "required": [ "id", "message" ], "title": "Warning", "type": "object" }, "type": "array" } }, "required": [ "data", "meta", "warnings" ], "title": "DeletedVisit", "type": "object" } } }, "description": "The deleted visit" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code exception_not_updated: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Delete a visit", "tags": [ "Visits" ] }, "get": { "callbacks": {}, "description": "An EVV visit: one caregiver's service to one client on one day, with its clocked, scheduled and adjusted times, its EVV attributes and its Sandata state. One visit also carries its clock calls, its changes with reason codes and who signed (never the signature image), the newest 200 of each. updated_since follows the visit's own fields; evidence added without changing them is read here.", "operationId": "getVisitsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/VisitDetail" } }, "required": [ "data" ], "type": "object" } } }, "description": "The visit" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no visit with that id in this agency, including another agency's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a visit", "tags": [ "Visits" ] }, "patch": { "callbacks": {}, "description": "Sets only the fields sent: the scheduled and adjusted times and the EVV attributes; the status moves only through /transitions. lock_version is required, and a visit changed since answers 409 stale_record. A change to adjusted_start_time or adjusted_end_time is recorded with reason_code and reason_memo, as Colorado requires; with no reason_code it is saved as OTHER and warnings says so; moving the visit (its date, times, type or group) onto another of the caregiver's visits is saved with an overlapping_visit warning. Editing what Sandata receives on a visit Sandata holds queues it to be sent again.", "operationId": "patchVisitsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitUpdate" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitWriteResult" } } }, "description": "The updated visit and its warnings" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a visit", "tags": [ "Visits" ] } }, "/api/v1/visits/{id}/reassign": { "post": { "callbacks": {}, "description": "Gives the visit to caregiver_id, as the web's Reassign does (US-98.33), whether or not it was clocked into. The clock calls on it by anyone else stay on the visit as history (superseded_at set) and no longer count: the actual times, the status of a visit not yet verified (none counting: scheduled) and the billable hours come from the calls left, so the new caregiver clocks in on their own. A visit Sandata holds is queued to be sent again. caregiver_id must be this agency's (422 caregiver_not_found); lock_version is required (409 stale_record). warnings names the calls superseded, a caregiver who is not active, and an overlap with the new caregiver's other visits.", "operationId": "postVisitsByIdReassign", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitReassign" } } }, "description": "The caregiver", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitWriteResult" } } }, "description": "The visit and its warnings" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code caregiver_not_found: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Hand a visit to another caregiver", "tags": [ "Visits" ] } }, "/api/v1/visits/{id}/sandata-exceptions": { "delete": { "callbacks": {}, "description": "Withdraws a wrong code recorded on the visit as raised by Sandata (US-98.29): the exception stays, with status withdrawn and a moved updated_at, leaves the acknowledgement queue, and the right code can then be recorded. Allowed while its acknowledgement is pending, failed or held; one already sent (submitted or accepted) is 422 already_sent. A visit with no code recorded, deleted or foreign, is 404.", "operationId": "deleteVisitsByIdSandataExceptions", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/VisitException" } }, "required": [ "data" ], "type": "object" } } }, "description": "The withdrawn exception" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code already_sent: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Withdraw the exception code recorded as raised by Sandata", "tags": [ "Visit exceptions" ] }, "post": { "callbacks": {}, "description": "Records the ACK exception Sandata raised on a visit it took (15 Unmatched Client ID / Phone or 21 No Show Exception, read off Sandata's Aggregator) as a sandata_raised exception, and queues its acknowledgement to Sandata. At most one per visit. A visit Sandata has not taken is 422 not_sent; a second record on the visit is 422 already_recorded; a deleted or foreign visit is 404.", "operationId": "postVisitsByIdSandataExceptions", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitSandataException" } } }, "description": "The exception Sandata raised", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/VisitException" } }, "required": [ "data" ], "type": "object" } } }, "description": "The recorded exception" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes already_recorded, not_sent: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Record the exception Sandata raised on a visit", "tags": [ "Visit exceptions" ] } }, "/api/v1/visits/{id}/transitions": { "post": { "callbacks": {}, "description": "Moves the visit to status, as the web's status buttons do: verifying queues it for Sandata, cancelling one Sandata holds queues the cancellation, and a cancelled visit can be reopened. Cancelling dismisses the visit's open exceptions (no Sandata acknowledgement is queued for them) and reopening opens again the ones the cancel dismissed; one that cannot be updated answers 422 exception_not_updated and nothing changes. lock_version is required (409 stale_record). A move the visit cannot take answers 422 invalid_transition naming the statuses it can move to; a missing status is 400. A cancel may carry cancellation_reason (the web's pick list) and cancellation_note, kept on the visit and shown in its history; a note without a reason is 422 validation_failed.", "operationId": "postVisitsByIdTransitions", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitTransition" } } }, "description": "The status", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Visit" } }, "required": [ "data" ], "type": "object" } } }, "description": "The visit" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Bad Request, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes exception_not_updated, invalid_transition, validation_failed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Move a visit's status", "tags": [ "Visits" ] } }, "/api/v1/webhook-deliveries/{id}/resend": { "post": { "callbacks": {}, "description": "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).", "operationId": "postWebhookDeliveriesByIdResend", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "attempts": { "description": "Attempts so far.", "type": "integer" }, "created_at": { "description": "When the event was queued (UTC).", "format": "date-time", "type": "string" }, "delivered_at": { "description": "When it was delivered (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "endpoint_id": { "description": "The endpoint it went to.", "format": "uuid", "type": "string" }, "event_id": { "description": "The event's id, the same on every attempt.", "format": "uuid", "type": "string" }, "event_type": { "description": "The event type.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_error": { "description": "The last failure.", "nullable": true, "type": "string" }, "last_status_code": { "description": "The last HTTP status the endpoint answered.", "nullable": true, "type": "integer" }, "status": { "description": "Where it stands.", "enum": [ "pending", "delivered", "failed" ], "type": "string" } }, "required": [ "id", "endpoint_id", "event_type", "status" ], "title": "WebhookDelivery", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The delivery" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code in_flight: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Send a delivery again", "tags": [ "Agency administration" ] } }, "/api/v1/webhook-endpoints": { "get": { "callbacks": {}, "description": "Newest first; never a signing secret. Needs Agency settings → View (403 forbidden otherwise).", "operationId": "getWebhookEndpoints", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "active": { "description": "Whether events are sent.", "type": "boolean" }, "created_at": { "description": "When it was registered (UTC).", "format": "date-time", "type": "string" }, "events": { "description": "Event types sent.", "items": { "type": "string" }, "type": "array" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "url": { "description": "Where events are posted.", "nullable": true, "type": "string" } }, "required": [ "id", "url", "events", "active" ], "title": "WebhookEndpoint", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "WebhookEndpointPage", "type": "object" } } }, "description": "A page of endpoints" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List the agency's webhook endpoints", "tags": [ "Agency administration" ] }, "post": { "callbacks": {}, "description": "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.", "operationId": "postWebhookEndpoints", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "events": { "description": "Event types to send.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "An https URL.", "type": "string" } }, "required": [ "url", "events" ], "title": "WebhookEndpointCreate", "type": "object" } } }, "description": "The endpoint", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "active": { "description": "Whether events are sent.", "type": "boolean" }, "created_at": { "description": "When it was registered (UTC).", "format": "date-time", "type": "string" }, "events": { "description": "Event types sent.", "items": { "type": "string" }, "type": "array" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "url": { "description": "Where events are posted.", "nullable": true, "type": "string" } }, "required": [ "id", "url", "events", "active" ], "title": "WebhookEndpoint", "type": "object" }, "secret": { "description": "The signing secret, shown this once.", "nullable": true, "type": "string" } }, "required": [ "data", "secret" ], "title": "WebhookEndpointCreated", "type": "object" } } }, "description": "The endpoint and its secret, once" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code web_only: Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Register a webhook endpoint", "tags": [ "Agency administration" ] } }, "/api/v1/webhook-endpoints/{id}": { "delete": { "callbacks": {}, "description": "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.", "operationId": "deleteWebhookEndpointsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "active": { "description": "Whether events are sent.", "type": "boolean" }, "created_at": { "description": "When it was registered (UTC).", "format": "date-time", "type": "string" }, "events": { "description": "Event types sent.", "items": { "type": "string" }, "type": "array" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "url": { "description": "Where events are posted.", "nullable": true, "type": "string" } }, "required": [ "id", "url", "events", "active" ], "title": "WebhookEndpoint", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code web_only: Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Remove a webhook endpoint", "tags": [ "Agency administration" ] }, "patch": { "callbacks": {}, "description": "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.", "operationId": "patchWebhookEndpointsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "active": { "description": "Whether events are sent.", "type": "boolean" }, "events": { "description": "Event types to send.", "items": { "type": "string" }, "type": "array" } }, "title": "WebhookEndpointUpdate", "type": "object" } } }, "description": "What to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "active": { "description": "Whether events are sent.", "type": "boolean" }, "created_at": { "description": "When it was registered (UTC).", "format": "date-time", "type": "string" }, "events": { "description": "Event types sent.", "items": { "type": "string" }, "type": "array" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "url": { "description": "Where events are posted.", "nullable": true, "type": "string" } }, "required": [ "id", "url", "events", "active" ], "title": "WebhookEndpoint", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The endpoint" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code web_only: Forbidden, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a webhook endpoint", "tags": [ "Agency administration" ] } }, "/api/v1/webhook-endpoints/{id}/deliveries": { "get": { "callbacks": {}, "description": "Newest first, as the delivery log shows them, without payloads. An endpoint of another agency answers 404. Needs Agency settings → View (403 forbidden otherwise).", "operationId": "getWebhookEndpointsByIdDeliveries", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "properties": { "attempts": { "description": "Attempts so far.", "type": "integer" }, "created_at": { "description": "When the event was queued (UTC).", "format": "date-time", "type": "string" }, "delivered_at": { "description": "When it was delivered (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "endpoint_id": { "description": "The endpoint it went to.", "format": "uuid", "type": "string" }, "event_id": { "description": "The event's id, the same on every attempt.", "format": "uuid", "type": "string" }, "event_type": { "description": "The event type.", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "last_error": { "description": "The last failure.", "nullable": true, "type": "string" }, "last_status_code": { "description": "The last HTTP status the endpoint answered.", "nullable": true, "type": "integer" }, "status": { "description": "Where it stands.", "enum": [ "pending", "delivered", "failed" ], "type": "string" } }, "required": [ "id", "endpoint_id", "event_type", "status" ], "title": "WebhookDelivery", "type": "object" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "WebhookDeliveryPage", "type": "object" } } }, "description": "A page of deliveries" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List an endpoint's deliveries", "tags": [ "Agency administration" ] } }, "/api/v1/work-orders": { "get": { "callbacks": {}, "description": "What was ordered for one client, caregiver and month. The agency's work orders in month order, newest month first, archived ones left out. With updated_since the order is change order, for a sync that pages with after_id.", "operationId": "getWorkOrders", "parameters": [ { "description": "Rows per page (default 100, at most 200; a larger value is served as 200).", "in": "query", "name": "limit", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows to skip.", "in": "query", "name": "offset", "schema": { "maximum": 1000000, "minimum": 0, "type": "integer" } }, { "description": "Only records with this status.", "in": "query", "name": "status", "schema": { "enum": [ "in_progress", "completed" ], "type": "string" } }, { "description": "Only records of this client.", "in": "query", "name": "client_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only records of this caregiver.", "in": "query", "name": "caregiver_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only records changed at or after this instant (ISO 8601, with an offset), compared to the second. The list is then in change order: updated_at, then id.", "in": "query", "name": "updated_since", "schema": { "format": "date-time", "type": "string" } }, { "description": "With updated_since, a cursor: send the last record's updated_at as updated_since and its id as after_id to get the next page. Use this, not offset, to sync: an offset skips a record when an earlier one changes between two requests. The sync is at least once: timestamps are whole seconds and set before commit, so a record changed in the cursor's second, or committed late, can fall behind the cursor. Start each sync pass a minute before the newest updated_at you saw, and treat every record returned as current: apply it over what you hold. A record can change twice within one second, and not every change moves lock_version, so the same updated_at and lock_version do not mean the same content.", "in": "query", "name": "after_id", "schema": { "format": "uuid", "type": "string" } }, { "description": "Only Work Orders of this type.", "in": "query", "name": "wo_type", "schema": { "enum": [ "standard", "temporary", "extra" ], "type": "string" } }, { "description": "Only Work Orders whose end date (expires_on) falls within this many days of today, and not closed before today.", "in": "query", "name": "expires_within_days", "schema": { "maximum": 365, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "One page of a list. The total counts every matching record under the same filters, so a client can tell the whole list from the first page.", "properties": { "data": { "items": { "$ref": "#/components/schemas/WorkOrder" }, "type": "array" }, "limit": { "description": "Rows asked for (default 100); a larger request is served 200.", "maximum": 200, "minimum": 1, "type": "integer" }, "offset": { "description": "Rows skipped.", "maximum": 1000000, "minimum": 0, "type": "integer" }, "total": { "description": "Every matching row.", "minimum": 0, "type": "integer" } }, "required": [ "data", "limit", "offset", "total" ], "title": "Work orderPage", "type": "object" } } }, "description": "A page of work orders" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code bad_request: a malformed limit, offset, search, updated_since, after_id or filter, named in the message." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "List work orders", "tags": [ "Work orders" ] }, "post": { "callbacks": {}, "operationId": "postWorkOrders", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkOrderCreate" } } }, "description": "The work order's fields", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/WorkOrder" } }, "required": [ "data" ], "type": "object" } } }, "description": "The created work order" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Create a work order", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}": { "get": { "callbacks": {}, "description": "What was ordered for one client, caregiver and month.", "operationId": "getWorkOrdersById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/WorkOrder" } }, "required": [ "data" ], "type": "object" } } }, "description": "The work order" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no work order with that id in this agency, including another agency's." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a work order", "tags": [ "Work orders" ] }, "patch": { "callbacks": {}, "description": "Sets only the fields sent. lock_version is required: send the value you read, and a record changed since answers 409 stale_record. A completed or archived work order is not edited through the API: any PATCH to one answers 422 not_editable.", "operationId": "patchWorkOrdersById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkOrderUpdate" } } }, "description": "The fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/WorkOrder" } }, "required": [ "data" ], "type": "object" } } }, "description": "The updated work order" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_found: no work order with that id in this agency, including another agency's." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: the work order changed since the lock_version sent was read, or while this request ran. Nothing was saved; read it again and retry." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code validation_failed: a field was refused; details names each field and why. Nothing was saved." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Update a work order", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/archive": { "post": { "callbacks": {}, "description": "Archives it, in any status, as the page does. lock_version is the one the Work Order was read with: a Work Order changed since answers 409 stale_record.", "operationId": "postWorkOrdersByIdArchive", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": [ "lock_version" ], "type": "object" } } }, "description": "Its lock_version", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/WorkOrder" } }, "required": [ "data" ], "type": "object" } } }, "description": "The Work Order" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Archive a Work Order", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/change-caregiver": { "post": { "callbacks": {}, "description": "As the page's Change caregiver does: from the Effective Date or earlier, a copy for caregiver_id with the same schedule, tasks and Care Instructions takes its place and this Work Order is archived (a month a timesheet or signature froze keeps its row); from a later date, this Work Order closes the day before and the copy starts on from. It needs work_orders.manage (403 forbidden). The same caregiver answers 422 same_caregiver, an archived Work Order 422 work_order_archived, a caregiver not of this agency 422 validation_failed. lock_version is the one the Work Order was read with: a Work Order changed since answers 409 stale_record. Answers the new Work Order's first month and the warnings the change found. Saved at once: send an Idempotency-Key so a retry makes no second copy.", "operationId": "postWorkOrdersByIdChangeCaregiver", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "caregiver_id": { "description": "The caregiver who takes over.", "format": "uuid", "type": "string" }, "from": { "description": "The first day the new caregiver works it, YYYY-MM-DD. On or before the Effective Date the whole Work Order moves and this one is archived; later, this one closes the day before.", "format": "date", "nullable": true, "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": [ "caregiver_id", "from", "lock_version" ], "title": "WorkOrderChangeCaregiver", "type": "object" } } }, "description": "The caregiver, the start date and lock_version", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/WorkOrder" }, "warnings": { "description": "What the change found (an overlap, a month kept); never holds it.", "items": { "properties": { "kind": { "description": "What was found.", "type": "string" }, "message": { "description": "The page's words for it.", "type": "string" } }, "required": [ "kind", "message" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The new Work Order" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes same_caregiver, validation_failed, work_order_archived: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Give a Work Order to another caregiver", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/close-document": { "post": { "callbacks": {}, "description": "Snapshots a completed Work Order's hours, billing and close details. An in-progress one answers 422 not_completed; one that has a close document 422 close_document_exists.", "operationId": "postWorkOrdersByIdCloseDocument", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CloseDocument" } }, "required": [ "data" ], "type": "object" } } }, "description": "The close document" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes close_document_exists, not_completed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Generate a Work Order's close document", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/days/{date}": { "put": { "callbacks": {}, "description": "shaded false marks the date not worked, clearing its visits and marks; true marks it worked again from the plan, as the timesheet page does. A date with recorded work answers 422 recorded_work naming it unless confirm is true; a frozen month 422 frozen; a date changed since seen 409 stale_record.", "operationId": "putWorkOrdersByIdDaysByDate", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "", "in": "path", "name": "date", "required": true, "schema": { "format": "date", "nullable": true, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "confirm": { "description": "Optional: mark a date with recorded work not worked.", "type": "boolean" }, "seen": { "description": "The date's value from seen_by_date on GET /api/v1/work-orders/{id} (the get_work_order tool answers it too), to refuse a date changed since that read.", "nullable": true, "type": "string" }, "shaded": { "description": "true worked, false not worked.", "type": "boolean" } }, "required": [ "shaded" ], "title": "WorkOrderDayChange", "type": "object" } } }, "description": "The change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/WorkOrder" } }, "required": [ "data" ], "type": "object" } } }, "description": "The Work Order" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code recorded_work: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Mark a date of a Work Order's month worked or not", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/dismiss-guidance": { "post": { "callbacks": {}, "operationId": "postWorkOrdersByIdDismissGuidance", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/WorkOrder" } }, "required": [ "data" ], "type": "object" } } }, "description": "The Work Order" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Dismiss a Work Order's Getting Started guidance", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/dismiss-warnings": { "post": { "callbacks": {}, "description": "Clears the warnings generating it found, as the page does once they are read. lock_version is the one the Work Order was read with: a Work Order changed since answers 409 stale_record.", "operationId": "postWorkOrdersByIdDismissWarnings", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": [ "lock_version" ], "type": "object" } } }, "description": "Its lock_version", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/WorkOrder" } }, "required": [ "data" ], "type": "object" } } }, "description": "The Work Order" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Dismiss a Work Order's generation warnings", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/duplicate": { "post": { "callbacks": {}, "description": "Two forms. Without mode: copies it into the month after it, or into month and year when both are sent, with its tasks and weekly pattern; a live Work Order already holding that month's slot answers 409 slot_taken naming its WO #. With mode (US-102.35): makes a new standing Work Order from this one, with the next WO #, as the page's Duplicate does: keep_both, close_previous (this Work Order is closed at closing_date in the same write; it needs the lock_version the Work Order was read with, and one changed since answers 409 stale_record) or temporary, for client_id and caregiver_id when sent. Every form needs work_orders.manage (403 forbidden). A choice the page refuses (a missing date, a Closing Date before this Work Order's Effective Date) answers 422 duplicate_refused in its words, a close of an archived Work Order 422 work_order_archived, a client or caregiver not of this agency 422 validation_failed. A field another mode takes is 400. Answers the copy's first month and the warnings the copy and the close found. Saved at once: send an Idempotency-Key so a retry makes no second copy. Mixing the two forms' fields is 400.", "operationId": "postWorkOrdersByIdDuplicate", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "caregiver_id": { "description": "With mode: the copy's caregiver, this agency's; this Work Order's when not sent.", "format": "uuid", "type": "string" }, "client_id": { "description": "With mode: the copy's client, this agency's; this Work Order's when not sent.", "format": "uuid", "type": "string" }, "closing_date": { "description": "close_previous: this Work Order's Closing Date; the day before effective_date when not sent, as the page's dialog fills it in. Refused before this Work Order's own Effective Date.", "format": "date", "type": "string" }, "effective_date": { "description": "keep_both and close_previous, which need it: the copy's Effective Date.", "format": "date", "type": "string" }, "lock_version": { "description": "With mode: the lock_version this Work Order was read with. close_previous needs it, since it closes this Work Order: one changed since answers 409 stale_record, as a second close from the page is refused. Checked when sent with the other modes.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "mode": { "description": "Makes a new standing Work Order as the page's Duplicate does: keep_both keeps this one as it is; close_previous closes it at closing_date; temporary makes a copy that runs temporary_from to temporary_to. Not with month or year.", "enum": [ "keep_both", "close_previous", "temporary" ], "type": "string" }, "month": { "description": "Target month; send with year.", "maximum": 12, "minimum": 1, "type": "integer" }, "temporary_from": { "description": "temporary, which needs it: the copy's first day.", "format": "date", "type": "string" }, "temporary_to": { "description": "temporary, which needs it: the copy's last day.", "format": "date", "type": "string" }, "year": { "description": "Target year; send with month.", "maximum": 2100, "minimum": 2020, "type": "integer" } }, "title": "WorkOrderDuplicate", "type": "object" } } }, "description": "The target month, or the mode and its dates", "required": false }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/WorkOrder" }, "warnings": { "description": "With mode: what the copy and the close found (an overlap with another of the caregiver's Work Orders, a month kept), which never holds the copy.", "items": { "properties": { "kind": { "description": "What was found.", "type": "string" }, "message": { "description": "The page's words for it.", "type": "string" } }, "required": [ "kind", "message" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The new Work Order" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Bad Request, as the operation's description says." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes slot_taken, stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes duplicate_refused, validation_failed, work_order_archived: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Duplicate a Work Order", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/fill-from-care-logs": { "post": { "callbacks": {}, "deprecated": true, "description": "Deprecated (US-118.17): writes nothing. A Work Order's delivered days now come straight from its care logs, so there is nothing to fill or keep in step. Answers the dates of the month the assembled month has a delivery on, in unchanged, with filled, updated, differences and flagged empty, and leaves lock_version as sent, so a retry at the same version answers the same. A Work Order that is not in progress still answers 422 not_editable. lock_version is the one the Work Order was read with: a Work Order changed since answers 409 stale_record. Deprecated on 2026-11-16; from 00:00 UTC on 2027-05-16 it answers 410 Gone. See /developers/changelog.", "operationId": "postWorkOrdersByIdFillFromCareLogs", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": [ "lock_version" ], "type": "object" } } }, "description": "Its lock_version", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "differences": { "description": "Always empty: the fill writes nothing (US-118.17).", "items": { "properties": { "date": { "format": "date", "type": "string" }, "reason": { "type": "string" } }, "type": "object" }, "type": "array" }, "filled": { "description": "Always empty: the fill writes nothing (US-118.17).", "items": { "format": "date", "type": "string" }, "type": "array" }, "flagged": { "description": "Always empty: the fill writes nothing (US-118.17).", "items": { "properties": { "date": { "format": "date", "type": "string" }, "reason": { "type": "string" } }, "type": "object" }, "type": "array" }, "unchanged": { "description": "Every date of the month with a delivery (a live care log the Work Order holds), each once, in order.", "items": { "format": "date", "type": "string" }, "type": "array" }, "updated": { "description": "Always empty: the fill writes nothing (US-118.17).", "items": { "format": "date", "type": "string" }, "type": "array" } }, "required": [ "filled", "updated", "unchanged", "differences", "flagged" ], "title": "WorkOrderCareLogFill", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The delivered days" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Gone, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_editable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Deprecated: list a Work Order's delivered days (formerly Fill from care logs)", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/fill-from-evv": { "post": { "callbacks": {}, "deprecated": true, "description": "Deprecated (US-118.17): writes nothing. A Work Order's delivered days now come straight from its care logs, so there is nothing to fill or keep in step. Answers the dates of the month the assembled month has a delivery on, in unchanged, with filled, updated, differences and flagged empty, and leaves lock_version as sent, so a retry at the same version answers the same. A Work Order that is not in progress still answers 422 not_editable. lock_version is the one the Work Order was read with: a Work Order changed since answers 409 stale_record. Deprecated on 2026-11-16; from 00:00 UTC on 2027-05-16 it answers 410 Gone. See /developers/changelog.", "operationId": "postWorkOrdersByIdFillFromEvv", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": [ "lock_version" ], "type": "object" } } }, "description": "Its lock_version", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "differences": { "description": "Always empty: the fill writes nothing (US-118.17).", "items": { "properties": { "date": { "format": "date", "type": "string" }, "entry_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "entry_time_in": { "description": "HH:MM:SS, Mountain.", "nullable": true, "type": "string" }, "entry_time_out": { "description": "HH:MM:SS, Mountain.", "nullable": true, "type": "string" }, "visit_clock_in": { "description": "The visit's clock-in (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "visit_clock_out": { "description": "The visit's clock-out (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "visit_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "type": "object" }, "type": "array" }, "filled": { "description": "Always empty: the fill writes nothing (US-118.17).", "items": { "format": "date", "type": "string" }, "type": "array" }, "flagged": { "description": "Always empty: the fill writes nothing (US-118.17).", "items": { "properties": { "date": { "format": "date", "type": "string" }, "reason": { "type": "string" } }, "type": "object" }, "type": "array" }, "unchanged": { "description": "Every date of the month with a delivery (a live care log the Work Order holds), each once, in order.", "items": { "format": "date", "type": "string" }, "type": "array" }, "updated": { "description": "Always empty: the fill writes nothing (US-118.17).", "items": { "format": "date", "type": "string" }, "type": "array" } }, "required": [ "filled", "updated", "unchanged", "differences", "flagged" ], "title": "WorkOrderEvvFill", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The delivered days" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Gone, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_editable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Deprecated: list a Work Order's delivered days (formerly Fill from EVV)", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/monthly-report": { "get": { "callbacks": {}, "description": "The report the Work Order month holds, as the report page shows it: answers, how it was taken, and its signing state. A Work Order with no report yet, or of another agency, is 404.", "operationId": "getWorkOrdersByIdMonthlyReport", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MonthlyClientReport" } }, "required": [ "data" ], "type": "object" } } }, "description": "The report" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Get a Work Order month's monthly report", "tags": [ "Monthly client reports" ] }, "post": { "callbacks": {}, "description": "Creates the month's report (201) or updates the one it holds (200): answers, comments and how it was taken. A signed report is 409 record_locked: it is corrected with an addendum, or voided and started again as a new draft. A report the client signed before the electronic record is 422 client_signed. A Work Order of another agency is 404.", "operationId": "postWorkOrdersByIdMonthlyReport", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonthlyClientReportInput" } } }, "description": "What to save", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MonthlyClientReport" } }, "required": [ "data" ], "type": "object" } } }, "description": "The updated report" }, "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MonthlyClientReport" } }, "required": [ "data" ], "type": "object" } } }, "description": "The created report" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code record_locked: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code client_signed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Save a Work Order month's monthly report", "tags": [ "Monthly client reports" ] } }, "/api/v1/work-orders/{id}/monthly-report/signatures": { "post": { "callbacks": {}, "description": "Records the office attestation of the month's saved report, typed as the credential's user: the staff member who conducted a phone or video check-in. The first signature locks the report. A line already signed answers 422 already_signed; a report another request changed while this one ran answers 409 stale_record; a voided one 409 voided. A Work Order with no report, or of another agency, is 404. 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.", "operationId": "postWorkOrdersByIdMonthlyReportSignatures", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "signer": { "description": "Whose line to sign: office, the staff member who conducted a phone or video check-in, signed as you. The client's line is drawn on the device in the app.", "enum": [ "office" ], "type": "string" } }, "required": [ "signer" ], "title": "MonthlyClientReportSignature", "type": "object" } } }, "description": "The signature", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MonthlyClientReport" } }, "required": [ "data" ], "type": "object" } } }, "description": "The report" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code signature_requires_person: Forbidden, as the operation's description says." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Not Found, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code already_signed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Sign a Work Order month's monthly report", "tags": [ "Monthly client reports" ] } }, "/api/v1/work-orders/{id}/paper-signatures": { "post": { "callbacks": {}, "description": "Marks the paper Time & Services card collected, or unmarks it when it was, as the page's toggle does. lock_version is the one the Work Order was read with: a Work Order changed since answers 409 stale_record.", "operationId": "postWorkOrdersByIdPaperSignatures", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": [ "lock_version" ], "type": "object" } } }, "description": "Its lock_version", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/WorkOrder" } }, "required": [ "data" ], "type": "object" } } }, "description": "The Work Order" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Flip a Work Order's paper-signatures mark", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/plan": { "get": { "callbacks": {}, "description": "The plan in force today of the Work Order this month row belongs to, as the Work Order page shows its grid: each weekday's visits and each task line with its minutes and per-weekday counts. lock_version is what a change sends back.", "operationId": "getWorkOrdersByIdPlan", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "lines": { "items": { "properties": { "minutes": { "description": "Minutes each time (the line's Min/Task).", "nullable": true, "type": "integer" }, "notes": { "description": "The line's notes.", "nullable": true, "type": "string" }, "task_definition_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "weekday_counts": { "description": "Times on each weekday, Monday first.", "items": { "maximum": 24, "minimum": 0, "type": "integer" }, "maxItems": 7, "minItems": 7, "type": "array" } }, "required": [ "task_definition_id" ], "type": "object" }, "type": "array" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "slot_days": { "additionalProperties": { "items": { "properties": { "time_in": { "description": "HH:MM:SS, Mountain.", "nullable": true, "type": "string" }, "time_out": { "description": "HH:MM:SS, Mountain.", "nullable": true, "type": "string" }, "time_out_computed": { "description": "Whether its Time Out was worked out from the day's tasks.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "description": "Weekday, 1 (Monday) to 7, to its visits in order.", "type": "object" }, "work_order_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "required": [ "work_order_id", "lock_version", "slot_days", "lines" ], "title": "WorkOrderPlan", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The plan" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "A Work Order's weekly plan", "tags": [ "Work orders" ] }, "patch": { "callbacks": {}, "description": "Writes the weekdays and lines sent into the plan in force today, as the Work Order page saves its grid, then lays the change onto every open month. A weekday sent replaces that day's visits ([] clears it); a line sent replaces that task's line; drop_lines removes lines. lock_version is the plan's as read: a plan changed since answers 409 stale_record, unless it already holds what is sent, which answers 200 with nothing written. A task definition that is not the agency's answers 422 unknown_task_definition. frozen_months names months that keep their schedule (a returned timesheet, a sent claim).", "operationId": "patchWorkOrdersByIdPlan", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "drop_lines": { "description": "Task definition ids whose lines to remove.", "items": { "description": "The record's id.", "format": "uuid", "type": "string" }, "type": "array" }, "lines": { "description": "Task lines: task_definition_id, minutes, weekday_counts (seven, Monday first), notes.", "items": { "properties": { "minutes": { "description": "Minutes each time (the line's Min/Task).", "nullable": true, "type": "integer" }, "notes": { "description": "The line's notes.", "nullable": true, "type": "string" }, "task_definition_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "weekday_counts": { "description": "Times on each weekday, Monday first.", "items": { "maximum": 24, "minimum": 0, "type": "integer" }, "maxItems": 7, "minItems": 7, "type": "array" } }, "required": [ "task_definition_id" ], "type": "object" }, "type": "array" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "slot_days": { "additionalProperties": { "items": { "properties": { "time_in": { "description": "HH:MM:SS, Mountain.", "nullable": true, "type": "string" }, "time_out": { "description": "HH:MM:SS, Mountain.", "nullable": true, "type": "string" }, "time_out_computed": { "description": "Whether its Time Out was worked out from the day's tasks.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "description": "Weekday 1 (Monday) to 7 => its visits, each time_in and time_out (HH:MM:SS); [] clears the day.", "type": "object" } }, "required": [ "lock_version" ], "title": "WorkOrderPlanUpdate", "type": "object" } } }, "description": "The days and lines to write", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "lines": { "items": { "properties": { "minutes": { "description": "Minutes each time (the line's Min/Task).", "nullable": true, "type": "integer" }, "notes": { "description": "The line's notes.", "nullable": true, "type": "string" }, "task_definition_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "weekday_counts": { "description": "Times on each weekday, Monday first.", "items": { "maximum": 24, "minimum": 0, "type": "integer" }, "maxItems": 7, "minItems": 7, "type": "array" } }, "required": [ "task_definition_id" ], "type": "object" }, "type": "array" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "slot_days": { "additionalProperties": { "items": { "properties": { "time_in": { "description": "HH:MM:SS, Mountain.", "nullable": true, "type": "string" }, "time_out": { "description": "HH:MM:SS, Mountain.", "nullable": true, "type": "string" }, "time_out_computed": { "description": "Whether its Time Out was worked out from the day's tasks.", "type": "boolean" } }, "type": "object" }, "type": "array" }, "description": "Weekday, 1 (Monday) to 7, to its visits in order.", "type": "object" }, "work_order_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "required": [ "work_order_id", "lock_version", "slot_days", "lines" ], "title": "WorkOrderPlan", "type": "object" }, "frozen_months": { "items": { "type": "object" }, "type": "array" }, "warnings": { "items": { "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The plan as saved" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code unknown_task_definition: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a Work Order's weekly plan", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/reopen": { "post": { "callbacks": {}, "description": "Moves a completed Work Order back to in progress, clearing its close details, as the page does. An in-progress one answers 422 not_completed; a replacement holding its slot 409 slot_taken. lock_version is the one the Work Order was read with: a Work Order changed since answers 409 stale_record.", "operationId": "postWorkOrdersByIdReopen", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": [ "lock_version" ], "type": "object" } } }, "description": "Its lock_version", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/WorkOrder" } }, "required": [ "data" ], "type": "object" } } }, "description": "The Work Order" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes slot_taken, stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_completed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Reopen a completed Work Order", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/signatures": { "post": { "callbacks": {}, "description": "Records one signature (client, provider, supervisor_designee or supervisor) on a completed Work Order, dated date or today, as the page's signature pad does. An in-progress one answers 422 not_completed. lock_version is the one the Work Order was read with: a Work Order changed since answers 409 stale_record. 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.", "operationId": "postWorkOrdersByIdSignatures", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "date": { "description": "The signature date, YYYY-MM-DD: today when left out or null.", "format": "date", "nullable": true, "type": "string" }, "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "signature": { "description": "The signature as the pad saves it: a base64 PNG of at most 50 KB, with or without a data:image/png;base64, prefix.", "type": "string" }, "signature_type": { "description": "Whose signature.", "enum": [ "client", "provider", "supervisor", "supervisor_designee" ], "type": "string" } }, "required": [ "signature_type", "signature", "lock_version" ], "title": "WorkOrderSign", "type": "object" } } }, "description": "The signature", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/WorkOrder" } }, "required": [ "data" ], "type": "object" } } }, "description": "The Work Order" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code signature_requires_person: Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code not_completed: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Sign a Work Order", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/tasks/{task_definition_id}/days/{date}": { "put": { "callbacks": {}, "description": "Records what the caregiver says about a task on one date, as the caregiver app does, on that day's care log (the Work Order's client, caregiver, service and shift; drafted when the day has none): true done, false not done, null clears the mark. The answer is the care log's mark. Needs timesheets.manage (403 forbidden otherwise). A day on a submitted, approved or exported Returned Timesheet answers 409 frozen; a signed care log 409 record_locked; a completed or archived Work Order 422 not_editable; a date outside its month 422 date_out_of_range.", "operationId": "putWorkOrdersByIdTasksByTaskDefinitionIdDaysByDate", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "", "in": "path", "name": "task_definition_id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } }, { "description": "", "in": "path", "name": "date", "required": true, "schema": { "format": "date", "nullable": true, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "completed": { "description": "true done, false not done, null untouched.", "nullable": true, "type": "boolean" } }, "required": [ "completed" ], "title": "WorkOrderTaskToggle", "type": "object" } } }, "description": "The mark", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "completed": { "nullable": true, "type": "boolean" }, "count": { "description": "Times that day.", "nullable": true, "type": "integer" }, "date": { "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "notes": { "nullable": true, "type": "string" }, "task_definition_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "warnings": { "description": "Dismissible warnings the day's care log raised on this write (a weekly or daily limit, a day a submitted Returned Timesheet missed), each with code and message. Absent for a combined Work Order.", "items": { "properties": { "code": { "nullable": true, "type": "string" }, "message": { "nullable": true, "type": "string" }, "task_definition_id": { "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "work_order_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "title": "WorkOrderTaskMark", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The task's mark" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code record_locked: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes date_out_of_range, not_editable: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Mark a task done, not done or untouched on a date", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/timesheet": { "post": { "callbacks": {}, "description": "Writes the timesheet of a completed Work Order from its days and tasks, as the Work Order page's Generate timesheet does. One that is not completed answers 422 work_order_not_ready, one with no hours 422 hours_not_verified, and one that has a report 409 timesheet_exists.", "operationId": "postWorkOrdersByIdTimesheet", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Timesheet" } }, "required": [ "data" ], "type": "object" } } }, "description": "The caregiver report" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code timesheet_exists: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes hours_not_verified, work_order_not_ready: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Generate a Work Order's caregiver report", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/timesheet/overwrite": { "post": { "callbacks": {}, "description": "Writes the timesheet of a completed Work Order again from its days and tasks as they are now, as the Work Order page's Overwrite does: the report on file, and the month's assignment reports billing the same hours, are deleted and a new one is written (with none on file, one is generated). A report with a claim on a live batch answers 409 has_claims, naming how many claims by status and the reports carrying them, and nothing changes; one with entries typed from the card 409 entries_typed. A Work Order that is not completed answers 422 work_order_not_ready.", "operationId": "postWorkOrdersByIdTimesheetOverwrite", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Timesheet" } }, "required": [ "data" ], "type": "object" } } }, "description": "The new caregiver report" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes entries_typed, has_claims: Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code work_order_not_ready: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Write a Work Order's caregiver report again", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/transition": { "post": { "callbacks": {}, "description": "Moves it to status, as the page's status control does. Completing one writes the caregiver report, or finds the one on file, and timesheet says which; a Work Order with no verified hours still completes. lock_version is the one the Work Order was read with: a Work Order changed since answers 409 stale_record.", "operationId": "postWorkOrdersByIdTransition", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "status": { "description": "The new status.", "enum": [ "in_progress", "completed" ], "type": "string" } }, "required": [ "status", "lock_version" ], "title": "WorkOrderTransition", "type": "object" } } }, "description": "The new status", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/WorkOrder" }, "timesheet": { "properties": { "outcome": { "enum": [ "generated", "existing", "none", "not_applicable" ], "type": "string" }, "reason": { "description": "Why none was written.", "nullable": true, "type": "string" }, "timesheet_id": { "description": "The caregiver report.", "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" } }, "required": [ "data", "timesheet" ], "type": "object" } } }, "description": "The Work Order and the caregiver report outcome" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Change a Work Order's status", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/unarchive": { "post": { "callbacks": {}, "description": "Puts an archived Work Order back. A replacement already holding its slot answers 409 slot_taken naming its WO #. lock_version is the one the Work Order was read with: a Work Order changed since answers 409 stale_record.", "operationId": "postWorkOrdersByIdUnarchive", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": [ "lock_version" ], "type": "object" } } }, "description": "Its lock_version", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/WorkOrder" } }, "required": [ "data" ], "type": "object" } } }, "description": "The Work Order" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes slot_taken, stale_record: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Unarchive a Work Order", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/unplanned-tasks": { "post": { "callbacks": {}, "description": "Adds a task done on a date that the Work Order's plan did not put there, as the caregiver app does, on that day's care log with the notes as its reason. Needs timesheets.manage (403 forbidden otherwise); a day on a submitted, approved or exported Returned Timesheet answers 409 frozen. A task_definition_id the agency cannot use (not a UUID, unknown, or another agency's; the system definitions it can see are accepted) answers 422 unknown_task_definition; a date outside the Work Order's month 422 date_out_of_range; a completed or archived Work Order 422 not_editable.", "operationId": "postWorkOrdersByIdUnplannedTasks", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "date": { "description": "The date, YYYY-MM-DD.", "format": "date", "type": "string" }, "notes": { "description": "Optional notes.", "nullable": true, "type": "string" }, "task_definition_id": { "description": "The task's definition id.", "format": "uuid", "type": "string" } }, "required": [ "task_definition_id", "date" ], "title": "WorkOrderUnplannedTask", "type": "object" } } }, "description": "The task", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "completed": { "nullable": true, "type": "boolean" }, "count": { "description": "Times that day.", "nullable": true, "type": "integer" }, "date": { "format": "date", "nullable": true, "type": "string" }, "id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "notes": { "nullable": true, "type": "string" }, "task_definition_id": { "description": "The record's id.", "format": "uuid", "type": "string" }, "warnings": { "description": "Dismissible warnings the day's care log raised on this write (a weekly or daily limit, a day a submitted Returned Timesheet missed), each with code and message. Absent for a combined Work Order.", "items": { "properties": { "code": { "nullable": true, "type": "string" }, "message": { "nullable": true, "type": "string" }, "task_definition_id": { "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" }, "work_order_id": { "description": "The record's id.", "format": "uuid", "type": "string" } }, "title": "WorkOrderTaskMark", "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The task's mark" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, as the operation's description says." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict, as the operation's description says." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Codes date_out_of_range, not_editable, unknown_task_definition: Unprocessable Content, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Record a task done that the plan did not hold", "tags": [ "Work orders" ] } }, "/api/v1/work-orders/{id}/verify-for-billing": { "post": { "callbacks": {}, "description": "Sets its verified hours, first and second half: the hours of the month's caregiver report when one is on file (the returned card billing reads), else the hours its days in the month carry. Completes it when it is in progress, writing the caregiver report or finding the one on file, as the timesheet page's Verify hours does. timesheet says what happened to the report and completion whether this call completed it. A Work Order with no hours still verifies; timesheet then answers none with the reason. lock_version is the one the Work Order was read with: a Work Order changed since answers 409 stale_record.", "operationId": "postWorkOrdersByIdVerifyForBilling", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "in": "path", "name": "id", "required": true, "schema": { "description": "The record's id.", "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "lock_version": { "description": "Optimistic lock. A PATCH must send the value it read; if the record changed since, the answer is 409 stale_record.", "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": [ "lock_version" ], "type": "object" } } }, "description": "Its lock_version", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "completion": { "description": "completed_now when this call completed the Work Order; already_complete when it was.", "enum": [ "completed_now", "already_complete" ], "type": "string" }, "data": { "$ref": "#/components/schemas/WorkOrder" }, "timesheet": { "properties": { "outcome": { "enum": [ "generated", "existing", "none", "not_applicable" ], "type": "string" }, "reason": { "description": "Why none was written.", "nullable": true, "type": "string" }, "timesheet_id": { "description": "The caregiver report.", "format": "uuid", "nullable": true, "type": "string" } }, "type": "object" } }, "required": [ "data", "timesheet", "completion" ], "type": "object" } } }, "description": "The Work Order, the caregiver report outcome and the completion" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Code stale_record: Conflict, as the operation's description says." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the shared envelope." } }, "summary": "Verify a Work Order's hours for billing", "tags": [ "Work orders" ] } } }, "security": [ { "bearer": [] } ], "servers": [ { "url": "https://www.homecarebilling.com", "variables": {} } ], "tags": [] }