Patient referrals provided to Aton Health.

Overview

Use these endpoints to:

  • Submit new referrals to the platform
  • Retrieve all referrals received by Aton Health
  • Look up specific referrals by trial and participant ID
  • Submit qualified referrals that have already been pre-screened
  • Retrieve qualified referrals stored in the system

All referral data is handled in compliance with HIPAA regulations and includes comprehensive tracking from submission through enrollment.

Base URLs

Environment Base URL
Development https://dev-api.aton.health/api/v1
Production https://api.aton.health/api/v1

Authentication

All endpoints require OAuth 2.0 authentication. Include your access token in the Authorization header:

Text Only
Authorization: Bearer {access_token}

See our authentication guide for details on obtaining access tokens.


Endpoints

Get All Referrals

Retrieves a list of all referrals successfully received by Aton Health from Outcomes.

HTTP
GET /referrals/

Request

Bash
curl -X GET "{base_url}/referrals/" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

Response

Returns a JSON array of referral objects with the following structure:

Field Type Description
outcomesId UUID Unique identifier for the referral (provided by Outcomes)
trialId string Unique identifier for the associated trial
versionId string Current version of the trial configuration
firstName string First name of the referred patient
lastName string Last name of the referred patient
phoneNumber string Phone number of the referred patient
email string Email address of the referred patient
zipCode string ZIP code of the referred patient
prescriberNPI string NPI number of the patient's prescriber
referralTimestamp string Referral date logged by Outcomes (MM/DD/YYYY)
receivedAt string Date/time Aton Health received the referral (ISO-8601 UTC)

Example Response

JSON
[
  {
    "outcomesId": "12345678-1234-1234-1234-891795972332",
    "trialId": "Aton_ColonoscopyPrep_20250930",
    "versionId": "Aton_ColonoscopyPrep_20250930v1",
    "firstName": "Ima",
    "lastName": "Person",
    "phoneNumber": "+1-555-123-4567",
    "email": "ima.person@example.com",
    "zipCode": "12345",
    "prescriberNPI": "1234567890",
    "referralTimestamp": "10/14/2025",
    "receivedAt": "2025-10-14T18:42:41.856829Z"
  }
]

Status Codes

Code Description
200 Success - Returns array of referrals
401 Unauthorized - Invalid or expired access token
403 Forbidden - Insufficient permissions
500 Internal Server Error

Get Referral by Outcomes ID

Retrieves a specific referral by its Outcomes ID within a particular trial.

HTTP
GET /referrals/{trial_id}/{outcomes_id}

Path Parameters

Parameter Type Required Description
trial_id string Yes Unique identifier for the clinical trial
outcomes_id string Yes Outcomes ID for the referral

Request

Bash
curl -X GET "{base_url}/referrals/{trial_id}/{outcomes_id}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

Example Request

Bash
curl -X GET "https://api.aton.health/api/v1/referrals/Aton_ColonoscopyPrep_20250930/12345678-1234-1234-1234-891795972005" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json"

Success Response (200 OK)

JSON
{
  "trialId": "Aton_ColonoscopyPrep_20250930",
  "outcomesId": "12345678-1234-1234-1234-891795972005",
  "participantName": "Jane Doe",
  "status": "enrolled"
}

Error Response (404 Not Found)

JSON
{
  "error": "Referral not found"
}

Status Codes

Code Description
200 Success - Referral found and returned
401 Unauthorized - Invalid or expired access token
403 Forbidden - Insufficient permissions
404 Not Found - No referral exists for the given IDs
500 Internal Server Error

Submit Referral

Submits a new patient referral to Aton Health for clinical trial matching.

HTTP
POST /referrals/

Request Body

Send a JSON object with the following required fields:

Field Type Required Description
outcomesId UUID Yes Unique identifier for the referral
trialId string Yes Unique identifier for the target trial
versionId string Yes Version of the trial configuration
firstName string Yes Patient's first name
lastName string Yes Patient's last name
phoneNumber string Yes Patient's phone number (E.164 format recommended)
email string Yes Patient's email address
zipCode string Yes Patient's ZIP code
prescriberNPI string Yes NPI number of the patient's prescriber
referralTimestamp string Yes Referral date in MM/DD/YYYY format

Example Request

