@symmetrichs/sdk

Symmetric Health Solutions SDK

Overview

Symmetric Health Solutions is a software company for healthcare supply chain data. Hundreds of hospitals — from large IDNs to community hospitals — use Symmetric's item and vendor data solutions to enable improvements in supply chain operations, business integration, and public health.

With Symmetric Health Solutions, the right information is delivered in the right interface, at the right time.

This SDK provides access to Symmetric APIs for searching and collecting data for medical supplies. The API (and by association the SDK) are split into four main categories:

1. Medical devices (e.g. gloves, MRI machines, screws)
2. Pharmaceuticals
3. Substitute devices (i.e. what products could be used as replacements for another)
4. Vendors

Generally each category provides SDK functions for:

1. Searching
2. Downloading
3. Counting

There are a few additional specialized functionalities:

1. For devices, there is a specialized search (referred to as "matching") that provides search results based on several mapped data fields in a way that a much larger variety of fuzzy matching is performed as compared to the more generalized search
2. For devices, there is the ability to get data for specific devices via UDI-DI
3. For pharmaceuticals, there is the ability to search for specific pharmaceuticals via NDC

Examples

Configuration

Before calling any SDK functions, the SDK must be configured:

import {configure} from "@symmetrichs/sdk";

configure({
    apiKey: process.env.YOUR_API_KEY,
    apiSecret: process.env.YOUR_SECRET_KEY,
    appKey: process.env.YOUR_APP_KEY
});

Devices

Search for a device by keyword

Notes:

1. The full list of available columns is available at the end of this document. Devices, pharmaceuticals, and vendors have different columns available.
2. This function will return a limited number of results (<1000). To retrieve a larger number of results (up to 10,000) use the
   download function below. To get a count of the number of results available for your search, use the count function below.

import {device} from "@symmetrichs/sdk";

const results = await device.search({
    query: 'needle',
    columns: ['Primary DI', 'GMDN By Name']
});

// Search with additional filters
const results = await device.search({
   query: 'needle',
   columns: ['Primary DI', 'GMDN By Name'],
   // Available filter types are 'ALL', 'ANY', and 'NONE_OF'. The filter is a substring
   // comparison, so for example:
   //
   // {column: 'Noun', values: ['RE', 'TAC'], type: 'ALL'} => results with a noun containing the substrings 'RE' AND 'TAC'
   // {column: 'Noun', values: ['RE', 'TAC'], type: 'ANY'} => results with a noun containing the substrings 'RE' OR 'TAC' 
   // {column: 'Noun', values: ['RE', 'TAC'], type: 'NONE_OF'} => results with a noun not containing either of the substrings 'RE' OR 'TAC' 
   filters: [{column: 'Noun', values: ['CONTAINER', 'RECEPTACLE'], type: 'ANY'}]
});

Download search results

import {device} from "@symmetrichs/sdk";

const download = await device.download({
   // Most options are the same as for `search`, including filters
   query: 'needle',
   columns: ['Primary DI', 'GMDN By Name'],
   // Some options are `download` specific
   format: 'csv' // Available formats are 'csv' and 'xlsx'
});
await download.ready();
const csvData = await fetch(download.url()).then(r => r.text());

Count search results

import {device} from "@symmetrichs/sdk";

const results = await device.count({
   // Options are the same as for `search`, including filters
   query: 'needle',
   column: 'Primary DI'
});

Match

Notes:

1. The match function only returns the UDI-DI's that best match the provided information, based on Symmetric's matching algorithms. With the UDI-DI's, you can call the device function below to collect additional information.
2. All possible fields are enumerated below. The more fields specified, the better the match results will be. At least one of [mnfCtlg, vendorCtlg, udiDi] must be specified.
3. The catalogs, UDI-DI, manufacturer, vendor, and description options need not be exact (that's the point of this API!) but the cleaner the options, the better the results (e.g. including or excluding leading 0's)

import {device} from "@symmetrichs/sdk";

const results = await device.match({
   mnfCtlg: '210295',
   mnfName: 'arkray'
});

