Skip to content
Last updated

Playback Health Notes API Documentation

This API provides endpoints for managing clinical notes and transcriptions. Below is a step-by-step guide on how to use the API.

Authentication

Step 1: Get Authorization Token

First, you need to authenticate to get a bearer token:

POST /api/v1/authorize
Content-Type: application/json

{
    "clientId": "your-client-id",
    "secret": "your-secret"
}

Note: To obtain API credentials (clientId and secret), please contact support@playbackhealth.com

The response will include an idToken that should be used as a bearer token in all subsequent requests:

{
    "idToken": "your.jwt.token"
}

Creating and Managing Notes

Step 2: Create a Note

Create a new note by specifying the template ID, language, and patient identifier:

POST /api/v1/notes
Authorization: Bearer your.jwt.token
Content-Type: application/json

{
    "templateId": "f7c4ae9b-49cb-4f5f-bf0e-80632b940fba",
    "language": "english",
    "patientId": "MRN123456"
}

Important Notes:

  1. Patient Identifier Flexibility:

    • For patientId, you can use any identifier from your system:
      • Medical Record Number (MRN)
      • EPIC ID
      • Your internal patient ID
      • Any other unique identifier
    • The same identifier can be used later to retrieve all notes or transcriptions for that patient
    • Be consistent with the identifier type across all API calls

  2. Response: The API will return:

    • A note ID
    • A pre-signed URL for uploading the audio file

Step 3: Upload Audio File

Use the pre-signed URL from the create note response to upload your .m4a audio file:

PUT <pre-signed-url>
Content-Type: audio/m4a

[Binary audio file content]

Step 4: Update Note Template

You can create a new version of the note using a different template:

POST /api/v1/notes/{noteId}/newtemplate
Authorization: Bearer your.jwt.token
Content-Type: application/json

{
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "language": "english"
}

Step 5: Retrieve Note

After the audio is processed, you can retrieve the note:

GET /api/v1/notes/{noteId}
Authorization: Bearer your.jwt.token

Searching and Filtering

Search Notes by Patient ID

Retrieve all notes for a specific patient using their identifier:

GET /api/v1/notes?patientId=MRN123456
Authorization: Bearer your.jwt.token

Get Transcriptions by Patient ID

Retrieve all transcriptions for a specific patient using their identifier:

GET /api/v1/transcriptions?patientId=MRN123456
Authorization: Bearer your.jwt.token

Note: Use the same patient identifier (e.g., MRN123456) that was used when creating the notes to ensure consistent results.

Additional Features

  • Filter transcriptions by date range using from and to parameters (format: YYYY-MM-DD)
  • Filter by language (english or spanish)
  • Filter by status (pending, success, error)
  • Pagination support using limit (default: 10, max: 100) and offset parameters

Rate Limits and Best Practices

  • Use appropriate pagination parameters to manage large result sets
  • Store the bearer token securely and refresh when needed
  • Include relevant filters to optimize response times
  • Use consistent patient identifiers across all API calls
  • When searching by patientId, use the exact same identifier format that was used during note creation

Support

For any issues or questions, please contact:

  • Email: support@playbackhealth.com
 
Next page