Sarva PMS Integration API

Read and write a practice's schedule, patients, billing and work from your own system.

Tokenhttps://core-api.sarvahealth.ai/oauth/token

API basehttps://pms-api.sarvahealth.ai/integrations/v1

Getting started

The API is for systems. Sarva gives you a client id and secret. A practice then installs your system in the Sarva Console, choosing what it may do. Nothing works on a practice until then.

curl -X POST https://core-api.sarvahealth.ai/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d audience=pms-integrations

A token lasts 10 minutes and names what your client may do, not which practices. Name the practice on every request:

curl https://pms-api.sarvahealth.ai/integrations/v1/appointments?service_date=2026-11-02 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Answers and errors

Success is {"data": ..., "meta": {"request_id": ...}}. Failure is application/problem+json with a stable code.

Status	Means
401	The token is missing, expired or not for this API.
403	The token, or the practice's consent, does not include this scope.
404	It does not exist, or your system is not installed on this practice.
409	It conflicts with the current state.
412, 428	Send the current version in `If-Match`.
422	The request is not valid. Fix it before retrying.
429	Rate limited. Wait for `Retry-After`.

Retrying safely

Send a unique Idempotency-Key on every write, and reuse it to retry. A repeat with the same body returns the first response, and a different body under the same key is refused. Registering a webhook endpoint and rotating its secret take no key, because a secret is never stored for replay. POST /payments is also protected by your processor reference: that money posts once, whatever the key. POST /voice/outcomes is keyed by call and outcome.

Pagination

Lists return meta.page.next_cursor when there is more. Pass it as cursor.

Rate limits

Per client, practice and class of work. Every answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset.

Class	Burst	Sustained
Reads	600	10 a second
Writes	120	2 a second
Eligibility	30	1 every 2 seconds

Webhooks

Register an HTTPS endpoint with POST /webhook-endpoints. The signing secret is shown once. You receive an event only while your installation holds its scope.

Answer 2xx within 10 seconds, then process.
Delivery is at least once and unordered: dedupe on id.
Failures retry for 3 days. An endpoint failing for all 3 is disabled. Events stay at GET /events for 30 days.
Payloads carry ids, states, amounts and times. Fetch anything else with your scopes.

Verify every delivery. Sarva-Signature is t=<unix>,v1=<hex>, an HMAC-SHA256 of t.body. While a secret rotates there are two v1 values.

import hashlib, hmac, time

def verify(header: str, secret: str, body: bytes) -> bool:
    parts = [p.partition("=") for p in header.split(",")]
    stamp = next(v for k, _, v in parts if k == "t")
    if abs(time.time() - int(stamp)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{stamp}.".encode() + body,
                        hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, v) for k, _, v in parts if k == "v1")

Versioning

Within v1, changes only add. A breaking change is v2, announced with Deprecation and Sunset headers and six months' notice. Ignore fields you do not know.

Scopes

Scope	Allows
`practice:read`	Read the practice: name, timezone, locations, providers
`appointments:read`	Read appointments and availability
`appointments:write`	Book, reschedule, cancel and confirm appointments
`patients:read`	Read patients and their coverages
`patients:write`	Create and update patients and coverages
`eligibility:read`	Read eligibility checks
`eligibility:write`	Request eligibility checks
`charges:read`	Read charges
`charges:write`	Create charges
`claims:read`	Read claims
`claims:status:write`	Report a payer's answer about a claim (any channel)
`payments:read`	Read payments
`payments:write`	Post a patient payment with a processor reference (posted once)
`balances:read`	Read patient balances
`balances:write`	Record payment plans and promises to pay
`statements:read`	Read patient statements
`remittances:write`	Submit remittance files (835)
`documents:read`	Read documents
`documents:write`	Submit documents
`work_items:read`	Read work items
`work_items:write`	Create and resolve work items
`voice:outcomes:write`	Report voice call outcomes
`webhooks:manage`	Manage webhook endpoints and redeliver events
`events:read`	Read the event log for reconciliation

Events

API version 2026-11-01.

