Skip to main content
POST
/
referring-providers
Create Referring Provider
curl --request POST \
  --url https://api.usecobalt.com/v1/referring-providers \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "first_name": "<string>",
  "last_name": "<string>",
  "npi": "<string>",
  "phone": "<string>",
  "fax": "<string>",
  "email": "<string>",
  "address": "<string>",
  "city": "<string>",
  "state": "<string>",
  "zip_code": "<string>"
}
'
{
  "success": true,
  "message": "<string>",
  "referring_provider_id": "<string>",
  "job_id": 123
}

​
Request Parameters

​
Required Fields

  • first_name (string, required): Provider’s first name
  • last_name (string, required): Provider’s last name
  • npi (string, required): National Provider Identifier

​
Optional Fields

  • phone (string): Contact phone number in XXX-XXX-XXXX format
  • fax (string): Fax number in XXX-XXX-XXXX format
  • email (string): Contact email address
  • address (string): Street address
  • city (string): City name
  • state (string): State abbreviation (e.g., “IL”, “CA”)
  • zip_code (string): ZIP code

​
Phone and Fax Format

Phone and fax numbers must be provided in XXX-XXX-XXXX format. If the format is incorrect, you will receive a 400 error. 
// Valid
"phone": "312-555-1234"

// Invalid
"phone": "3125551234"
"phone": "(312) 555-1234"

​
Example Request

curl -X POST https://api.usecobalt.com/v1/referring-providers \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "first_name": "John",
    "last_name": "Smith",
    "npi": "1234567890",
    "phone": "312-555-1234",
    "fax": "312-555-5678",
    "email": "[email protected]",
    "address": "123 Main St",
    "city": "Chicago",
    "state": "IL",
    "zip_code": "60601"
}'

​
Example Response

{
    "success": true,
    "message": "Referring provider processing. A webhook event will be sent upon completion.",
    "referring_provider_id": "e35e82b85df58f08a9b38e06a91e9f1a",
    "job_id": 12345
}
The response includes:
  • referring_provider_id: Unique identifier for the created referring provider record (UUID without dashes)
  • job_id: Job execution identifier for tracking the async operation

​
Error Responses

​
Missing Required Field

{
    "success": false,
    "message": "Missing required fields: npi."
}

​
Invalid Phone Format

{
    "success": false,
    "message": "Phone number must be in XXX-XXX-XXXX format."
}

​
Invalid Fax Format

{
    "success": false,
    "message": "Fax number must be in XXX-XXX-XXXX format."
}

​
Webhook Notifications

When the referring provider processing is complete, we will send a webhook to your registered endpoint. Here are examples of what those webhook payloads will look like:

​
Success

{
    "id": "evt_1J9X2q2eZvKYlo2CluR9g9gV",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cxyz",
    "object": "event",
    "created": "2025-01-18T10:30:00Z",
    "type": "referring_provider.created",
    "job_id": "12345",
    "data": {
        "referring_provider_id": "e35e82b85df58f08a9b38e06a91e9f1a",
        "ehr_id": "350143",
        "first_name": "John",
        "last_name": "Smith",
        "npi": "1234567890"
    }
}

​
Failure - Invalid NPI

{
    "id": "evt_1J9X2q2eZvKYlo2CluR9g9gW",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cxyz",
    "object": "event",
    "created": "2025-01-18T10:35:00Z",
    "type": "referring_provider.failed",
    "job_id": "12345",
    "data": {
        "referring_provider_id": "e35e82b85df58f08a9b38e06a91e9f1a",
        "first_name": "John",
        "last_name": "Smith",
        "npi": "1234567890",
        "failure_reason": "Invalid NPI: 1234567890. The NPI number is not valid.",
        "error_type": "invalid_npi"
    }
}

​
Failure - ECW Validation Error

{
    "id": "evt_1J9X2q2eZvKYlo2CluR9g9gX",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cxyz",
    "object": "event",
    "created": "2025-01-18T10:40:00Z",
    "type": "referring_provider.failed",
    "job_id": "12345",
    "data": {
        "referring_provider_id": "e35e82b85df58f08a9b38e06a91e9f1a",
        "first_name": "John",
        "last_name": "Smith",
        "npi": "1234567890",
        "failure_reason": "Unable to create referring provider in eCW. ECW rejected the request. Please verify all required fields are provided and the provider doesn't already exist.",
        "error_type": "ecw_validation_failure"
    }
}

​
Failure - Other Errors

{
    "id": "evt_1J9X2q2eZvKYlo2CluR9g9gY",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cxyz",
    "object": "event",
    "created": "2025-01-18T10:45:00Z",
    "type": "referring_provider.failed",
    "job_id": "12345",
    "data": {
        "referring_provider_id": "e35e82b85df58f08a9b38e06a91e9f1a",
        "first_name": "John",
        "last_name": "Smith",
        "npi": "1234567890",
        "failure_reason": "Failed to create referring provider"
    }
}
Referring provider creation is asynchronous. Store the returned referring_provider_id and listen for webhooks to determine the final status.

​
Usage with Patient Creation

Once created, you can use the referring_provider_id when creating patients instead of providing referring provider names. See the Create Patient documentation for details on using referring_provider_id.

​
Notes

  • NPI validation is performed by the EMR system (e.g., eClinicalWorks)
  • Some EMRs may reject duplicate providers with the same NPI
  • Phone and fax numbers are normalized before being sent to the EMR
  • The ehr_id returned in the success webhook is the provider’s ID in your EMR system

Authorizations

​
client_id
string
header
required
​
client_secret
string
header
required
​
access_token
string
header
required

Body

application/json
​
first_name
string
required

Provider's first name

​
last_name
string
required

Provider's last name

​
npi
string
required

National Provider Identifier

​
phone
string

Contact phone number in XXX-XXX-XXXX format

​
fax
string

Fax number in XXX-XXX-XXXX format

​
email
string

Contact email address

​
address
string

Street address

​
city
string

City name

​
state
string

State abbreviation (e.g., IL, CA)

​
zip_code
string

ZIP code

Response

Successful response

​
success
boolean
​
message
string
​
referring_provider_id
string

Cobalt referring provider ID (UUID without dashes)

​
job_id
integer

Job execution identifier for tracking the async operation