Create a prior authorization on a policy

curl --request POST \
  --url https://api.maxcare.ai/v4/ehr/patients/{patientId}/insurances/{policyRef}/prior-authorizations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Organization-Id: <x-organization-id>' \
  --header 'x-session-token: <x-session-token>' \
  --data '
{
  "authorizationNumber": "A12345678",
  "description": "Mohs surgery, left cheek",
  "authType": "authorization",
  "active": true,
  "startDate": "<string>",
  "endDate": "<string>",
  "numVisits": 50,
  "unlimited": false,
  "note": "<string>",
  "appointmentTypeIds": [
    "<string>"
  ],
  "assignedProviderRef": "<string>",
  "referringProvider": {
    "npi": "1234567893",
    "name": "Jane Doe MD"
  },
  "documentRef": "<string>"
}
'

import requests

url = "https://api.maxcare.ai/v4/ehr/patients/{patientId}/insurances/{policyRef}/prior-authorizations"

payload = {
    "authorizationNumber": "A12345678",
    "description": "Mohs surgery, left cheek",
    "authType": "authorization",
    "active": True,
    "startDate": "<string>",
    "endDate": "<string>",
    "numVisits": 50,
    "unlimited": False,
    "note": "<string>",
    "appointmentTypeIds": ["<string>"],
    "assignedProviderRef": "<string>",
    "referringProvider": {
        "npi": "1234567893",
        "name": "Jane Doe MD"
    },
    "documentRef": "<string>"
}
headers = {
    "x-session-token": "<x-session-token>",
    "X-Organization-Id": "<x-organization-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-session-token': '<x-session-token>',
    'X-Organization-Id': '<x-organization-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    authorizationNumber: 'A12345678',
    description: 'Mohs surgery, left cheek',
    authType: 'authorization',
    active: true,
    startDate: '<string>',
    endDate: '<string>',
    numVisits: 50,
    unlimited: false,
    note: '<string>',
    appointmentTypeIds: ['<string>'],
    assignedProviderRef: '<string>',
    referringProvider: {npi: '1234567893', name: 'Jane Doe MD'},
    documentRef: '<string>'
  })
};

fetch('https://api.maxcare.ai/v4/ehr/patients/{patientId}/insurances/{policyRef}/prior-authorizations', 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.maxcare.ai/v4/ehr/patients/{patientId}/insurances/{policyRef}/prior-authorizations",
  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([
    'authorizationNumber' => 'A12345678',
    'description' => 'Mohs surgery, left cheek',
    'authType' => 'authorization',
    'active' => true,
    'startDate' => '<string>',
    'endDate' => '<string>',
    'numVisits' => 50,
    'unlimited' => false,
    'note' => '<string>',
    'appointmentTypeIds' => [
        '<string>'
    ],
    'assignedProviderRef' => '<string>',
    'referringProvider' => [
        'npi' => '1234567893',
        'name' => 'Jane Doe MD'
    ],
    'documentRef' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Organization-Id: <x-organization-id>",
    "x-session-token: <x-session-token>"
  ],
]);

