Create Referring Provider

Creates a new referring provider record in your EMR system.

POST /referring-providers

Create Referring Provider

cURL

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>"
}
'

200

{
  "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": "[phone]"

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": "[e-mail]",
    "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

200

application/json

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