Skip to content

Get started

Authentication

Every call carries your organization's API key. Retries are safe when you reuse the same ID and body.

API keys

Create a key in the dashboard under Integrations. It's shown once. Send it on every request in the Authorization header:

cURL
curl "https://api.nezercare.com/v1/clinical-cases/CASE_ID/progress" \
  --header "Authorization: Bearer nzh_prod_..."

A request with no key gets 401 with code MISSING_API_CREDENTIAL; an invalid, expired or revoked key gets 401 with code INVALID_API_CREDENTIAL.

API keys are for your server's calls about cases and conversations. On your website, a patient is added the first time your site signs them into the widget, with a token signed by your widget signing secret, not an API key. See Sign patients in.

If you have your own patient portal and use NezerCare through the API instead of the widget (Patient messaging), your server identifies patients with an API key that has the portal_messaging scope. No existing key has it. An owner or administrator turns it on when they create a new key, after confirming that the portal meets the safety requirements; the confirmation is recorded and audited, and a replacement key keeps the scope.

Every key does only what it was made for. When you create one you choose its scopes, at least one: care_handoff (the clinical-case routes), conversation_gateway (the conversation routes), conversation_internal_notes (on top of the gateway: reading the care team's staff-only internal notes with includeInternal=true; an owner or administrator gives it) and portal_messaging. A call to a route the key wasn't made for gets 403 with code INSUFFICIENT_SCOPE, before anything is read or changed. A key never gains a scope later: make a new key. Keys made before scopes were enforced have care_handoff and conversation_gateway and work as they did. A key with portal_messaging (it acts as any of your patients) or conversation_internal_notes can only be created, or replaced with a new secret, by an owner or an administrator (PORTAL_MESSAGING_OWNER_ONLY, INTERNAL_NOTES_OWNER_ONLY).

Every key is limited to 600 requests a minute and 20,000 an hour, counted over everything it calls: patient messaging, the conversation gateway and the care hand-off. Past that a call is 429 RATE_LIMITED with Retry-After, before anything is read, written or recorded.

Keep keys on your server

Never put an API key or a webhook signing secret in browser or mobile code. Rotate any key that has been pasted into chat, logs, source control or another untrusted place.

Key prefixes

Your organization has one workspace, and a key reaches only the organization that issued it: anything else answers 404. Every key uses the same base URL.

KeyPrefixBase URL
New keysnzh_prod_https://api.nezercare.com
Keys made before October 2026nzh_sb_ or nzh_prod_https://api.nezercare.com
NezerCare setup test keysnzh_test_https://api.nezercare.com

Your workspace is production. A key made earlier keeps working if it belongs to the workspace your organization kept, whatever its prefix. If your organization had a sandbox and a production, the copy it didn't keep was retired, and its keys (most often nzh_sb_ ones) get 409 with code ENVIRONMENT_RETIRED on every request: create a new key under Integrations. To try things without reaching real patients, sign yourself or a colleague into the widget on your site, so the patient is you.

While NezerCare sets your workspace up, before you're invited, it may give you a setup test key (nzh_test_). Every request with it sees only NezerCare's made-up test patients, never a real one; it works before the BAA is signed; and it can't be rotated. It stops working when your invitation is sent, with every test patient: create your own key then.

The BAA

API keys, webhooks and every patient feature stay off until your organization has signed its BAA. An owner or administrator signs it in the dashboard under Settings → Data and compliance, and it takes effect within about half a minute. Until then every call answers 403 with code BAA_REQUIRED. Don't retry it: sign the BAA, then call again.

Idempotency and ordering

Every case update, provider message and conversation message carries an ID you generate (a UUID): updateId, messageId or requestId.

  • Retry an uncertain request with the same ID and an identical body. You get the original result back, marked duplicate: true (status 200 on the clinical-case routes, 201 on a conversation message).
  • Reusing an ID with a different body returns 409.
  • Case updates must use the consecutive nextSequence from the progress endpoint. An update out of sequence returns 409.

Errors and retries

Errors are JSON with a message, and a code where one applies. The message is for you, never for a patient. It is a sentence, or a list of sentences when a request failed validation. On the clinical-case and conversation routes, a not-found, a conflict and a validation error carry no code, only the status, and the web framework's error and statusCode beside the message: branch on the status for those. Every error of Patient messaging has a code.

StatusMeaningRetry?
400The request is malformed or breaks the contract. A field the operation doesn't take is refused, not ignored.No. Fix the request.
401No key was sent (MISSING_API_CREDENTIAL), or the key is invalid, expired or revoked (INVALID_API_CREDENTIAL).No.
403The organization hasn't signed its BAA (BAA_REQUIRED).No. Sign the BAA first.
403The key wasn't made for this route (INSUFFICIENT_SCOPE).No. Make a new key with the scope.
404Not found in this key's organization.No.
409An ID reused with different content; an update out of sequence; a first update that isn't processed; an update to a case that is already resolved; or a message to a closed conversation.No. An update out of sequence carries nextSequence; read the progress if the error doesn't, then send the right update.
409The key belongs to a retired workspace (ENVIRONMENT_RETIRED).No. Create a new key.
429RATE_LIMITED: your key has called more than 600 times a minute or 20,000 an hour, across every route it can call. Honor Retry-After; nothing was read or written.Yes, after the wait.
5xxA problem on our side.Yes, with exponential backoff and jitter.

Network errors are safe to retry too, with the same ID and body.

The clinical boundary

A delivered webhook confirms transport only; it never means a clinician reviewed the case. NezerCare has no appointment-booking API: if your system schedules care, report it with a scheduled case update. Only an explicit resolution closes a case: your resolved update, or a team member resolving it in NezerCare.