Bash
curl -X POST "{base_url}/referrals/" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "outcomesId": "12345678-1234-1234-1234-123456789012",
    "trialId": "Aton_ColonoscopyPrep_20250930",
    "versionId": "Aton_ColonoscopyPrep_20250930v2",
    "firstName": "Jane",
    "lastName": "Doe",
    "phoneNumber": "+1-555-123-4567",
    "email": "jdoe@example.com",
    "zipCode": "12345",
    "prescriberNPI": "1234567890",
    "referralTimestamp": "10/14/2025"
  }'

Response

JSON
{
    "outcomesId": "12345678-1234-1234-1234-891795972803",
    "trialId": "Aton_ColonoscopyPrep_20250930",
    "altTrialId": "Aton_ColonoscopyPrep_20250930",
    "versionId": "Aton_ColonoscopyPrep_20250930v2",
    "firstName": "Michael",
    "lastName": "Scott",
    "phoneNumber": "+1-555-123-4567",
    "email": "mscott@example.com",
    "zipCode": "12345",
    "prescriberNPI": "1234567890",
    "referralTimestamp": "10/14/2025",
    "message": "Referral received",
    "warnings": [
        "Version mismatch: received 'Aton_ColonoscopyPrep_20250930v2', expected 'Aton_ColonoscopyPrep_20250930v1'"
    ]
}

⚠️ Version Mismatches

Referrals submitted with versionId values that do not match the current version of the given trialId are still accepted, but a warnings property with an appropriate message will be appended to the response.

Status Codes

Code Description
201 Created - Referral successfully submitted
400 Bad Request - Invalid request data or missing required fields
401 Unauthorized - Invalid or expired access token
403 Forbidden - Insufficient permissions
409 Conflict - Referral with same outcomesId already exists
422 Unprocessable Entity - Valid JSON but invalid field values
500 Internal Server Error

Qualified Referrals

These endpoints handle pre-qualified patient referrals that have already been confirmed as eligible for a study.

Submit Qualified Referral

Submits a pre-qualified patient referral to Aton Health.

HTTP
POST /referrals/qualified

Request Body

Send a JSON object with the following fields:

Field Type Required Description
firstName string Yes Patient's first name
middleName string No Patient's middle name
lastName string Yes Patient's last name
mobilePhone string Yes Mobile phone number, including country code
homePhone string No Home phone number
workPhone string No Work phone number
email string No Patient email address
birthday string Yes Date of birth in YYYY-MM-DD format
gender string Yes Male, Female, or Other
addressStreet1 string No Primary street address
addressStreet2 string No Secondary address line
addressCity string No City
addressState string No Province/State abbreviation
addressZip string No Postal or ZIP code
providerNpi string Yes Prescribing Provider's NPI
socAppointmentDate string Yes Scheduled colonoscopy appointment in ISO format
colonoscopyNaive boolean Yes Indicates if patient has never had prior colonoscopy
dateOfLastColonoscopy string No Date of last colonoscopy in YYYY-MM-DD format
ibdCrohns boolean Yes Whether patient has IBD or Crohn's
externalSourceId string Yes Unique ID from vendor system for traceability
noteTitle string Yes Title or subject of note
noteDescription string Yes Narrative or description of note

Example Request

Bash
curl -X POST "{base_url}/referrals/qualified" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Smith",
    "mobilePhone": "+1-555-123-4567",
    "email": "john.smith@example.com",
    "birthday": "1980-06-15",
    "gender": "Male",
    "addressStreet1": "123 Main Street",
    "addressCity": "Anytown",
    "addressState": "CA",
    "addressZip": "12345",
    "providerNpi": "1234567890",
    "socAppointmentDate": "2025-11-15T10:00:00Z",
    "colonoscopyNaive": true,
    "ibdCrohns": false,
    "externalSourceId": "DELFA-12345",
    "noteTitle": "Colonoscopy Prep Study Referral",
    "noteDescription": "Patient referred for colonoscopy preparation study participation"
  }'

Response

JSON
{
  "firstName": "John",
  "lastName": "Smith",
  "mobilePhone": "+1-555-123-4567",
  "email": "john.smith@example.com",
  "birthday": "1980-06-15",
  "gender": "Male",
  "addressStreet1": "123 Main Street",
  "addressCity": "Anytown",
  "addressState": "CA",
  "addressZip": "12345",
  "providerNpi": "1234567890",
  "socAppointmentDate": "2025-11-15T10:00:00Z",
  "colonoscopyNaive": true,
  "ibdCrohns": false,
  "externalSourceId": "DELFA-12345",
  "noteTitle": "Colonoscopy Prep Study Referral",
  "noteDescription": "Patient referred for colonoscopy preparation study participation",
  "message": "Qualified referral received"
}

