# Amplifier Health — User Guide This guide explains how to build applications against the Amplifier Health voice biomarker API. It covers what the API does, how to choose between endpoints, the async job flow, the available use case bundles and models, audio requirements, how to interpret results, and what to verify before going to production. For exact request shapes, response field types, enumerations, and error codes, see the companion **[API Reference](api-reference.md)**. --- ## 1. What it is The Amplifier Health API analyzes acoustic properties of a speaker's voice and returns structured health signals — numeric scores, categorical levels, and workflow-oriented fields — across behavioral, cognitive, metabolic, and respiratory conditions. It is delivered over HTTPS at `https://api.amplifierhealth.com` and authenticated with a per-account `X-Account-ID` plus `X-API-Key` header pair. Three concepts drive every integration: - **Signal** — One model's output for a recording. A signal is described by `model_id`, a numeric `score` (0.0–1.0), a categorical `level`, and a `flagged` boolean. - **Level** — A discrete display primitive: `none`, `low`, `consider`, `moderate`, `elevated`, or `inconclusive`. Use `level` (not raw `score`) for routing and UI. - **Recommended action** — A workflow primitive aggregated across signals (for use-case responses) or derived from a single signal (for condition responses): `none`, `monitor`, `consider`, `review`, `escalate`, or `inconclusive`. ### Evidence tiers Each model carries one of three evidence tiers that describe the **depth of published academic and scientific research** behind that voice biomarker: - **Established** — Three or more peer-reviewed studies; findings replicated across two or more independent research groups; at least one prospective or large-scale validation. Best for workflows that require the strongest published evidence base. - **Emerging** — Published peer-reviewed evidence with replication, but not yet at clinical-validation scale. Suitable for research partnerships, pilots, and validation studies. - **Investigational** — Acoustically plausible mechanism with physiological rationale; no peer-reviewed voice-specific detection study published. Use for exploratory research, hypothesis generation, and supplementary data streams. Tiers describe research depth — they are not a separate commercial tier, contract, or entitlement. ### As-is All models and API outputs are provided **as-is**. This disclaimer is stated once, here. The API reports voice-derived signals to support workflow routing; clinical decisions belong with qualified care staff. ### Security The platform is **Secure by Design**: traffic is encrypted in transit and at rest. Credentials should be kept in a secrets manager and never embedded in client-side code or committed to source control. ### Migrating from v1 If you are integrating with v1, see the v1-to-v2 migration guide at . --- ## 2. Choosing an endpoint The v2 API exposes two analyze endpoints. Both use `multipart/form-data` with an `audio` file plus a selector field, both return a job object immediately, and both are retrieved later via `GET /v2/jobs/{job_id}` or webhook. | Endpoint | Selector field | Returns | Best for | |---|---|---|---| | `POST /v2/use-case/analyze` | `use_case` | `summary` + `signals[]` + aggregated `recommended_action` | Out-of-the-box workflows that fit one of the eight pre-built bundles | | `POST /v2/condition/analyze` | `condition` | A single `signal` object with its own `recommended_action` and `description` | Custom analysis logic — call multiple conditions and compose your own aggregation | ### Decision tree ``` Does an existing use case bundle match your scenario? ├── Yes → POST /v2/use-case/analyze with the matching `use_case` ID. │ One call returns a summary + per-model signals + a single recommended_action. └── No → POST /v2/condition/analyze, one call per model_id. Aggregate the per-condition signals in your application. ``` Prefer the use-case bundle when one exists for your context — bundles are configured with the models most validated for their respective populations, which improves both precision and the clinical relevance of `recommended_action`. Use the condition endpoint only when your population or scenario does not match any existing bundle, or when you need to compose a custom set of models. For exact request fields and curl examples, see [API Reference §2 (use-case)](api-reference.md#post-v2use-caseanalyze) and [§3 (condition)](api-reference.md#post-v2conditionanalyze). --- ## 3. Job flow Both analyze endpoints are **asynchronous**. Submit returns a job object right away with `status: running` and `result: null`. Retrieve the completed result by polling `GET /v2/jobs/{job_id}` or by configuring a webhook. Terminal states are `done` and `failed`: - **`done`** — `result` contains the full analysis. - **`failed`** — `result` is typically `null`. `completed_at` may also be `null`. For a valid `job_id` on your account, the API returns `200 OK` with the job object — failure is expressed in `status`, not via a 4xx HTTP code. If you need the failure reason, check your operational logs or contact support. Non-terminal states are `pending` and `running`. Poll at 2–5 second intervals; most jobs complete within a few seconds, longer recordings can take up to ~30 seconds (longer with diarization). ### End-to-end example (use case) ```bash # Step 1 — submit audio curl -X POST https://api.amplifierhealth.com/v2/use-case/analyze \ -H "X-Account-ID: $AMPLIFIER_ACCOUNT_ID" \ -H "X-API-Key: $AMPLIFIER_API_KEY" \ -F "use_case=behavioral-health" \ -F "audio=@recording.wav;type=audio/wav" ``` Submit response (the same job object shape as `GET /v2/jobs/{job_id}`, with `status: running` and `result: null`): ```json { "job_id": "189bce4a-52cb-4e60-8586-cef89e719109", "status": "running", "created_at": "2026-02-22T09:14:00Z", "completed_at": null, "result": null, "audio_content_type": "audio/wav", "audio_size_bytes": 876032, "audio_duration_seconds": 27.4, "audio_sample_rate": 16000, "job_type": "use_case", "api_version": "v2", "use_case": "behavioral-health", "condition": null } ``` ```bash # Step 2 — poll until status is done or failed curl https://api.amplifierhealth.com/v2/jobs/189bce4a-52cb-4e60-8586-cef89e719109 \ -H "X-Account-ID: $AMPLIFIER_ACCOUNT_ID" \ -H "X-API-Key: $AMPLIFIER_API_KEY" ``` Completed response (abbreviated): ```json { "job_id": "189bce4a-52cb-4e60-8586-cef89e719109", "status": "done", "completed_at": "2026-02-22T09:14:03Z", "use_case": "behavioral-health", "result": { "summary": { "overall_level": "elevated", "recommended_action": "escalate", "flagged_count": 3, "primary_signals": ["depression", "anxiety", "acute-stress"], "description": { "summary": "...", "vocal_features": [ ... ] } }, "signals": [ {"model_id": "depression", "label": "Depression", "score": 0.81, "level": "elevated", "flagged": true}, {"model_id": "anxiety", "label": "Anxiety", "score": 0.71, "level": "elevated", "flagged": true}, {"model_id": "acute-stress","label": "Acute Stress & Nervousness","score": 0.54,"level": "consider","flagged": true} ], "audio_quality": { "issues": [], "voice_percentage": 82.4, "audio_clarity": 74.1 }, "extended_metrics": [ ... ] } } ``` ### Webhook delivery As an alternative to polling, configure a webhook so the API pushes the completed job to your server. Two configuration levels are available: - **Account-level** — `POST /v2/account/webhook` sets a default `url` and `secret_key` for all jobs on the account. - **Per-request** — pass `webhook_url` and `webhook_secret_key` form fields on the analyze request to override the account default for that job. When delivery happens, the API sends an HTTP POST to your URL with the completed job payload (`job_id`, `status`, `use_case`/`condition`, `result`). The body is signed with `X-Webhook-Signature` (HMAC-SHA256 of the raw body, computed with your `secret_key`). Verify the signature with a constant-time comparison before processing. Delivery retries up to 5 times with increasing delays if your endpoint returns a non-2xx status or does not respond within 30 seconds. See [API Reference §6 (Webhook payload)](api-reference.md#webhook-payload). ### Timestamps `created_at` and `completed_at` are ISO 8601 / RFC 3339-compatible. Formatting varies between responses: a `Z` suffix or a numeric offset may or may not be present, and fractional seconds may appear with variable precision. Use a standard ISO 8601 datetime parser; do not string-compare timestamps. Treat values without a designator as UTC. --- ## 4. Use cases Eight `use_case` IDs select fixed bundles of models. The list order below is identical to [API Reference §8 (Enumerations)](api-reference.md#enumerations). | `use_case` | When to pick | |---|---| | `behavioral-health` | General behavioral health screening — primary care, teletherapy, employee mental health. Signals: depression, anxiety, acute stress & nervousness, PTSD, ADHD, fatigue. | | `substance-use` | Recovery programs, behavioral health practices, outpatient substance use treatment. Signals: alcohol use disorder, psychoactive substance use, depression, anxiety, acute stress, fatigue. | | `womens-health` | Women's health platforms, OB/GYN practices, hormonal health programs. Signals: hyperandrogenism (PCOS), anemia, dehydration, depression-female, anxiety-female, fatigue, elevated blood pressure. | | `wellness` | General wellness and readiness monitoring; employer-sponsored wellness, EAP, daily check-ins. Signals: fatigue & malaise, acute stress, dehydration, depression, anxiety, elevated blood pressure. | | `athletics-occupational` | Sports medicine, athletic training, occupational health. Signals: traumatic brain injury, cognitive impairment, fatigue, dehydration, acute stress, anxiety, elevated blood pressure. | | `cognitive` | Cognitive health platforms, neurology practices, brain health programs, ADHD management. Signals: cognitive impairment. | | `cardiometabolic` | Cardiometabolic risk screening; metabolic conditions detectable through voice acoustics. Signals: elevated blood pressure, overweight & obesity, dehydration, anemia, dry mouth, fatigue. | | `respiratory` | Chronic respiratory issues — telemedicine triage, between-appointment check-ins, respiratory research. Signals: COPD, allergy. | Each bundle may also run additional contextual models that inform the analysis without being exposed as primary signals. If no bundle matches your population, prefer composing your own logic with `POST /v2/condition/analyze` rather than picking a near-fit. To request a custom bundle, contact . --- ## 5. Models Each `model_id` corresponds to one entry in the `signals` array of a use-case response, or to the singular `signal` object in a condition response. | `model_id` | Label | Tier | In use case bundles | |---|---|---|---| | `acute-stress` | Acute Stress & Nervousness | Established | behavioral-health, substance-use, wellness, athletics-occupational | | `adhd` | ADHD | Emerging | behavioral-health | | `alcohol-use` | Alcohol Use Disorder | Emerging | substance-use | | `allergy` | Allergy | Emerging | respiratory | | `anemia` | Anemia | Investigational | womens-health, cardiometabolic | | `anxiety` | Anxiety | Established | behavioral-health, substance-use, wellness, athletics-occupational | | `anxiety-female` | Anxiety (Female) | Established | womens-health | | `cognitive-impairment` | Cognitive Impairment | Established | athletics-occupational, cognitive | | `copd` | COPD | Established | respiratory | | `dehydration` | Dehydration | Investigational | wellness, athletics-occupational, womens-health, cardiometabolic | | `depression` | Depression | Established | behavioral-health, substance-use, wellness | | `depression-female` | Depression (Female) | Established | womens-health | | `dry-mouth` | Dry Mouth | Investigational | cardiometabolic | | `elevated-blood-pressure` | Elevated Blood Pressure | Established | wellness, athletics-occupational, womens-health, cardiometabolic | | `fatigue` | Fatigue & Malaise | Established | behavioral-health, substance-use, wellness, athletics-occupational, womens-health, cardiometabolic, respiratory | | `hyperandrogenism` | Hyperandrogenism (PCOS) | Emerging | womens-health | | `overweight-obesity` | Overweight & Obesity | Emerging | cardiometabolic | | `ptsd` | PTSD | Emerging | behavioral-health | | `substance-use` | Psychoactive Substance Use | Emerging | substance-use | | `traumatic-brain-injury` | Traumatic Brain Injury | Established | athletics-occupational | Use the same `model_id` value with `POST /v2/condition/analyze` to analyze a single condition outside of a bundle. ### Wellness metrics (extended_metrics) Some bundles also return a `result.extended_metrics[]` array of wellness metric scores — emotional and behavioral dimensions of the voice such as mood, stress, energy, and personality traits. Each entry has `metric_id`, `label`, `score_mean`, `score_std`, and `low_anchor` / `high_anchor` words that describe the ends of the scale. The set of metrics returned depends on the `use_case`. See [API Reference §7 (Schemas — extended_metrics)](api-reference.md#extended_metrics-array) for the field shape. --- ## 6. Audio requirements ### Formats and limits | Constraint | Value | |---|---| | Supported formats | WAV, FLAC, MP3 | | Maximum file size | 32 MB per upload | | Minimum duration | 15 seconds | | Maximum duration | 20 minutes (1200 seconds) | For longer recordings, **MP3** or **FLAC** typically keep the file under the 32 MB limit while preserving good analysis quality. Submitting an unsupported format returns `UNSUPPORTED_FORMAT` with HTTP `400`. ### Duration guidance | Duration | Outcome | |---|---| | < 15 seconds | `400 Bad Request` (`AUDIO_TOO_SHORT`); submit a recording of at least 15 seconds. | | 15–19 seconds | Processed; check `audio_quality` for guidance on use. Recordings on the shorter end are more likely to produce `insufficient_speech` issues. | | 20–120 seconds | Recommended range for best results. | | 2–20 minutes | Accepted; longer recordings have longer processing times. | | > 20 minutes | `400 Bad Request` (`AUDIO_TOO_LONG`); trim before submitting. | ### Sample rate and channels Record at **16 000 Hz mono** when possible. The API accepts 8 000 Hz minimum and downsamples higher rates internally. Stereo input is auto-downmixed to mono; mixing to mono before submission is still preferred. ### Recording environment The acoustic environment affects every model. To get the best results: - Record in a quiet space; eliminate fans, HVAC, notifications, and echo. - Use a close-proximity microphone (headset, lavalier, or phone handset held close). Avoid speakerphone or far-field microphones. - Keep input gain such that peaks are around -6 dBFS. Avoid clipping. - Capture a single speaker per recording — the subject being assessed, not a clinician or interviewer. Before deploying in a new environment, test recording levels with a sample recording and verify `audio_quality.issues` is empty. ### Speaker diarization Pass `diarize=true` on either analyze endpoint to enable speaker separation for multi-speaker recordings. The diarizer identifies each speaker and runs analysis on their voice segments separately. Single-speaker recordings analyzed with `diarize=true` still work, but diarization adds a flat 50 tokens to the cost (see §9). ### Language support Models are currently trained on **English-language speech**. Verify language support for your target population before deploying with audio in other languages — submitting unsupported-language audio can return signal values without a quality warning. Contact for the current language matrix. ### Audio quality issue codes When the API detects recording problems, it returns codes in `result.audio_quality.issues`. Results may still be returned alongside issues — use the codes to decide whether to use the result or re-record. **This is the canonical definition; the API Reference lists these codes only and links back here.** | Code | Condition | Recommended action | |---|---|---| | `poor_voice_quality` | Recording conditions may be below optimal for analysis. | Re-record in a quieter environment with a better microphone. | | `insufficient_speech` | Limited speech detected; more continuous speech may improve results. | Re-record with more active continuous speech; eliminate long pauses. | | `high_background_noise` | Background noise may affect analysis quality. | Re-record in a quieter space or with a closer microphone. | | `invalid_speaker` | No clear single-speaker human speech detected. | Verify the recording contains the intended speaker's voice; request a new recording before routing on the result. | For critical routing decisions, prefer re-recording when quality issues are present. `audio_quality` also includes two scalar scores (each 0–100, or `null`): - `voice_percentage` — percentage of the recording containing active speech. Values below 30 typically correspond to an `insufficient_speech` issue. - `audio_clarity` — background-noise quality score derived from SI-SDR. Higher values indicate a clearer recording. Values below 50 typically correspond to a `high_background_noise` issue. --- ## 7. Interpreting results ### Levels Levels are applied to individual models in the `signals` array and to `overall_level` in `summary`. **This is the canonical definition; the API Reference lists these values only and links back here.** | Level | Description | |---|---| | `none` | Signal not detected at a meaningful threshold. | | `low` | Faint signal detected. Monitor for changes. | | `consider` | Signal worth considering. Review alongside other clinical context. | | `moderate` | Signal present. Provider review indicated. | | `elevated` | Signal present at the highest level. Trigger your escalation workflow. | | `inconclusive` | Analysis inconclusive or incomplete (for example, limited speech or notable `audio_quality` issues); prefer re-recording or collecting more information before routing. | Score-to-level mapping uses a distribution-based calibration unique to each model, rather than fixed numeric ranges. The score value corresponding to each level varies by model. Use `level` — not raw `score` — for routing and display logic. ### Recommended actions `recommended_action` is determined by evaluating the full set of signal levels for use-case responses, or from the single signal level for condition responses. **This is the canonical definition; the API Reference lists these values only and links back here.** | Condition | `recommended_action` | |---|---| | No signals at low, consider, moderate, or elevated | `none` | | 1+ at low (none at consider, moderate, or elevated) | `monitor` | | 1+ at consider | `consider` | | 1+ at moderate OR 2+ at consider | `review` | | 1+ at elevated | `escalate` | `escalate` takes precedence: when any signal is `elevated`, the action is `escalate` regardless of other signals. When recording conditions may be below optimal for analysis, the API may return `recommended_action: "inconclusive"` and `overall_level: "inconclusive"` — treat this as "no clear signal; prefer re-recording or collecting more information" rather than as a monitoring, review, or escalation trigger. ### Display rules Amplifier outputs include fields intended for internal system logic and fields appropriate for end-user display. Mixing these up is the most common integration mistake. **Use for display:** - `level` — primary display primitive. - `label` — human-readable model name. - `flagged` — filter which signals appear in user-facing views (`true` when `level` is `consider`, `moderate`, or `elevated`). **Use for internal logic; keep out of patient/end-user UIs:** - `score` — log for analytics and version tracking; do not surface raw values to patients or end users. - `description.summary` — auto-generated narrative; display only after review by qualified care staff, not in automated alerts or patient-facing output. - `model_id` — internal identifier; use `label` for display. Recommended display labels: | `level` | Display label | UI treatment | |---|---|---| | `none` | Within normal range | Neutral | | `low` | Faint indicator | Informational | | `consider` | Worth considering | Informational / Caution | | `moderate` | Notable indicator | Caution | | `elevated` | Significant indicator | Alert | | `inconclusive` | Analysis inconclusive | Neutral; suggest re-recording or collecting more information rather than treating this as a risk level | Use language that is informational and non-diagnostic; do not use clinical diagnostic terms. ### Reading the response For use-case responses, read `result.summary` first: 1. If `recommended_action` is `none` or `monitor`, your workflow may not need to inspect individual signals. 2. If it is `consider`, `review`, or `escalate`, read `summary.primary_signals` to identify the top contributing models, then inspect those entries in `signals[]`. 3. Inspect `audio_quality.issues` before routing — when non-empty, decide whether to act or re-record using the issue codes in §6. For condition responses, the same logic applies to the singular `result.signal`: read `signal.recommended_action`, `signal.level`, and `signal.flagged`, then inspect `result.audio_quality.issues`. `flagged: false` signals are still valuable for logging and analytics — they establish a baseline for detecting changes over time. For the exact field-level shape of `summary`, `signals[]`, `signal`, `audio_quality`, and `extended_metrics`, see [API Reference §7 (Schemas)](api-reference.md#schemas). --- ## 8. Production checklist ### Audio quality - Tested recording setup with sample audio in the target environment; `audio_quality.issues` is empty in test runs. - Production recording pipeline uses 16 kHz mono WAV or FLAC (recommended; the API also accepts MP3 and 8 kHz minimum). - Single-speaker capture confirmed. - Microphone placement follows the recording environment guidelines in §6. ### Credential management - `X-Account-ID` and `X-API-Key` are stored as environment variables or in a secrets manager — not in source code. - Credentials are excluded from all logging pipelines. - Access to credentials is restricted to the services that need them. ### Error handling For the full error code table, see [API Reference §9 (Error reference)](api-reference.md#error-reference). Categories to handle: - **Authentication (`401 UNAUTHORIZED`)** — surface an alert to the integration team; correct credentials and resubmit. - **Credits (`402 INSUFFICIENT_CREDITS`)** — show a clear message; add credits or contact support before resubmitting. - **Request shape (`400`/`422` — `AUDIO_TOO_SHORT`, `AUDIO_TOO_LONG`, `UNSUPPORTED_FORMAT`, `AUDIO_POOR_QUALITY`, `INVALID_USE_CASE`)** — show a user-facing prompt to correct the request and try again. - **Rate limit (`429 RATE_LIMIT_EXCEEDED`)** — read the `Retry-After` response header and retry using exponential backoff (start at 1 s, double per attempt, max 5 retries). - **Server (`500 PROCESSING_ERROR`)** — retry with the same payload using exponential backoff. - **Not found (`404 NOT_FOUND`)** — verify the `job_id` and `X-Account-ID`. ### Display - `score` values are not displayed to patients or end users. - `description.summary` is not surfaced in automated alerts or patient-facing output — shown only after review by qualified care staff. - `level` and `label` are used as the display primitives in user-facing views. - `flagged: true` is used to filter which signals appear in user-facing views. - Display labels follow the recommended mapping in §7. ### Webhooks (if applicable) - Webhook URL is HTTPS. - Signature verification is implemented before processing any webhook payload (HMAC-SHA256 of the raw request body, compared with `X-Webhook-Signature` using a constant-time comparison). - Idempotency check on `job_id` is implemented to handle webhook retries (up to 5 retries with increasing delays). - Webhook receiver responds within 30 seconds to avoid delivery timeout. ### Use case selection and compliance - The `use_case` ID matches the clinical or wellness context of your user population. - If the bundle includes Emerging or Investigational models, appropriate clinical oversight is in place. - If serving multiple population contexts, separate requests use the most specific `use_case` ID for each group. - Data handling and retention requirements reviewed with your legal and compliance team. - For `wellness`: individual employee results have appropriate privacy controls; aggregated team-level signals (not individual scores) are used for dashboards and manager views. ### Security The platform is **Secure by Design**: traffic is encrypted in transit and at rest. (No HIPAA or FDA claims.) ### Final verification - End-to-end test completed with a real recording in the target environment. - `escalate` workflow tested with a simulated high-signal result. - `consider` workflow tested to verify signals are surfaced and routed appropriately. - `recommended_action` of `none` or `inconclusive` cases handled gracefully (no alert, log only). --- ## 9. Billing and cost Pricing is based on **audio tokens**. Charges are **flat per call** — audio duration does not affect cost. | API call | Tokens | With diarization | |---|:---:|:---:| | Condition API (`/v2/condition/analyze`) | 50 | 100 | | Use-case API (`/v1/analyze-audio`, `/v2/use-case/analyze`) | 75 | 125 | The diarization add-on costs a flat **+50 tokens** regardless of audio length. Token price: **$0.002 per token** ($10 = 5,000 tokens). ### What counts as a billable call Billing is tied to **processing**, not to whether every signal is decisive. Once the API has analyzed your audio, that usage counts regardless of signal outcome or `audio_quality` flags. Decisive, inconclusive, and quality-flagged responses all reflect completed compute. Failed jobs (`status: "failed"`) and request-shape errors (`400`/`422`) returned before processing do not count. ### Free trial and viewing usage Sign up at for trial credits. View remaining credits with `GET /v2/account/credits` (returns `{"credits": }`) or in the console. If the account has no remaining credits, analyze endpoints return `402 Payment Required` (`INSUFFICIENT_CREDITS`). ### Example calculations | Scenario | Tokens | Cost | |---|---|---| | Depression screen (Condition API, any duration) | 50 | $0.10 | | `behavioral-health` use case, no diarization | 75 | $0.15 | | `behavioral-health` use case + diarization | 125 | $0.25 | | Condition API + diarization | 100 | $0.20 | --- ## 10. Where to go next For exact endpoint shapes, response schemas, enum values, error codes, and webhook payload format, open the companion **[API Reference](api-reference.md)**: - [Base URL & authentication](api-reference.md#base-url--authentication) - [POST /v2/use-case/analyze](api-reference.md#post-v2use-caseanalyze) - [POST /v2/condition/analyze](api-reference.md#post-v2conditionanalyze) - [GET /v2/jobs/{job_id}](api-reference.md#get-v2jobsjob_id) - [Account endpoints](api-reference.md#account-endpoints) - [Webhook payload](api-reference.md#webhook-payload) - [Schemas](api-reference.md#schemas) - [Enumerations](api-reference.md#enumerations) - [Error reference](api-reference.md#error-reference) For account setup and console walkthrough, visit . For support and partnership requests, contact ; for rate-limit and pricing changes, contact .