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:
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.
Request
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
[
{
"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.
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
curl -X GET "{base_url}/referrals/{trial_id}/{outcomes_id}" \
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/json"
Example Request
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)
{
"trialId": "Aton_ColonoscopyPrep_20250930",
"outcomesId": "12345678-1234-1234-1234-891795972005",
"participantName": "Jane Doe",
"status": "enrolled"
}
Error Response (404 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.
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
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
{
"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
versionIdvalues that do not match the current version of the giventrialIdare still accepted, but awarningsproperty 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.
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
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
{
"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.
Request
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:
[
{
"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.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
external_source_id |
string | Yes | External source ID for the referral |
Request
curl -X GET "{base_url}/referrals/qualified/DELFA-12345" \
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/json"
Success Response (200 OK)
{
"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)
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
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
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, orOther
Error Handling
Common Error Scenarios
400 Bad Request
{
"error": "Bad Request",
"message": "Missing required field: firstName",
"details": {
"missing_fields": ["firstName"]
}
}
409 Conflict
{
"error": "Conflict",
"message": "Referral with outcomesId 12345678-1234-1234-1234-123456789012 already exists"
}
422 Unprocessable Entity
{
"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
- Check HTTP status codes before processing responses
- Parse error messages for specific field validation issues
- Implement retry logic for temporary failures (5xx errors)
- Log error details for debugging and monitoring
- Validate data locally before submission to reduce API errors
Testing
Development Environment
Use the development environment for testing:
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