Type	Needs	Fields
`appointment.created`	`appointments:read`	id, status, starts_at, ends_at, patient_id, provider_id, location_id
`appointment.rescheduled`	`appointments:read`	id, status, starts_at, ends_at, patient_id, provider_id, location_id
`appointment.cancelled`	`appointments:read`	id, status, starts_at, ends_at, patient_id, provider_id, location_id
`appointment.confirmed`	`appointments:read`	id, status, starts_at, ends_at, patient_id, provider_id, location_id
`appointment.checked_in`	`appointments:read`	id, status, starts_at, ends_at, patient_id, provider_id, location_id
`appointment.no_show`	`appointments:read`	id, status, starts_at, ends_at, patient_id, provider_id, location_id
`patient.created`	`patients:read`	id, status, merged_into_id
`patient.updated`	`patients:read`	id, status, merged_into_id
`patient.merged`	`patients:read`	id, status, merged_into_id
`coverage.created`	`patients:read`	id, patient_id, status
`coverage.ended`	`patients:read`	id, patient_id, status
`eligibility_check.completed`	`eligibility:read`	id, patient_id, status
`charge.created`	`charges:read`	id, patient_id, status, amount
`charge.released`	`charges:read`	id, patient_id, status, amount
`claim.submitted`	`claims:read`	id, patient_id, status, amount
`claim.rejected`	`claims:read`	id, patient_id, status, amount
`claim.acknowledged`	`claims:read`	id, patient_id, status, amount
`claim.status_updated`	`claims:read`	id, patient_id, status, amount
`claim.adjudicated`	`claims:read`	id, patient_id, status, amount
`claim.denied`	`claims:read`	id, patient_id, status, amount
`payment.posted`	`payments:read`	id, patient_id, status, amount
`remittance.posted`	`payments:read`	id, status, amount
`refund.issued`	`payments:read`	id, patient_id, status, amount
`statement.sent`	`statements:read`	id, patient_id, status, amount
`payment_plan.created`	`balances:read`	id, patient_id, status, amount
`payment_plan.behind`	`balances:read`	id, patient_id, status, amount
`balance.changed`	`balances:read`	id, patient_id, amount
`work_item.created`	`work_items:read`	id, status, work_item_type
`work_item.assigned`	`work_items:read`	id, status, work_item_type
`work_item.resolved`	`work_items:read`	id, status, work_item_type
`document.received`	`documents:read`	id, patient_id, status
`document.filed`	`documents:read`	id, patient_id, status
`webhook.test`	`webhooks:manage`	id

Appointments

get`/appointments`

One day's schedule, cancelled and missed visits included

Scope appointments:read

Parameter	In	Type
`service_date`	query	date
`provider_id`	query	uuid
`location_id`	query	uuid

Answers 200401403404422429500

get/appointments

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/appointments?service_date=2026-11-02' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": [
    {
      "cancellation_reason": "string",
      "confirmed_at": "2026-11-02T14:00:00Z",
      "ends_at": "2026-11-02T14:00:00Z",
      "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "location_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "object": "appointment",
      "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "provider_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "rescheduled_to_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "service_date": "2026-11-02",
      "starts_at": "2026-11-02T14:00:00Z",
      "status": "string"
    }
  ],
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/appointments`

Book an appointment

Scope appointments:write

Field	Type	Required
`ends_at`	date-time	required
`external_appointment_id`	string	optional
`location_id`	uuid	optional
`patient_id`	uuid	required
`provider_id`	uuid	optional
`starts_at`	date-time	required

Answers 201401403404409422429500

post/appointments

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/appointments' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ends_at": "2026-11-02T14:00:00Z",
    "external_appointment_id": "string",
    "location_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "provider_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "starts_at": "2026-11-02T14:00:00Z"
  }'

Response 201

{
  "data": {
    "cancellation_reason": "string",
    "confirmed_at": "2026-11-02T14:00:00Z",
    "ends_at": "2026-11-02T14:00:00Z",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "location_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "object": "appointment",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "provider_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "rescheduled_to_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "service_date": "2026-11-02",
    "starts_at": "2026-11-02T14:00:00Z",
    "status": "string"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

get`/appointments/{appointment_id}`

One appointment

Scope appointments:read

Parameter	In	Type
`appointment_id`	path	uuid

Answers 200401403404422429500

get/appointments/{appointment_id}

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/appointments/{appointment_id}' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": {
    "cancellation_reason": "string",
    "confirmed_at": "2026-11-02T14:00:00Z",
    "ends_at": "2026-11-02T14:00:00Z",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "location_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "object": "appointment",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "provider_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "rescheduled_to_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "service_date": "2026-11-02",
    "starts_at": "2026-11-02T14:00:00Z",
    "status": "string"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/appointments/{appointment_id}:cancel`

Cancel a visit, saying whose decision it was

Scope appointments:write

Parameter	In	Type
`appointment_id`	path	uuid

Field	Type	Required
`reason`	patient_cancelled \| practice_cancelled \| provider_unavailable \| closure	required

Answers 200401403404409422429500

post/appointments/{appointment_id}:cancel

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/appointments/{appointment_id}:cancel' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "patient_cancelled"
  }'

Response 200

