Product Catalog Search

Complete guide to searching medical products using the Picos Health Product Catalog search endpoint. Find products by description, manufacturer, category, and more.

Overview

The Product Catalog search endpoint gives you access to 34,000+ medical products with detailed information. Search by product name, manufacturer, category, and filter by inventory status and pricing.

34,000+ products - Comprehensive medical product database
Fuzzy search - Find products with partial or misspelled terms
Pagination - Fetch results in manageable pages
Manufacturer filtering - Search by brand or manufacturer
Inventory tracking - Filter in-stock products
Pricing information - Access product pricing details
HCPCS codes - Associated healthcare procedure codes
Multi-tenant - Data scoped by organization

Authentication

All Product Suite 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 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

Parameter	Type	Required	Description	Example
`q`	string	Yes	Search query (fuzzy match)	`respiratory`, `wheelchair`, `glucose`
`limit`	number	No	Results per page (max 100)	`10` (default: 10)
`page`	number	No	Page number (starts at 1)	`1` (default: 1)

Search Examples

Basic product search

const searchProducts = 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 searchProducts(token, 'respiratory');
console.log(`Found ${respiratoryProducts.totalCount} respiratory products`);

Search by manufacturer

const searchByManufacturer = async (token, manufacturer) => {
  // 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`);

Pagination example

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

  while (hasMore) {
    const response = await fetch(
      `https://{org-name}.api.picoshealth.com/v1/sku/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 allRespiratoryProducts = await getAllResults(token, 'respiratory');
console.log(`Total respiratory products: ${allRespiratoryProducts.length}`);

Response Fields

Field	Type	Description
`SKU`	string	Stock Keeping Unit / Product code
`LONG_DESCRIPTION`	string	Complete product description
`SHORT_DESCRIPTION`	string	Brief product name
`MANUFACTURER`	string	Manufacturer name
`CATEGORY`	string	Product category
`SUBCATEGORY`	string	Product subcategory
`PRICE`	string	Product price
`IN_STOCK`	boolean	Inventory status
`HCPCS_CODE`	string	Associated HCPCS code (if applicable)

Common Search Queries

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

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

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

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

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

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

Advanced Patterns

Link products to HCPCS codes

Use the HCPCS Code Search to find procedure codes associated with your products:

const findCodesForProduct = async (token, productKeyword) => {
  // Get product details
  const productResponse = await fetch(
    `https://{org-name}.api.picoshealth.com/v1/sku/search?q=${productKeyword}&limit=1`,
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  const productData = await productResponse.json();
  const product = productData.results[0];

  if (!product) return null;

  // If product has HCPCS code, get its details
  if (product.HCPCS_CODE) {
    const codeResponse = await fetch(
      `https://{org-name}.api.picoshealth.com/v1/hcpcs/search?q=${product.HCPCS_CODE}&limit=1`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    const codeData = await codeResponse.json();
    return {
      product,
      hcpcsCode: codeData.results[0]
    };
  }

  return { product, hcpcsCode: null };
};

// Find HCPCS code for oxygen concentrator
const oxygenInfo = await findCodesForProduct(token, 'oxygen concentrator');

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/sku/search?q=${searchTerm}&limit=5`,
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  const data = await response.json();

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

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

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
}

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/sku/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

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

const searchCache = new Map();

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

Use Pagination - Don't fetch all results at once

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

// Avoid - could timeout
fetch(`...?limit=10000`)

Specific Queries - Use specific search terms for better results

// Better
const results = await searchProducts(token, 'oxygen concentrator 5L ResMed');

// Less specific
const results = await searchProducts(token, 'medical');

Handle Empty Results

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

Multi-Tenant Considerations

Product Suite search is multi-tenant aware. Results are 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

Issue	Solution
No results found	Try more specific keywords or shorter queries
Timeout on large queries	Use pagination (limit=50) or more specific search terms
Different results per tenant	Each tenant has separate product catalogs - expected behavior
Product not found	Use partial terms or manufacturer name instead

HCPCS Code Search - Find healthcare procedure codes
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