Quickstart

Use the sandbox host and a token from Get API keys. Successful requests count toward the 2,000 / 7 day allowance. 4xx and 5xx do not.

export SCAN_API_TOKEN="..."
export SCAN_API="https://api.staging.scan.com/api/v2"

1. Bootstrap fixtures

curl -X POST "$SCAN_API/testing/fixtures" \
  -H "Authorization: Bearer $SCAN_API_TOKEN"

Save cpt_code_id, icd10_code_id, and body_part_id from the response.

2. Create a referral

This uses a tiny valid PDF as a data URL. The name parameter preserves the attachment filename. Replace the CPT id from step 1. order_form, injury_type, incident_date, and visits are required. payment_type defaults to pi if omitted. cpt_code_id infers modality, so do not send a modality string.

PDF="data:application/pdf;name=order.pdf;base64,JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PgplbmRvYmoKMiAwIG9iago8PC9UeXBlL1BhZ2VzL0NvdW50IDEvS2lkc1szIDAgUl0+PgplbmRvYmoKMyAwIG9iago8PC9UeXBlL1BhZ2UvUGFyZW50IDIgMCBSL01lZGlhQm94WzAgMCA2MTIgNzkyXT4+CmVuZG9iagp4cmVmCjAgNAowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMTUgMDAwMDAgbiAKMDAwMDAwMDA3NCAwMDAwMCBuIAowMDAwMDAwMTMzIDAwMDAwIG4gCnRyYWlsZXIKPDwvU2l6ZSA0L1Jvb3QgMSAwIFI+PgpzdGFydHhyZWYKMjE3CiUlRU9GCg=="

curl -X POST "$SCAN_API/referrals" \
  -H "Authorization: Bearer $SCAN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"referral\": {
      \"order_form\": \"$PDF\",
      \"payment_type\": \"pi\",
      \"injury_type\": \"other\",
      \"incident_date\": \"2026-01-15\",
      \"state_brand_abbreviation\": \"MA\",
      \"patient\": {
        \"first_name\": \"Ada\",
        \"last_name\": \"Sandbox\",
        \"phone_number\": \"5555550100\",
        \"date_of_birth\": \"1988-05-21\",
        \"zip_code\": \"02108\",
        \"gender\": \"female\"
      },
      \"visits\": [{
        \"orders\": [{ \"cpt_code_id\": \"CPT_ID_FROM_FIXTURES\" }]
      }]
    }
  }"

Create returns 200 and the referral snapshot, including id.

3. Poll the referral

curl "$SCAN_API/referrals/REFERRAL_ID" \
  -H "Authorization: Bearer $SCAN_API_TOKEN"

Key off visits[].status. See Track referral status.

4. Fire a test webhook

curl -X POST "$SCAN_API/testing/events" \
  -H "Authorization: Bearer $SCAN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event_name":"visit.status_changed"}'

Next: Testing, Errors and limits.

Get started

Launch

Patient journey

Referral status

Lines of business

1. Bootstrap fixtures

2. Create a referral

3. Poll the referral

4. Fire a test webhook

​1. Bootstrap fixtures

​2. Create a referral

​3. Poll the referral

​4. Fire a test webhook

1. Bootstrap fixtures

2. Create a referral

3. Poll the referral

4. Fire a test webhook