Skip to main content
Follow these steps to go from zero to classifying your first adverse event.

​
1. List MedDRA versions

curl https://api.meddra.co/versions
This returns the releases we currently host, ordered with the latest first. Each item includes the version identifier, optional releaseDate, aggregated counts/changes, and an isLatest flag. If you do nothing else, every endpoint will use the latest release.
Want to pin to a specific MedDRA version? Pass ?version=28.1 (or the release you need) or add X-MedDRA-Version: 28.1 to the request headers.

​
2. Search MedDRA codes

curl "https://api.meddra.co/codes?q=anaphylactic&limit=5"
You can filter by hierarchy (soc, hlgt, hlt, llt), restrict to a particular level (level=PT), or zero in on release deltas (changeType=ADDED). The response includes a meta block with pagination data plus hierarchy context for each match so you can link straight to detail pages in the app.

​
3. View a MedDRA code

curl https://api.meddra.co/codes/10011906
You’ll get the Preferred Term, related LLTs, parent hierarchy, change status, and metadata across releases. Append ?version=28.1 to see the same code in an older release.

​
4. Identify discrete adverse events

curl -X POST https://api.meddra.co/identify \
  -H "X-API-Key: sk-<API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Patient developed acute infusion reaction with hypotension and later reported dyspnea.",
    "options": {
      "page": 1,
      "limit": 5
    }
  }'
The response contains a results array of objects with description, reasons, and confidence, such as: 
{
	"results": [
		{
			"description": "Acute infusion reaction with throat swelling",
			"reasons": [
				"\"infusion reaction\" and \"throat swelling\" appear together in the narrative"
			],
			"confidence": 0.84
		},
		{
			"description": "Hypotension requiring IV fluids",
			"reasons": [
				"Narrative states the patient required IV fluids for blood pressure support"
			],
			"confidence": 0.77
		},
		{
			"description": "Dyspnea during post-infusion monitoring",
			"reasons": [
				"\"Dyspnea\" reported while the patient was under observation"
			],
			"confidence": 0.72
		}
	],
	"meta": {
		"page": 1,
		"limit": 5,
		"total": 3,
		"next": null,
		"previous": null
	}
}
Use this output to fan out downstream logic (classification, case routing) per event instead of trying to split the narrative yourself. Only /identify and /classify require the X-API-Key header—catalog endpoints stay public.

​
5. Predict a MedDRA code with an event description

curl -X POST https://api.meddra.co/classify \
  -H "X-API-Key: sk-<API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Patient reported dizziness and vertigo after first cycle.",
    "assessments": {
      "meddra": {
        "version": "28.1"
      }
    }
  }'
The classifier responds with ranked Preferred Terms, confidence scores, and the supporting hierarchy context. You can also request seriousness and severity assessments by enabling them in the assessments object. Severity is split per grading system so CTCAE and the 3-level scale each include their own confidence and reasons: 
{
  "results": {
    "meddraCodes": [...],
    "severity": {
      "ctcae": {
        "value": { "grade": 3, "label": "Severe" },
        "confidence": 0.82,
        "reasons": ["Narrative describes inpatient care and significant functional impact."]
      },
      "simple": {
        "value": { "grade": "severe" },
        "confidence": 0.78,
        "reasons": ["Patient unable to perform usual activities without medical support."]
      }
    }
  }
}
If you omit the version, the service uses the latest release (or respects the X-MedDRA-Version header). Calls without the X-API-Key header will be rejected with 401 Unauthorized.

​
6. Focus on release changes

curl "https://api.meddra.co/codes?changeType=ADDED&soc=10029205&limit=5"
Combine changeType with hierarchy filters to highlight additions, updates, or retirements in a specific slice of the terminology between releases.

​
Next steps

  • Review version selection guidance for deeper control over releases and precedence rules.
  • Browse the API reference for every endpoint, schema, and rate-limit note.
  • Prototype UI flows with the public web app at meddra.co and reuse the same endpoints server-side.