$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.maxcare.ai/v4/ehr/patients/{patientId}/insurances/{policyRef}/prior-authorizations"

	payload := strings.NewReader("{\n  \"authorizationNumber\": \"A12345678\",\n  \"description\": \"Mohs surgery, left cheek\",\n  \"authType\": \"authorization\",\n  \"active\": true,\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\",\n  \"numVisits\": 50,\n  \"unlimited\": false,\n  \"note\": \"<string>\",\n  \"appointmentTypeIds\": [\n    \"<string>\"\n  ],\n  \"assignedProviderRef\": \"<string>\",\n  \"referringProvider\": {\n    \"npi\": \"1234567893\",\n    \"name\": \"Jane Doe MD\"\n  },\n  \"documentRef\": \"<string>\"\n}")

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

	req.Header.Add("x-session-token", "<x-session-token>")
	req.Header.Add("X-Organization-Id", "<x-organization-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	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.maxcare.ai/v4/ehr/patients/{patientId}/insurances/{policyRef}/prior-authorizations")
  .header("x-session-token", "<x-session-token>")
  .header("X-Organization-Id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"authorizationNumber\": \"A12345678\",\n  \"description\": \"Mohs surgery, left cheek\",\n  \"authType\": \"authorization\",\n  \"active\": true,\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\",\n  \"numVisits\": 50,\n  \"unlimited\": false,\n  \"note\": \"<string>\",\n  \"appointmentTypeIds\": [\n    \"<string>\"\n  ],\n  \"assignedProviderRef\": \"<string>\",\n  \"referringProvider\": {\n    \"npi\": \"1234567893\",\n    \"name\": \"Jane Doe MD\"\n  },\n  \"documentRef\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.maxcare.ai/v4/ehr/patients/{patientId}/insurances/{policyRef}/prior-authorizations")

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

request = Net::HTTP::Post.new(url)
request["x-session-token"] = '<x-session-token>'
request["X-Organization-Id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"authorizationNumber\": \"A12345678\",\n  \"description\": \"Mohs surgery, left cheek\",\n  \"authType\": \"authorization\",\n  \"active\": true,\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\",\n  \"numVisits\": 50,\n  \"unlimited\": false,\n  \"note\": \"<string>\",\n  \"appointmentTypeIds\": [\n    \"<string>\"\n  ],\n  \"assignedProviderRef\": \"<string>\",\n  \"referringProvider\": {\n    \"npi\": \"1234567893\",\n    \"name\": \"Jane Doe MD\"\n  },\n  \"documentRef\": \"<string>\"\n}"

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

{
  "code": "success",
  "data": {
    "ref": "<string>",
    "ehr": "modmed",
    "authorizationNumber": "A12345678",
    "ignoredFields": [
      "referringProvider"
    ],
    "documentLinked": true
  }
}

{
  "code": "bad_request",
  "message": "'id' must be a valid UUID",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "unauthorized",
  "message": "Invalid or missing API key",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "forbidden",
  "message": "Insufficient scope",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "not_found",
  "message": "Resource not found",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "conflict",
  "message": "Cannot edit a signed note",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "controlled_substance_unsupported",
  "message": "Controlled substances cannot be prescribed through the API",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {}
}

{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Maximum 1000 requests per 60 seconds.",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "capability_unsupported",
  "message": "This organization's EHR has no appointment finder.",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "server_unresponsive",
  "message": "EHR integration is not available for this note",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

EHR live reads

Create a prior authorization on a policy

Writes one authorization to the EHR, live; nothing is de-duplicated here, so read GET …/prior-authorizations first. Send exactly one of numVisits or unlimited: true. documentRef (a document ref from POST /v4/patients/{id}/documents or GET /v4/ehr/patients/{id}/documents) is linked to the new authorization on ModMed; documentLinked: false means the authorization exists but the link did not land. On ModMed, note is Additional Notes, assignedProviderRef is a provider id from the reads, and referringProvider is matched by individual NPI to the practice’s active referral contacts (a group NPI is not matched). ignoredFields lists sent fields that were not written: on ModMed only referringProvider when it could not be matched to a referral contact (none has that NPI, or the lookup failed); on EZDerm authType, active, note, appointmentTypeIds, assignedProviderRef, referringProvider and documentRef (EZDerm stores description as its note). Send an Idempotency-Key: a replay returns the first result for 24 hours. 409 ehr_write_uncertain when the EHR’s answer is unknown: re-read the list before sending again. 422 prior_auth_refused when the EHR refused it (nothing written). 404 for an unknown patient, policy or documentRef. Requires write:prior_authorizations.

POST

ehr

patients

{patientId}

insurances

{policyRef}

prior-authorizations

Create a prior authorization on a policy

curl --request POST \
  --url https://api.maxcare.ai/v4/ehr/patients/{patientId}/insurances/{policyRef}/prior-authorizations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Organization-Id: <x-organization-id>' \
  --header 'x-session-token: <x-session-token>' \
  --data '
{
  "authorizationNumber": "A12345678",
  "description": "Mohs surgery, left cheek",
  "authType": "authorization",
  "active": true,
  "startDate": "<string>",
  "endDate": "<string>",
  "numVisits": 50,
  "unlimited": false,
  "note": "<string>",
  "appointmentTypeIds": [
    "<string>"
  ],
  "assignedProviderRef": "<string>",
  "referringProvider": {
    "npi": "1234567893",
    "name": "Jane Doe MD"
  },
  "documentRef": "<string>"
}
'

import requests

url = "https://api.maxcare.ai/v4/ehr/patients/{patientId}/insurances/{policyRef}/prior-authorizations"

payload = {
    "authorizationNumber": "A12345678",
    "description": "Mohs surgery, left cheek",
    "authType": "authorization",
    "active": True,
    "startDate": "<string>",
    "endDate": "<string>",
    "numVisits": 50,
    "unlimited": False,
    "note": "<string>",
    "appointmentTypeIds": ["<string>"],
    "assignedProviderRef": "<string>",
    "referringProvider": {
        "npi": "1234567893",
        "name": "Jane Doe MD"
    },
    "documentRef": "<string>"
}
headers = {
    "x-session-token": "<x-session-token>",
    "X-Organization-Id": "<x-organization-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-session-token': '<x-session-token>',
    'X-Organization-Id': '<x-organization-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    authorizationNumber: 'A12345678',
    description: 'Mohs surgery, left cheek',
    authType: 'authorization',
    active: true,
    startDate: '<string>',
    endDate: '<string>',
    numVisits: 50,
    unlimited: false,
    note: '<string>',
    appointmentTypeIds: ['<string>'],
    assignedProviderRef: '<string>',
    referringProvider: {npi: '1234567893', name: 'Jane Doe MD'},
    documentRef: '<string>'
  })
};