const results = await device.match({
   mnfCtlg: '210295',
   mnfName: 'arkray',
   vendorCtlg: undefined,
   vendorName: undefined,
   udiDi: undefined,
   description: 'your item description'
});

Get information by UDI-DI

import {device} from "@symmetrichs/sdk";

const results = await device.get({
   ids: ['00366975005090', '00606959054202'],  // Up to 20 items can be specified, must be an array
   columns: ['Primary DI', 'GMDN By Name']
});

Pharmaceuticals

Search for a pharmaceutical by keyword

Notes:

1. The full list of available columns is available at the end of this document. Devices, pharmaceuticals, and vendors have different columns available.
2. This function will return a limited number of results (<1000). To retrieve a larger number of results use the download function below. To get a count of the number of results available for your search, use the count function below.

import {pharmacy} from "@symmetrichs/sdk";

const results = await pharmacy.search({
   query: 'ibuprofen',
   columns: ['Generic Name', 'Labeler Name']
});

// Search with additional filters
const results = await pharmacy.search({
   query: 'ibuprofen',
   columns: ['Generic Name', 'Labeler Name'],
   // Available filter types are 'ALL', 'ANY', and 'NONE_OF'. The filter is a substring
   // comparison, so for example:
   //
   // {column: 'Noun', values: ['O', 'TC'], type: 'ALL'} => results with a noun containing the substrings 'RE' AND 'TAC'
   // {column: 'Noun', values: ['O', 'TC'], type: 'ANY'} => results with a noun containing the substrings 'RE' OR 'TAC' 
   // {column: 'Noun', values: ['O', 'TC'], type: 'NONE_OF'} => results with a noun not containing either of the substrings 'RE' OR 'TAC' 
   filters: [{column: 'OTC', values: ['OTC', 'RX'], type: 'ANY'}]
});

Download search results

import {pharmacy} from "@symmetrichs/sdk";

const download = await pharmacy.download({
   // Most options are the same as for `search`, including filters
   query: 'ibuprofen',
   columns: ['Product Packaging NDC', 'Generic Name', 'Labeler Name'],
   // Some options are `download` specific
   format: 'csv' // Available formats are 'csv' and 'xlsx'
});
await download.ready();
const csvData = await fetch(download.url()).then(r => r.text());

Count search results

import {pharmacy} from "@symmetrichs/sdk";

const results = await pharmacy.count({
   // Options are the same as for `search`, including filters
   query: 'ibuprofen',
   column: 'Generic Name'
});

Get information by NDC

Notes:

1. This function only accepts the NDC-11 format with dashes (e.g. 24385-0546-62)

import {pharmacy} from "@symmetrichs/sdk";

const results = await pharmacy.get({
   ids: ['24385-0546-62', '00573-0164-40'],
   columns: ['Generic Name', 'Labeler Name']
});

Device Substitutes

Search for substitutes by UDI-DI

Notes:

1. The full list of available columns is available at the end of this document. Devices, pharmaceuticals, and vendors have different columns available.
2. This function will return a limited number of results (<1000). To retrieve a larger number of results use the download function below. To get a count of the number of results available for your search, use the count function below.

import {substitutes} from "@symmetrichs/sdk";

const results = await substitutes.search({
   query: '00008712000028',
   columns: ['Primary DI', 'Manufacturer Name Cleansed'],
   manufacturer: 'DIFFERENT'  // One of: 'ALL', 'DIFFERENT', or 'SAME'
});

// Search with additional filters
const results = await substitutes.search({
   query: '00008712000028',
   columns: ['Primary DI', 'Manufacturer Name Cleansed'],
   manufacturer: 'DIFFERENT',
   // Available filter types are 'ALL', 'ANY', and 'NONE_OF'. The filter is a substring
   // comparison, so for example:
   //
   // {column: 'Noun', values: ['CON', 'NER'], type: 'ALL'} => results with a noun containing the substrings 'RE' AND 'TAC'
   // {column: 'Noun', values: ['CON', 'NER'], type: 'ANY'} => results with a noun containing the substrings 'RE' OR 'TAC' 
   // {column: 'Noun', values: ['CON', 'NER'], type: 'NONE_OF'} => results with a noun not containing either of the substrings 'RE' OR 'TAC' 
   filters: [{column: 'Noun', values: ['CONTAINER'], type: 'ANY'}]
});

