Post

Beta

POST

/eligibility-checks/v1

POST

/eligibility-checks/v1

1 curl -X POST https://pre-api.joincandidhealth.com/eligibility-checks/v1 \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "payer_id": "payer_id",
6   "provider": {
7     "npi": "npi"
8   },
9   "subscriber": {
10     "first_name": "first_name",
11     "last_name": "last_name"
12   }
13 }'

Try it

200Successful

1 {
2   "response": {
3     "key": "value"
4   },
5   "batch_id": "batch_id",
6   "errors": [
7     {
8       "source": "CANDID",
9       "errorDetails": {
10         "field?": "field?",
11         "description?": "description?",
12         "location?": "location?",
13         "possibleResolutions?": "possibleResolutions?",
14         "code?": "code?",
15         "followupAction?": "followupAction?"
16       }
17     },
18     {
19       "source": "CANDID",
20       "errorDetails": {
21         "field?": "field?",
22         "description?": "description?",
23         "location?": "location?",
24         "possibleResolutions?": "possibleResolutions?",
25         "code?": "code?",
26         "followupAction?": "followupAction?"
27       }
28     }
29   ],
30   "request": {
31     "payer_id": "payer_id",
32     "provider": {
33       "first_name": "first_name",
34       "last_name": "last_name",
35       "npi": "npi"
36     },
37     "subscriber": {
38       "first_name": "first_name",
39       "last_name": "last_name",
40       "member_id": "member_id",
41       "date_of_birth": "2023-01-15"
42     },
43     "submitter_transaction_identifier": "submitter_transaction_identifier",
44     "dependent": {
45       "first_name": "first_name",
46       "last_name": "last_name",
47       "member_id": "member_id",
48       "date_of_birth": "2023-01-15"
49     },
50     "encounter": {
51       "date_of_service": "2023-01-15",
52       "service_type_codes": [
53         "service_type_codes",
54         "service_type_codes"
55       ]
56     }
57   },
58   "parsed_response": {
59     "eligibility_status": "ACTIVE",
60     "plan_metadata": {
61       "payer_name": "payer_name",
62       "insurance_type": "insurance_type",
63       "insurance_type_code": "insurance_type_code",
64       "plan_name": "plan_name",
65       "member_id": "member_id",
66       "group_number": "group_number",
67       "start_date": "2023-01-15",
68       "end_date": "2023-01-15",
69       "plan_dates": [
70         {
71           "start_date": "2023-01-15",
72           "field_name": "field_name",
73           "end_date": "2023-01-15"
74         },
75         {
76           "start_date": "2023-01-15",
77           "field_name": "field_name",
78           "end_date": "2023-01-15"
79         }
80       ],
81       "subscriber": {
82         "member_id": "member_id",
83         "group_number": "group_number",
84         "first_name": "first_name",
85         "middle_name": "middle_name",
86         "last_name": "last_name",
87         "date_of_birth": "date_of_birth",
88         "gender": "gender",
89         "address": {
90           "address1": "address1",
91           "address2": "address2",
92           "city": "city",
93           "state": "state",
94           "postal_code": "postal_code",
95           "country_code": "country_code",
96           "country_sub_division_code": "country_sub_division_code"
97         }
98       },
99       "dependent": {
100         "member_id": "member_id",
101         "group_number": "group_number",
102         "first_name": "first_name",
103         "middle_name": "middle_name",
104         "last_name": "last_name",
105         "date_of_birth": "date_of_birth",
106         "gender": "gender",
107         "address": {
108           "address1": "address1",
109           "address2": "address2",
110           "city": "city",
111           "state": "state",
112           "postal_code": "postal_code",
113           "country_code": "country_code",
114           "country_sub_division_code": "country_sub_division_code"
115         }
116       }
117     },
118     "benefits": {
119       "plan_coverage": {
120         "in_network": {
121           "deductible": {},
122           "deductible_contract": {},
123           "deductible_remaining": {},
124           "deductible_year_to_date": {},
125           "oop_max": {},
126           "oop_max_contract": {},
127           "oop_max_remaining": {},
128           "oop_max_year_to_date": {},
129           "additional_notes": "additional_notes"
130         },
131         "in_network_flat": [
132           {
133             "type": "DEDUCTIBLE",
134             "coverageLevel": "EMPLOYEE_AND_CHILDREN",
135             "unit": "PERCENT",
136             "value": 1.1
137           },
138           {
139             "type": "DEDUCTIBLE",
140             "coverageLevel": "EMPLOYEE_AND_CHILDREN",
141             "unit": "PERCENT",
142             "value": 1.1
143           }
144         ],
145         "out_of_network": {
146           "deductible": {},
147           "deductible_contract": {},
148           "deductible_remaining": {},
149           "deductible_year_to_date": {},
150           "oop_max": {},
151           "oop_max_contract": {},
152           "oop_max_remaining": {},
153           "oop_max_year_to_date": {},
154           "additional_notes": "additional_notes"
155         },
156         "out_of_network_flat": [
157           {
158             "type": "DEDUCTIBLE",
159             "coverageLevel": "EMPLOYEE_AND_CHILDREN",
160             "unit": "PERCENT",
161             "value": 1.1
162           },
163           {
164             "type": "DEDUCTIBLE",
165             "coverageLevel": "EMPLOYEE_AND_CHILDREN",
166             "unit": "PERCENT",
167             "value": 1.1
168           }
169         ]
170       },
171       "service_specific_coverage": [
172         {
173           "service_code": "1",
174           "in_network": {},
175           "in_network_flat": [],
176           "out_of_network": {},
177           "out_of_network_flat": []
178         },
179         {
180           "service_code": "1",
181           "in_network": {},
182           "in_network_flat": [],
183           "out_of_network": {},
184           "out_of_network_flat": []
185         }
186       ],
187       "benefits_related_entities": [
188         {
189           "entityIdentifier": "entityIdentifier",
190           "entityType": "entityType",
191           "entityName": "entityName",
192           "contactInformation": [
193             {},
194             {}
195           ],
196           "serviceTypeCodes": [
197             "1",
198             "1"
199           ]
200         },
201         {
202           "entityIdentifier": "entityIdentifier",
203           "entityType": "entityType",
204           "entityName": "entityName",
205           "contactInformation": [
206             {},
207             {}
208           ],
209           "serviceTypeCodes": [
210             "1",
211             "1"
212           ]
213         }
214       ],
215       "notes": "notes"
216     }
217   },
218   "request_corrections": [
219     {
220       "property": "property",
221       "request_value": "request_value",
222       "corrected_value": "corrected_value"
223     },
224     {
225       "property": "property",
226       "request_value": "request_value",
227       "corrected_value": "corrected_value"
228     }
229   ]
230 }

Sends real-time eligibility checks to payers through Stedi.

Headers

AuthorizationstringRequired

OAuth authentication of the form <token>.

Request

This endpoint expects an object.

payer_idstringRequired

Supported payer ID values can be found here.

providerobjectRequired

subscriberobjectRequired

The primary policyholder for the insurance plan or a dependent with a unique member ID.

If a dependent has a unique member ID, include their information here and leave dependent undefined.

submitter_transaction_identifierstringOptional

A unique identifier for the eligibility check within the batch. Candid returns this identifier in the response for the /batch/{batch_id} polling endpoint so you can correlate benefit responses with the original eligibility check.

dependentobjectOptional

If a dependent has a unique member ID, include their information as subscriber and leave this field undefined.

encounterobjectOptional

Response

This endpoint returns an object.

responseany

batch_idstring or null

errorslist of objects or null

requestobject or null

An object representing the data for an eligibility request.

parsed_responseobject or null

request_correctionslist of objects or null