Policies

GET /policies

Search Medicare coverage policies by keyword, type, or jurisdiction.

Request

GET /v1/policies?q=ultrasound&policy_type=LCD&limit=10

Query Parameters

Parameter	Type	Required	Description
`q`	string	No	Search query (max 500 characters)
`mode`	string	No	Search mode: `keyword` (default), `semantic`
`policy_type`	string	No	Filter by type: `LCD`, `Article`, `NCD`, `PayerPolicy`, `Medical Policy`, `Drug Policy`
`jurisdiction`	string	No	Filter by MAC jurisdiction code
`payer`	string	No	Filter by payer name
`status`	string	No	Filter by status: `active`, `retired`, `all` (default: `active`)
`cursor`	string	No	Pagination cursor (base64url encoded)
`limit`	number	No	Results per page (1-100, default 50)
`include`	string	No	Additional data: `summary`, `criteria`, `codes` (comma-separated)

Semantic search uses AI embeddings to find policies based on meaning rather than exact keywords. This feature requires a Starter plan or higher. Semantic search has a 10x rate limit cost multiplier.

Response

The response includes base policy fields. Additional fields (summary, criteria, codes) are included when specified via the include parameter.

{
  "success": true,
  "data": [
    {
      "policy_id": "L33345",
      "title": "Ultrasound Guidance for Needle Placement",
      "policy_type": "LCD",
      "jurisdiction": "JM",
      "status": "active",
      "effective_date": "2024-01-01",
      "retire_date": null,
      "source_url": "https://www.cms.gov/medicare-coverage-database/...",
      "summary": "This LCD outlines coverage criteria..."
    }
  ],
  "meta": {
    "pagination": {
      "cursor": "eyJpZCI6MTIzfQ",
      "has_more": true,
      "limit": 10
    },
    "search": {
      "query": "ultrasound",
      "mode": "keyword"
    },
    "filters": {
      "policy_type": "LCD",
      "jurisdiction": null,
      "status": "active"
    }
  }
}

The summary field shown above is only included when include=summary is specified in the request.

GET /policies/:id

Get detailed information about a specific policy.

Request

GET /v1/policies/L33345?include=criteria,codes

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Policy ID (e.g., L33345)

Query Parameters

Parameter	Type	Required	Description
`include`	string	No	Additional data: `criteria`, `codes`, `attachments`, `versions` (comma-separated)

Using include parameters incurs a 2x rate limit cost multiplier.

Response

{
  "success": true,
  "data": {
    "policy_id": "L33345",
    "title": "Ultrasound Guidance for Needle Placement",
    "policy_type": "LCD",
    "jurisdiction": "JM",
    "status": "active",
    "effective_date": "2024-01-01",
    "retire_date": null,
    "last_reviewed_date": "2024-06-15",
    "version": "R1",
    "source_url": "https://www.cms.gov/medicare-coverage-database/...",
    "pdf_url": "https://...",
    "description": "Full policy description...",
    "summary": "This LCD outlines coverage criteria...",
    "specialty": ["Radiology", "Interventional"],
    "keywords": ["ultrasound", "guidance", "needle"],
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-06-15T10:30:00Z",
    "sections": {
      "indications": "Detailed indications text...",
      "limitations": "Detailed limitations text...",
      "documentation": "Documentation requirements text..."
    },
    "mac": {
      "name": "Palmetto GBA",
      "code": "JM",
      "jurisdiction_name": "Jurisdiction M",
      "states": ["TX", "OK", "NM"]
    },
    "payer": {
      "name": "Medicare",
      "code": "medicare",
      "type": "government"
    },
    "criteria": {
      "indications": [
        {
          "block_id": "cb_12345",
          "text": "Ultrasound guidance is covered when...",
          "logic_ast": null,
          "tags": ["imaging", "guidance"],
          "requires_manual_review": false,
          "confidence_score": 0.95
        }
      ],
      "limitations": []
    },
    "criteria_count": 5,
    "codes": {
      "HCPCS": [
        {
          "code": "76942",
          "display": "Ultrasonic guidance for needle placement",
          "disposition": "covered",
          "condition_reference": null,
          "notes": null
        }
      ]
    },
    "code_count": 12,
    "attachments": [
      {
        "file_type": "pdf",
        "url": "https://...",
        "title": "Billing Guide",
        "page_number": null,
        "file_size_bytes": 125400
      }
    ],
    "versions": [
      {
        "old_version": "R0",
        "new_version": "R1",
        "change_type": "updated",
        "change_summary": "Updated coverage criteria",
        "changed_fields": ["indications", "limitations"],
        "timestamp": "2024-06-15T10:30:00Z"
      }
    ]
  },
  "meta": {
    "includes": ["criteria", "codes", "attachments", "versions"]
  }
}

