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

import requests

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

payload = {
    "first_name": "<string>",
    "last_name": "<string>",
    "npi": "<string>",
    "phone": "<string>",
    "fax": "<string>",
    "email": "<string>",
    "address": "<string>",
    "city": "<string>",
    "state": "<string>",
    "zip_code": "<string>"
}
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: '<string>',
    last_name: '<string>',
    npi: '<string>',
    phone: '<string>',
    fax: '<string>',
    email: '<string>',
    address: '<string>',
    city: '<string>',
    state: '<string>',
    zip_code: '<string>'
  })
};

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' => '<string>',
    'last_name' => '<string>',
    'npi' => '<string>',
    'phone' => '<string>',
    'fax' => '<string>',
    'email' => '<string>',
    'address' => '<string>',
    'city' => '<string>',
    'state' => '<string>',
    'zip_code' => '<string>'
  ]),
  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\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"npi\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"fax\": \"<string>\",\n  \"email\": \"<string>\",\n  \"address\": \"<string>\",\n  \"city\": \"<string>\",\n  \"state\": \"<string>\",\n  \"zip_code\": \"<string>\"\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\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"npi\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"fax\": \"<string>\",\n  \"email\": \"<string>\",\n  \"address\": \"<string>\",\n  \"city\": \"<string>\",\n  \"state\": \"<string>\",\n  \"zip_code\": \"<string>\"\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\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"npi\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"fax\": \"<string>\",\n  \"email\": \"<string>\",\n  \"address\": \"<string>\",\n  \"city\": \"<string>\",\n  \"state\": \"<string>\",\n  \"zip_code\": \"<string>\"\n}"

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

{
  "success": true,
  "message": "<string>",
  "referring_provider_id": "<string>",
  "job_id": 123
}

{
  "success": true,
  "message": "<string>"
}

{
  "success": true,
  "message": "<string>"
}

{
  "success": true,
  "message": "<string>"
}

{
  "success": true,
  "message": "<string>"
}

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

import requests

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

payload = {
    "first_name": "<string>",
    "last_name": "<string>",
    "npi": "<string>",
    "phone": "<string>",
    "fax": "<string>",
    "email": "<string>",
    "address": "<string>",
    "city": "<string>",
    "state": "<string>",
    "zip_code": "<string>"
}
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: '<string>',
    last_name: '<string>',
    npi: '<string>',
    phone: '<string>',
    fax: '<string>',
    email: '<string>',
    address: '<string>',
    city: '<string>',
    state: '<string>',
    zip_code: '<string>'
  })
};

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' => '<string>',
    'last_name' => '<string>',
    'npi' => '<string>',
    'phone' => '<string>',
    'fax' => '<string>',
    'email' => '<string>',
    'address' => '<string>',
    'city' => '<string>',
    'state' => '<string>',
    'zip_code' => '<string>'
  ]),
  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\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"npi\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"fax\": \"<string>\",\n  \"email\": \"<string>\",\n  \"address\": \"<string>\",\n  \"city\": \"<string>\",\n  \"state\": \"<string>\",\n  \"zip_code\": \"<string>\"\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\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"npi\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"fax\": \"<string>\",\n  \"email\": \"<string>\",\n  \"address\": \"<string>\",\n  \"city\": \"<string>\",\n  \"state\": \"<string>\",\n  \"zip_code\": \"<string>\"\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\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"npi\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"fax\": \"<string>\",\n  \"email\": \"<string>\",\n  \"address\": \"<string>\",\n  \"city\": \"<string>\",\n  \"state\": \"<string>\",\n  \"zip_code\": \"<string>\"\n}"

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

{
  "success": true,
  "message": "<string>",
  "referring_provider_id": "<string>",
  "job_id": 123
}

{
  "success": true,
  "message": "<string>"
}

{
  "success": true,
  "message": "<string>"
}

{
  "success": true,
  "message": "<string>"
}

{
  "success": true,
  "message": "<string>"
}

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 - 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

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

Update Referral Get Referring Providers

​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 - ECW 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 - ECW Validation Error

Failure - Other Errors

Usage with Patient Creation

Notes