Status Codes

Code Description
201 Created - Qualified referral successfully submitted
400 Bad Request - Invalid request data or missing required fields
401 Unauthorized - Invalid or expired access token
403 Forbidden - Insufficient permissions
422 Unprocessable Entity - Valid JSON but invalid field values
500 Internal Server Error

Get All Qualified Referrals

Retrieves all stored qualified referrals.

HTTP
GET /referrals/qualified

Request

Bash
curl -X GET "{base_url}/referrals/qualified" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

Response

Returns a JSON array of qualified referral objects including all submitted fields plus a receivedAt timestamp:

JSON
[
  {
    "firstName": "John",
    "lastName": "Smith",
    "mobilePhone": "+1-555-123-4567",
    "email": "john.smith@example.com",
    "birthday": "1980-06-15",
    "gender": "Male",
    "addressStreet1": "123 Main Street",
    "addressCity": "Anytown",
    "addressState": "CA",
    "addressZip": "12345",
    "providerNpi": "1234567890",
    "socAppointmentDate": "2025-11-15T10:00:00Z",
    "colonoscopyNaive": true,
    "ibdCrohns": false,
    "externalSourceId": "DELFA-12345",
    "noteTitle": "Colonoscopy Prep Study Referral",
    "noteDescription": "Patient referred for colonoscopy preparation study participation",
    "receivedAt": "2025-10-28T14:30:00.123456Z"
  }
]

Status Codes

Code Description
200 Success - Returns array of qualified referrals
401 Unauthorized - Invalid or expired access token
403 Forbidden - Insufficient permissions
500 Internal Server Error

Get Qualified Referral by External ID

Retrieves a specific qualified referral by its external source ID.

HTTP
GET /referrals/qualified/{external_source_id}

Path Parameters

Parameter Type Required Description
external_source_id string Yes External source ID for the referral

Request

Bash
curl -X GET "{base_url}/referrals/qualified/DELFA-12345" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

Success Response (200 OK)

JSON
{
  "firstName": "John",
  "lastName": "Smith",
  "mobilePhone": "+1-555-123-4567",
  "email": "john.smith@example.com",
  "birthday": "1980-06-15",
  "gender": "Male",
  "addressStreet1": "123 Main Street",
  "addressCity": "Anytown",
  "addressState": "CA",
  "addressZip": "12345",
  "providerNpi": "1234567890",
  "socAppointmentDate": "2025-11-15T10:00:00Z",
  "colonoscopyNaive": true,
  "ibdCrohns": false,
  "externalSourceId": "DELFA-12345",
  "noteTitle": "Colonoscopy Prep Study Referral",
  "noteDescription": "Patient referred for colonoscopy preparation study participation",
  "receivedAt": "2025-10-28T14:30:00.123456Z"
}

Error Response (404 Not Found)

JSON
{
  "detail": "Qualified referral not found"
}

Status Codes

Code Description
200 Success - Qualified referral found and returned
401 Unauthorized - Invalid or expired access token
403 Forbidden - Insufficient permissions
404 Not Found - No referral exists for the given ID
500 Internal Server Error

Code Examples

Python

Python
import requests
from datetime import datetime

class AtonReferralsAPI:
    def __init__(self, base_url, auth_client):
        self.base_url = base_url
        self.auth_client = auth_client

    def get_all_referrals(self):
        """Retrieve all referrals."""
        token = self.auth_client.get_access_token()

        response = requests.get(
            f"{self.base_url}/referrals/",
            headers={
                "Authorization": f"Bearer {token}",
                "Content-Type": "application/json"
            }
        )
        response.raise_for_status()
        return response.json()

    def get_referral_by_id(self, trial_id, outcomes_id):
        """Get a specific referral by trial ID and outcomes ID."""
        token = self.auth_client.get_access_token()

        response = requests.get(
            f"{self.base_url}/referrals/{trial_id}/{outcomes_id}",
            headers={
                "Authorization": f"Bearer {token}",
                "Content-Type": "application/json"
            }
        )
        response.raise_for_status()
        return response.json()

    def submit_referral(self, referral_data):
        """Submit a new referral."""
        token = self.auth_client.get_access_token()

        response = requests.post(
            f"{self.base_url}/referrals/",
            headers={
                "Authorization": f"Bearer {token}",
                "Content-Type": "application/json"
            },
            json=referral_data
        )
        response.raise_for_status()
        return response.json()

    def submit_qualified_referral(self, qualified_referral_data):
        """Submit a new qualified referral."""
        token = self.auth_client.get_access_token()

        response = requests.post(
            f"{self.base_url}/referrals/qualified",
            headers={
                "Authorization": f"Bearer {token}",
                "Content-Type": "application/json"
            },
            json=qualified_referral_data
        )
        response.raise_for_status()
        return response.json()

    def get_all_qualified_referrals(self):
        """Retrieve all qualified referrals."""
        token = self.auth_client.get_access_token()

        response = requests.get(
            f"{self.base_url}/referrals/qualified",
            headers={
                "Authorization": f"Bearer {token}",
                "Content-Type": "application/json"
            }
        )
        response.raise_for_status()
        return response.json()

    def get_qualified_referral_by_external_id(self, external_source_id):
        """Get a specific qualified referral by external source ID."""
        token = self.auth_client.get_access_token()

        response = requests.get(
            f"{self.base_url}/referrals/qualified/{external_source_id}",
            headers={
                "Authorization": f"Bearer {token}",
                "Content-Type": "application/json"
            }
        )
        response.raise_for_status()
        return response.json()