Download search results

import {substitutes} from "@symmetrichs/sdk";

const download = await substitutes.download({
   // Most options are the same as for `search`, including filters
   query: '00008712000028',
   columns: ['Primary DI', 'Manufacturer Name Cleansed'],
   manufacturer: 'DIFFERENT',
   // Some options are `download` specific
   format: 'csv' // Available formats are 'csv' and 'xlsx'
});
await download.ready();
const csvData = await fetch(download.url()).then(r => r.text());

Count search results

import {substitutes} from "@symmetrichs/sdk";

const results = await substitutes.count({
   // Most options are the same as for `search`, including filters
   query: '00008712000028',
   column: 'Manufacturer Name Cleansed',
   manufacturer: 'DIFFERENT'
});

Vendors

Search for vendors by keyword

Notes:

1. The full list of available columns is available at the end of this document. Devices, pharmaceuticals, and vendors have different columns available.
2. This function will return a limited number of results (<1000). To retrieve a larger number of results use the download function below. To get a count of the number of results available for your search, use the count function below.

import {vendor} from "@symmetrichs/sdk";

const results = await vendor.search({
   query: 'seattle',
   columns: ['Name', 'City']
});

// Search with additional filters
const results = await vendor.search({
   query: 'seattle',
   columns: ['Name', 'City'],
   // Available filter types are 'ALL', 'ANY', and 'NONE_OF'. The filter is a substring
   // comparison, so for example:
   //
   // {column: 'Noun', values: ['98', '121'], type: 'ALL'} => results with a noun containing the substrings 'RE' AND 'TAC'
   // {column: 'Noun', values: ['98', '121'], type: 'ANY'} => results with a noun containing the substrings 'RE' OR 'TAC' 
   // {column: 'Noun', values: ['98', '121'], type: 'NONE_OF'} => results with a noun not containing either of the substrings 'RE' OR 'TAC'
   filters: [{column: 'Zip', values: ['98121', '98208'], type: 'ANY'}]
});

Download search results

import {vendor} from "@symmetrichs/sdk";

const download = await vendor.download({
   // Most options are the same as for `search`, including filters
   query: 'seattle',
   columns: ['Name', 'City'],
   // Some options are `download` specific
   format: 'csv' // Available formats are 'csv' and 'xlsx'
});
await download.ready();
const csvData = await fetch(download.url()).then(r => r.text());

Count search results

import {vendor} from "@symmetrichs/sdk";

const results = await vendor.count({
   // Most options are the same as for `search`, including filters
   query: 'seattle',
   column: 'City'
});

Full Node.js Example

const {configure, device} = require("@symmetrichs/sdk");

configure({
   apiKey: process.env.YOUR_API_KEY,
   apiSecret: process.env.YOUR_SECRET_KEY,
   appKey: process.env.YOUR_APP_KEY
});

(async () => {
  const results = await device.search({
    query: 'needle',
    columns: ['Primary DI', 'GMDN By Name']
  });
  console.log(JSON.stringify(results, null, 2));
})();

Documentation

Available Columns

A full list of columns is available at https://www.symmetrichealthsolutions.com/data. The column names as seen in the field_name_app of the download are the columns used by the SDK, and can be filtered on the database_name to view columns available for each of the sections above (device, pharmaceuticals, and vendors). Note that the substitute columns are the same columns as device.

Some example columns are as follows:

1. Device
   1. Primary DI
   2. Brand Name
   3. Noun
   4. UNSPSC
   5. HCPCS
   6. Parent Company Name
   7. Manufacturer Name Cleansed
   8. GMDN Preferred Term
2. Pharmaceuticals
   1. Product Packaging NDC
   2. Generic Name
   3. Labeler Name
   4. Package Description
   5. Established Pharmacologic Class
   6. Proprietary Name
   7. Substance Name
   8. Product NDC
3. Vendors
   1. Name
   2. City
   3. Minority Classification
   4. Vendor Description