Creates a referral

Creates a referral

curl --request POST \
  --url https://api.staging.scan.com/api/v2/referrals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "referral": {
    "order_form": "data:application/pdf;name=order.pdf;base64,JVBERi0xLjQK",
    "incident_date": "<string>",
    "visits": [
      {
        "orders": [
          {
            "cpt_code_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "body_part_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          }
        ],
        "modality_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      }
    ],
    "payment_type": "pi",
    "physician_notes": "<string>",
    "referred_by": "<string>",
    "state_brand_abbreviation": "<string>",
    "icd10_codes": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "patient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}
'

require 'uri'
require 'net/http'

url = URI("https://api.staging.scan.com/api/v2/referrals")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"referral\": {\n    \"order_form\": \"data:application/pdf;name=order.pdf;base64,JVBERi0xLjQK\",\n    \"incident_date\": \"<string>\",\n    \"visits\": [\n      {\n        \"orders\": [\n          {\n            \"cpt_code_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n            \"body_part_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n          }\n        ],\n        \"modality_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n      }\n    ],\n    \"payment_type\": \"pi\",\n    \"physician_notes\": \"<string>\",\n    \"referred_by\": \"<string>\",\n    \"state_brand_abbreviation\": \"<string>\",\n    \"icd10_codes\": [\n      \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n    ],\n    \"patient_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  }\n}"

response = http.request(request)
puts response.read_body

import requests

url = "https://api.staging.scan.com/api/v2/referrals"

payload = { "referral": {
        "order_form": "data:application/pdf;name=order.pdf;base64,JVBERi0xLjQK",
        "incident_date": "<string>",
        "visits": [
            {
                "orders": [
                    {
                        "cpt_code_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                        "body_part_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
                    }
                ],
                "modality_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            }
        ],
        "payment_type": "pi",
        "physician_notes": "<string>",
        "referred_by": "<string>",
        "state_brand_abbreviation": "<string>",
        "icd10_codes": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
        "patient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    referral: {
      order_form: 'data:application/pdf;name=order.pdf;base64,JVBERi0xLjQK',
      incident_date: '<string>',
      visits: [
        {
          orders: [
            {
              cpt_code_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
              body_part_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
            }
          ],
          modality_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
        }
      ],
      payment_type: 'pi',
      physician_notes: '<string>',
      referred_by: '<string>',
      state_brand_abbreviation: '<string>',
      icd10_codes: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
      patient_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    }
  })
};

