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, and from there you 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 the practitioner’s name, their NPPES-registered specialties, and their scope of practice:

{
  "name": "Dr. Naomi Park",
  "nppesSpecialties": ["Ophthalmology"],
  "referralScopeMatches": [
    {
      "specialty": "Ophthalmology",
      "target": "Cataract evaluation and surgery",
      "label": "very_likely_match"
    }
  ]
}

Each entry in referralScopeMatches pairs a target (a specific reason a provider is referred into a specialty, like cataract evaluation in ophthalmology) with a label describing how well the provider fits it. The API returns one of six labels: five sit on a single scale from strong match to strong rule-out, and the sixth marks the cases where there is too little data to judge.

Label	What it means
`very_likely_match`	Strong evidence this provider fits the target
`likely_match`	Good evidence this provider fits the target
`uncertain`	Evaluable, but the evidence is genuinely mixed
`unlikely_match`	Good evidence this provider does not fit
`very_unlikely_match`	Strong evidence this provider does not fit
`insufficient_data`	Too little billing data to make a confident call

The strong labels (very_likely_match, very_unlikely_match) are calibrated to be correct at least 95% of the time, and the moderate labels (likely_match, unlikely_match) at least 80%. See Methodology & limitations for how we derive and validate the scale.

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