# Usage example
from aton_auth import AtonHealthAuth  # Your auth implementation

auth = AtonHealthAuth()
referrals_api = AtonReferralsAPI("https://api.aton.health/api/v1", auth)

# Get all referrals
all_referrals = referrals_api.get_all_referrals()
print(f"Found {len(all_referrals)} referrals")

# Submit a new referral
new_referral = {
    "outcomesId": "12345678-1234-1234-1234-123456789012",
    "trialId": "Aton_ColonoscopyPrep_20250930",
    "versionId": "Aton_ColonoscopyPrep_20250930v2",
    "firstName": "John",
    "lastName": "Smith",
    "phoneNumber": "+1-555-987-6543",
    "email": "john.smith@example.com",
    "zipCode": "54321",
    "prescriberNPI": "0987654321",
    "referralTimestamp": datetime.now().strftime("%m/%d/%Y")
}

result = referrals_api.submit_referral(new_referral)

# Submit a qualified referral
qualified_referral = {
    "firstName": "Jane",
    "lastName": "Doe",
    "mobilePhone": "+1-555-987-6543",
    "email": "jane.doe@example.com",
    "birthday": "1975-03-20",
    "gender": "Female",
    "addressStreet1": "456 Oak Avenue",
    "addressCity": "Springfield",
    "addressState": "IL",
    "addressZip": "62701",
    "providerNpi": "0987654321",
    "socAppointmentDate": "2025-12-01T14:30:00Z",
    "colonoscopyNaive": false,
    "dateOfLastColonoscopy": "2020-05-15",
    "ibdCrohns": false,
    "externalSourceId": "DELFA-67890",
    "noteTitle": "Pre-qualified Study Patient",
    "noteDescription": "Patient has been pre-screened and qualified for colonoscopy prep study"
}

qualified_result = referrals_api.submit_qualified_referral(qualified_referral)
print("Qualified referral submitted:", qualified_result["message"])

Node.js

JavaScript
const axios = require('axios');

class AtonReferralsAPI {
  constructor(baseUrl, authClient) {
    this.baseUrl = baseUrl;
    this.authClient = authClient;
  }

  async getAllReferrals() {
    const token = await this.authClient.getAccessToken();

    const response = await axios.get(`${this.baseUrl}/referrals/`, {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    });

    return response.data;
  }

  async getReferralById(trialId, outcomesId) {
    const token = await this.authClient.getAccessToken();

    const response = await axios.get(
      `${this.baseUrl}/referrals/${trialId}/${outcomesId}`,
      {
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        }
      }
    );

    return response.data;
  }

  async submitReferral(referralData) {
    const token = await this.authClient.getAccessToken();

    const response = await axios.post(
      `${this.baseUrl}/referrals/`,
      referralData,
      {
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        }
      }
    );

    return response.data;
  }

  async submitQualifiedReferral(qualifiedReferralData) {
    const token = await this.authClient.getAccessToken();

    const response = await axios.post(
      `${this.baseUrl}/referrals/qualified`,
      qualifiedReferralData,
      {
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        }
      }
    );

    return response.data;
  }

  async getAllQualifiedReferrals() {
    const token = await this.authClient.getAccessToken();

    const response = await axios.get(`${this.baseUrl}/referrals/qualified`, {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    });

    return response.data;
  }

  async getQualifiedReferralByExternalId(externalSourceId) {
    const token = await this.authClient.getAccessToken();

    const response = await axios.get(
      `${this.baseUrl}/referrals/qualified/${externalSourceId}`,
      {
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        }
      }
    );

    return response.data;
  }
}

