Skip to content
API Docs/
/
Your first API call
Last updated

Your first API call

This guide walks you through making your first successful API call — registering a patient via NHS PDS (Personal Demographics Service). PDS tracing is at the heart of Hero's patient communication and booking flows: it ensures you're working with the most up-to-date contact details for a patient before sending a message or generating a booking link.

Prerequisites

Before you begin:

Step 1: Store your credentials

Store your API key and practice group ID in environment variables. Never hard-code credentials in source files.

# .env
HERO_API_KEY=your_staging_or_production_key_here
HERO_PRACTICE_GROUP_ID=your_practice_group_id_here
Start on staging

Use your staging API key and https://api.staging.htech.app as the base URL while building and testing your integration. Switch to https://api.herohealth.net and your production key when you go live.

Step 2: Register a patient via PDS

POST /v1/patients/register_pds traces a patient against the NHS Spine using their NHS number and date of birth. Hero returns a patient_id you can use in subsequent messaging and booking calls.

curl -X POST "https://api.staging.htech.app/v1/patients/register_pds" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-practice-group-id: YOUR_PRACTICE_GROUP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "nhs_number": "123 456 7891",
    "dob": "1992-01-01"
  }'

Step 3: Understand the response

There are two possible success responses depending on whether the patient needs to verify their identity.

Patient registered successfully

{
  "patient_id": "98765"
}

Store the patient_id — you'll pass it to subsequent API calls such as generating a booking link or sending a message.

Patient identity verification required

{
  "message": "Patient must verify their identity before proceeding",
  "login_url": "https://patient.herohealth.net/verify/abc123"
}

This occurs when Hero cannot fully confirm the patient's identity from PDS alone. Direct the patient to the login_url to complete verification before retrying.

Handling errors

StatusCauseFix
400 Bad RequestMissing or invalid nhs_number or dobCheck the request body matches the expected format
401 UnauthorizedMissing or invalid x-api-keyVerify your key and that you're pointing at the right environment
403 ForbiddenKey does not have access to this practiceCheck your x-practice-group-id matches your key's configured practice
404 Not FoundNo patient found on PDS for the given NHS number and DOBConfirm the details are correct and the patient is registered with NHS
429 Too Many RequestsRate limit exceededRetry with exponential backoff using the Retry-After header

Retry with backoff

async function postWithRetry(url, options, retries = 3) {
  const response = await fetch(url, options);

  if (response.status === 429 && retries > 0) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '60', 10);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return postWithRetry(url, options, retries - 1);
  }

  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }

  return response.json();
}

Next steps

With a patient_id in hand, you can now:

Previous page
Next page