fetch('https://api.staging.scan.com/api/v2/referrals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.staging.scan.com/api/v2/referrals",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'referral' => [
        'order_form' => 'data:application/pdf;name=order.pdf;base64,JVBERi0xLjQK',
        'incident_date' => '<string>',
        'visits' => [
                [
                                'orders' => [
                                                                [
                                                                                                                                'cpt_code_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
                                                                                                                                'body_part_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
                                                                ]
                                ],
                                'modality_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
                ]
        ],
        'payment_type' => 'pi',
        'physician_notes' => '<string>',
        'referred_by' => '<string>',
        'state_brand_abbreviation' => '<string>',
        'icd10_codes' => [
                '3c90c3cc-0d44-4b50-8888-8dd25736052a'
        ],
        'patient_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.staging.scan.com/api/v2/referrals"

	payload := strings.NewReader("{\n  \"referral\": {\n    \"order_form\": \"data:application/pdf;name=order.pdf;base64,JVBERi0xLjQK\",\n    \"incident_date\": \"<string>\",\n    \"visits\": [\n      {\n        \"orders\": [\n          {\n            \"cpt_code_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n            \"body_part_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n          }\n        ],\n        \"modality_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n      }\n    ],\n    \"payment_type\": \"pi\",\n    \"physician_notes\": \"<string>\",\n    \"referred_by\": \"<string>\",\n    \"state_brand_abbreviation\": \"<string>\",\n    \"icd10_codes\": [\n      \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n    ],\n    \"patient_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "11111111-1111-1111-1111-111111111111",
  "reference": "1234567890",
  "status": "pending",
  "visits": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "modality": "MRI",
      "procedures": [
        {
          "body_part": "Brain",
          "procedure": "MRI Brain without contrast",
          "contrast": "without_contrast",
          "laterality": "not_present",
          "cpt_code": "70551",
          "cpt_system": "http://www.ama-assn.org/go/cpt",
          "accession_id": "ACC-1001",
          "study_uid": null,
          "series_uid": null,
          "image_link": null,
          "report_link": null
        }
      ],
      "status": "pending",
      "start_time": "2021-01-01T00:00:00Z",
      "radiologist_group_name": "East Coast Radiology",
      "location": {
        "id": "11111111-1111-1111-1111-111111111111",
        "name": "Anytown Medical Center",
        "npi": "1234567890",
        "address_line_1": "123 Main St",
        "address_line_2": null,
        "city": "Anytown",
        "state": "GA",
        "zip_code": "30303"
      }
    }
  ],
  "line_of_business": "personal_injury",
  "payment_type": "lien",
  "incident_state": "GA",
  "referring_provider": "Dr. Jane Smith",
  "provider": {
    "id": "11111111-1111-1111-1111-111111111111",
    "name": "Dr. Jane Smith",
    "npi": "1234567890"
  },
  "law_firm": {
    "id": "11111111-1111-1111-1111-111111111111",
    "name": "Acme LLP"
  },
  "practice": {
    "id": "11111111-1111-1111-1111-111111111111",
    "name": "Peachtree Family Practice"
  },
  "icd10_codes": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "code": "M54.5",
      "system": "http://hl7.org/fhir/sid/icd-10-cm",
      "short_description": "Low back pain"
    }
  ],
  "patient": {
    "id": "11111111-1111-1111-1111-111111111111",
    "identifier": {
      "system": "https://scan.com/fhir/sid/patient-id",
      "value": "11111111-1111-1111-1111-111111111111"
    },
    "name": "Alex Patient",
    "first_name": "Alex",
    "last_name": "Patient",
    "date_of_birth": "05/21/1988",
    "date_of_birth_iso": "1988-05-21",
    "email": "[email protected]",
    "phone_number": "5551234567",
    "gender": "male",
    "address_line_1": "123 Main St",
    "city": "Anytown",
    "state": "GA",
    "zip_code": "30303"
  }
}

POST

api

referrals

Creates a referral

curl --request POST \
  --url https://api.staging.scan.com/api/v2/referrals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "referral": {
    "order_form": "data:application/pdf;name=order.pdf;base64,JVBERi0xLjQK",
    "incident_date": "<string>",
    "visits": [
      {
        "orders": [
          {
            "cpt_code_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "body_part_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          }
        ],
        "modality_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      }
    ],
    "payment_type": "pi",
    "physician_notes": "<string>",
    "referred_by": "<string>",
    "state_brand_abbreviation": "<string>",
    "icd10_codes": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "patient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}
'

require 'uri'
require 'net/http'

url = URI("https://api.staging.scan.com/api/v2/referrals")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"referral\": {\n    \"order_form\": \"data:application/pdf;name=order.pdf;base64,JVBERi0xLjQK\",\n    \"incident_date\": \"<string>\",\n    \"visits\": [\n      {\n        \"orders\": [\n          {\n            \"cpt_code_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n            \"body_part_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n          }\n        ],\n        \"modality_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n      }\n    ],\n    \"payment_type\": \"pi\",\n    \"physician_notes\": \"<string>\",\n    \"referred_by\": \"<string>\",\n    \"state_brand_abbreviation\": \"<string>\",\n    \"icd10_codes\": [\n      \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n    ],\n    \"patient_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  }\n}"

response = http.request(request)
puts response.read_body

import requests

url = "https://api.staging.scan.com/api/v2/referrals"

payload = { "referral": {
        "order_form": "data:application/pdf;name=order.pdf;base64,JVBERi0xLjQK",
        "incident_date": "<string>",
        "visits": [
            {
                "orders": [
                    {
                        "cpt_code_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                        "body_part_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
                    }
                ],
                "modality_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            }
        ],
        "payment_type": "pi",
        "physician_notes": "<string>",
        "referred_by": "<string>",
        "state_brand_abbreviation": "<string>",
        "icd10_codes": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
        "patient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    referral: {
      order_form: 'data:application/pdf;name=order.pdf;base64,JVBERi0xLjQK',
      incident_date: '<string>',
      visits: [
        {
          orders: [
            {
              cpt_code_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
              body_part_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
            }
          ],
          modality_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
        }
      ],
      payment_type: 'pi',
      physician_notes: '<string>',
      referred_by: '<string>',
      state_brand_abbreviation: '<string>',
      icd10_codes: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
      patient_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    }
  })
};

