Sandbox and test mode

Every developer account starts in test mode with a sandbox. Here is what it can and cannot show you.

What you get when you sign up

A demo practice. An institution named after your organization plus "Demo Practice", with one location and sample data.
A sandbox API key. Generate it on the API Key page of the Developer Portal. Each organization has one sandbox key and one production key. The portal shows a key once, so save it.
Tokens. A bearer token from /authenticates lasts 1 hour, in the sandbox and in production.

Sandbox and production calls go to the same base URL, https://nexhealth.info, with different keys.

What the demo practice does and does not do

Every read works. POST /appointments returns 201 and the appointment is readable.

There is no health record system behind the demo practice and no sync, so:

Nothing is written to a system. foreign_id and last_sync_time stay null on everything you create.
No sync-driven webhook fires. *_insertion events need a system to insert into, and appointment events come from the sync seeing a change in one. patient_created and patient_updated do fire, because they come from NexHealth's own record.
notify_patient=true sends nothing. Those messages come from the practice's NexHealth messaging, which the demo practice lacks.
POST /payments and POST /adjustments return 202, but the write waits for a sync that does not exist.
PATCH /appointments returns 400 Cannot update appointment because it is not synced with the PMS and/or a live client for every change except cancelled: true. PATCH /patients is accepted and changes NexHealth only.

The demo location looks like a live Dentrix location (insert_appt_client: true, a Dentrix foreign_id_type), but GET /sync_status returns an empty list because no sync runs behind it.

Two ids you will mix up

institution_id and location_id are different numbers. Calls take subdomain for the practice and location_id for the office. Read both from GET /institutions first.

Errors you can cause on purpose

No Authorization header: 401.
A subdomain your key cannot reach: 403 You don't have access to perform this action.
resource_type: appointment (lowercase) on a webhook subscription: 400 Invalid value for parameter resource_type.
The same POST /patients twice, a few seconds apart: 400 A patient with that information already exists - id=123. An immediate repeat can create a second record; the check runs on the search index.
PATCH /appointments with confirmed: true on an appointment you just booked: the 400 above.
A parameter the endpoint does not take, such as location_id on GET /institutions: 200 with Note that following parameters are ignored: location_id. in description.

Test a real write

To watch a write land, connect a test system to your demo practice:

Install the free demo version of Open Dental. See Setting up an Open Dental sandbox sync.
In the Developer Portal, open your demo practice and click "Create new sync".
Install the Synchronizer with the product key the portal shows.

Your sandbox key keeps working. With the sync connected, foreign_id fills in, appointment_insertion fires, and the Payments quickstart works.

Credits and production

To go to production, upgrade in the Developer Portal (it needs a credit card), switch the "Test mode" toggle at the top right, and create an institution and a sync for each practice. The upgrade comes with 10,000 free API calls and 10,000 free webhook deliveries. Production calls spend them; sandbox calls do not.

Next: Setting up webhooks. Reference: Errors.