# Toxicology

Subscribe to `toxicology` to receive drug test results.

| `event_type` | Sent when |
| --- | --- |
| `toxicology.result.posted` | A test result is posted or changed. |
| `toxicology.result.deleted` | A test result is deleted. |

## toxicology.result.posted

```json
{
  "event_type": "toxicology.result.posted",
  "data": {
    "medical_record_number": "3f2b8c1e-7a4d-4e9b-9c55-0d6a1f2e8b47",
    "plan_name": "Standard Plan",
    "test_date": "2026-01-01T00:00:00.000Z",
    "test_type": "Saliva Lab Confirmation",
    "test_result": "Positive",
    "self_reported": false,
    "test_notes": "Confirmed by lab.",
    "kit_id": "KIT-000123",
    "test_id": "665f1c2ab7e4d90012a3f4c2",
    "lab_results": [
      { "code": "LCMSAMPH", "name": "Amphetamine", "result": "Not Detected", "units": "ng/mL", "cutoff": "2" },
      { "code": "LCMSCOTN", "name": "Cotinine", "result": "444.29", "units": "ng/mL", "cutoff": "2" },
      { "code": "LCMSFENT", "name": "Fentanyl", "result": "Not Detected", "units": "ng/mL", "cutoff": "0.25" }
    ]
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `medical_record_number` | string (UUID) | The member's medical record number. |
| `plan_name` | string | The member's plan. Optional. |
| `test_date` | string (date-time) | The calendar day of the test. See [Test dates](#test-dates). |
| `test_type` | string | See [Test types](#test-types). |
| `test_result` | string | The overall result: `Positive`, `Negative`, `Inconclusive` or `Missed`. `Inconclusive` is sent only for lab tests. |
| `self_reported` | boolean | `true` when the member reported the result themselves. |
| `test_notes` | string | Notes on the result. Optional. |
| `kit_id` | string | The test kit ID. Optional. |
| `test_id` | string | The result's ID. The same ID is sent again if the result changes or is deleted. |
| `lab_results` | array | The lab's per-analyte panel. Lab tests only. See [Lab results](#lab-results). |

A changed result is sent as another `toxicology.result.posted` with the same `test_id`. Save by `test_id` so the newer event replaces the older one.

### Test types

`test_type` is one of:

- `10 Panel Instant`
- `10 Panel Instant w/ THC`
- `14 Panel Instant`
- `Cotinine`
- `Saliva Lab Confirmation`
- `Urine Analysis`
- `Urine Instant`

New test types can be added. Don't reject a value you don't recognize.

### Test dates

`test_date` is the calendar day of the test in UTC. The time is always `00:00:00.000Z`.

`2026-01-01T00:00:00.000Z` means the test happened on January 1, 2026. Read the date part only. Converting to a local time zone can shift it by a day.

### Lab results

`lab_results` is the full panel from the lab, with one entry per analyte tested.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | The lab's analyte code, such as `LCMSAMPH`. |
| `name` | string or null | The analyte name as the lab reports it. |
| `result` | string or null | The lab's result text. |
| `units` | string or null | Units as reported by the lab, such as `ng/mL`. |
| `cutoff` | string or null | The cutoff as reported by the lab. |

- Sent only for lab tests (`Saliva Lab Confirmation`, `Urine Analysis`) that have a panel. On every other result the field is left out, not `null`.
- The panel depends on the lab. Analytes, codes, names, units, cutoffs and result values all vary by lab and panel. Treat every value as display text, not as a fixed list.
- As an example, one lab sends `"Not Detected"` for a negative analyte and the measured concentration, such as `"444.29"`, when it is detected. Other labs use different values.
- `test_result` is still the overall result for the test.
- The lab's PDF report is not included.

## toxicology.result.deleted

```json
{
  "event_type": "toxicology.result.deleted",
  "data": {
    "test_id": "665f1c2ab7e4d90012a3f4c2"
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `test_id` | string | The ID of the deleted result. |

## JSON Schemas

- [`toxicology.result.posted`](https://developers.youareaccountable.com/schemas/toxicology.result.posted.json)
- [`toxicology.result.deleted`](https://developers.youareaccountable.com/schemas/toxicology.result.deleted.json)
