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
  }
}

Playback Health Notes API (1.0.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude