Skip to content

Playback Health Notes API (1.0.0)

REST APIs for managing clinical notes, transcriptions, and authentication

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Mock server
https://apidocs.playbackhealth.com/_mock/openapi/
Production server
https://api.public.playbackhealth.com/v1/

Get authentication token

Request

Authenticate a client using a client ID and secret to obtain an ID token. This endpoint is used for service-to-service authentication. The obtained token should be used as a Bearer token in subsequent API calls.

Bodyapplication/jsonrequired
clientIdstringrequired

Client identifier for authentication

Example: "internaluseradt@playbackhealth.com"
secretstringrequired

Secret key associated with the client

Example: "your-secret-key"
curl -i -X POST \
  https://apidocs.playbackhealth.com/_mock/openapi/authorize \
  -H 'Content-Type: application/json' \
  -d '{
    "clientId": "internaluseradt@playbackhealth.com",
    "secret": "internal-user-secret"
  }'

Responses

Authentication successful

Bodyapplication/json
idTokenstringrequired

JWT token to be used for subsequent API calls

Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Response
application/json
{
  "idToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkludGVybmFsIFVzZXIiLCJpYXQiOjE1MTYyMzkwMjJ9.abc123..."
}

Get list of notes

Request

Retrieve a paginated list of clinical notes. Supports filtering by date range and email address. Results are sorted by creation date in descending order.

Security
BearerAuth
Query
limitinteger[ 1 .. 100 ]

Number of notes to return per page

Default 10
Example: limit=10
offsetinteger>= 0

Number of notes to skip for pagination

Default 0
fromstring(date)

Start date for filtering notes (inclusive)

Example: from=2025-09-01
tostring(date)

End date for filtering notes (inclusive)

Example: to=2025-09-11
emailstring(email)

Filter notes by associated email address

Example: email=doctor@playbackhealth.com
patientIdstring

Filter notes by patient identifier (e.g., MRN, EPIC ID, or your internal patient ID). This should match the identifier used when creating the note.

Example: patientId=MRN123456
curl -i -X GET \
  'https://apidocs.playbackhealth.com/_mock/openapi/notes?limit=10&offset=0&from=2025-09-01&to=2025-09-11&email=doctor%40playbackhealth.com&patientId=MRN123456' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

List of notes retrieved successfully

Bodyapplication/json
successbooleanrequired
Example: true
dataArray of objectsrequired
Example: [{"noteId":"550e8400-e29b-41d4-a716-446655440000","titleText":"Patient Follow-up Notes","createdAt":"2025-09-11T10:00:00Z","email":"doctor@playbackhealth.com"},{"noteId":"660e8400-e29b-41d4-a716-446655440001","titleText":"Initial Consultation","createdAt":"2025-09-10T15:30:00Z","email":"doctor@playbackhealth.com"}]
data[].​noteIdstring(uuid)required
Example: "550e8400-e29b-41d4-a716-446655440000"
data[].​titleTextstringrequired
Example: "Patient Follow-up Notes"
data[].​createdAtstring(date-time)required
Example: "2025-09-11T10:00:00Z"
data[].​emailstring(email)required
Example: "doctor@playbackhealth.com"
data[].​patientIdstring

Patient identifier (e.g., MRN, EPIC ID, or your internal patient ID). This matches the identifier used when creating the note.

Example: "MRN123456"
paginationobjectrequired
Example: {"limit":10,"offset":0,"total":45}
pagination.​limitinteger[ 1 .. 100 ]required
Example: 10
pagination.​offsetinteger>= 0required
Example: 0
pagination.​totalinteger>= 0required
Example: 45
Response
application/json
{
  "success": true,
  "data": [
    { … },
    { … }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 45
  }
}

Create a new note

Request

Create a new clinical note with optional template and language settings. Returns a pre-signed URL for uploading an audio file. Creates both note and transcription entries, with transcription content to be populated later. The providerId is automatically set from the authenticated user's token.

