Ritten API Integration

Python SDK for connecting applications to the Ritten EMR Platform. This library simplifies integration with Ritten's Behavioral Health Operations API, allowing developers to use Ritten API seamlessly from any Python environment.

Ritten API specifications:

• Documentation
• Version: 1

Installation

The SDK requires Python 3.10 or higher. Install it directly via pip:

pip install ritten-python-sdk

# Using poetry
poetry add ritten-python-sdk

# Using pipenv
pipenv install ritten-python-sdk

Quickstart Guide

To get started, you must first obtain your integrator client_id and client_secret from your Ritten administrator portal.

---

Resources

• Review the official Ritten API Documentation for explicit payload schemas.

API Coverage

Coverage against the Ritten OpenAPI specification (v1.0.0). Checked items are available in this SDK today; unchecked items are not yet implemented.

OAuth

• POST /oauth/token - Obtain an access token (client_credentials grant) - handled automatically by Ritten/Auth, no resource method needed

Patients

• GET /patients - List patients in a clinic
• POST /patients - Create a new patient
• GET /patients/{id} - Retrieve a patient by ID
• PATCH /patients/{id} - Update a patient by ID
• GET /patients/external/{externalId} - Retrieve a patient by external ID
• POST /patients/{id}/vitals - Record patient vitals
• GET /patients/{id}/relationships - List a patient's relationships
• POST /patients/{id}/relationships - Create a new patient relationship
• PATCH /patients/{id}/relationships/{relationshipId} - Update a patient relationship
• DELETE /patients/{id}/relationships/{relationshipId} - Delete a patient relationship
• POST /patients/{id}/attachments - Attach a document to a patient chart
• PATCH /patients/{id}/attachments/{attachmentId} - Update a document on a patient chart

Contacts

• GET /contacts - List contacts in a clinic
• POST /contacts - Create a new contact
• GET /contacts/{id} - Retrieve a contact by ID
• PATCH /contacts/{id} - Update a contact by ID
• GET /contacts/{id}/relationships - List a contact's relationships
• POST /contacts/{id}/relationships - Create a new contact relationship

Users

• GET /staff - List all clinic staff users
• POST /users - Create a new user
• DELETE /users/{id} - Delete a user
• POST /users/{id}/roles - Assign a role to a user
• DELETE /users/{id}/roles/{roleID} - Remove a role from a user
• POST /users/{id}/security-groups - Set a user's security groups
• GET /security-groups - List all security groups
• GET /teams - List all clinic teams

Calendar

• POST /calendar/events/list - Query calendar events
• POST /calendar/events - Create a new calendar event

Insurance

• GET /insurance/payers - List insurance payers
• GET /insurance/payers/{id} - Retrieve an insurance payer by ID

Encounters

• POST /encounters - Create an encounter
• GET /encounter-types - List encounter types

Forms

• GET /forms/definitions - List form definitions
• POST /patients/{id}/forms - Create a form on a patient chart and submit field values

Insights

• GET /insights/admissions - Get admissions report
• GET /insights/discharges - Get discharges report
• GET /insights/alos - Get average length of stay report
• GET /insights/program-census - Get program census report
• GET /insights/census-report - Get census report
• GET /insights/dbs - Get daily billable services report
• GET /insights/event-audit - Get event audit report
• GET /insights/facility-census - Get facility census report
• GET /insights/clinic-organizations - Get clinic organizations
• GET /insights/organization-notes - Get organization notes
• GET /insights/created-cases - Get created cases report
• GET /insights/disqualified-cases - Get disqualified cases report
• GET /insights/care-teams - Get care teams report
• GET /insights/encounter-history - Get encounter history report
• GET /insights/client-event-history - Get client event history report
• GET /insights/client-attendance-by-status - Get client attendance by status report
• GET /insights/all-transactions - Get the All Transactions report
• GET /insights/form-outcomes - Get form outcomes report

Cases

• GET /cases - List cases in a clinic
• POST /cases - Create a case
• GET /cases/{id} - Retrieve a case by ID
• PATCH /cases/{id} - Update a case
• POST /cases/{id}/notes - Create a case note
• POST /cases/{id}/action-items - Create a case action item

Facilities

• GET /facilities - List active facilities in a clinic
• POST /facilities - Create a facility in a clinic
• PATCH /facilities/{id} - Update a facility

Programs

• GET /programs - List active programs in a clinic
• POST /programs - Create a clinic program
• GET /programs/{id} - Get an active program
• PATCH /programs/{id} - Update a clinic program

Organizations

• GET /organizations - List active organizations in a clinic
• POST /organizations - Create an organization in a clinic
• GET /organizations/{id} - Get an active organization
• PATCH /organizations/{id} - Update an organization
• GET /organizations/{id}/members - List active organization members

Tasks

• GET /tasks - List tasks in a clinic
• POST /tasks - Create a task
• PATCH /tasks/{id} - Update a task

Calls

• POST /calls - Create or update a call

Webhooks (inbound events)

These are events Ritten sends to a receiver endpoint you host - they aren't operations the SDK calls, so there's nothing for a resource method to implement. Listed here for completeness; the SDK does not currently provide helpers for verifying or parsing incoming webhook payloads.

• patient.admit, patient.transfer, patient.discharge, patient.created
• case.created, case.status.update
• encounter.created, encounter.status.update
• appointment.created
• contact.created

About the Author

This SDK is developed and maintained by Wesley Gonçalves under MIT license. Contributions and feedback are welcome!