POST /policies/compare

Compare coverage policies across different MAC jurisdictions for the same procedure codes.

Request

POST /v1/policies/compare
Content-Type: application/json
X-Idempotency-Key: unique-request-id

{
  "procedure_codes": ["76942", "76937"],
  "jurisdictions": ["JM", "JH", "JK"]
}

Request Body

Field	Type	Required	Description
`procedure_codes`	string[]	Yes	Array of CPT/HCPCS codes (max 10)
`policy_type`	string	No	Filter by policy type: `LCD`, `Article`, `NCD`
`jurisdictions`	string[]	No	Specific jurisdictions to compare

The X-Idempotency-Key header is recommended for safe retries on POST requests.

Response

{
  "success": true,
  "data": {
    "comparison": [
      {
        "jurisdiction": "JM",
        "mac": {
          "name": "Palmetto GBA",
          "code": "JM",
          "jurisdiction_name": "Jurisdiction M",
          "states": ["TX", "OK", "NM"]
        },
        "policies": [
          {
            "policy_id": "L33345",
            "title": "Ultrasound Guidance",
            "policy_type": "LCD",
            "effective_date": "2024-01-01",
            "codes": [
              {
                "code": "76942",
                "code_system": "HCPCS",
                "disposition": "covered"
              }
            ]
          }
        ],
        "coverage_summary": {
          "covered": 2,
          "not_covered": 0,
          "requires_pa": 0,
          "conditional": 1
        }
      }
    ],
    "national_policies": [
      {
        "policy_id": "NCD220.6",
        "title": "National Coverage for Ultrasound",
        "policy_type": "NCD",
        "effective_date": "2023-01-01",
        "is_national": true,
        "codes": [
          {
            "code": "76942",
            "code_system": "HCPCS",
            "disposition": "covered"
          }
        ]
      }
    ],
    "summary": {
      "total_jurisdictions": 3,
      "jurisdictions_with_coverage": 3,
      "national_policies_count": 1,
      "has_variation": true,
      "queried_codes": ["76942", "76937"],
      "policy_type_filter": null
    }
  },
  "meta": {
    "idempotency_key": "unique-request-id"
  }
}

GET /policies/changes

Get a feed of policy changes for monitoring updates.

Request

GET /v1/policies/changes?since=2024-01-01T00:00:00Z

Query Parameters

Parameter	Type	Required	Description
`since`	string	No	ISO8601 timestamp - only show changes after
`policy_id`	string	No	Filter to a specific policy
`change_type`	string	No	Filter by type: `created`, `updated`, `retired`, `codes_changed`, `criteria_changed`, `metadata_changed`
`cursor`	string	No	Pagination cursor
`limit`	number	No	Results per page (1-100, default 50)

Response

{
  "success": true,
  "data": [
    {
      "diff_id": 12345,
      "policy_id": "L33345",
      "policy_title": "Ultrasound Guidance",
      "old_version": "R0",
      "new_version": "R1",
      "change_type": "updated",
      "change_summary": "Updated coverage criteria for...",
      "changed_at": "2024-06-15T10:30:00Z",
      "details": {
        "changed_fields": ["indications", "limitations"],
        "added_codes": ["76943"],
        "removed_codes": [],
        "modified_criteria": ["indications"]
      }
    }
  ],
  "meta": {
    "pagination": {
      "cursor": "eyJpZCI6MTIzfQ",
      "has_more": true,
      "limit": 50
    },
    "filters": {
      "since": "2024-01-01T00:00:00Z",
      "policy_id": null,
      "change_type": null
    }
  }
}

Change Types

Type	Description
`created`	New policy was published
`updated`	Policy content was modified
`retired`	Policy was retired/deactivated
`codes_changed`	Covered codes were added or removed
`criteria_changed`	Coverage criteria were modified
`metadata_changed`	Policy metadata (dates, jurisdiction, etc.) was updated

Policies

On this page