Skip to main content
POST
/
v1
/
payors
Create Payor
curl --request POST \
  --url https://api.example.com/v1/payors \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "patient_id": "<string>",
  "insurance_id": "<string>",
  "relationship_to_subscriber": "spouse",
  "insured_member_id": "<string>",
  "group_number": "<string>",
  "group_description": "<string>",
  "payor_responsibility": "primary",
  "coverage_from": "2023-11-07T05:31:56Z",
  "coverage_to": "2023-11-07T05:31:56Z",
  "provider_network_status": "unknown",
  "plan_funding_type": "fully_funded",
  "plan_name": "<string>",
  "plan_type": "01",
  "plan_renewal_date_type": "calendar_year",
  "cob_on_file": "not_required",
  "cob_notes": "<string>",
  "cob_last_verified_at": "2023-11-07T05:31:56Z",
  "has_other_active_coverage": true,
  "out_of_state_benefits": true,
  "out_of_state_benefits_comments": "<string>",
  "in_grace_period": true,
  "last_payment_date": "2023-12-25",
  "is_cobra_coverage": true,
  "deductible_apply_to_oop": true,
  "eligibility_check_status": "pending",
  "eligibility_check_comment": "<string>",
  "eligibility_check_date": "2023-11-07T05:31:56Z",
  "eligibility_version": 0,
  "individual_deductible_policy_in_network": 123,
  "individual_deductible_policy_out_network": 123,
  "individual_deductible_remaining_in_network": 123,
  "individual_deductible_remaining_out_network": 123,
  "family_deductible_policy_in_network": 123,
  "family_deductible_policy_out_network": 123,
  "family_deductible_remaining_in_network": 123,
  "family_deductible_remaining_out_network": 123,
  "individual_oop_max_policy_in_network": 123,
  "individual_oop_max_policy_out_network": 123,
  "individual_oop_max_remaining_in_network": 123,
  "individual_oop_max_remaining_out_network": 123,
  "family_oop_max_policy_in_network": 123,
  "family_oop_max_policy_out_network": 123,
  "family_oop_max_remaining_in_network": 123,
  "family_oop_max_remaining_out_network": 123,
  "benefits_related_entities": [
    {}
  ],
  "subscriber": {
    "first_name": "<string>",
    "last_name": "<string>",
    "middle_name": "<string>",
    "dob": "2023-11-07T05:31:56Z",
    "gender": "male",
    "insured_member_id": "<string>",
    "address": "<string>",
    "address2": "<string>",
    "city": "<string>",
    "state": "alabama",
    "zip": "<string>"
  },
  "subscriber_id": "<string>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "<string>",
  "updated_at": "<string>",
  "patient_id": "<string>",
  "insurance_id": "<string>",
  "subscriber_id": "<string>",
  "relationship_to_subscriber": "spouse",
  "insured_member_id": "<string>",
  "group_number": "<string>",
  "group_description": "<string>",
  "payor_responsibility": "primary",
  "coverage_from": "<string>",
  "coverage_to": "<string>",
  "provider_network_status": "unknown",
  "plan_funding_type": "fully_funded",
  "plan_name": "<string>",
  "plan_type": "01",
  "plan_renewal_date_type": "calendar_year",
  "cob_on_file": "not_required",
  "cob_notes": "<string>",
  "cob_last_verified_at": "<string>",
  "has_other_active_coverage": true,
  "out_of_state_benefits": true,
  "out_of_state_benefits_comments": "<string>",
  "in_grace_period": true,
  "last_payment_date": "<string>",
  "is_cobra_coverage": true,
  "deductible_apply_to_oop": true,
  "eligibility_check_status": "pending",
  "eligibility_check_comment": "<string>",
  "eligibility_check_date": "<string>",
  "eligibility_version": 0,
  "individual_deductible_policy_in_network": 123,
  "individual_deductible_policy_out_network": 123,
  "individual_deductible_remaining_in_network": 123,
  "individual_deductible_remaining_out_network": 123,
  "family_deductible_policy_in_network": 123,
  "family_deductible_policy_out_network": 123,
  "family_deductible_remaining_in_network": 123,
  "family_deductible_remaining_out_network": 123,
  "individual_oop_max_policy_in_network": 123,
  "individual_oop_max_policy_out_network": 123,
  "individual_oop_max_remaining_in_network": 123,
  "individual_oop_max_remaining_out_network": 123,
  "family_oop_max_policy_in_network": 123,
  "family_oop_max_policy_out_network": 123,
  "family_oop_max_remaining_in_network": 123,
  "family_oop_max_remaining_out_network": 123,
  "benefits_related_entities": [
    {}
  ],
  "insurance": {},
  "subscriber": {},
  "services": [
    {
      "copay_in_network": 25,
      "created_at": "2024-01-15T10:30:00Z",
      "eligibility_check_status": "ELIGIBLE",
      "id": "550e8400-e29b-41d4-a716-446655440014",
      "payor_id": "550e8400-e29b-41d4-a716-446655440012",
      "service_type": "PT",
      "updated_at": "2024-01-15T10:30:00Z",
      "verification_benefits_status": "VERIFIED"
    }
  ],
  "version": 1
}

