Quickstart - Perfect Referral

From API token to your first request in three steps.

This guide takes you from zero to your first successful API call. By the end, you’ll have an API token and a working request that looks up a practitioner by their NPI number.

New to working with APIs? An API is just a way for your software to ask ours a question and get a structured answer back. You will need an API token to identify yourself, send a request, and read the response. This guide assumes no prior experience and shows every step.

Create an account

Create an API token

Open the API tokens page

Once signed in, go to the API tokens section of the developer portal.

Generate a new token

Click Create API token, give it a descriptive name (for example, local-testing or production), and confirm.

Copy and store it safely

Your token is shown only once. Copy it and store it somewhere secure, such as a password manager.

Treat your API token like a password. Don’t commit it to source control, paste it into client-side code, or share it. If a token is exposed, revoke it in the developer portal and create a new one.

Make your first request

Every request is authenticated with your API token sent as a Bearer token in the Authorization header, and is made against the base URL:

https://api.perfectreferral.com/v1

The example below looks up an individual practitioner by their NPI number using the GET /practitioners/{npiNumber} endpoint. Replace YOUR_API_TOKEN with the token you just created and 1234567890 with the NPI you want to look up.

curl https://api.perfectreferral.com/v1/practitioners/1234567890 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

import requests

API_TOKEN = "YOUR_API_TOKEN"
npi_number = "1234567890"

response = requests.get(
    f"https://api.perfectreferral.com/v1/practitioners/{npi_number}",
    headers={"Authorization": f"Bearer {API_TOKEN}"},
)
response.raise_for_status()

print(response.json())

const API_TOKEN = "YOUR_API_TOKEN";
const npiNumber = "1234567890";

const response = await fetch(
  `https://api.perfectreferral.com/v1/practitioners/${npiNumber}`,
  { headers: { Authorization: `Bearer ${API_TOKEN}` } },
);

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

console.log(await response.json());

The Python example uses the requests library; install it with pip install requests. The JavaScript example uses the built-in fetch, available in Node.js 18+ and all modern browsers (though for security, only call the API from a server, never from browser code where your token would be exposed).

Understand the response

A successful request returns 200 OK with core practitioner data and the available model outputs. Each model has its own response field and label:

{
  "name": "Dr. Naomi Park",
  "nppesSpecialties": ["Ophthalmology"],
  "referralScopeMatches": [
    {
      "specialty": "Ophthalmology",
      "target": "Cataract evaluation and surgery",
      "label": "very_likely_match"
    }
  ],
  "locations": [
    {
      "line1": "123 Main Street",
      "city": "San Diego",
      "state": "CA",
      "postalCode": "92103",
      "staleAffiliationRisk": {
        "label": "very_likely_active"
      }
    }
  ]
}

referralScopeMatches describes how well the practitioner fits a referral target, while staleAffiliationRisk describes whether a practitioner-location affiliation is active today. The Methodology & limitations pages explain each model and its labels.

Next steps

API Reference

Explore the full list of endpoints, parameters, and response schemas.

Need help? Reach out to us at support@threshold.health.

​Create an account

​Create an API token

​Make your first request

​Understand the response

​Next steps

API Reference

Create an account

Create an API token

Make your first request

Understand the response

Next steps