Procedures

Endpoints for searching medical procedures by description and looking up individual procedure details by HCPCS code.

Search Procedures

GET /procedures/search

Fuzzy search medical procedures by description. Use this endpoint to find HCPCS codes when you know the procedure name but not the exact code.

Parameters

Parameter	Type	Required	Default	Description
q	string	Yes	—	Search query (min 2 characters)
limit	int	No	20	Results per page (max 100)
offset	int	No	0	Pagination offset

Example Request

curl -H "X-API-Key: your_key_here" \
  "https://api.healthcare-oracle.dev/procedures/search?q=mri&limit=5"

Example Response

{
  "status": "ok",
  "data": [
    {
      "hcpcs_code": "70553",
      "short_description": "MRI BRAIN W/O & W/DYE",
      "long_description": "Magnetic resonance imaging, brain, without contrast material(s), followed by contrast material(s) and further sequences"
    },
    {
      "hcpcs_code": "70551",
      "short_description": "MRI BRAIN W/O DYE",
      "long_description": "Magnetic resonance imaging, brain (including brain stem); without contrast material"
    },
    {
      "hcpcs_code": "73721",
      "short_description": "MRI JNT OF LWR EXTRM W/O DYE",
      "long_description": "Magnetic resonance imaging, any joint of lower extremity; without contrast material(s)"
    },
    {
      "hcpcs_code": "72148",
      "short_description": "MRI LUMBAR SPINE W/O DYE",
      "long_description": "Magnetic resonance imaging, spinal canal and contents, lumbar; without contrast material"
    },
    {
      "hcpcs_code": "73221",
      "short_description": "MRI JOINT UPR EXTREM W/O DYE",
      "long_description": "Magnetic resonance imaging, any joint of upper extremity; without contrast material(s)"
    }
  ],
  "meta": { "total": 47, "limit": 5, "offset": 0 }
}

Get Procedure Detail

GET /procedures/{hcpcs_code}

Look up a single procedure by its exact HCPCS code. Returns the full procedure detail including short and long descriptions.

Path Parameters

Parameter	Type	Required	Description
hcpcs_code	string	Yes	HCPCS procedure code (e.g., 99213)

Example Request

curl -H "X-API-Key: your_key_here" \
  "https://api.healthcare-oracle.dev/procedures/99213"

Example Response

{
  "status": "ok",
  "data": {
    "hcpcs_code": "99213",
    "short_description": "OFFICE/OUTPATIENT VISIT EST",
    "long_description": "Office or other outpatient visit for the evaluation and management of an established patient",
    "category": "Evaluation and Management",
    "effective_date": "2025-01-01"
  }
}

Error Responses

404 PROCEDURE_NOT_FOUND

No procedure exists for the given HCPCS code.

{
  "status": "error",
  "error": {
    "code": "PROCEDURE_NOT_FOUND",
    "message": "No procedure found for code ZZZZZ"
  }
}

422 Validation Error

Returned when the q parameter is missing or shorter than 2 characters.

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Query parameter 'q' must be at least 2 characters"
  }
}