Security
BearerAuth
Bodyapplication/jsonrequired
templateIdstring(uuid)

Template ID to use for the note

Example: "f7c4ae9b-49cb-4f5f-bf0e-80632b940fba"
languagestring

Language of the note content

Default "english"
Enum"english""spanish"
Example: "english"
patientIdstring

Any identifier for the patient from your system (e.g., MRN, EPIC ID, or your internal patient ID). This same identifier can be used later to retrieve notes or transcriptions for the patient.

Example: "MRN123456"
audioChunkCountinteger

Number of audio chunks to upload. When provided and greater than 0, enables chunked upload mode

Example: 5
addContextobject

Additional patient context data to store as JSON in S3

Example: {"patientHistory":"Previous back pain episodes in 2020","allergies":["Penicillin","Latex"],"medications":["Ibuprofen 200mg daily"],"symptoms":["Lower back pain","Morning stiffness"],"notes":"Patient prefers morning appointments"}
curl -i -X POST \
  https://apidocs.playbackhealth.com/_mock/openapi/notes \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "templateId": "f7c4ae9b-49cb-4f5f-bf0e-80632b940fba",
    "language": "english",
    "patientId": "MRN123456"
  }'

Responses

Note created successfully

Bodyapplication/json
One of:
idstring(uuid)required

Unique identifier for the created note

Example: "550e8400-e29b-41d4-a716-446655440000"
urlstringrequired

Pre-signed URL for single file upload (when audioChunkCount is not provided or ≤ 0)

Example: "https://storage.playbackhealth.com/notes/550e8400-e29b-41d4-a716-446655440000/recording-final.m4a?signed=xyz"
Response
application/json

Response when audioChunkCount is not provided or ≤ 0

{
  "id": "f7c4ae9b-49cb-4f5f-bf0e-80632b940fba",
  "url": "https://storage.playbackhealth.com/notes/550e8400-e29b-41d4-a716-446655440000/recording-final.m4a?signed=xyz"
}

Get a specific note

Request

Retrieve a specific clinical note by its ID. Returns the note's content and metadata.

Security
BearerAuth
Path
idstring(uuid)required

Unique identifier of the note

Example: 550e8400-e29b-41d4-a716-446655440000
curl -i -X GET \
  https://apidocs.playbackhealth.com/_mock/openapi/notes/550e8400-e29b-41d4-a716-446655440000 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Note retrieved successfully

Bodyapplication/json
notestringrequired

The clinical note content

Example: "Patient presented with..."
statusstringrequired

Current status of the note

Enum"pending""success""error"
Example: "success"
createdAtstring(date-time)required

Note creation timestamp

Example: "2025-09-11T10:00:00Z"
templateobject or null

Template information used for the note

Example: {"name":"Clinical Note Template","id":"550e8400-e29b-41d4-a716-446655440000"}
noteObjectobject or null

Structured note object data

Example: null
languagestring

Language of the note (e.g., english, spanish)

Example: "english"
billingCodesobject

Clinical billing codes (CPT and ICD codes) associated with the note