Authorizations

X-API-Key
string
header
required

Body

application/json

Request model for creating a payor (patient-insurance relationship)

patient_id
string
required

Patient ID

insurance_id
string
required

Insurance ID

relationship_to_subscriber
enum<string> | null

Relationship to subscriber

Available options:
spouse,
self,
child,
employee,
unknown,
organ_donor,
cadaver_donor,
life_partner,
other_relationship
insured_member_id
string | null

Member ID

group_number
string | null

Group number for the insurance plan

group_description
string | null

Group description for the insurance plan

payor_responsibility
enum<string>
default:primary

Primary, Secondary, Tertiary, or Quaternary

Available options:
primary,
secondary,
tertiary,
quaternary
coverage_from
string<date-time> | null

Coverage start date

coverage_to
string<date-time> | null

Coverage end date

provider_network_status
enum<string> | null

Provider network status

Available options:
unknown,
in_network,
out_of_network
plan_funding_type
enum<string> | null

Plan funding type

Available options:
fully_funded,
self_funded,
unknown
plan_name
string | null

Plan name

plan_type
enum<string> | null

Plan type (HMO, PPO, etc.)

Available options:
01,
02,
03,
12,
13,
14,
15,
16,
17,
18,
19,
41,
42,
43,
47,
48,
49,
AP,
C1,
CO,
CP,
D,
DB,
EP,
FF,
GP,
HB,
HD,
HG,
HM,
HN,
HP,
HS,
IN,
IP,
LC,
LD,
LI,
LT,
M,
MA,
MB,
MC,
MD,
ME,
MH,
MI,
MJ,
MK,
ML,
MM,
MN,
MO,
MP,
MR,
MT,
OA,
OT,
PE,
PL,
PP,
PR,
PS,
QM,
RP,
SA,
SP,
TF,
WC,
WU
plan_renewal_date_type
enum<string> | null

Plan renewal date type

Available options:
calendar_year,
service_year,
contract
cob_on_file
enum<string> | null

Coordination of Benefits status

Available options:
not_required,
pending,
complete
cob_notes
string | null

Notes about COB

cob_last_verified_at
string<date-time> | null

Last COB verification date

has_other_active_coverage
boolean | null

Whether patient has other active coverage

out_of_state_benefits
boolean | null

Whether plan covers out-of-state services

out_of_state_benefits_comments
string | null

Notes about out-of-state coverage

in_grace_period
boolean | null

Whether coverage is in grace period

last_payment_date
string<date> | null

Last premium payment date

is_cobra_coverage
boolean | null

Whether this is COBRA coverage

deductible_apply_to_oop
boolean | null

Whether deductible applies to out-of-pocket maximum

eligibility_check_status
enum<string>
default:pending

Eligibility check status

Available options:
active,
inactive,
pending,
failed
eligibility_check_comment
string | null

Eligibility check comment

eligibility_check_date
string<date-time> | null

Eligibility check date

eligibility_version
integer
default:0

Eligibility version number

individual_deductible_policy_in_network
number | null

Individual deductible policy in network

individual_deductible_policy_out_network
number | null

Individual deductible policy out of network

individual_deductible_remaining_in_network
number | null

Individual deductible remaining in network

individual_deductible_remaining_out_network
number | null

Individual deductible remaining out of network

family_deductible_policy_in_network
number | null

Family deductible policy in network

family_deductible_policy_out_network
number | null

Family deductible policy out of network

family_deductible_remaining_in_network
number | null

Family deductible remaining in network

family_deductible_remaining_out_network
number | null

Family deductible remaining out of network

