Submit a referral

curl --request POST \
  --url https://api.clinikehr.com/v1/clinics/{clinic_id}/referrals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "patient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "service": {
    "text": "<string>"
  },
  "reason": {
    "text": "<string>"
  },
  "priority": "routine",
  "needed_by": "2023-12-25",
  "clinical_summary": "<string>",
  "requester": {
    "name": "<string>",
    "organization": "<string>",
    "npi": "<string>"
  },
  "client_reference": "<string>",
  "origin_assistant_name": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    patient_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    service: {text: '<string>'},
    reason: {text: '<string>'},
    priority: 'routine',
    needed_by: '2023-12-25',
    clinical_summary: '<string>',
    requester: {name: '<string>', organization: '<string>', npi: '<string>'},
    client_reference: '<string>',
    origin_assistant_name: '<string>'
  })
};

fetch('https://api.clinikehr.com/v1/clinics/{clinic_id}/referrals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.clinikehr.com/v1/clinics/{clinic_id}/referrals"

payload = {
    "patient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "service": { "text": "<string>" },
    "reason": { "text": "<string>" },
    "priority": "routine",
    "needed_by": "2023-12-25",
    "clinical_summary": "<string>",
    "requester": {
        "name": "<string>",
        "organization": "<string>",
        "npi": "<string>"
    },
    "client_reference": "<string>",
    "origin_assistant_name": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "submission_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "patient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "resource_type": "condition",
    "action": "create",
    "review_status": "pending",
    "target_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "accepted_automatically": true,
    "source": "api",
    "submitted_at": "2023-11-07T05:31:56Z",
    "decided_at": "2023-11-07T05:31:56Z",
    "decision_reason": "<string>",
    "result_record_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "client_reference": "<string>",
    "origin_assistant_name": "<string>",
    "payload": {}
  },
  "idempotent_replay": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "pointer": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "pointer": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "pointer": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "pointer": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "pointer": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "pointer": "<string>",
      "message": "<string>"
    }
  ]
}

Referrals

Submit a referral

Permission: referrals:write

Submit a referral to the clinic for its staff to confirm.

The referral is held for review and answers 202 Accepted with a Location header pointing at the submission; it is not on the clinic’s referral list until staff confirm it (unless the clinic has chosen to accept such submissions automatically). Confirming adds it as received - it does not accept the referral or book anything; the clinic decides that next, and a sender cannot. The Idempotency-Key header is REQUIRED - a retry with the same key returns the original submission, never a second one. This is a clinical referral, not the clinic referral programme. JSON only: a FHIR ServiceRequest body is not accepted.

POST

clinics

{clinic_id}

referrals

Submit a referral

curl --request POST \
  --url https://api.clinikehr.com/v1/clinics/{clinic_id}/referrals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "patient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "service": {
    "text": "<string>"
  },
  "reason": {
    "text": "<string>"
  },
  "priority": "routine",
  "needed_by": "2023-12-25",
  "clinical_summary": "<string>",
  "requester": {
    "name": "<string>",
    "organization": "<string>",
    "npi": "<string>"
  },
  "client_reference": "<string>",
  "origin_assistant_name": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    patient_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    service: {text: '<string>'},
    reason: {text: '<string>'},
    priority: 'routine',
    needed_by: '2023-12-25',
    clinical_summary: '<string>',
    requester: {name: '<string>', organization: '<string>', npi: '<string>'},
    client_reference: '<string>',
    origin_assistant_name: '<string>'
  })
};

fetch('https://api.clinikehr.com/v1/clinics/{clinic_id}/referrals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.clinikehr.com/v1/clinics/{clinic_id}/referrals"

payload = {
    "patient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "service": { "text": "<string>" },
    "reason": { "text": "<string>" },
    "priority": "routine",
    "needed_by": "2023-12-25",
    "clinical_summary": "<string>",
    "requester": {
        "name": "<string>",
        "organization": "<string>",
        "npi": "<string>"
    },
    "client_reference": "<string>",
    "origin_assistant_name": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "submission_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "patient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "resource_type": "condition",
    "action": "create",
    "review_status": "pending",
    "target_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "accepted_automatically": true,
    "source": "api",
    "submitted_at": "2023-11-07T05:31:56Z",
    "decided_at": "2023-11-07T05:31:56Z",
    "decision_reason": "<string>",
    "result_record_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "client_reference": "<string>",
    "origin_assistant_name": "<string>",
    "payload": {}
  },
  "idempotent_replay": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "pointer": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "pointer": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "pointer": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "pointer": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "pointer": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "pointer": "<string>",
      "message": "<string>"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

required

A unique value you choose for this request, such as a UUID. Sending the same key again returns the first answer instead of doing the work twice, so a timed-out request is safe to retry. Reusing a key for a different request is refused with 409 idempotency_key_conflict, and retrying while the first request is still running with 409 idempotency_key_reused. See Retries and idempotency.

Minimum string length: 1

Path Parameters

clinic_id

string<uuid>

required

Body

application/json

A referral to this clinic, submitted for clinic staff to confirm. It does not appear on the clinic's referral list until they do (unless the clinic has chosen to accept such submissions automatically); either way it lands as received and the clinic decides whether to accept, decline or schedule it. This is a clinical referral, not the clinic referral programme. Send code on service or reason only with its system. client_reference (your own id, up to 200 characters) makes a second submission of the same record with different content a client_reference_conflict.

patient_id

string<uuid>

required

service

object

required

Show child attributes

reason

object

required

Show child attributes

priority

enum<string>

default:routine

Available options:

routine,

urgent,

asap,

stat

needed_by

string<date>

Not earlier than yesterday.

clinical_summary

string

Required string length: 1 - 8000

requester

object

Show child attributes

client_reference

string

Maximum string length: 200

origin_assistant_name

string

Maximum string length: 200

Response

Accepted - waiting for clinic staff. If the clinic has chosen to accept this kind of item from your key or connection without review, the body already shows review_status: confirmed and accepted_automatically: true; read review_status, not the status code.

data

object

required

What the clinic's review queue holds for something this key sent: one outside record waiting for, or already past, a clinician's decision.

Show child attributes

idempotent_replay

boolean

Present and true when this Idempotency-Key was already used and the original submission is returned.

Overview

Your key

Connections

Patients

Appointments

Encounters

Notes

Conditions

Allergies

Medications

Referrals

Submissions

Providers

Care providers

Insurance payers

Insurance coverage

Inventory

Dispensing

Drug requests

Pharmacy listings

CRM

Events

FHIR

Submit a referral

Authorizations

Headers

Path Parameters

Body

Response