Skip to main content
An outside care provider is a clinician or practice a patient names who is not on the clinic’s own team: their primary care doctor, the clinician who referred them, a specialist. It is a contact record. Nothing here gives that clinician access to anything. It is different from the provider directory, which lists the clinic’s own clinicians. In ClinikEHR the list appears as Outside care team on the client’s record. These are patient-data permissions: the API add-on, the agreement and, for an organization, the approval for the Outside care team kind all apply. See Permissions. A patient the clinic has restricted, or a contact that does not exist, returns 404 with code: "not_found". The two are never told apart. See Errors.

​
What an outside care provider looks like

The clinic’s private notes are never returned.

​
List contacts

The list holds every contact for the patient, whoever added it, so you can show the whole picture.

​
Add a contact

The answer is 201 Created with the contact. Idempotency-Key is required on POST and optional on PATCH. See Retries and duplicates. You may send patient_id, name, type, practice_name, specialty, npi, phone, fax, address, is_primary and origin_assistant_name. patient_id, name and type are required. A field this list does not name is refused with invalid_request, and the error names the field. The clinic’s notes cannot be sent. A contact is saved straight away: it does not wait for a clinician. It appears at the clinic with From and your system’s name.

​
You change only what your app added

This is the rule to build around. A contact is yours when your app added it. For a workspace key that means any key in the same organization, so rolling a key does not strand its contacts. For a clinic’s own key it means that clinic.
  • PATCH and DELETE work on your own contacts.
  • On a contact the clinic’s staff or an intake form added, or one another app added, they are refused with 409 care_provider_clinic_managed. The contact is still readable. Only the clinic can change it.
  • The clinic’s staff may edit or remove any contact, including yours.
The editable field tells you in advance. See Errors.

​
Change a contact

Send any of name, type, practice_name, specialty, npi, phone, fax, address and is_primary, at least one. patient_id cannot be changed. The answer is 200 with the contact. Each value must be a non-empty string (or true/false for is_primary): a key cannot clear an optional field such as phone or fax. To blank one, ask the clinic to edit the contact, or remove the contact and add it again.

​
Remove a contact

DELETE answers 204 No Content with no body. A contact is a reference the clinic holds, not a clinical record, so it is removed rather than marked. The clinic’s audit trail still records that it was removed. Deleting a contact that is already gone returns 404.

​
As FHIR

Outside care providers are JSON only. There is no FHIR representation for them, and a FHIR body or an Accept: application/fhir+json header on these routes is refused. See FHIR.

​
On the Patients routes

A patient read by GET /v1/clinics/{clinic_id}/patients shows care_providers as a read-only field. Writing it there is refused. Use these routes instead.

​
Test keys

A test key sees one fictional primary care doctor for each sandbox patient, plus the contacts it adds itself.