HCPCS & SKU Search/Finder APIs

Complete guide to using the Picos Health HCPCS and SKU product finder endpoints for searching healthcare procedure codes and medical products.

Overview

Picos Health provides two powerful search endpoints to help you find and manage medical products and procedure codes:

• HCPCS Finder - Search 75,000+ Healthcare Common Procedure Coding System codes
• SKU Finder - Search 34,000+ products by description, manufacturer, category, and more

Both endpoints support full-text fuzzy search, pagination, and multi-tenant data isolation.

Authentication

All search endpoints 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.

HCPCS Code Finder

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}`);

Find codes 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');

SKU Product Finder

Quick Start

Search for products by name, manufacturer, or category:

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

Response:

{
  "results": [
    {
      "SKU": "RSP-001",
      "LONG_DESCRIPTION": "Oxygen concentrator, 5L per minute",
      "SHORT_DESCRIPTION": "O2 Concentrator 5L",
      "MANUFACTURER": "ResMed",
      "CATEGORY": "Respiratory Equipment",
      "SUBCATEGORY": "Oxygen Systems",
      "PRICE": "899.99",
      "IN_STOCK": true,
      "HCPCS_CODE": "E1390"
    },
    {
      "SKU": "RSP-002",
      "LONG_DESCRIPTION": "Portable oxygen tank, 2L capacity",
      "MANUFACTURER": "Inogen",
      "CATEGORY": "Respiratory Equipment",
      "PRICE": "1299.99"
    }
  ],
  "totalCount": 237
}

Endpoint

GET /v1/sku/search

Query Parameters

Search Examples

Basic product search:

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

// Search for respiratory equipment
const respiratoryProducts = await searchSKU(token, 'respiratory');
console.log(`Found ${respiratoryProducts.totalCount} respiratory products`);

Search by manufacturer:

const searchByManufacturer = async (token, manufacturer) => {
  const allResults = [];
  let page = 1;

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

  // Filter results by manufacturer
  return data.results.filter(product => 
    product.MANUFACTURER?.toLowerCase().includes(manufacturer.toLowerCase())
  );
};

const inogenProducts = await searchByManufacturer(token, 'Inogen');
console.log(`${inogenProducts.length} Inogen products found`);

Find in-stock products:

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

  // Filter for products currently in stock
  return data.results.filter(product => product.IN_STOCK === true);
};

const inStockWheelchairs = await findInStockProducts(token, 'wheelchair');
console.log(`${inStockWheelchairs.length} wheelchairs in stock`);

Search with price filtering:

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

  return data.results.filter(product => {
    const price = parseFloat(product.PRICE);
    return price >= minPrice && price <= maxPrice;
  });
};

const affordableOxygenSystems = await searchByPriceRange(token, 'oxygen', 500, 1500);
console.log(`Found ${affordableOxygenSystems.length} oxygen systems between $500-$1500`);

Response Fields

Common Search Queries

// Respiratory products
const respiratory = await searchSKU(token, 'oxygen concentrator');

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

// Wound care
const woundCare = await searchSKU(token, 'bandage dressing gauze');

// Diagnostic equipment
const diagnostic = await searchSKU(token, 'glucose meter blood pressure');

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

// Orthopedic supplies
const orthopedic = await searchSKU(token, 'brace cast support');

Advanced Patterns

Combining HCPCS & SKU Search

Link procedure codes to available products:

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, type = 'hcpcs') => {
  if (searchTerm.length < 2) return [];

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

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

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

Bulk Search/Import

Batch process multiple searches:

const bulkSearchProducts = async (token, keywords) => {
  const results = [];

  for (const keyword of keywords) {
    const response = await fetch(
      `https://{org-name}.api.picoshealth.com/v1/sku/search?q=${keyword}&limit=10`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    const data = await response.json();
    results.push({
      keyword,
      count: data.totalCount,
      topProduct: data.results[0]
    });
  }

  return results;
};

const catalog = await bulkSearchProducts(token, [
  'oxygen',
  'wheelchair',
  'glucose',
  'compression',
  'crutch'
]);

Error Handling

Common Errors

Missing authentication:

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

Invalid query parameter:

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

Multi-tenant data isolation:

{
  "results": [],
  "totalCount": 0,
  "message": "No results found for this organization's data"
}

Error Handling Pattern

const safeSearch = async (token, endpoint, query) => {
  try {
    const response = await fetch(
      `https://{org-name}.api.picoshealth.com/v1/${endpoint}/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, 'hcpcs', '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, endpoint, query) => {
     const key = `${endpoint}:${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 more specific search terms for better results

   // Better
   const results = await searchSKU(token, 'oxygen concentrator 5L');
   
   // Less specific
   const results = await searchSKU(token, 'medical');
   

4. Handle Null/Empty Results:

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

Multi-Tenant Considerations

The HCPCS and SKU search endpoints are multi-tenant aware. They automatically return data scoped to your organization:

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

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

// Same search term, different results per tenant

Support & Troubleshooting

Common Issues

Contact Support

For issues or feature requests:

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