fetch('https://api.staging.scan.com/api/v2/referrals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.staging.scan.com/api/v2/referrals",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'referral' => [
        'order_form' => 'data:application/pdf;name=order.pdf;base64,JVBERi0xLjQK',
        'incident_date' => '<string>',
        'visits' => [
                [
                                'orders' => [
                                                                [
                                                                                                                                'cpt_code_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
                                                                                                                                'body_part_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
                                                                ]
                                ],
                                'modality_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
                ]
        ],
        'payment_type' => 'pi',
        'physician_notes' => '<string>',
        'referred_by' => '<string>',
        'state_brand_abbreviation' => '<string>',
        'icd10_codes' => [
                '3c90c3cc-0d44-4b50-8888-8dd25736052a'
        ],
        'patient_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.staging.scan.com/api/v2/referrals"

	payload := strings.NewReader("{\n  \"referral\": {\n    \"order_form\": \"data:application/pdf;name=order.pdf;base64,JVBERi0xLjQK\",\n    \"incident_date\": \"<string>\",\n    \"visits\": [\n      {\n        \"orders\": [\n          {\n            \"cpt_code_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n            \"body_part_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n          }\n        ],\n        \"modality_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n      }\n    ],\n    \"payment_type\": \"pi\",\n    \"physician_notes\": \"<string>\",\n    \"referred_by\": \"<string>\",\n    \"state_brand_abbreviation\": \"<string>\",\n    \"icd10_codes\": [\n      \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n    ],\n    \"patient_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "11111111-1111-1111-1111-111111111111",
  "reference": "1234567890",
  "status": "pending",
  "visits": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "modality": "MRI",
      "procedures": [
        {
          "body_part": "Brain",
          "procedure": "MRI Brain without contrast",
          "contrast": "without_contrast",
          "laterality": "not_present",
          "cpt_code": "70551",
          "cpt_system": "http://www.ama-assn.org/go/cpt",
          "accession_id": "ACC-1001",
          "study_uid": null,
          "series_uid": null,
          "image_link": null,
          "report_link": null
        }
      ],
      "status": "pending",
      "start_time": "2021-01-01T00:00:00Z",
      "radiologist_group_name": "East Coast Radiology",
      "location": {
        "id": "11111111-1111-1111-1111-111111111111",
        "name": "Anytown Medical Center",
        "npi": "1234567890",
        "address_line_1": "123 Main St",
        "address_line_2": null,
        "city": "Anytown",
        "state": "GA",
        "zip_code": "30303"
      }
    }
  ],
  "line_of_business": "personal_injury",
  "payment_type": "lien",
  "incident_state": "GA",
  "referring_provider": "Dr. Jane Smith",
  "provider": {
    "id": "11111111-1111-1111-1111-111111111111",
    "name": "Dr. Jane Smith",
    "npi": "1234567890"
  },
  "law_firm": {
    "id": "11111111-1111-1111-1111-111111111111",
    "name": "Acme LLP"
  },
  "practice": {
    "id": "11111111-1111-1111-1111-111111111111",
    "name": "Peachtree Family Practice"
  },
  "icd10_codes": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "code": "M54.5",
      "system": "http://hl7.org/fhir/sid/icd-10-cm",
      "short_description": "Low back pain"
    }
  ],
  "patient": {
    "id": "11111111-1111-1111-1111-111111111111",
    "identifier": {
      "system": "https://scan.com/fhir/sid/patient-id",
      "value": "11111111-1111-1111-1111-111111111111"
    },
    "name": "Alex Patient",
    "first_name": "Alex",
    "last_name": "Patient",
    "date_of_birth": "05/21/1988",
    "date_of_birth_iso": "1988-05-21",
    "email": "[email protected]",
    "phone_number": "5551234567",
    "gender": "male",
    "address_line_1": "123 Main St",
    "city": "Anytown",
    "state": "GA",
    "zip_code": "30303"
  }
}

