Migrating from v1 to v2

v2 is a different contract, not a versioned copy of v1 — endpoints were consolidated, renamed and in some cases dropped. This page maps what you use today onto its v2 equivalent, and says what has no equivalent yet.

v2 is in beta

v1 remains the current, supported version. Use this page to plan, not as a signal that you need to migrate now.

Read API v2 Overview for the response-shape, error and pagination changes that affect every call.

v2 doesn't yet cover everything in v1

SOAP notes, patient documents, tasks, webhooks, eligibility history and ICD code search have no v2 endpoints. If your integration uses any of them, you'll be running against both versions during migration. See Not yet in v2.

Before you start

	v1	v2
Host	https://provider.sprypt.com	https://api.sprypt.com (sandbox: https://api.staging.spryhealth.care)
Path prefix	/apis/..., /v1/..., service-specific	/v2/...
Success body	{ code: 2000, data: {...} }	the resource itself
Success status	always 200	200 / 201 / 204
Update verb	POST /resource/{id}	PATCH /resource/{id}

The host change means v2 isn't a URL-rewrite away from v1. Plan on a client change, not a config change.

Endpoint mapping

Scheduling

v1	v2
GET /apis/v1/branch/organisation/{id}/get-all-clinics	GET /v2/clinics — one endpoint replaces five clinic-list variants
POST /v1/doctor	POST /v2/providers — now routed through onboarding
GET /v1/doctor	GET /v2/providers
GET /v1/doctor/{doctorId}	GET /v2/providers/{provider_id}
POST /v1/doctor/{doctorId}	PATCH /v2/providers/{provider_id}
POST /v1/doctor-block	POST /v2/providers/{provider_id}/blocks
GET /v1/doctor-block	GET /v2/providers/{provider_id}/blocks
DELETE /v1/doctor-block/{id}	DELETE /v2/blocks/{block_id}
GET /v1/doctor-block/{id}	no direct equivalent — read the list, or see notes below
POST /v1/doctor-block/modify-block/{id}	no equivalent — delete and recreate
POST /v1/doctor-block/bulk-modify/{id}	no equivalent
DELETE /v1/doctor-block/bulk-delete/{id}	no equivalent
—	GET|POST /v2/providers/{id}/schedules — working-hours shifts, newly exposed
—	GET /v2/slots — bookable slots, typed
GET /apis/v1/appointment/category	GET /v2/appointment-types — renamed; read-only
POST /apis/v1/appointment	POST /v2/appointments
GET /apis/v1/appointment/{id}	GET /v2/appointments/{appointment_id}
GET /apis/v1/appointment/calendar/events	GET /v2/appointments — one search replaces six
Cancel appointment	POST /v2/appointments/{id}/cancel
Get cancellation reasons	no equivalent — pass reason_key directly
—	POST /v2/appointments/{id}/check-in, check-out
POST /apis/v1/waitlist-requests	POST /v2/waitlist-requests
GET /apis/v1/waitlist-requests	GET /v2/waitlist-requests
GET /apis/v1/waitlist-requests/{id}	GET /v2/waitlist-requests/{id}
PATCH /apis/v1/waitlist-requests/{id}	PATCH /v2/waitlist-requests/{id}
DELETE /apis/v1/waitlist-requests/{id}	DELETE /v2/waitlist-requests/{id}
—	Accept / Decline waitlist invites

Patients and clinical