// Usage example
const { AtonHealthAuth } = require('./aton-auth'); // Your auth implementation

const auth = new AtonHealthAuth();
const referralsAPI = new AtonReferralsAPI('https://api.aton.health/api/v1', auth);

// Get all referrals
referralsAPI.getAllReferrals()
  .then(referrals => console.log(`Found ${referrals.length} referrals`))
  .catch(error => console.error('Error:', error.message));

// Submit new referral
const newReferral = {
  outcomesId: '12345678-1234-1234-1234-123456789012',
  trialId: 'Aton_ColonoscopyPrep_20250930',
  versionId: 'Aton_ColonoscopyPrep_20250930v2',
  firstName: 'Jane',
  lastName: 'Doe',
  phoneNumber: '+1-555-123-4567',
  email: 'jane.doe@example.com',
  zipCode: '12345',
  prescriberNPI: '1234567890',
  referralTimestamp: new Date().toLocaleDateString('en-US')
};

referralsAPI.submitReferral(newReferral)
  .then(result => console.log('Referral submitted successfully:', result))
  .catch(error => console.error('Error submitting referral:', error.message));

// Submit qualified referral
const qualifiedReferral = {
  firstName: 'Michael',
  lastName: 'Johnson',
  mobilePhone: '+1-555-999-8888',
  email: 'michael.johnson@example.com',
  birthday: '1982-08-10',
  gender: 'Male',
  addressStreet1: '789 Pine Street',
  addressCity: 'Portland',
  addressState: 'OR',
  addressZip: '97201',
  providerNpi: '1122334455',
  socAppointmentDate: '2025-11-20T09:15:00Z',
  colonoscopyNaive: true,
  ibdCrohns: false,
  externalSourceId: 'DELFA-11223',
  noteTitle: 'Qualified Patient Referral',
  noteDescription: 'Patient meets all study criteria and is ready for enrollment'
};

referralsAPI.submitQualifiedReferral(qualifiedReferral)
  .then(result => console.log('Qualified referral submitted:', result.message))
  .catch(error => console.error('Error submitting qualified referral:', error.message));

Data Validation

Phone Number Format

  • Recommended: E.164 format (+1-555-123-4567)
  • Accepted: Various formats with country code

Email Validation

  • Must be a valid email address format
  • Aton Health will use this for patient communication

NPI Validation

  • Must be a valid 10-digit National Provider Identifier
  • Used to identify and validate the prescribing healthcare provider

Date Format

  • referralTimestamp: MM/DD/YYYY format
  • birthday: YYYY-MM-DD format
  • dateOfLastColonoscopy: YYYY-MM-DD format
  • socAppointmentDate: ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)

Gender Validation

  • Must be one of: Male, Female, or Other

Error Handling

Common Error Scenarios

400 Bad Request

JSON
{
  "error": "Bad Request",
  "message": "Missing required field: firstName",
  "details": {
    "missing_fields": ["firstName"]
  }
}

409 Conflict

JSON
{
  "error": "Conflict",
  "message": "Referral with outcomesId 12345678-1234-1234-1234-123456789012 already exists"
}

422 Unprocessable Entity

JSON
{
  "error": "Unprocessable Entity",
  "message": "Invalid field values",
  "details": {
    "invalid_fields": {
      "email": "Invalid email format",
      "birthday": "birthday must be in YYYY-MM-DD format",
      "gender": "gender must be one of: Male, Female, Other"
    }
  }
}

Best Practices for Error Handling

  1. Check HTTP status codes before processing responses
  2. Parse error messages for specific field validation issues
  3. Implement retry logic for temporary failures (5xx errors)
  4. Log error details for debugging and monitoring
  5. Validate data locally before submission to reduce API errors

Testing

Development Environment

Use the development environment for testing:

Bash
# Base URL for testing
https://dev-api.aton.health/api/v1

Test Data Guidelines

  • Use realistic but fictional patient data
  • Ensure phone numbers and emails are formatted correctly
  • Use proper date formats (YYYY-MM-DD for birthdays, ISO 8601 for appointments)
  • Test with both colonoscopy-naive and experienced patients

Need Help?

Contact our integration team at integration-support@atonhealth.com