# 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:


```http
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:


```json
{
    "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:


```http
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:


```http
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:


```http
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:


```http
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:


```http
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:


```http
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