Skip to main content

Referring Providers via API

Search, create, and update referring providers (physicians) so you can attach them to orders and prescriptions.

Search for a Referring Provider

GET /v1/referring-providers

Always search before creating, to avoid duplicates.

Filter

Notes

npi

10-digit NPI. The most reliable way to match.

fullName

Provider's name

address

Part of the address

pageIndex / pageSize

Paging

GET /v1/referring-providers?npi=1144338880
{
"Count": 1,
"Items": [
{
"Id": "RP01d8eb00863baa596d54c7ab32b5a2d8",
"General": {
"Npi": "1144338880",
"Name": { "FirstName": "Steve", "LastName": "Johnson" },
"Practice": "Example Family Physicians"
},
"PrimaryLocation": {
"Id": "RL01d8eb00863b3ff9aef47dd9f5309dfa",
"Address": { "AddressLine": "123 Main St", "City": "Birmingham", "State": "AL", "Zip": "35203" },
"Contacts": { "Phone": "2055551234", "Fax": "2055555678" }
}
}
]
}

ID

Format

Used as

Provider Id

RP + 32 characters

ReferringProviderId on orders, TreatingProviderId on prescriptions

PrimaryLocation.Id

RL + 32 characters

ReferringProviderLocationId on orders, TreatingProviderLocationId on prescriptions

Get One Provider

GET /v1/referring-providers/{id}

Also returns any additional Locations, Note, and PecosEnrollment (whether the provider is PECOS-enrolled).


Create a Referring Provider

POST /v1/referring-providers

Fields

Field

Required

Notes

General.Npi

✅

Exactly 10 digits

General.Name.FirstName / LastName

✅

General.Title

e.g. MD, DO, NP

General.Practice

Practice name

PrimaryLocation.Address

✅

Requires AddressLine, City, Zip

PrimaryLocation.Contacts

✅

Phone, Fax, Email

PrimaryLocation.Name

Location name

Locations

Additional locations, same shape as PrimaryLocation

PayerOptions

Payer-specific provider type (see below)

Note

Free text

SalesAgentId and ContactPerson at the top level are deprecated. Set SalesAgentId, ContactPerson, and SalesAgentNote on each location instead.

Payer Options

Use PayerOptions when a provider should be submitted as a different provider type for a specific payer or plan.

Field

Required

Notes

ProviderType

✅

ReferringProvider or OrderingProvider

PayerId

From GET /v1/payers/dictionary

PayerPlanId

From GET /v1/payers/{payerId}/plans/dictionary

Example

POST /v1/referring-providers
{
"General": {
"Npi": "1144338880",
"Name": { "FirstName": "Steve", "LastName": "Johnson" },
"Title": "MD",
"Practice": "Example Family Physicians"
},
"PrimaryLocation": {
"Name": "Main Office",
"Address": {
"AddressLine": "123 Main St",
"City": "Birmingham",
"State": "AL",
"Zip": "35203"
},
"Contacts": {
"Phone": "2055551234",
"Fax": "2055555678"
}
}
}

Response: 201 Created

{ "Id": "RP01d8eb00863baa596d54c7ab32b5a2d8" }

💡 The response returns the provider's ID only. Call GET /v1/referring-providers/{id} to get the new PrimaryLocation.Id, which you'll need for orders and prescriptions.


Update a Referring Provider

PUT /v1/referring-providers/{id}

Send the full provider, using the same fields as creating one. To update an existing additional location, include its Id in Locations.

Response: 200 OK


Delete a Referring Provider

DELETE /v1/referring-providers/{id}

Response: 200 OK


Get Notified of Changes

Subscribe to referring-provider.created, referring-provider.updated, and referring-provider.deleted.


Common Errors

Code

Meaning

400

Invalid request, e.g. an NPI that isn't 10 digits, or a missing address or contacts

401

Token missing, expired, or invalid

403

You don't have permission to access this resource

404

Provider not found

429

Too many requests


Related articles

Did this answer your question?