{
  "data": {
    "cancellation_reason": "string",
    "confirmed_at": "2026-11-02T14:00:00Z",
    "ends_at": "2026-11-02T14:00:00Z",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "location_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "object": "appointment",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "provider_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "rescheduled_to_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "service_date": "2026-11-02",
    "starts_at": "2026-11-02T14:00:00Z",
    "status": "string"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/appointments/{appointment_id}:confirm`

Record that the patient confirmed

Scope appointments:write

Parameter	In	Type
`appointment_id`	path	uuid

Answers 200401403404409422429500

post/appointments/{appointment_id}:confirm

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/appointments/{appointment_id}:confirm' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Idempotency-Key: $(uuidgen)"

Response 200

{
  "data": {
    "cancellation_reason": "string",
    "confirmed_at": "2026-11-02T14:00:00Z",
    "ends_at": "2026-11-02T14:00:00Z",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "location_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "object": "appointment",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "provider_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "rescheduled_to_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "service_date": "2026-11-02",
    "starts_at": "2026-11-02T14:00:00Z",
    "status": "string"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/appointments/{appointment_id}:reschedule`

Move a visit: answers with the new appointment

A reschedule books a new appointment and cancels this one, together. The response is the **new** appointment, with its own id.

Scope appointments:write

Parameter	In	Type
`appointment_id`	path	uuid

Field	Type	Required
`ends_at`	date-time	required
`location_id`	uuid	optional
`provider_id`	uuid	optional
`starts_at`	date-time	required

Answers 201401403404409422429500

post/appointments/{appointment_id}:reschedule

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/appointments/{appointment_id}:reschedule' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ends_at": "2026-11-02T14:00:00Z",
    "location_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "provider_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "starts_at": "2026-11-02T14:00:00Z"
  }'

Response 201

{
  "data": {
    "cancellation_reason": "string",
    "confirmed_at": "2026-11-02T14:00:00Z",
    "ends_at": "2026-11-02T14:00:00Z",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "location_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "object": "appointment",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "provider_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "rescheduled_to_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "service_date": "2026-11-02",
    "starts_at": "2026-11-02T14:00:00Z",
    "status": "string"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

get`/availability`

A provider's bookable slots on one day

Scope appointments:read

Parameter	In	Type
`provider_id`	query	uuid
`date`	query	date
`duration_minutes`	query	integer
`location_id`	query	uuid

Answers 200401403404422429500

get/availability

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/availability?provider_id=0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10&date=2026-11-02' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": [
    {
      "capacity": 1,
      "ends_at": "2026-11-02T14:00:00Z",
      "starts_at": "2026-11-02T14:00:00Z",
      "taken": 1
    }
  ],
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

Billing

get`/balances`

Patients who owe this practice, largest first

Scope balances:read

Parameter	In	Type
`min_balance`	query	number \| string
`limit`	query	integer

Answers 200401403404422429500

get/balances

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/balances' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": [
    {
      "amount": "125.00",
      "last_statement_at": "2026-11-02T14:00:00Z",
      "object": "balance",
      "owing_since": "2026-11-02T14:00:00Z",
      "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10"
    }
  ],
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

get`/claims`

Claims on this practice

Scope claims:read

Parameter	In	Type
`state`	query	string
`patient_id`	query	uuid
`claim_number`	query	string
`limit`	query	integer
`cursor`	query	string

Answers 200401403404422429500

get/claims

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/claims' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": [
    {
      "balance_amount": "125.00",
      "claim_number": "string",
      "currency": "string",
      "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "object": "claim",
      "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "payer_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "service_date_from": "2026-11-02",
      "service_date_to": "2026-11-02",
      "status": "string",
      "total_charge_amount": "125.00",
      "total_paid_amount": "125.00"
    }
  ],
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

get`/claims/{claim_id}`

One claim

Scope claims:read

Parameter	In	Type
`claim_id`	path	uuid

Answers 200401403404422429500

get/claims/{claim_id}

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/claims/{claim_id}' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": {
    "balance_amount": "125.00",
    "claim_number": "string",
    "currency": "string",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "object": "claim",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "payer_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "service_date_from": "2026-11-02",
    "service_date_to": "2026-11-02",
    "status": "string",
    "total_charge_amount": "125.00",
    "total_paid_amount": "125.00"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/claims/{claim_id}/status-reports`

Report a payer's answer about a claim, from any channel

Normalised by lookup: a code the table does not hold reads as inconclusive and reaches a person. The claim is not moved: this is one party's account, recorded beside it.

Scope claims:status:write

Parameter	In	Type
`claim_id`	path	uuid

Field	Type	Required
`adjudicated_on`	date	optional
`channel`	phone \| portal \| edi	required
`paid_amount`	number \| string	optional
`requested_at`	date-time	required
`responded_at`	date-time	optional
`source`	string	required
`status_category_code`	string	required
`status_code`	string	optional

Answers 201401403404409422429500

post/claims/{claim_id}/status-reports

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/claims/{claim_id}/status-reports' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "adjudicated_on": "2026-11-02",
    "channel": "phone",
    "paid_amount": "125.00",
    "requested_at": "2026-11-02T14:00:00Z",
    "responded_at": "2026-11-02T14:00:00Z",
    "source": "string",
    "status_category_code": "string",
    "status_code": "string"
  }'

Response 201

{
  "data": {
    "claim_found_at_payer": true,
    "claim_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "is_inconclusive": true,
    "normalized_state": "string",
    "object": "claim_status_report"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

get`/patients/{patient_id}/balance`

What one patient owes, derived from the ledger

Scope balances:read

Parameter	In	Type
`patient_id`	path	uuid

Answers 200401403404422429500

get/patients/{patient_id}/balance

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/patients/{patient_id}/balance' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": {
    "amount": "125.00",
    "last_statement_at": "2026-11-02T14:00:00Z",
    "object": "balance",
    "owing_since": "2026-11-02T14:00:00Z",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/payment-plans`

Record a payment plan

Scope balances:write

Field	Type	Required
`currency`	string	optional
`first_due_date`	date	required
`frequency`	weekly \| biweekly \| monthly	required
`instalment_amount`	number \| string	required
`note`	string	optional
`patient_id`	uuid	required
`total_amount`	number \| string	required

