Picos Health API Reference

The Picos Health API is a RESTful service that enables developers to integrate with the Picos Health platform that provides access to user management, products, orders, care management, and financial operations.

** Important:** The Picos Health API uses multi-tenant subdomains. All API URLs include your organization's assigned subdomain. See the Your Organization section below for details on finding your subdomain.

Introduction

Get up and running with the Picos Health API. This section covers the essential information you need to start integrating with our platform, including authentication, making your first request, and understanding the core concepts.

Key Features

• Comprehensive user management with role-based access control
• Product catalog with HCPCS code support for medical supplies
• Order management and fulfillment tracking
• Care list management for coordinated patient care
• Financial operations including transactions and payment methods
• Messaging system for patient-provider communication
• Real-time webhooks for event-driven integrations

Quick Start

1. Your Organization

Before you can use the API, identify your organization's assigned subdomain.

How to find your organization's subdomain:

• If your subdomain is org-name from the Picos Health Platform URL.
• Use that subdomain in all API URLs:

https://{org-name}.api.picoshealth.com/v1

Note: Your organization's subdomain is unique and assigned at account creation. If unsure, contact your administrator or check your welcome email.

2. Get Your API Token

To use the Picos Health API, you'll need a Bearer token. Obtain it by exchanging your API key:

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

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

3. Make Your First API Request

Use your token to access the API:

const token = "your-bearer-token-here";

const response = await fetch('https://{org-name}.api.picoshealth.com/v1/users', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);

Authentication

All API requests require a Bearer token in the Authorization header. The token is a JWT (JSON Web Token) that expires after 1 hour.

Bearer Token Format

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Generating Tokens

Tokens are generated by exchanging your API key for a bearer token:

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

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

Token Expiration and Refresh

Tokens have a 1-hour expiration. To make another API request after expiration, generate a new token by exchanging your API key again:

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

Best Practices

• Store API keys securely (use environment variables, secrets managers, never commit to version control)
• Generate new tokens before expiration by exchanging your API key
• Don't share API keys or tokens with untrusted parties
• Use HTTPS for all API requests
• Rotate API keys periodically for security
• Use separate API keys for different applications or environments

Last Updated: June 22, 2026