fetch('https://api.maxcare.ai/v4/ehr/patients/{patientId}/insurances/{policyRef}/prior-authorizations', 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.maxcare.ai/v4/ehr/patients/{patientId}/insurances/{policyRef}/prior-authorizations",
  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([
    'authorizationNumber' => 'A12345678',
    'description' => 'Mohs surgery, left cheek',
    'authType' => 'authorization',
    'active' => true,
    'startDate' => '<string>',
    'endDate' => '<string>',
    'numVisits' => 50,
    'unlimited' => false,
    'note' => '<string>',
    'appointmentTypeIds' => [
        '<string>'
    ],
    'assignedProviderRef' => '<string>',
    'referringProvider' => [
        'npi' => '1234567893',
        'name' => 'Jane Doe MD'
    ],
    'documentRef' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Organization-Id: <x-organization-id>",
    "x-session-token: <x-session-token>"
  ],
]);

$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.maxcare.ai/v4/ehr/patients/{patientId}/insurances/{policyRef}/prior-authorizations"

	payload := strings.NewReader("{\n  \"authorizationNumber\": \"A12345678\",\n  \"description\": \"Mohs surgery, left cheek\",\n  \"authType\": \"authorization\",\n  \"active\": true,\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\",\n  \"numVisits\": 50,\n  \"unlimited\": false,\n  \"note\": \"<string>\",\n  \"appointmentTypeIds\": [\n    \"<string>\"\n  ],\n  \"assignedProviderRef\": \"<string>\",\n  \"referringProvider\": {\n    \"npi\": \"1234567893\",\n    \"name\": \"Jane Doe MD\"\n  },\n  \"documentRef\": \"<string>\"\n}")

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

	req.Header.Add("x-session-token", "<x-session-token>")
	req.Header.Add("X-Organization-Id", "<x-organization-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	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.maxcare.ai/v4/ehr/patients/{patientId}/insurances/{policyRef}/prior-authorizations")
  .header("x-session-token", "<x-session-token>")
  .header("X-Organization-Id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"authorizationNumber\": \"A12345678\",\n  \"description\": \"Mohs surgery, left cheek\",\n  \"authType\": \"authorization\",\n  \"active\": true,\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\",\n  \"numVisits\": 50,\n  \"unlimited\": false,\n  \"note\": \"<string>\",\n  \"appointmentTypeIds\": [\n    \"<string>\"\n  ],\n  \"assignedProviderRef\": \"<string>\",\n  \"referringProvider\": {\n    \"npi\": \"1234567893\",\n    \"name\": \"Jane Doe MD\"\n  },\n  \"documentRef\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.maxcare.ai/v4/ehr/patients/{patientId}/insurances/{policyRef}/prior-authorizations")

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

