Skip to main content

​
Quick Start Guide

Welcome to the Decoda Health API! This guide will help you make your first API call and start building integrations.

​
Prerequisites

  • API credentials (API key and tenant identifier)
  • cURL, Postman, or your preferred HTTP client
  • Basic understanding of REST APIs

​
Step 1: Get Your API Credentials

If you don’t have API credentials yet, contact Decoda Health Support to request access. You’ll receive:
  • API Key: Your authentication token
  • Tenant: Your tenant identifier (usually your organization’s subdomain)
Never expose your API key in client-side code or public repositories. Always use environment variables or secure configuration management.

​
Step 2: Make Your First API Call

Let’s start by fetching your tenant information to verify your credentials work: 
curl -X GET "https://api.decodahealth.com/tenant/public" \
     -H "API-KEY: YOUR_API_KEY" \
     -H "TENANT: YOUR_TENANT"
If successful, you’ll receive a JSON response with your tenant details. If you get an authentication error, double-check your API key and tenant identifier.

​
Step 3: Create Your First Patient

Now let’s create a patient record: 
curl -X POST "https://api.decodahealth.com/user/patient/create" \
     -H "API-KEY: YOUR_API_KEY" \
     -H "TENANT: YOUR_TENANT" \
     -H "Content-Type: application/json" \
     -d '{
       "first_name": "John",
       "last_name": "Doe",
       "phone_number": "+1234567890",
       "email": "[email protected]"
     }'
Save the patient ID from the response - you’ll need it for the next steps!

​
Step 4: Create an Appointment

Let’s schedule an appointment for the patient you just created: 
curl -X POST "https://api.decodahealth.com/calendar/appointment" \
     -H "API-KEY: YOUR_API_KEY" \
     -H "TENANT: YOUR_TENANT" \
     -H "Content-Type: application/json" \
     -d '{
       "patient_id": "PATIENT_ID_FROM_STEP_3",
       "start_time": "2024-03-15T10:00:00Z",
       "duration_minutes": 30,
       "service_id": "YOUR_SERVICE_ID"
     }'
You’ll need to replace YOUR_SERVICE_ID with an actual service ID from your tenant. Use the List Services endpoint to find available services.

​
Step 5: Process a Payment

Now let’s create a charge and process a payment: 
# First, create a charge
curl -X POST "https://api.decodahealth.com/billing/charge" \
     -H "API-KEY: YOUR_API_KEY" \
     -H "TENANT: YOUR_TENANT" \
     -H "Content-Type: application/json" \
     -d '{
       "patient_id": "PATIENT_ID_FROM_STEP_3",
       "items": [
         {
           "item_id": "YOUR_ITEM_ID",
           "quantity": 1,
           "unit_price_cents": 10000
         }
       ]
     }'

# Then, process the payment
curl -X POST "https://api.decodahealth.com/billing/payment" \
     -H "API-KEY: YOUR_API_KEY" \
     -H "TENANT: YOUR_TENANT" \
     -H "Content-Type: application/json" \
     -d '{
       "charge_id": "CHARGE_ID_FROM_ABOVE",
       "payment_method_id": "PATIENT_PAYMENT_METHOD_ID",
       "amount_cents": 10000
     }'

​
Step 6: Set Up Webhooks (Optional)

To receive real-time notifications about events in your account, set up webhooks: 
curl -X POST "https://api.decodahealth.com/webhook/create" \
     -H "API-KEY: YOUR_API_KEY" \
     -H "TENANT: YOUR_TENANT" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://your-server.com/webhooks",
       "subscriptions": ["PAYMENT_CREATED", "PATIENT_CREATED"],
       "notification_email": "[email protected]"
     }'
Save the webhook secret securely - you’ll need it to verify webhook signatures. See the Webhook Security guide for details.

​
Next Steps

Congratulations! You’ve completed the quick start guide. Here’s what to explore next:

API Reference

Browse all available endpoints organized by functionality

Webhooks

Learn how to receive real-time event notifications

Workflow Guides

See how to build complete workflows

Best Practices

Learn recommended patterns and practices

​
Common Issues

​
Authentication Errors

If you get a 401 Unauthorized error:
  • Verify your API key is correct
  • Check that your tenant identifier matches your account
  • Ensure headers are formatted correctly (case-sensitive)

​
Not Found Errors

If you get a 404 Not Found error:
  • Verify the endpoint URL is correct
  • Check that required IDs (patient_id, service_id, etc.) exist in your tenant
  • Ensure you’re using the correct API version

​
Rate Limiting

If you get a 429 Too Many Requests error:
  • Implement exponential backoff
  • Check rate limit headers in responses
  • Consider batching requests where possible

​
Getting Help