The sandbox environment includes special-case inputs and predefined provider test data that allow developers to simulate edge cases during integration testing. See the list below for available scenarios:
API Endpoint Test Scenarios
This page documents test scenarios for various API endpoints to support validation and debugging of behaviors in different input cases. All endpoints are assumed to return standard HTTP response codes alongside expected JSON structures unless otherwise noted.
GET /v1/providers
Field
Input
Result
npis
npi_error
Results in a 500 error response.
npis
npi_missing
Returns no matching providers.
npis
npi_multipleproviders
Returns multiple matching providers.
npis
npi_multiplelocations
Returns a provider with multiple locations.
npis
npi_allvirtual
Returns a provider with one virtual location.
npis
npi_hasvirtual
Returns a provider with both an in-person and virtual location.
npis
npi_insuranceIdRequired
Returns a provider that requires an insurance member id and plan id.
insurance_plan_id
ip_0
Returns 400 error response due to invalid insurance plan.
GET /v1/provider_locations
Field
Input
Result
zip_code
10112
Results in a 500 error response.
zip_code
99734
Returns no matching provider locations.
zip_code
11201
Returns a response that includes booking requirements.
insurance_plan_id
ip_0
Returns 400 error response due to invalid insurance plan.
GET /v1/appointments and GET /v1/appointments/{appointment_id}
Appointment ID
Status
Provider Location ID
Visit Reason ID
Developer Patient ID
2b29f79b-6d7f-472a-9603-d0c378bc9531
pending_booking
pr_pending / lo_pending
pc_FRO-18leckytNKtruw5dLR
381ee8f4-8aa7-46c6-b27c-1ea9fdfa4bac
d2ee5bd8-643a-42c8-8c5a-be450e903430
confirmed (new patient)
pr_confirmed / lo_confirmed
pc_TlZW-r06U0W3pCsIGtSI5B
f92f5116-a43a-46a9-b5b7-197eea5d7aca
423e6a11-8dac-4873-b933-d8d02f9a370f
confirmed (existing patient)
pr_confirmed / lo_confirmed
pc_TlZW-r06U0W3pCsIGtSI5B
f92f5116-a43a-46a9-b5b7-197eea5d7aca
34e4ead3-ca69-4448-9438-58702dd1048f
booking_failed
pr_bookingfailed / lo_bookingfailed
pc_zZWhkaURvEGlZpSimNILaB
4a2363b8-a2a0-4afc-bc43-ed5e0fd80191
21990114-ea71-4d7d-9d1e-00c43ae44bcd
cancelled
pr_cancelled / lo_cancelled
pc_p1KdCTTzuU6A04ZjEt837x
7f754fc6-3ccb-457b-96b9-39412fb1066b
a0a7770d-e667-416c-9f06-9c3b40a7bb84
no_show
pr_noshow / lo_noshow
pc_T1T3MOA0kUuE201i1ZfIWR
909ea2c6-c0d8-4d1c-91e9-8830af3178c4
63f995c2-49c4-40c8-a93a-140fb32e913b
pending_reschedule
pr_pendingreschedule / lo_pendingreschedule
pc_FRO-18leckytNKtruw5dLR
381ee8f4-8aa7-46c6-b27c-1ea9fdfa4bac
8507d05f-cbe5-4732-b72a-22add9c80120
rescheduled
pr_rescheduled / lo_rescheduled
pc_peZqujk5w0jL8SblyLoIoz
07eeb104-1f80-44ae-8f48-32af1072eda7
84d04f67-b2cf-4afd-ab64-193072498ed5
reschedule_failed
pr_reschedulefailed / lo_reschedulefailed
pc_PS_BTW9rmkuIfaIH_Hxdwg
5db43e60-c33e-47cb-84b2-325c1b95f10a
Errors
Appointment ID
Result
83f5cf14-3eb1-4034-be1f-e7c3058aad21
404 error response.
dc69a428-8a73-461b-bd7b-df755910a3fb
500 error response.
POST /v1/appointments/cancel
Same error test cases as above.
POST /v1/appointments/reschedule
Same error test cases as above.
POST /v1/appointments/{appointment_id}/attachments
Appointment ID
Result
83f5cf14-3eb1-4034-be1f-e7c3058aad21
404 error response.
dc69a428-8a73-461b-bd7b-df755910a3fb
500 error response.
08399012-db42-4f0b-92a5-4fbceffcbd58
Returns multiple existing attachments.
PUT /v1/schedulable_entities/overlaps
NPI
Result
npi_overlaps_not_found
NPI that returns with a schedulable status of 'NotSchedulable'.
npi_overlaps_pending
NPI that returns with a schedulable status of 'AddedToQueue'.
POST /v1/webhook/mock-request
Sends one signed sample appointment webhook to webhook_url, signed with webhook_key, and returns the body it sent. Requires the external.appointment.read scope. Returns 404 outside Sandbox.
Field
Input
Result
appointment_update_type
updated (default), cancelled, created
Sets appointment_update_type. Only updated includes practice_id and changed_attributes.
webhook_url
Malformed URL
400 error response.
webhook_key
Not base64
400 error response.
Every sample uses appointment_id62g4ar44-1yv9-0931-dl3t-e9c2174kks09. The updated sample uses practice_idpt_1234.
POST /v1/webhook/insurance-ref-data/mock-request
Sends one signed sample insurance reference-data notification to webhook_url, signed with webhook_key, and returns the notification it sent. Any authenticated token works. Returns 404 outside Sandbox.
Field
Input
Result
event_type
insurance_plans_updated (default)
changed_entities contains plans ip_5432 and ip_2345.
event_type
insurance_carriers_updated
changed_entities contains carrier ic_440.
webhook_url
Malformed, unreachable or not https
400 error response.
webhook_url
Resolves to a non-public address
400 error response.
webhook_key
Not base64
400 error response.
Every sample uses event_idevt_4f2c8a91d0b34e6f8a1c7d5e9b0f2a63. Only event_time_utc changes between calls.
A 200 means Zocdoc sent the request, not that your endpoint accepted it. Redirects are not followed.
Verify the signature against the raw bytes your endpoint received. The response can differ from the signed body in key order and null fields.