Answers 201401403404409422429500

post/payment-plans

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/payment-plans' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "first_due_date": "2026-11-02",
    "frequency": "weekly",
    "instalment_amount": "125.00",
    "note": "string",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "total_amount": "125.00"
  }'

Response 201

{
  "data": {
    "first_due_date": "2026-11-02",
    "frequency": "string",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "instalment_amount": "125.00",
    "object": "payment_plan",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "status": "string",
    "total_amount": "125.00"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

get`/payments`

Patient payments on this practice, newest first

Scope payments:read

Parameter	In	Type
`limit`	query	integer
`cursor`	query	uuid

Answers 200401403404422429500

get/payments

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/payments' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": [
    {
      "amount": "125.00",
      "created": true,
      "currency": "string",
      "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "object": "payment",
      "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "payment_date": "2026-11-02",
      "processor_reference": "string",
      "status": "string"
    }
  ],
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/payments`

Record a patient payment a processor took; posted once

Scope payments:write

Field	Type	Required
`amount`	number \| string	required
`currency`	string	optional
`paid_on`	date	optional
`patient_id`	uuid	required
`processor_reference`	string	required

Answers 201401403404409422429500

post/payments

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/payments' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "125.00",
    "currency": "USD",
    "paid_on": "2026-11-02",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "processor_reference": "string"
  }'

Response 201

{
  "data": {
    "amount": "125.00",
    "created": true,
    "currency": "string",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "object": "payment",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "payment_date": "2026-11-02",
    "processor_reference": "string",
    "status": "string"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/promises`

Record a promise to pay; a person checks it on the day

Scope balances:write

Field	Type	Required
`amount`	number \| string	required
`currency`	string	optional
`patient_id`	uuid	required
`promised_for`	date	required

Answers 201401403404409422429500

post/promises

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/promises' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "125.00",
    "currency": "USD",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "promised_for": "2026-11-02"
  }'

Response 201

{
  "data": {
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "object": "promise",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "work_item_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

Records

get`/charges`

Charges on this practice

Scope charges:read

Parameter	In	Type
`state`	query	string
`encounter_id`	query	uuid
`limit`	query	integer
`cursor`	query	string

Answers 200401403404422429500

get/charges

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/charges' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": [
    {
      "encounter_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "object": "charge",
      "procedure_code": "string",
      "service_date": "2026-11-02",
      "status": "string",
      "total_charge_amount": "125.00"
    }
  ],
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/charges`

Enter a charge on an encounter

The same price, checks and charge rules as the web API. Required modifiers are added.

Scope charges:write

Field	Type	Required
`diagnosis_codes`	array of string	required
`encounter_id`	uuid	required
`modifier_1`	string	optional
`modifier_2`	string	optional
`procedure_code`	string	required
`procedure_code_set`	CPT \| HCPCS	optional
`units`	string	optional

Answers 201401403404409422429500

post/charges

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/charges' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "diagnosis_codes": [
      "string"
    ],
    "encounter_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "modifier_1": "string",
    "modifier_2": "string",
    "procedure_code": "string",
    "procedure_code_set": "CPT",
    "units": "125.00"
  }'

Response 201

{
  "data": {
    "encounter_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "object": "charge",
    "procedure_code": "string",
    "service_date": "2026-11-02",
    "status": "string",
    "total_charge_amount": "125.00"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/documents`

Submit a document. It arrives unfiled and a person places it

Scope documents:write

Field	Type	Required
`content_base64`	string	required
`media_type`	string	required

Answers 201401403404409422429500

post/documents

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/documents' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "content_base64": "string",
    "media_type": "string"
  }'

Response 201

