Create Referring Provider

Create a 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": "Jane",
  "last_name": "Doe",
  "npi": "1234567890",
  "middle_initial": "A",
  "speciality": "Cardiology",
  "phone": "555-123-4567",
  "fax": "555-123-4568",
  "email": "referrals@example-clinic.com",
  "address": "123 Main Street",
  "city": "Los Angeles",
  "state": "CA",
  "zip_code": "90001",
  "callback_urls": [
    "https://example.com/webhooks/cobalt"
  ]
}
'

import requests

url = "https://api.usecobalt.com/v1/referring-providers"

payload = {
    "first_name": "Jane",
    "last_name": "Doe",
    "npi": "1234567890",
    "middle_initial": "A",
    "speciality": "Cardiology",
    "phone": "555-123-4567",
    "fax": "555-123-4568",
    "email": "referrals@example-clinic.com",
    "address": "123 Main Street",
    "city": "Los Angeles",
    "state": "CA",
    "zip_code": "90001",
    "callback_urls": ["https://example.com/webhooks/cobalt"]
}
headers = {
    "client_id": "<api-key>",
    "client_secret": "<api-key>",
    "access_token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    client_id: '<api-key>',
    client_secret: '<api-key>',
    access_token: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    first_name: 'Jane',
    last_name: 'Doe',
    npi: '1234567890',
    middle_initial: 'A',
    speciality: 'Cardiology',
    phone: '555-123-4567',
    fax: '555-123-4568',
    email: 'referrals@example-clinic.com',
    address: '123 Main Street',
    city: 'Los Angeles',
    state: 'CA',
    zip_code: '90001',
    callback_urls: ['https://example.com/webhooks/cobalt']
  })
};

fetch('https://api.usecobalt.com/v1/referring-providers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecobalt.com/v1/referring-providers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'first_name' => 'Jane',
    'last_name' => 'Doe',
    'npi' => '1234567890',
    'middle_initial' => 'A',
    'speciality' => 'Cardiology',
    'phone' => '555-123-4567',
    'fax' => '555-123-4568',
    'email' => 'referrals@example-clinic.com',
    'address' => '123 Main Street',
    'city' => 'Los Angeles',
    'state' => 'CA',
    'zip_code' => '90001',
    'callback_urls' => [
        'https://example.com/webhooks/cobalt'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "access_token: <api-key>",
    "client_id: <api-key>",
    "client_secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecobalt.com/v1/referring-providers"

	payload := strings.NewReader("{\n  \"first_name\": \"Jane\",\n  \"last_name\": \"Doe\",\n  \"npi\": \"1234567890\",\n  \"middle_initial\": \"A\",\n  \"speciality\": \"Cardiology\",\n  \"phone\": \"555-123-4567\",\n  \"fax\": \"555-123-4568\",\n  \"email\": \"referrals@example-clinic.com\",\n  \"address\": \"123 Main Street\",\n  \"city\": \"Los Angeles\",\n  \"state\": \"CA\",\n  \"zip_code\": \"90001\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("client_id", "<api-key>")
	req.Header.Add("client_secret", "<api-key>")
	req.Header.Add("access_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usecobalt.com/v1/referring-providers")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"first_name\": \"Jane\",\n  \"last_name\": \"Doe\",\n  \"npi\": \"1234567890\",\n  \"middle_initial\": \"A\",\n  \"speciality\": \"Cardiology\",\n  \"phone\": \"555-123-4567\",\n  \"fax\": \"555-123-4568\",\n  \"email\": \"referrals@example-clinic.com\",\n  \"address\": \"123 Main Street\",\n  \"city\": \"Los Angeles\",\n  \"state\": \"CA\",\n  \"zip_code\": \"90001\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usecobalt.com/v1/referring-providers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"first_name\": \"Jane\",\n  \"last_name\": \"Doe\",\n  \"npi\": \"1234567890\",\n  \"middle_initial\": \"A\",\n  \"speciality\": \"Cardiology\",\n  \"phone\": \"555-123-4567\",\n  \"fax\": \"555-123-4568\",\n  \"email\": \"referrals@example-clinic.com\",\n  \"address\": \"123 Main Street\",\n  \"city\": \"Los Angeles\",\n  \"state\": \"CA\",\n  \"zip_code\": \"90001\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Request processed.",
  "referring_provider_id": "980a7e9525a34ca39bf39ba318448ace",
  "job_id": 1234
}

{
  "success": false,
  "message": "Bad request — missing or invalid parameters"
}

{
  "success": false,
  "message": "Unauthorized — missing or invalid credentials"
}

{
  "success": false,
  "message": "Internal server error"
}

POST

referring-providers

Create a 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": "Jane",
  "last_name": "Doe",
  "npi": "1234567890",
  "middle_initial": "A",
  "speciality": "Cardiology",
  "phone": "555-123-4567",
  "fax": "555-123-4568",
  "email": "referrals@example-clinic.com",
  "address": "123 Main Street",
  "city": "Los Angeles",
  "state": "CA",
  "zip_code": "90001",
  "callback_urls": [
    "https://example.com/webhooks/cobalt"
  ]
}
'

import requests

url = "https://api.usecobalt.com/v1/referring-providers"

payload = {
    "first_name": "Jane",
    "last_name": "Doe",
    "npi": "1234567890",
    "middle_initial": "A",
    "speciality": "Cardiology",
    "phone": "555-123-4567",
    "fax": "555-123-4568",
    "email": "referrals@example-clinic.com",
    "address": "123 Main Street",
    "city": "Los Angeles",
    "state": "CA",
    "zip_code": "90001",
    "callback_urls": ["https://example.com/webhooks/cobalt"]
}
headers = {
    "client_id": "<api-key>",
    "client_secret": "<api-key>",
    "access_token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    client_id: '<api-key>',
    client_secret: '<api-key>',
    access_token: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    first_name: 'Jane',
    last_name: 'Doe',
    npi: '1234567890',
    middle_initial: 'A',
    speciality: 'Cardiology',
    phone: '555-123-4567',
    fax: '555-123-4568',
    email: 'referrals@example-clinic.com',
    address: '123 Main Street',
    city: 'Los Angeles',
    state: 'CA',
    zip_code: '90001',
    callback_urls: ['https://example.com/webhooks/cobalt']
  })
};