individual_oop_max_policy_in_network
number | null

Individual OOP max policy in network

individual_oop_max_policy_out_network
number | null

Individual OOP max policy out of network

individual_oop_max_remaining_in_network
number | null

Individual OOP max remaining in network

individual_oop_max_remaining_out_network
number | null

Individual OOP max remaining out of network

family_oop_max_policy_in_network
number | null

Family OOP max policy in network

family_oop_max_policy_out_network
number | null

Family OOP max policy out of network

family_oop_max_remaining_in_network
number | null

Family OOP max remaining in network

family_oop_max_remaining_out_network
number | null

Family OOP max remaining out of network

Benefits related entities from eligibility check

subscriber
SubscriberCreateInline · object

Subscriber information (creates new subscriber)

subscriber_id
string | null

Existing subscriber ID (references existing subscriber)

Response

Successful Response

Payor resource.

Represents the relationship between a patient and their insurance coverage. Includes related insurance, subscriber, and service information.

id
string<uuid>
required
created_at
string | null
required
updated_at
string | null
required
patient_id
string
required
insurance_id
string
required
subscriber_id
string | null
relationship_to_subscriber
enum<string> | null

Relationship to subscriber enum matching Prisma @map values

Available options:
spouse,
self,
child,
employee,
unknown,
organ_donor,
cadaver_donor,
life_partner,
other_relationship
insured_member_id
string | null
group_number
string | null
group_description
string | null
payor_responsibility
enum<string> | null

Insurance tier enum matching Prisma

Available options:
primary,
secondary,
tertiary,
quaternary
coverage_from
string | null
coverage_to
string | null
provider_network_status
enum<string> | null

Provider network status enum matching Prisma @map values

Available options:
unknown,
in_network,
out_of_network
plan_funding_type
enum<string> | null

Plan funding type enum matching Prisma @map values

Available options:
fully_funded,
self_funded,
unknown
plan_name
string | null
plan_type
enum<string> | null

Insurance plan type enum matching Prisma - X12 standard codes

Available options:
01,
02,
03,
12,
13,
14,
15,
16,
17,
18,
19,
41,
42,
43,
47,
48,
49,
AP,
C1,
CO,
CP,
D,
DB,
EP,
FF,
GP,
HB,
HD,
HG,
HM,
HN,
HP,
HS,
IN,
IP,
LC,
LD,
LI,
LT,
M,
MA,
MB,
MC,
MD,
ME,
MH,
MI,
MJ,
MK,
ML,
MM,
MN,
MO,
MP,
MR,
MT,
OA,
OT,
PE,
PL,
PP,
PR,
PS,
QM,
RP,
SA,
SP,
TF,
WC,
WU
plan_renewal_date_type
enum<string> | null

Plan renewal date type enum matching Prisma @map values

Available options:
calendar_year,
service_year,
contract
cob_on_file
enum<string> | null

COB status enum matching Prisma @map values

Available options:
not_required,
pending,
complete
cob_notes
string | null
cob_last_verified_at
string | null
has_other_active_coverage
boolean | null
out_of_state_benefits
boolean | null
out_of_state_benefits_comments
string | null
in_grace_period
boolean | null
last_payment_date
string | null
is_cobra_coverage
boolean | null
deductible_apply_to_oop
boolean | null
eligibility_check_status
enum<string>
default:pending

Eligibility check status enum matching Prisma EligibilityStatus

Available options:
active,
inactive,
pending,
failed
eligibility_check_comment
string | null
eligibility_check_date
string | null
eligibility_version
integer
default:0
individual_deductible_policy_in_network
number | null
individual_deductible_policy_out_network
number | null
individual_deductible_remaining_in_network
number | null
individual_deductible_remaining_out_network
number | null
family_deductible_policy_in_network
number | null
family_deductible_policy_out_network
number | null
family_deductible_remaining_in_network
number | null
family_deductible_remaining_out_network
number | null
individual_oop_max_policy_in_network
number | null
individual_oop_max_policy_out_network
number | null
individual_oop_max_remaining_in_network
number | null
individual_oop_max_remaining_out_network
number | null
family_oop_max_policy_in_network
number | null
family_oop_max_policy_out_network
number | null
family_oop_max_remaining_in_network
number | null
family_oop_max_remaining_out_network
number | null
insurance
Insurance · object
subscriber
Subscriber · object
services
PayorService · object[] | null
version
integer
default:1