zingageRequest access
Getting Started / Introduction

Introduction

Zingage Operator layers autonomous workforce operations — scheduling, staffing, and voice communication — on top of a partner's existing system of record. It reads context, takes action, and writes results back, with a full audit trail.

Access and endpoint scope are provisioned per partner during onboarding.
Base URL
https://api.zingage.com/v1
Getting Started / Authentication

Authentication

Zingage supports OAuth 2.0, API key, or service account credentials. A dedicated service account is provisioned per agency; every action is attributable to it. Pass credentials via the Authorization header on every request.

Authorization: Bearer sk_live_<token>
Getting Started / Core Concepts

Core Concepts

System of record
The partner platform remains the source of truth for all patient, practitioner, and visit data.
Bidirectional flow
Operational context flows down to Zingage; enriched insights flow back up.
Idempotent writes
Write operations are safe to retry. Use an Idempotency-Key header on POSTs.
Audit trail
Every action is logged with timestamp, actor, and rationale.
Getting Started / Integration Methods

Integration Methods

Three integration tiers, ordered by preference. Most partners begin at Tier 3 to launch quickly and migrate up as engineering capacity allows.

Tier 1
REST / GraphQL APIpreferred
Real-time sync, lowest-latency operations, full attribute coverage.
Tier 2
Embedded widgetwhite-label
Zingage operations embedded in the partner UI; white-label options for branding.
Tier 3
Managed Integrationmanaged
When a partner's system doesn't expose a suitable API, Zingage can operate through a secure managed integration layer that Zingage establishes and maintains.
API Resources / Patients

Patients

A Patient represents a care recipient as modeled in the partner's system of record.

Attributes

Attribute
Type
Description
idrequired
string
Unique identifier for the patient.
names
object
Given, family, prefix, and suffix name parts.
status
enum
active or inactive.
contactPoints
array
Phone and email entries with system + use.
addresses
array
Street, city, state, and postal code.
responsibleParties
array
Name, relationship, and contact for next-of-kin and decision-makers.
profileNotes
array
Free-form notes with type tags.
tags
array
Free-form labels.

Operations

Read patient records and add notes.

API Resources / Practitioners

Practitioners

A Practitioner is a caregiver who delivers visits.

Attributes

Attribute
Type
Description
idrequired
string
Unique identifier for the practitioner.
names
object
Given, family, prefix, and suffix name parts.
status
enum
active or inactive.
contactPoints
array
Phone and email entries with system + use.
addresses
array
Home address(es).
tags
array
Free-form labels.
classes
array
Service categories the practitioner can deliver.
profileNotes
array
Free-form notes with type tags.

Operations

Read caregiver records and record availability.

API Resources / Visits

Visits

A Visit is a single shift — a scheduled service for one patient, optionally assigned to a practitioner. Clock-in and clock-out events drive billing and payroll.

Attributes

Attribute
Type
Description
idrequired
string
Unique identifier for the visit.
patientId
string
Patient receiving the service.
practitionerId
string
Caregiver assigned. Null for open shifts.
scheduledStart
timestamp
Planned start (ISO-8601 UTC).
scheduledEnd
timestamp
Planned end (ISO-8601 UTC).
clockIn
timestamp
Actual clock-in time, if recorded.
clockOut
timestamp
Actual clock-out time, if recorded.
clockedIn
boolean
True once clock-in is recorded.
clockedOut
boolean
True once clock-out is recorded.
status
enum
active, tentative, canceled, or completed.
service
object
Service code and description (e.g., T1019).
notes
array
Visit-level notes.
scheduleId
string
Parent recurring schedule, if any.

Operations

Read visits, record clock-in / clock-out, assign a caregiver, and add notes.

API Resources / Schedules

Schedules

A Schedule represents a recurring care plan — a template that generates visits over an effective period.

Attributes

Attribute
Type
Description
idrequired
string
Unique identifier for the schedule.
patientId
string
Patient receiving the recurring service.
practitionerId
string
Assigned caregiver. Null = open.
recurrence
object
frequency (daily / weekly / biweekly / monthly), daysOfWeek, interval.
scheduledTime
object
Daily start and end time (local).
effectivePeriod
object
Start and end dates the schedule is active.
service
object
Service code applied to generated visits.

Operations

Read recurring schedules.

API Resources / Messaging

Messaging

Messaging endpoints read and write the conversation thread between the agency and a caregiver, routed through the partner's native channel so messages appear in the existing inbox.

Attributes

Attribute
Type
Description
messageHistory
array
Thread between agency and caregiver. Each entry has direction, channel, body, and createdAt.

Operations

Read and send caregiver messages.

API Resources / Open Shifts

Open Shifts

Open shifts are unassigned visits that need coverage.

Attributes

Attribute
Type
Description
visitId
string
The unassigned visit.
patientId
string
Patient receiving the service.
scheduledStart
timestamp
Planned start (ISO-8601 UTC).
scheduledEnd
timestamp
Planned end (ISO-8601 UTC).
service
object
Service code and description.

Operations

Read unassigned shifts needing coverage.

Platform / Webhooks & Events

Webhooks & Events

Zingage can subscribe to real-time events for low-latency operations. Configure a webhook endpoint and we'll deliver signed JSON payloads.

Event Types

visit.createdvisit.updatedvisit.canceledpatient.createdpractitioner.updated
Platform / Errors

Errors

Zingage uses conventional HTTP status codes. Error responses include a machine-readabletype and code, plus a human-readable message.

Status
Meaning
200
OK — request succeeded.
201
Created — resource was created.
400
Bad Request — malformed request.
401
Unauthorized — missing or invalid credentials.
403
Forbidden — credentials lack the required scope.
404
Not Found — resource doesn't exist.
409
Conflict — state precondition failed (e.g., duplicate visit).
422
Unprocessable — validation failed on request body.
429
Too Many Requests — rate limited; honor Retry-After.
5xx
Server Error — retry with exponential backoff.
Platform / Rate Limits

Rate Limits

Requests are rate-limited per service account. 429 responses include a Retry-After header indicating how many seconds to wait before retrying. Burst and sustained limits are confirmed during onboarding.

Platform / Versioning

Versioning

The API is versioned in the path (/v1). Breaking changes ship under a new version; non-breaking additions (new optional fields, new endpoints) are made in place. We give partners at least 12 months of notice before deprecating a version.

Trust / Security & Compliance

Security & Compliance

Zingage treats PHI as the highest-trust asset. Our security program is built around HIPAA and least-privilege access throughout.

Area
Detail
HIPAA
Business Associate Agreement (BAA) available.
Encryption
AES-256 at rest; TLS 1.2+ in transit.
Access control
Dedicated service account per agency; role-based permissions.
Audit trail
Every action logged with timestamp, actor, and rationale.
Data residency
US-based infrastructure on AWS.
PHI handling
Minimum necessary standard; no PHI in AI training data.
GET /v1/patients
{
  "endpoint": "https://api.zingage.com/v1",
  "auth": "Bearer sk_live_<token>",
  "scopes": ["patients:read", "visits:write"]
}