fetch('https://api.usecobalt.com/v1/referring-providers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecobalt.com/v1/referring-providers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'first_name' => 'Jane',
    'last_name' => 'Doe',
    'npi' => '1234567890',
    'middle_initial' => 'A',
    'speciality' => 'Cardiology',
    'phone' => '555-123-4567',
    'fax' => '555-123-4568',
    'email' => 'referrals@example-clinic.com',
    'address' => '123 Main Street',
    'city' => 'Los Angeles',
    'state' => 'CA',
    'zip_code' => '90001',
    'callback_urls' => [
        'https://example.com/webhooks/cobalt'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "access_token: <api-key>",
    "client_id: <api-key>",
    "client_secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecobalt.com/v1/referring-providers"

	payload := strings.NewReader("{\n  \"first_name\": \"Jane\",\n  \"last_name\": \"Doe\",\n  \"npi\": \"1234567890\",\n  \"middle_initial\": \"A\",\n  \"speciality\": \"Cardiology\",\n  \"phone\": \"555-123-4567\",\n  \"fax\": \"555-123-4568\",\n  \"email\": \"referrals@example-clinic.com\",\n  \"address\": \"123 Main Street\",\n  \"city\": \"Los Angeles\",\n  \"state\": \"CA\",\n  \"zip_code\": \"90001\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("client_id", "<api-key>")
	req.Header.Add("client_secret", "<api-key>")
	req.Header.Add("access_token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usecobalt.com/v1/referring-providers")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"first_name\": \"Jane\",\n  \"last_name\": \"Doe\",\n  \"npi\": \"1234567890\",\n  \"middle_initial\": \"A\",\n  \"speciality\": \"Cardiology\",\n  \"phone\": \"555-123-4567\",\n  \"fax\": \"555-123-4568\",\n  \"email\": \"referrals@example-clinic.com\",\n  \"address\": \"123 Main Street\",\n  \"city\": \"Los Angeles\",\n  \"state\": \"CA\",\n  \"zip_code\": \"90001\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usecobalt.com/v1/referring-providers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"first_name\": \"Jane\",\n  \"last_name\": \"Doe\",\n  \"npi\": \"1234567890\",\n  \"middle_initial\": \"A\",\n  \"speciality\": \"Cardiology\",\n  \"phone\": \"555-123-4567\",\n  \"fax\": \"555-123-4568\",\n  \"email\": \"referrals@example-clinic.com\",\n  \"address\": \"123 Main Street\",\n  \"city\": \"Los Angeles\",\n  \"state\": \"CA\",\n  \"zip_code\": \"90001\",\n  \"callback_urls\": [\n    \"https://example.com/webhooks/cobalt\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Request processed.",
  "referring_provider_id": "980a7e9525a34ca39bf39ba318448ace",
  "job_id": 1234
}

{
  "success": false,
  "message": "Bad request — missing or invalid parameters"
}

{
  "success": false,
  "message": "Unauthorized — missing or invalid credentials"
}

{
  "success": false,
  "message": "Internal server error"
}

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": "john.smith@example.com",
    "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 - EMR 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
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

Referring provider first name.

Example:

"Jane"

last_name

string

required

Referring provider last name.

Example:

"Doe"

npi

string

required

Referring provider National Provider Identifier.

Example:

"1234567890"

middle_initial

string

Referring provider middle initial. Not sent to the EMR. Accepted, but no EMR uses it, so it has no effect.

Example:

"A"

speciality

string

Referring provider speciality. Not sent to the EMR. Accepted, but no EMR uses it, so it has no effect.

Example:

"Cardiology"

phone

string

Phone number in XXX-XXX-XXXX format.

Example:

"555-123-4567"

fax

string

Fax number in XXX-XXX-XXXX format.

Example:

"555-123-4568"

string

Referring provider email address.

Example:

"referrals@example-clinic.com"

address

string

Street address.

Example:

"123 Main Street"

city

string

City.

Example:

"Los Angeles"

state

string

State code.

Example:

"CA"

zip_code

string

ZIP code.

Example:

"90001"

callback_urls

string[]

URLs to receive the completion webhook for this referring provider, in addition to the account webhook.

Example:

["https://example.com/webhooks/cobalt"]

Response

Referring provider queued for creation

success

boolean

required

Example:

true

message

string

required

Example:

"Request processed."

referring_provider_id

string

required

Example:

"980a7e9525a34ca39bf39ba318448ace"

job_id

required

Example:

1234

​Request Parameters

​Required Fields

​Optional Fields

​Phone and Fax Format

​Example Request

​Example Response

​Error Responses

​Missing Required Field

​Invalid Phone Format

​Invalid Fax Format

​Webhook Notifications

​Success

​Failure - Invalid NPI

​Failure - EMR Validation Error

​Failure - Other Errors

​Usage with Patient Creation

​Notes

Authorizations

Body

Response

Request Parameters

Required Fields

Optional Fields

Phone and Fax Format

Example Request

Example Response

Error Responses

Missing Required Field

Invalid Phone Format

Invalid Fax Format

Webhook Notifications

Success

Failure - Invalid NPI

Failure - EMR Validation Error

Failure - Other Errors

Usage with Patient Creation

Notes