request = Net::HTTP::Post.new(url)
request["x-session-token"] = '<x-session-token>'
request["X-Organization-Id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"authorizationNumber\": \"A12345678\",\n  \"description\": \"Mohs surgery, left cheek\",\n  \"authType\": \"authorization\",\n  \"active\": true,\n  \"startDate\": \"<string>\",\n  \"endDate\": \"<string>\",\n  \"numVisits\": 50,\n  \"unlimited\": false,\n  \"note\": \"<string>\",\n  \"appointmentTypeIds\": [\n    \"<string>\"\n  ],\n  \"assignedProviderRef\": \"<string>\",\n  \"referringProvider\": {\n    \"npi\": \"1234567893\",\n    \"name\": \"Jane Doe MD\"\n  },\n  \"documentRef\": \"<string>\"\n}"

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

{
  "code": "success",
  "data": {
    "ref": "<string>",
    "ehr": "modmed",
    "authorizationNumber": "A12345678",
    "ignoredFields": [
      "referringProvider"
    ],
    "documentLinked": true
  }
}

{
  "code": "bad_request",
  "message": "'id' must be a valid UUID",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "unauthorized",
  "message": "Invalid or missing API key",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "forbidden",
  "message": "Insufficient scope",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "not_found",
  "message": "Resource not found",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "conflict",
  "message": "Cannot edit a signed note",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "controlled_substance_unsupported",
  "message": "Controlled substances cannot be prescribed through the API",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {}
}

{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Maximum 1000 requests per 60 seconds.",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "capability_unsupported",
  "message": "This organization's EHR has no appointment finder.",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "server_unresponsive",
  "message": "EHR integration is not available for this note",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

Authorizations

Authorization

string

header

required

Marketplace API key

Headers

x-session-token

string

required

idempotency-key

string

Client-generated key protecting retries for 24 hours

X-Organization-Id

string

required

Target clinic organization ID

Path Parameters

patientId

string

required

policyRef

string

required

The policy's ref or pol_ id

Body

application/json

authorizationNumber

string

required

The payer's authorization number

Example:

"A12345678"

description

string

required

Maximum string length: 500

Example:

"Mohs surgery, left cheek"

authType

enum<string>

default:authorization

Available options:

authorization,

referral

active

boolean

default:true

startDate

string | null

YYYY-MM-DD

endDate

string | null

YYYY-MM-DD, on or after startDate

numVisits

integer | null

Send this or unlimited: true, not both.

Required range: 1 <= x <= 99

unlimited

boolean

default:false

No visit cap. Send this or numVisits, not both.

note

string | null

Maximum string length: 500

appointmentTypeIds

string[]

ModMed appointment type ids the auth covers.

assignedProviderRef

string | null

A provider id (prv_…) as returned on appointments and encounters.

referringProvider

object | null

ModMed: matched by individual NPI (not a group NPI) to the practice's active referral contacts; name is not stored; a miss is reported in ignoredFields.

Show child attributes

documentRef

string | null

A chart document to attach: the ref from POST /v4/patients/{id}/documents or GET /v4/ehr/patients/{id}/documents.

Response

Created

code

string

required

Response code

Example:

"success"

data

object

required

Show child attributes