HCPCS Code Search

Complete guide to searching Healthcare Common Procedure Coding System (HCPCS) codes using the Picos Health HCPCS search endpoint.

Overview

The HCPCS search endpoint gives you access to 75,000+ healthcare procedure codes. Search by keywords, filter by coverage type, and retrieve detailed information about procedures and services.

• 75,000+ codes - Comprehensive HCPCS database
• Fuzzy search - Find codes with partial or misspelled terms
• Pagination - Fetch results in manageable pages
• Coverage filtering - Filter by Medicare, Medicaid coverage types
• Multi-tenant - Data scoped by organization

Authentication

All HCPCS search requests require JWT bearer token authentication:

Authorization: Bearer YOUR_JWT_TOKEN

Getting a token:

curl -X POST https://{org-name}.api.picoshealth.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"apiKey":"pk_live_xxxxxxxxxxxxxxxxxxxx"}'

See API Authentication Guide for detailed steps.

Quick Start

Search for healthcare procedure codes by keyword:

curl -s "https://{org-name}.api.picoshealth.com/v1/hcpcs/search?q=mask&limit=10&page=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "results": [
    {
      "HCPC": "A4620",
      "SEQNUM": "0010",
      "RECID": "3",
      "LONG DESCRIPTION": "Variable concentration mask",
      "SHORT DESCRIPTION": "Variable concentration mask",
      "PRICE1": "00",
      "BETOS": "D1C",
      "TOS1": "P",
      "COV": "D",
      "MCM1": "3312"
    },
    {
      "HCPC": "A4928",
      "LONG DESCRIPTION": "Surgical mask, per 20",
      "SHORT DESCRIPTION": "Surgical mask",
      "COV": "D"
    }
  ],
  "totalCount": 1000
}

Endpoint

GET /v1/hcpcs/search

Query Parameters

Search Examples

Basic keyword search

const searchHCPCS = async (token, keyword) => {
  const response = await fetch(
    `https://{org-name}.api.picoshealth.com/v1/hcpcs/search?q=${encodeURIComponent(keyword)}&limit=10`,
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  return response.json();
};

// Search for mask products
const masks = await searchHCPCS(token, 'mask');
console.log(`Found ${masks.totalCount} mask codes`);

Pagination example

const getAllHCPCSResults = async (token, keyword) => {
  const allResults = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://{org-name}.api.picoshealth.com/v1/hcpcs/search?q=${keyword}&page=${page}&limit=50`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    const data = await response.json();
    allResults.push(...data.results);

    // Stop if we've fetched all results or this page is empty
    if (allResults.length >= data.totalCount || data.results.length === 0) {
      hasMore = false;
    }
    page++;
  }

  return allResults;
};

const allDressingCodes = await getAllHCPCSResults(token, 'dressing');
console.log(`Total dressing codes: ${allDressingCodes.length}`);

Filter by coverage type