{
  "data": {
    "document_type": "string",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "match_status": "string",
    "mime_type": "string",
    "object": "document",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "received_at": "2026-11-02T14:00:00Z"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

get`/documents/{document_id}`

One document's record; bytes are not served here

Scope documents:read

Parameter	In	Type
`document_id`	path	uuid

Answers 200401403404422429500

get/documents/{document_id}

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/documents/{document_id}' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": {
    "document_type": "string",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "match_status": "string",
    "mime_type": "string",
    "object": "document",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "received_at": "2026-11-02T14:00:00Z"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/eligibility-checks`

Ask the payer about a patient's coverage

Answers `202`. Read `GET /eligibility-checks/{id}`, or subscribe to `eligibility_check.completed`. A repeat with the same `Idempotency-Key` starts no second 270.

Scope eligibility:write

Field	Type	Required
`coverage_id`	uuid	optional
`patient_id`	uuid	required
`service_date`	date	optional
`service_type_code`	string	optional

Answers 202401403404422429500

post/eligibility-checks

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/eligibility-checks' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "coverage_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "service_date": "2026-11-02",
    "service_type_code": "string"
  }'

Response 202

{
  "data": {
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "object": "eligibility_check",
    "status": "pending"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

get`/eligibility-checks/{check_id}`

One eligibility check and its answer

Scope eligibility:read

Parameter	In	Type
`check_id`	path	uuid

Answers 200401403404422429500

get/eligibility-checks/{check_id}

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/eligibility-checks/{check_id}' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": {
    "coverage_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "coverage_status": "string",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "object": "eligibility_check",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "plan_name": "string",
    "received_at": "2026-11-02T14:00:00Z",
    "service_date": "2026-11-02",
    "status": "string"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

get`/practice`

This practice: name, timezone, locations, providers

Scope practice:read

Answers 200401403404422429500

get/practice

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/practice' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": {
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "locations": [
      {
        "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
        "name": "string"
      }
    ],
    "name": "string",
    "object": "practice",
    "providers": [
      {
        "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
        "name": "string"
      }
    ],
    "timezone": "string"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/remittances`

Submit an 835. It is ingested; a person posts it

Scope remittances:write

Field	Type	Required
`content_base64`	string	required

Answers 201401403404409422429500

post/remittances

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/remittances' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "content_base64": "string"
  }'

Response 201

{
  "data": {
    "claim_count": 1,
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "matched_claim_count": 1,
    "object": "remittance"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

get`/statements`

Patient statements on this practice, newest first

Scope statements:read

Parameter	In	Type
`patient_id`	query	uuid
`limit`	query	integer

Answers 200401403404422429500

get/statements

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/statements' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": [
    {
      "balance_amount": "125.00",
      "currency": "string",
      "delivery_channel": "string",
      "generated_at": "2026-11-02T14:00:00Z",
      "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "object": "statement",
      "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "sent_at": "2026-11-02T14:00:00Z",
      "statement_number": "string"
    }
  ],
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

Webhooks

post`/deliveries/{delivery_id}:redeliver`

Queue this delivery again

Takes no `Idempotency-Key`: redelivering twice queues one delivery.

Scope webhooks:manage

Parameter	In	Type
`delivery_id`	path	uuid

Answers 202401403404422429500

post/deliveries/{delivery_id}:redeliver

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/deliveries/{delivery_id}:redeliver' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 202

{
  "data": {
    "attempts": 1,
    "created_at": "2026-11-02T14:00:00Z",
    "delivered_at": "2026-11-02T14:00:00Z",
    "event_id": "string",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "last_attempt_at": "2026-11-02T14:00:00Z",
    "last_error": "string",
    "last_latency_ms": 1,
    "last_status_code": 1,
    "next_attempt_at": "2026-11-02T14:00:00Z",
    "object": "webhook_delivery",
    "status": "pending"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

get`/webhook-endpoints`

List this client's webhook endpoints on the practice

Scope webhooks:manage

Answers 200401403404422429500

get/webhook-endpoints

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/webhook-endpoints' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": [
    {
      "created_at": "2026-11-02T14:00:00Z",
      "description": "string",
      "disabled_reason": "string",
      "event_types": [
        "string"
      ],
      "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "object": "webhook_endpoint",
      "status": "enabled",
      "url": "string"
    }
  ],
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/webhook-endpoints`

Takes no `Idempotency-Key`: a repeat answers `409 ALREADY_EXISTS`.

Scope webhooks:manage

Field	Type	Required
`description`	string	optional
`event_types`	array of string	required
`url`	uri	required

Answers 201401403404409422429500

post/webhook-endpoints

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/webhook-endpoints' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "string",
    "event_types": [
      "string"
    ],
    "url": "https://example.com/webhooks/sarva"
  }'

Response 201

{
  "data": {
    "created_at": "2026-11-02T14:00:00Z",
    "description": "string",
    "disabled_reason": "string",
    "event_types": [
      "string"
    ],
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "object": "webhook_endpoint",
    "previous_secret_expires_at": "2026-11-02T14:00:00Z",
    "secret": "string",
    "status": "enabled",
    "url": "string"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

patch`/webhook-endpoints/{endpoint_id}`

Change an endpoint, or enable or disable it

Scope webhooks:manage

Parameter	In	Type
`endpoint_id`	path	uuid

Field	Type	Required
`description`	string	optional
`event_types`	array of string	optional
`status`	enabled \| disabled	optional
`url`	uri	optional

Answers 200401403404409422429500

patch/webhook-endpoints/{endpoint_id}

Request

curl -X PATCH 'https://pms-api.sarvahealth.ai/integrations/v1/webhook-endpoints/{endpoint_id}' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "string",
    "event_types": [
      "string"
    ],
    "status": "enabled",
    "url": "https://example.com/webhooks/sarva"
  }'

Response 200

{
  "data": {
    "created_at": "2026-11-02T14:00:00Z",
    "description": "string",
    "disabled_reason": "string",
    "event_types": [
      "string"
    ],
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "object": "webhook_endpoint",
    "status": "enabled",
    "url": "string"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

delete`/webhook-endpoints/{endpoint_id}`

Delete an endpoint and its delivery log

Scope webhooks:manage

Parameter	In	Type
`endpoint_id`	path	uuid

Answers 204401403404422429500

delete/webhook-endpoints/{endpoint_id}

Request

curl -X DELETE 'https://pms-api.sarvahealth.ai/integrations/v1/webhook-endpoints/{endpoint_id}' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 204

No body.

get`/webhook-endpoints/{endpoint_id}/deliveries`

The delivery log: status, latency and response code, never a response body

Scope webhooks:manage

Parameter	In	Type
`endpoint_id`	path	uuid
`limit`	query	integer

Answers 200401403404422429500

get/webhook-endpoints/{endpoint_id}/deliveries

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/webhook-endpoints/{endpoint_id}/deliveries' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": [
    {
      "attempts": 1,
      "created_at": "2026-11-02T14:00:00Z",
      "delivered_at": "2026-11-02T14:00:00Z",
      "event_id": "string",
      "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "last_attempt_at": "2026-11-02T14:00:00Z",
      "last_error": "string",
      "last_latency_ms": 1,
      "last_status_code": 1,
      "next_attempt_at": "2026-11-02T14:00:00Z",
      "object": "webhook_delivery",
      "status": "pending"
    }
  ],
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/webhook-endpoints/{endpoint_id}:rotate-secret`

A new signing secret; both sign for 24 hours

Takes no `Idempotency-Key`: a repeat rotates again, which is harmless.

Scope webhooks:manage

Parameter	In	Type
`endpoint_id`	path	uuid

Answers 200401403404422429500

post/webhook-endpoints/{endpoint_id}:rotate-secret

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/webhook-endpoints/{endpoint_id}:rotate-secret' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": {
    "created_at": "2026-11-02T14:00:00Z",
    "description": "string",
    "disabled_reason": "string",
    "event_types": [
      "string"
    ],
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "object": "webhook_endpoint",
    "previous_secret_expires_at": "2026-11-02T14:00:00Z",
    "secret": "string",
    "status": "enabled",
    "url": "string"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/webhook-endpoints/{endpoint_id}:send-test`

Queue a `webhook.test` event to this endpoint

Scope webhooks:manage

Parameter	In	Type
`endpoint_id`	path	uuid

Answers 202401403404422429500

post/webhook-endpoints/{endpoint_id}:send-test

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/webhook-endpoints/{endpoint_id}:send-test' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 202

{
  "data": {
    "attempts": 1,
    "created_at": "2026-11-02T14:00:00Z",
    "delivered_at": "2026-11-02T14:00:00Z",
    "event_id": "string",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "last_attempt_at": "2026-11-02T14:00:00Z",
    "last_error": "string",
    "last_latency_ms": 1,
    "last_status_code": 1,
    "next_attempt_at": "2026-11-02T14:00:00Z",
    "object": "webhook_delivery",
    "status": "pending"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

Events

get`/events`

Events on this practice, newest first, last 30 days

Scope events:read

Parameter	In	Type
`limit`	query	integer
`type`	query	string
`since`	query	date-time
`cursor`	query	string

Answers 200401403404422429500

get/events

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/events' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": [
    {
      "api_version": "string",
      "created": "2026-11-02T14:00:00Z",
      "data": {},
      "id": "string",
      "practice_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "type": "string"
    }
  ],
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

get`/events/{event_id}`

One event

Scope events:read

Parameter	In	Type
`event_id`	path	string

Answers 200401403404422429500

get/events/{event_id}

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/events/{event_id}' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": {
    "api_version": "string",
    "created": "2026-11-02T14:00:00Z",
    "data": {},
    "id": "string",
    "practice_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "type": "string"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

Patients

get`/patients`

Find patients on this practice by name, MRN or external id

Scope patients:read

Parameter	In	Type
`name`	query	string
`mrn`	query	string
`external_patient_id`	query	string
`limit`	query	integer
`cursor`	query	string

Answers 200401403404422429500

get/patients

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/patients' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": [
    {
      "email": "string",
      "external_patient_id": "string",
      "first_name": "string",
      "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "last_name": "string",
      "mrn": "string",
      "object": "patient",
      "phone": "string",
      "status": "string",
      "version": 1
    }
  ],
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/patients`

Scope patients:write

Field	Type	Required
`date_of_birth`	date	required
`email`	string	optional
`external_patient_id`	string	optional
`first_name`	string	required
`last_name`	string	required
`phone`	string	optional
`sex_at_birth`	M \| F \| U	optional

Answers 201401403404409422429500

post/patients

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/patients' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "date_of_birth": "2026-11-02",
    "email": "string",
    "external_patient_id": "string",
    "first_name": "string",
    "last_name": "string",
    "phone": "string",
    "sex_at_birth": "M"
  }'

Response 201

{
  "data": {
    "email": "string",
    "external_patient_id": "string",
    "first_name": "string",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "last_name": "string",
    "mrn": "string",
    "object": "patient",
    "phone": "string",
    "status": "string",
    "version": 1
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

get`/patients/{patient_id}`

One patient

Scope patients:read

Parameter	In	Type
`patient_id`	path	uuid

Answers 200401403404422429500

get/patients/{patient_id}

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/patients/{patient_id}' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": {
    "email": "string",
    "external_patient_id": "string",
    "first_name": "string",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "last_name": "string",
    "mrn": "string",
    "object": "patient",
    "phone": "string",
    "status": "string",
    "version": 1
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

patch`/patients/{patient_id}`

Correct a patient's contact details and name

`If-Match` is required: two systems must not overwrite each other.

Scope patients:write

Parameter	In	Type
`patient_id`	path	uuid
`If-Match`	header	string

Field	Type	Required
`email`	string	optional
`first_name`	string	optional
`last_name`	string	optional
`phone`	string	optional

Answers 200401403404409412422428429500

patch/patients/{patient_id}

Request

curl -X PATCH 'https://pms-api.sarvahealth.ai/integrations/v1/patients/{patient_id}' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "If-Match: $VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "phone": "string"
  }'

Response 200

{
  "data": {
    "email": "string",
    "external_patient_id": "string",
    "first_name": "string",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "last_name": "string",
    "mrn": "string",
    "object": "patient",
    "phone": "string",
    "status": "string",
    "version": 1
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

get`/patients/{patient_id}/coverages`

A patient's policies, primary first; a subscriber's date of birth is never returned

Scope patients:read

Parameter	In	Type
`patient_id`	path	uuid

Answers 200401403404422429500

get/patients/{patient_id}/coverages

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/patients/{patient_id}/coverages' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": [
    {
      "cob_rank": 1,
      "effective_from": "2026-11-02",
      "effective_to": "2026-11-02",
      "group_number": "string",
      "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "member_id": "string",
      "object": "coverage",
      "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "payer_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "status": "string"
    }
  ],
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/patients/{patient_id}/coverages`

Put a policy on a patient

Scope patients:write

Parameter	In	Type
`patient_id`	path	uuid

Field	Type	Required
`cob_rank`	integer	required
`effective_from`	date	required
`effective_to`	date	optional
`group_number`	string	optional
`member_id`	string	required
`payer_id`	uuid	required
`subscriber_date_of_birth`	date	optional
`subscriber_first_name`	string	optional
`subscriber_last_name`	string	optional
`subscriber_relationship`	self \| spouse \| child \| other	required

Answers 201401403404409422429500

post/patients/{patient_id}/coverages

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/patients/{patient_id}/coverages' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "cob_rank": 1,
    "effective_from": "2026-11-02",
    "effective_to": "2026-11-02",
    "group_number": "string",
    "member_id": "string",
    "payer_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "subscriber_date_of_birth": "2026-11-02",
    "subscriber_first_name": "string",
    "subscriber_last_name": "string",
    "subscriber_relationship": "self"
  }'

Response 201

{
  "data": {
    "cob_rank": 1,
    "effective_from": "2026-11-02",
    "effective_to": "2026-11-02",
    "group_number": "string",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "member_id": "string",
    "object": "coverage",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "payer_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "status": "string"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

Voice

post`/voice/outcomes`

Report what a call achieved; applied automatically where it can be

`disposition` says what happened: `applied`, or `work_item` with the `floor` that needed a person. A resend with the same `call_id` and `outcome` returns the first result (`200`).

Scope voice:outcomes:write

Field	Type	Required
`appointment_id`	uuid	optional
`call_id`	uuid	required
`claim_number`	string	optional
`note`	string	optional
`outcome`	confirmed \| rescheduled \| cancelled \| paid \| payment_plan \| promise_to_pay \| billing_question \| callback_requested \| wrong_number \| opted_out \| no_contact \| payer_answer	required
`patient_id`	uuid	optional
`payment`	object	optional
`plan`	object	optional
`promise`	object	optional
`reschedule`	object	optional

Answers 201401403404422429500

post/voice/outcomes

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/voice/outcomes' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "call_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "claim_number": "string",
    "note": "string",
    "outcome": "confirmed",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "payment": {
      "amount": "125.00",
      "currency": "USD",
      "paid_on": "2026-11-02",
      "processor_reference": "string"
    },
    "plan": {
      "currency": "USD",
      "first_due_date": "2026-11-02",
      "frequency": "weekly",
      "instalment_amount": "125.00",
      "total_amount": "125.00"
    },
    "promise": {
      "amount": "125.00",
      "currency": "USD",
      "promised_for": "2026-11-02"
    },
    "reschedule": {
      "ends_at": "2026-11-02T14:00:00Z",
      "location_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "provider_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "starts_at": "2026-11-02T14:00:00Z"
    }
  }'

Response 201

{
  "data": {
    "call_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "created_at": "2026-11-02T14:00:00Z",
    "disposition": "applied",
    "floor": "string",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "object": "voice_outcome",
    "outcome": "string",
    "result_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "result_type": "string",
    "work_item_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

Work items

get`/work-items`

Work items on this practice

Scope work_items:read

Parameter	In	Type
`state`	query	string
`work_item_type`	query	string
`limit`	query	integer
`cursor`	query	string

Answers 200401403404422429500

get/work-items

Request

curl 'https://pms-api.sarvahealth.ai/integrations/v1/work-items' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID"

Response 200

{
  "data": [
    {
      "created_at": "2026-11-02T14:00:00Z",
      "due_at": "2026-11-02T14:00:00Z",
      "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "object": "work_item",
      "resolution_code": "string",
      "state": "string",
      "subject_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
      "subject_type": "string",
      "title": "string",
      "work_item_type": "string"
    }
  ],
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/work-items`

Ask a person at the practice to do something about a patient

Scope work_items:write

Field	Type	Required
`detail`	string	required
`due_at`	date-time	optional
`patient_id`	uuid	required
`title`	string	required

Answers 201401403404422429500

post/work-items

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/work-items' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "detail": "string",
    "due_at": "2026-11-02T14:00:00Z",
    "patient_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "title": "string"
  }'

Response 201

{
  "data": {
    "created_at": "2026-11-02T14:00:00Z",
    "due_at": "2026-11-02T14:00:00Z",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "object": "work_item",
    "resolution_code": "string",
    "state": "string",
    "subject_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "subject_type": "string",
    "title": "string",
    "work_item_type": "string"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

post`/work-items/{work_item_id}:resolve`

Close a work item with a code

An item with a live governing obligation answers `OBLIGATION_UNRESOLVED`: closing over a live deadline stays with a person.

Scope work_items:write

Parameter	In	Type
`work_item_id`	path	uuid

Field	Type	Required
`note`	string	optional
`resolution_code`	actioned \| no_action_required \| information_missing \| duplicate \| superseded \| referred_externally	required

Answers 200401403404409422429500

post/work-items/{work_item_id}:resolve

Request

curl -X POST 'https://pms-api.sarvahealth.ai/integrations/v1/work-items/{work_item_id}:resolve' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Sarva-Practice-Id: $PRACTICE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "string",
    "resolution_code": "actioned"
  }'

Response 200

{
  "data": {
    "created_at": "2026-11-02T14:00:00Z",
    "due_at": "2026-11-02T14:00:00Z",
    "id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "object": "work_item",
    "resolution_code": "string",
    "state": "string",
    "subject_id": "0193f2a4-7c1e-7b3d-9a2f-5e6d4c3b2a10",
    "subject_type": "string",
    "title": "string",
    "work_item_type": "string"
  },
  "meta": {
    "page": {
      "next_cursor": "string"
    }
  }
}

Sarva PMS Integration API

Getting started

Answers and errors

Retrying safely

Pagination

Rate limits

Webhooks

Versioning

Scopes

Events

Appointments

get/appointments

post/appointments

get/appointments/{appointment_id}

post/appointments/{appointment_id}:cancel

post/appointments/{appointment_id}:confirm

post/appointments/{appointment_id}:reschedule

get/availability

Billing

get/balances

get/claims

get/claims/{claim_id}

post/claims/{claim_id}/status-reports

get/patients/{patient_id}/balance

post/payment-plans

get/payments

post/payments

post/promises

Records

get/charges

post/charges

post/documents

get/documents/{document_id}

post/eligibility-checks

get/eligibility-checks/{check_id}

get/practice

post/remittances

get/statements

Webhooks

post/deliveries/{delivery_id}:redeliver

get/webhook-endpoints

post/webhook-endpoints

patch/webhook-endpoints/{endpoint_id}

delete/webhook-endpoints/{endpoint_id}

get/webhook-endpoints/{endpoint_id}/deliveries

post/webhook-endpoints/{endpoint_id}:rotate-secret

post/webhook-endpoints/{endpoint_id}:send-test

Events

get/events

get/events/{event_id}

Patients

get/patients

post/patients

get/patients/{patient_id}

patch/patients/{patient_id}

get/patients/{patient_id}/coverages

post/patients/{patient_id}/coverages

Meta

get/ping

Voice

post/voice/outcomes

Work items

get/work-items

post/work-items

post/work-items/{work_item_id}:resolve

get`/appointments`

post`/appointments`

get`/appointments/{appointment_id}`

post`/appointments/{appointment_id}:cancel`

post`/appointments/{appointment_id}:confirm`

post`/appointments/{appointment_id}:reschedule`

get`/availability`

get`/balances`

get`/claims`

get`/claims/{claim_id}`

post`/claims/{claim_id}/status-reports`

get`/patients/{patient_id}/balance`

post`/payment-plans`

get`/payments`

post`/payments`

post`/promises`

get`/charges`

post`/charges`

post`/documents`

get`/documents/{document_id}`

post`/eligibility-checks`

get`/eligibility-checks/{check_id}`

get`/practice`

post`/remittances`

get`/statements`

post`/deliveries/{delivery_id}:redeliver`

get`/webhook-endpoints`

post`/webhook-endpoints`

patch`/webhook-endpoints/{endpoint_id}`

delete`/webhook-endpoints/{endpoint_id}`

get`/webhook-endpoints/{endpoint_id}/deliveries`

post`/webhook-endpoints/{endpoint_id}:rotate-secret`

post`/webhook-endpoints/{endpoint_id}:send-test`

get`/events`

get`/events/{event_id}`

get`/patients`

post`/patients`

get`/patients/{patient_id}`

patch`/patients/{patient_id}`

get`/patients/{patient_id}/coverages`

post`/patients/{patient_id}/coverages`

get`/ping`

post`/voice/outcomes`

get`/work-items`

post`/work-items`

post`/work-items/{work_item_id}:resolve`