v1	v2
POST /apis/v1/patient	POST /v2/patients
GET /apis/v1/patient/{id}	GET /v2/patients/{patient_id}
GET /v2/patients (v1 docs)	GET /v2/patients
—	PATCH and DELETE on patients
Get patient insurance cards	GET /v2/patients/{id}/coverages — now full CRUD
—	POST /v2/patients/{id}/coverages/{id}/eligibility-checks
POST /apis/soap-enrichment/v1/patientCase	POST /v2/cases
GET /apis/soap-enrichment/v1/patientCase/{id}	GET /v2/cases/{spry_case_id}
POST /apis/soap-enrichment/v1/patientCase/{id}	PATCH /v2/cases/{spry_case_id} — now typed
—	GET /v2/cases, a patient's cases, discharge
GET /apis/v4/organisation/{id}/config/dynamic-form (specializations)	no equivalent — speciality is a plain string
POST /apis/soap-enrichment/v1/authorization	POST /v2/cases/{id}/coverages/{id}/authorizations
GET /apis/soap-enrichment/v1/authorization	GET /v2/cases/{id}/authorizations
GET /apis/soap-enrichment/v1/authorization/{id}	GET .../authorizations/{id}
POST /apis/soap-enrichment/v1/authorization/{id}	PATCH .../authorizations/{id} — now typed
DELETE /apis/soap-enrichment/v1/authorization/{id}	DELETE .../authorizations/{id}
GET /apis/soap-enrichment/v1/authorization/search	no equivalent — use the case roll-up
POST /apis/v2/referring-physician	POST /v2/referring-physicians
GET /apis/v1/referring-physician/{id}	GET /v2/referring-physicians/{id}
POST /apis/v2/referring-physician/{id}	PATCH /v2/referring-physicians/{id}
Referring physician search (metadata)	GET /v2/referring-physicians?query=

Administrative

v1	v2
POST /v1/clinic/add-clinic-staff	POST /v2/staff
POST /v1/clinic/update-clinic-staff/{id}	PATCH /v2/staff/{staff_id}
DELETE /v1/user/deleteStaff/{id}	DELETE /v2/staff/{staff_id}
—	GET /v2/staff, GET /v2/staff/{id}
—	GET /v2/payers — payer registry, needed to create a coverage
—	Organisations and Onboarding

Not yet in v2

These v1 capabilities have no v2 endpoint. Keep using v1 for them, or ask Spry about timelines.

Capability	v1 endpoints	Status in v2
SOAP notes	/apis/hep/v2/soap-context, /apis/v1/soap-context*	Not implemented
Patient documents	/apis/v1/patient-document*, /apis/v1/file/upload/unsigned	Not implemented
Tasks / todos	/todo-service/v1/todos*	Not implemented
Webhooks	/apis/v1/webhooks/subscriptions	Not implemented — planned
Eligibility history	/apis/eligibility/v2/insurance/eligibility/search	Only real-time checks, per coverage
Manual eligibility capture	/apis/eligibility/v2/insurance/eligibility/offline	Not implemented
ICD code search	metadata ICD search	No public endpoint; codes are validated and expanded on case and authorization writes
Appointment cancellation reasons	reasons list	Not implemented — send reason_key directly
Recurring block bulk edits	/v1/doctor-block/bulk-*	Not implemented
App-to-web SSO	/apis/v1/launch-tickets, /apis/v1/tickets/verify	Unchanged; not versioned under v2

Behaviour changes to watch for

Things that will compile and run but behave differently.

• Creating a clinic or provider no longer produces a usable record immediately. v2 routes creation through onboarding and returns a draft with id: null and status: "ONBOARDING". Publishing happens separately. If your v1 flow created a provider and immediately booked against it, that flow doesn't carry over — see Onboarding vs operational records.
• payment_mode is required when booking. v1 let the field be omitted and failed with an unhelpful error; v2 rejects the request up front.
• Unknown ICD codes now reject the write. v1 accepted whatever it was handed, leaving cases with codes that had no description or revision. v2 resolves every code first and returns 400 naming the ones that didn't resolve.
• Cases no longer carry copies of insurance cards. They hold primary_coverage_id and secondary_coverage_id pointers into the patient's coverages. Set them by PATCHing the case, and read the resolved plans from Get a Case's Coverages.
• Referring physicians are a registry, not inline objects. Create or look up the record, then point the case at it with referring_physician_id. Inline physician objects on a case aren't accepted.
• A referring physician created without an address can't be updated at all until one is supplied — the constraint applies to any field, not just the address.
• patient_id is the correlation key. There's no external-reference field in v2.
• Timestamps are ISO-8601 UTC everywhere. Several v1 fields were zoneless.

Suggested migration order

1. Point a test client at the v2 host and get a token.
2. Replace reads first — clinics, providers, patients, appointments — since response-shape changes are the bulk of the work and reads are safe to run in parallel with v1.
3. Move appointment booking, which is where the required-field and validation changes bite.
4. Move case, coverage and authorization writes, checking the pointer model against your data.
5. Leave anything in Not yet in v2 on v1 until an equivalent exists.