Find answers to common questions about integrating with the Aton Health Patient Referrals API. If you can't find what you're looking for, contact our support team.

Getting Started

How do I get API access?

To get started with the Aton Health Patient Referrals API:

1. Contact our integration team at integration-support@atonhealth.com
2. Sign a partnership agreement covering data sharing and HIPAA compliance
3. Receive your credentials including Client ID, Client Secret, and Scope
4. Test in our sandbox environment before moving to production

Timeline: Initial setup typically takes 3-5 business days after agreement signing.

What credentials do I need?

For OAuth 2.0 authentication, you'll receive:

• Authentication URL: The URL used to request API access tokens.
• Client ID: Your application's unique identifier
• Client Secret: Secret key for authentication
• Scope: Permissions scope for Aton Health APIs

These credentials are provided separately for development and production environments.

Is there a sandbox environment?

Yes! We provide a full-featured development environment for testing:

• Development API: https://dev-api.aton.health/api/v1
• Same authentication flow using Microsoft Identity Platform
• Test data available for integration development
• No impact on production systems

Authentication

How long do access tokens last?

Access tokens expire approximately 1 hour after being issued. Your application should:

• Cache tokens and reuse them until near expiration
• Implement automatic refresh logic before tokens expire
• Handle 401 errors by refreshing tokens and retrying requests

What happens if my token expires during a request?

If your token expires during use:

1. API returns 401 Unauthorized
2. Your application should automatically request a new token
3. Retry the original request with the new token
4. Log the token refresh for monitoring purposes

Can I use API keys instead of OAuth 2.0?

OAuth 2.0 is our recommended and primary authentication method. API keys are available for legacy integrations but:

• OAuth 2.0 is more secure with automatic token expiration
• Better monitoring and auditing capabilities
• Future features may require OAuth 2.0

New integrations should use OAuth 2.0.

I'm getting "invalid_client" errors. What's wrong?

This usually indicates:

• Incorrect client ID or secret - verify credentials with our team
• Credentials for wrong environment - dev credentials won't work in production and vice versa

Solution: Double-check all credential values and contact support if issues persist.

API Usage

How should I handle rate limiting?

When you receive a 429 response:

1. Check the Retry-After header for recommended wait time
2. Implement exponential backoff for retries
3. Cache data when possible to reduce API calls
4. Contact support if limits are not appropriate for your use case

Can I submit multiple referrals simultaneously?

Currently, referrals must be submitted one at a time using individual POST requests to /referrals/.

Best practice: Implement retry logic and proper error handling for each submission.

How do I know if a referral was successfully submitted?

A successful referral submission returns:

• HTTP 201 Created status code
• Response body with confirmation details
• Unique tracking identifier for the referral

Failed submissions return appropriate error codes (400, 422, etc.) with detailed error messages.

What trial IDs should I use for referrals?

Always use the current active trial IDs from the /referrals/trials endpoint:

1. Fetch active trials regularly (recommended: every 5-15 minutes)
2. Validate trial ID before submitting referrals
3. Use the exact trialId value returned by the API

Don't hardcode trial IDs as they may change or become inactive.

Data and Integration

How should I format phone numbers?

Recommended format: E.164 international format (+1-555-123-4567)

Accepted formats:

• +1-555-123-4567 (preferred)
• +15551234567
• 555-123-4567 (US numbers)

Can I modify or cancel a referral after submission?

Currently, referrals cannot be modified or canceled through the API after submission.

To handle changes:

• Contact our support team for urgent modifications
• Ensure accuracy before submission
• Implement validation in your application

Technical Issues

I'm getting network timeouts. What should I do?

For timeout issues:

1. Check your network connection and firewall settings
2. Verify DNS resolution for api.aton.health and dev-api.aton.health
3. Implement appropriate timeouts (recommended: 30 seconds for API calls)
4. Add retry logic with exponential backoff
5. Contact your IT team if corporate firewall is blocking requests

The API is returning 500 errors. Is the service down?

Possibly. 500-level errors indicate server-side issues:

1. Try the request again after a brief wait
2. Implement retry logic for temporary failures
3. Contact support if errors persist longer than 15 minutes

How do I troubleshoot "malformed JSON" errors?

For JSON parsing errors:

1. Validate your JSON using online tools or your development environment
2. Check for special characters that need escaping
3. Ensure UTF-8 encoding for all requests
4. Review field data types match API specifications
5. Test with minimal payloads to isolate the issue

I'm not receiving expected data. What could be wrong?

Common causes of missing or unexpected data:

• Caching issues: Clear your application cache
• Environment mismatch: Verify you're using the correct API base URL
• Stale authentication: Refresh your access token
• Field changes: Check if the API response structure has changed
• Filtering: Verify you're not inadvertently filtering out data

HIPAA and Compliance

Is the Aton Health API HIPAA-compliant?

Yes, the Aton Health API is built to HIPAA standards:

• Encrypted data transmission (TLS 1.2+)
• Secure authentication with OAuth 2.0
• Audit logging of all API access
• Data retention policies per partnership agreements

Your responsibility: Ensure your application also maintains HIPAA compliance.

What are my HIPAA obligations as an API user?

As a covered entity or business associate:

• Implement appropriate safeguards (technical, administrative, physical)
• Maintain audit logs of patient data access
• Secure credential storage and access controls
• Follow data retention and deletion policies
• Report security incidents promptly

How is patient data secured in transit?

All API communications use:

• TLS 1.2 or higher encryption
• Certificate pinning for added security
• OAuth 2.0 bearer tokens for authentication
• No sensitive data in URLs or query parameters

Can I store API responses containing patient data?

Patient data storage must comply with:

• Your partnership agreement with Aton Health
• HIPAA requirements for data protection
• Local regulations and organizational policies
• Data retention limits as specified in agreements

Best practice: Only cache non-sensitive data and implement secure storage for any patient information.

Billing and Limits

Is there a cost for API access?

In most cases, no.

API pricing is determined by your partnership agreement with Aton Health. Contact integration-support@atonhealth.com for questions regarding API pricing.

Are there usage limits beyond rate limiting?

Usage limits depend on your partnership tier and agreement:

• Data access restrictions based on partnership scope
• Geographic limitations for certain trial types

Check your agreement or contact support for specific limits.

What happens if I exceed my usage limits?

If usage limits are exceeded:

• API may return 429 or 403 status codes
• Temporary service restrictions may apply

Getting Help

How do I report a bug or issue?

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

Please include the following in your message:

• Detailed error description
• Request/response examples (remove any sensitive data)
• Timestamp of the issue
• Your environment (dev/prod)
• Steps to reproduce

Where can I find code examples?

Code examples are available in our documentation:

• Authentication examples in Python, Node.js, .NET
• API Reference with basic details and links to additional endpoint documentation

Additional resources: Our support team can provide custom examples for your specific use case.

Still have questions?

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