const findCoveredCodes = async (token, keyword) => {
  const response = await fetch(
    `https://{org-name}.api.picoshealth.com/v1/hcpcs/search?q=${keyword}&limit=50`,
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  const data = await response.json();

  // Filter for Medicare covered codes (COV: 'C' or 'D')
  return data.results.filter(code => ['C', 'D'].includes(code.COV));
};

const coveredOxygenCodes = await findCoveredCodes(token, 'oxygen');
console.log(`Found ${coveredOxygenCodes.length} covered oxygen codes`);

Response Fields

Common Search Queries

// Respiratory equipment
const respiratory = await searchHCPCS(token, 'oxygen mask');

// Wound care supplies
const woundCare = await searchHCPCS(token, 'dressing gauze');

// Mobility aids
const mobility = await searchHCPCS(token, 'wheelchair walker crutch');

// Diagnostic supplies
const diagnostic = await searchHCPCS(token, 'glucose meter test strips');

// Compression therapy
const compression = await searchHCPCS(token, 'compression stocking wrap');

Advanced Patterns

Link codes to products

Use the Product Catalog Search to find available products for a HCPCS code:

const findProductsForCode = async (token, hcpcsCode) => {
  // Get HCPCS code details
  const codeResponse = await fetch(
    `https://{org-name}.api.picoshealth.com/v1/hcpcs/search?q=${hcpcsCode}&limit=1`,
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  const codeData = await codeResponse.json();
  const codeDescription = codeData.results[0]?.LONG_DESCRIPTION || '';

  // Search for related products using the description keywords
  const keywords = codeDescription.split(' ').slice(0, 3).join(' ');
  const productResponse = await fetch(
    `https://{org-name}.api.picoshealth.com/v1/sku/search?q=${keywords}&limit=20`,
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  const productData = await productResponse.json();

  return {
    hcpcsCode,
    description: codeDescription,
    availableProducts: productData.results
  };
};

// Find products for oxygen therapy code
const oxygenSupplies = await findProductsForCode(token, 'E1390');

Auto-complete search

Implement type-ahead functionality:

const searchWithAutoComplete = async (token, searchTerm) => {
  if (searchTerm.length < 2) return [];

  const response = await fetch(
    `https://{org-name}.api.picoshealth.com/v1/hcpcs/search?q=${searchTerm}&limit=5`,
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  const data = await response.json();

  // Return formatted suggestions
  return data.results.map(item => ({
    label: `${item.HCPC} - ${item.SHORT_DESCRIPTION}`,
    value: item.HCPC,
    item: item
  }));
};

// As user types, fetch suggestions
const suggestions = await searchWithAutoComplete(token, 'ox');

Error Handling

Common Errors

Missing authentication:

{
  "error": "Unauthorized: Missing or invalid Bearer token",
  "statusCode": 401
}

Missing query parameter:

{
  "error": "Query parameter 'q' is required",
  "statusCode": 400
}

No results found:

{
  "results": [],
  "totalCount": 0
}

Error handling pattern

const safeSearch = async (token, query) => {
  try {
    const response = await fetch(
      `https://{org-name}.api.picoshealth.com/v1/hcpcs/search?q=${encodeURIComponent(query)}&limit=10`,
      {
        headers: { 'Authorization': `Bearer ${token}` }
      }
    );

    if (!response.ok) {
      if (response.status === 401) {
        throw new Error('Authentication failed - refresh token');
      }
      if (response.status === 400) {
        throw new Error('Invalid search query');
      }
      throw new Error(`HTTP ${response.status}`);
    }

    return response.json();
  } catch (error) {
    console.error(`Search error: ${error.message}`);
    return { results: [], totalCount: 0, error: error.message };
  }
};

const results = await safeSearch(token, 'oxygen');

Rate Limiting & Best Practices

Rate Limits

• Limit: 1000 requests per hour per API key
• Burst: 100 requests per minute
• Batch Limit: 50 results per page (max)

Best Practices

1. Cache Results - Store search results client-side to reduce API calls

   const searchCache = new Map();
   
   const cachedSearch = async (token, query) => {
     const key = `hcpcs:${query}`;
     if (searchCache.has(key)) {
       return searchCache.get(key);
     }
     
     const result = await fetch(`...`);
     searchCache.set(key, result);
     return result;
   };
   

2. Use Pagination - Don't fetch all results at once

   // Good - pagination
   fetch(`...?limit=50&page=1`)
   
   // Avoid - could timeout
   fetch(`...?limit=10000`)
   

3. Specific Queries - Use specific search terms for better results

   // Better
   const results = await searchHCPCS(token, 'oxygen concentration mask');
   
   // Less specific
   const results = await searchHCPCS(token, 'medical');
   

4. Handle Empty Results

   const results = await searchHCPCS(token, 'xyz123');
   if (!results.results || results.results.length === 0) {
     console.log('No codes found - try different keywords');
   }
   

Multi-Tenant Considerations

HCPCS search is multi-tenant aware. Results are scoped to your organization:

// DEMO tenant - searches DEMO HCPCS catalog
const demoSearch = await fetch(
  'https://demo.api.picoshealth.com/v1/hcpcs/search?q=oxygen',
  { headers: { 'Authorization': `Bearer demo_token` } }
);

// EEDA tenant - searches EEDA HCPCS catalog
const eedaSearch = await fetch(
  'https://eeda.api.picoshealth.com/v1/hcpcs/search?q=oxygen',
  { headers: { 'Authorization': `Bearer eeda_token` } }
);

// Same search term, different results per tenant

Support & Troubleshooting

Common Issues

Related Documentation

• Product Suite Search - Find available products
• API Authentication - How to get tokens
• API Overview - General API information

Contact Support

For issues or feature requests:

• Email: support@picoshealth.com
• Documentation: See API Guide