Authorizations

Authorization

string

header

required

Authorization: Bearer <api_token>. Sandbox tokens come from Get API keys and allow 2,000 successful requests or 7 days. Failed 4xx/5xx responses do not consume the allowance. Production tokens are issued from the group's API access tab.

Body

application/json

referral

Imaging referral · object

required

Imaging referral
Workers' compensation referral

Show child attributes

Response

referral created

Referral snapshot (same shape as GET /api/v2/referrals/{id})

string<uuid>

Appointment (referral) ID

reference

string

Human-readable referral reference

Example:

"1234567890"

status

string

The referral's case and billing state, distinct from visits[].status. pending covers an open referral from create through reporting; invoice_ready, invoice_sent, closed, and canceled are the other partner-meaningful values. Remaining values are internal accounts-receivable states with no integration meaning. Scheduling logic belongs on visits[].status — see Track referral status.

Example:

"pending"

line_of_business

enum<string> | null

Encounter line of business. patient_direct can appear on reads but cannot currently be selected through POST /api/v2/referrals.

Available options:

personal_injury,

workers_comp,

health_plan,

patient_direct

payment_type

enum<string> | null

Funding or order type returned by the referral serializer. This is distinct from the create request's legacy payment_type field (normally pi). Workers' compensation referrals are returned as insurance. funding is retained for older referrals; new referrals use funded.

Available options:

lien,

insurance,

med_pay,

pip,

cash_pay,

funded,

servicing,

outside_servicing,

funding

Example:

"lien"

incident_state

string | null

Two-letter state abbreviation associated with the incident

Example:

"GA"

visits

object[]

All visits on the referral

Show child attributes

referring_provider

string | null

Submitting provider full name

provider

object

Referring provider

Show child attributes

law_firm

object

Show child attributes

practice

object

Show child attributes

payor

object

Present only for workers' compensation and health plan referrals. Omitted entirely for PI and other lines. Nested keys are omitted when blank.

Show child attributes

insurance_number

string | null

Insurance member number. Present only for workers' compensation and health plan referrals.

wc_number

string | null

Workers' compensation board number. Present only for workers' compensation referrals.

icd10_codes

object[]

Combined appointment and order ICD-10 codes

Show child attributes

patient

object

Show child attributes

call_notes

object[]

Call log notes on the referral

Show child attributes

documents

object[]

Public AOB and invoice attachments when available

answered_medical_questionnaire

boolean

Whether medical safety answers are stored on the referral

preferred_location

object

Patient preferred imaging center, when set

Show child attributes

scheduling_mode

enum<string> | null

Availability preference submitted for this referral. Scan books from this preference.

Available options:

anytime_anywhere,

time_preferences,

existing_appointment,

needs_other_location

auto_book_request

object | null

Latest auto-book request, when one has been submitted

Show child attributes

Referrals

Courier SSO

Referral Orders

Patients

Practices

Law Firms

Body Parts

CPT Codes

ICD-10 Codes

Modalities

Locations

Order Documents

Status

Testing

FHIR

Authorizations

Body

Response