Skip to main content
POST
/
identify
Identify adverse events
curl --request POST \
  --url https://api.meddra.co/identify \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "description": "Patient experienced an acute infusion reaction with hypotension and later developed hypoxia.",
  "options": {
    "page": 1,
    "limit": 8
  }
}
'
{
  "requestId": "req_01JD4N8RTM82ZEQTBFTN045C3B",
  "version": "28.1",
  "results": [
    {
      "description": "Acute infusion reaction with throat swelling",
      "reasons": [
        "\"infusion reaction with throat swelling\" indicates airway involvement",
        "Emergency medication administered during infusion"
      ],
      "confidence": 0.82
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 245,
    "next": "?page=2&limit=50",
    "previous": "?page=1&limit=50"
  }
}
POST /identify segments a clinical narrative into self-contained adverse events so you can run downstream classification, severity, or reporting logic against each individual event. The endpoint never assigns MedDRA codes—it only returns clean event strings. All safety assessments remain AI-generated. Review every extracted event before trusting it in regulatory submissions.

​
Authentication

Include the header X-API-Key: sk-<API_KEY> with every request to this endpoint. Requests without the key return 401 Unauthorized.

​
When to use this endpoint

  • Pre-process investigator reports before fanning out parallel POST /classify calls per event.
  • Normalize verbose narratives into short, declarative strings that make UI surfacing and deduplication easier.
  • Implement guardrails that reject submissions lacking clear adverse events.

​
Extraction behavior

  • Single-event fallbacks: If the extractor struggles to separate events, it returns a single entry covering the entire narrative so downstream workflows still have something to classify.
  • LLM + heuristic pipeline: We start with an LLM tuned for pharmacovigilance narratives and fall back to sentence-level heuristics when the model is unavailable. Both strategies feed the same normalization and deduplication layers.
  • Deduplication: Always on to collapse near-identical statements (“syncope” vs “syncopal episode”) so paginated responses stay concise.
  • Ordering: Events always remain in reading order, which makes it easy to correlate them with timeline data in your UI.
  • Explainability: Each event includes a description, reasons array pointing to the narrative evidence, and a confidence score (0–1) so you can surface lightweight provenance before calling /classify.

Headers

​
X-API-Key
string
required

Static API key required for POST /classify, POST /labels/classify, and POST /identify requests.

Example:

"sk-<API_KEY>"

​
X-API-Version
string
default:1

Override the default API version. Defaults to 1.

Example:

"1"

​
X-MedDRA-Version
string

Target a specific MedDRA release. Defaults to the latest.

Example:

"28.0"

Body

application/json
​
description
string
required

Narrative adverse event description.

Minimum string length: 1
Example:

"Patient experienced an acute infusion reaction with hypotension and later developed hypoxia."

​
options
object

Optional tuning controls for event extraction.

Response

List of self-contained adverse events mentioned in the narrative.

​
requestId
string
required

Unique identifier for this identification request.

Example:

"req_01JD4N8RTM82ZEQTBFTN045C3B"

​
version
string
required

MedDRA version used to normalize language before identification.

Example:

"28.1"

​
results
object[]
required

Ordered list of adverse events with supporting rationale.

​
meta
object
required