Example: {"status":"success","cptCodes":[{"code":"99213","active":true,"reason":"Comprehensive examination performed","thumbs":null,"confidence":0.9,"description":"Office visit, established patient","sourceSentence":["On examination findings..."]}],"icdCodes":[{"code":"J20.8","active":true,"reason":"Provider diagnoses viral bronchitis","thumbs":null,"confidence":0.85,"description":"Acute bronchitis due to other specified organisms","sourceSentence":["Patient reports symptoms..."]}]}
Response
application/json
{
  "note": "Patient presented with mild discomfort in lower back. Prescribed physical therapy and follow-up in 2 weeks.",
  "status": "success",
  "createdAt": "2025-09-11T10:00:00Z",
  "template": {
    "name": "Clinical Note Template",
    "id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "noteObject": null,
  "language": "english",
  "billingCodes": {
    "status": "success",
    "cptCodes": [ … ],
    "icdCodes": [ … ]
  }
}

Get transcription for a note

Request

Retrieve the transcription of a clinical note's audio recording. Returns both raw text and structured transcription data with timestamps.

Security
BearerAuth
Path
idstring(uuid)required

Unique identifier of the note

Example: 550e8400-e29b-41d4-a716-446655440000
curl -i -X GET \
  https://apidocs.playbackhealth.com/_mock/openapi/notes/550e8400-e29b-41d4-a716-446655440000/transcription \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Transcription retrieved successfully

Bodyapplication/json
textstringrequired

Raw transcription text

Example: "Patient reports experiencing mild discomfort in the lower back..."
objectobjectrequired

Structured transcription data

Example: {"segments":[{"start":0,"end":15.2,"text":"Patient reports experiencing mild discomfort"},{"start":15.2,"end":30.5,"text":"in the lower back region for the past two days"}]}
object.​segmentsArray of objects
Example: [{"start":0,"end":15.2,"text":"Patient reports experiencing mild discomfort"},{"start":15.2,"end":30.5,"text":"in the lower back region for the past two days"}]
createdAtstring(date-time)required
Example: "2025-09-11T10:00:00Z"
Response
application/json
{
  "text": "Patient reports experiencing mild discomfort in the lower back region for the past two days. No radiating pain or numbness. Patient denies any recent injury or trauma.",
  "object": {
    "segments": [ … ]
  },
  "createdAt": "2025-09-11T10:00:00Z"
}

Get billing codes for a note

Request

Retrieve clinical billing codes (CPT and ICD codes) for a specific note. Returns both CPT (Current Procedural Terminology) and ICD (International Classification of Diseases) codes.

Security
BearerAuth
Path
idstring(uuid)required

Unique identifier of the note

Example: 550e8400-e29b-41d4-a716-446655440000
curl -i -X GET \
  https://apidocs.playbackhealth.com/_mock/openapi/notes/550e8400-e29b-41d4-a716-446655440000/billingcodes \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Billing codes retrieved successfully

Bodyapplication/json
successbooleanrequired
Example: true
statusstringrequired

Status of the clinical coding data

Enum"processing""success"
Example: "success"
cptCodesArray of objectsrequired

Current Procedural Terminology codes with detailed information

cptCodes[].​codestringrequired

CPT code

Example: "99213"
cptCodes[].​activebooleanrequired

Whether the code is active/applicable

Example: true
cptCodes[].​reasonstring or null

Reason for the code assignment

Example: "Comprehensive examination performed with moderate complexity decision making for established problem"
cptCodes[].​thumbsstring or null

User feedback on code accuracy

Example: null
cptCodes[].​confidencenumber(float)[ 0 .. 1 ]required

AI confidence score for the code assignment

Example: 0.9
cptCodes[].​descriptionstringrequired

Human-readable description of the code

Example: "Office visit, established patient, low to moderate complexity"
cptCodes[].​sourceSentenceArray of strings
Example: ["On facial examination, there's mild pain to palpation of the frontal sinuses bilaterally."]
icdCodesArray of objectsrequired

International Classification of Diseases codes with detailed information

icdCodes[].​codestringrequired

ICD code

Example: "J20.8"
icdCodes[].​activebooleanrequired

Whether the code is active/applicable

Example: true
icdCodes[].​reasonstring or null

Reason for the code assignment

Example: "Provider explicitly diagnoses viral bronchitis based on symptoms and examination findings"
icdCodes[].​thumbsstring or null

User feedback on code accuracy

Example: null
icdCodes[].​confidencenumber(float)[ 0 .. 1 ]required

AI confidence score for the code assignment

Example: 0.85
icdCodes[].​descriptionstringrequired

Human-readable description of the code

Example: "Acute bronchitis due to other specified organisms"
icdCodes[].​sourceSentenceArray of strings
Example: ["So for your cough, I do believe that you most likely just have a viral syndrome, like a viral bronchitis."]
Response
application/json
{
  "success": true,
  "status": "success",
  "cptCodes": [
    { … }
  ],
  "icdCodes": [
    { … },
    { … }
  ]
}

Finish a note

Request

Marks a note as finished by uploading an empty audio file to S3. This endpoint validates the note ID format, checks user access to the note, and uploads an empty audio file to trigger note processing. The note must belong to the authenticated user's enterprise.

Security
BearerAuth
Path
idstring(uuid)required

Unique identifier of the note to finish (must be valid UUID format)

Example: 550e8400-e29b-41d4-a716-446655440000
curl -i -X POST \
  https://apidocs.playbackhealth.com/_mock/openapi/notes/550e8400-e29b-41d4-a716-446655440000/finish \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Note finished successfully

Bodyapplication/json
successbooleanrequired
Example: true
Response
application/json
{
  "success": true
}

Get list of transcriptions

Request

Retrieve a paginated list of transcriptions. Supports filtering by date range, status, and language. Results are sorted by creation date in descending order.

Security
BearerAuth
Query
limitinteger[ 1 .. 100 ]

Number of transcriptions to return per page

Default 10
Example: limit=10
offsetinteger>= 0

Number of transcriptions to skip for pagination

Default 0
fromstring(date)

Start date for filtering transcriptions (inclusive)

Example: from=2025-09-01
tostring(date)

End date for filtering transcriptions (inclusive)

Example: to=2025-09-11
statusstring

Filter by transcription status

Enum"pending""success""error"
Example: status=success
languagestring

Filter by transcription language

Enum"english""spanish"
Example: language=english
noteIdstring(uuid)

Filter by associated note ID

Example: noteId=550e8400-e29b-41d4-a716-446655440000
patientIdstring

Filter transcriptions by patient identifier (e.g., MRN, EPIC ID, or your internal patient ID). This should match the identifier used when creating the note.

Example: patientId=MRN123456
curl -i -X GET \
  'https://apidocs.playbackhealth.com/_mock/openapi/transcriptions?limit=10&offset=0&from=2025-09-01&to=2025-09-11&status=success&language=english&noteId=550e8400-e29b-41d4-a716-446655440000&patientId=MRN123456' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

List of transcriptions retrieved successfully

Bodyapplication/json
successbooleanrequired
Example: true
dataArray of objectsrequired
Example: [{"id":"550e8400-e29b-41d4-a716-446655440000","text":"Patient reports experiencing mild discomfort in the lower back...","createdAt":"2025-09-11T10:00:00Z","noteId":"660e8400-e29b-41d4-a716-446655440001","status":"success","language":"english"},{"id":"770e8400-e29b-41d4-a716-446655440002","text":"Follow-up visit for previous back pain complaint...","createdAt":"2025-09-10T15:30:00Z","noteId":"880e8400-e29b-41d4-a716-446655440003","status":"success","language":"english"}]
data[].​idstring(uuid)required

Unique identifier for the transcription

Example: "550e8400-e29b-41d4-a716-446655440000"
data[].​textstringrequired

Raw transcription text

Example: "Patient reports experiencing mild discomfort..."
data[].​createdAtstring(date-time)required

When the transcription was created

Example: "2025-09-11T10:00:00Z"
data[].​noteIdstring(uuid)required

ID of the associated note

Example: "660e8400-e29b-41d4-a716-446655440001"
data[].​statusstring

Current status of the transcription

Enum"pending""success""error"
Example: "success"
data[].​languagestring

Language of the transcription (e.g., english, spanish)

Example: "english"
paginationobjectrequired
Example: {"limit":10,"offset":0,"total":45}
pagination.​limitinteger[ 1 .. 100 ]required
Example: 10
pagination.​offsetinteger>= 0required
Example: 0
pagination.​totalinteger>= 0required
Example: 45
Response
application/json
{
  "success": true,
  "data": [
    { … },
    { … }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 45
  }
}