For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Contact Sales
DocsAPI reference
DocsAPI reference
  • API Reference
        • Mocking Eligibility Checks
          • POSTPost
          • POSTBatch
          • GETPoll Batch
          • GETPayer Search
          • GETRecommendation
          • POSTCreate Recommendation
          • PUTVote Recommendation
          • GETGet Multi
Contact Sales
LogoLogo
API ReferencePre EncounterEligibility ChecksV1

Post

GA
POST
/eligibility-checks/v1
POST
/eligibility-checks/v1
$curl -X POST https://pre-api.joincandidhealth.com/eligibility-checks/v1 \
> -H "Authorization: Bearer <token>" \
> -H "Content-Type: application/json" \
> -d '{
> "payer_id": "payer_id",
> "provider": {
> "npi": "npi"
> },
> "subscriber": {
> "first_name": "first_name",
> "last_name": "last_name"
> }
>}'
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 "get_existing_check_initiated_after": "2024-01-15T09:30:00Z",
58 "source": "source",
59 "portal_password": "portal_password",
60 "portal_username": "portal_username"
61 },
62 "parsed_response": {
63 "eligibility_status": "ACTIVE",
64 "plan_metadata": {
65 "payer_name": "payer_name",
66 "insurance_type": "insurance_type",
67 "insurance_type_code": "insurance_type_code",
68 "plan_name": "plan_name",
69 "member_id": "member_id",
70 "group_number": "group_number",
71 "start_date": "2023-01-15",
72 "end_date": "2023-01-15",
73 "plan_dates": [
74 {
75 "start_date": "2023-01-15",
76 "field_name": "field_name",
77 "end_date": "2023-01-15"
78 },
79 {
80 "start_date": "2023-01-15",
81 "field_name": "field_name",
82 "end_date": "2023-01-15"
83 }
84 ],
85 "subscriber": {
86 "member_id": "member_id",
87 "group_number": "group_number",
88 "first_name": "first_name",
89 "middle_name": "middle_name",
90 "last_name": "last_name",
91 "date_of_birth": "date_of_birth",
92 "gender": "gender",
93 "address": {
94 "address1": "address1",
95 "address2": "address2",
96 "city": "city",
97 "state": "state",
98 "postal_code": "postal_code",
99 "country_code": "country_code",
100 "country_sub_division_code": "country_sub_division_code"
101 }
102 },
103 "dependent": {
104 "member_id": "member_id",
105 "group_number": "group_number",
106 "first_name": "first_name",
107 "middle_name": "middle_name",
108 "last_name": "last_name",
109 "date_of_birth": "date_of_birth",
110 "gender": "gender",
111 "address": {
112 "address1": "address1",
113 "address2": "address2",
114 "city": "city",
115 "state": "state",
116 "postal_code": "postal_code",
117 "country_code": "country_code",
118 "country_sub_division_code": "country_sub_division_code"
119 }
120 }
121 },
122 "benefits": {
123 "plan_coverage": {
124 "in_network": {
125 "deductible": {},
126 "deductible_contract": {},
127 "deductible_remaining": {},
128 "deductible_year_to_date": {},
129 "oop_max": {},
130 "oop_max_contract": {},
131 "oop_max_remaining": {},
132 "oop_max_year_to_date": {},
133 "additional_notes": "additional_notes"
134 },
135 "in_network_flat": [
136 {
137 "type": "DEDUCTIBLE",
138 "coverageLevel": "EMPLOYEE_AND_CHILDREN",
139 "unit": "PERCENT",
140 "value": 1.1
141 },
142 {
143 "type": "DEDUCTIBLE",
144 "coverageLevel": "EMPLOYEE_AND_CHILDREN",
145 "unit": "PERCENT",
146 "value": 1.1
147 }
148 ],
149 "out_of_network": {
150 "deductible": {},
151 "deductible_contract": {},
152 "deductible_remaining": {},
153 "deductible_year_to_date": {},
154 "oop_max": {},
155 "oop_max_contract": {},
156 "oop_max_remaining": {},
157 "oop_max_year_to_date": {},
158 "additional_notes": "additional_notes"
159 },
160 "out_of_network_flat": [
161 {
162 "type": "DEDUCTIBLE",
163 "coverageLevel": "EMPLOYEE_AND_CHILDREN",
164 "unit": "PERCENT",
165 "value": 1.1
166 },
167 {
168 "type": "DEDUCTIBLE",
169 "coverageLevel": "EMPLOYEE_AND_CHILDREN",
170 "unit": "PERCENT",
171 "value": 1.1
172 }
173 ]
174 },
175 "service_specific_coverage": [
176 {
177 "service_code": "1",
178 "in_network": {},
179 "in_network_flat": [],
180 "out_of_network": {},
181 "out_of_network_flat": []
182 },
183 {
184 "service_code": "1",
185 "in_network": {},
186 "in_network_flat": [],
187 "out_of_network": {},
188 "out_of_network_flat": []
189 }
190 ],
191 "benefits_related_entities": [
192 {
193 "entityIdentifier": "entityIdentifier",
194 "entityType": "entityType",
195 "entityName": "entityName",
196 "contactInformation": [
197 {},
198 {}
199 ],
200 "serviceTypeCodes": [
201 "1",
202 "1"
203 ]
204 },
205 {
206 "entityIdentifier": "entityIdentifier",
207 "entityType": "entityType",
208 "entityName": "entityName",
209 "contactInformation": [
210 {},
211 {}
212 ],
213 "serviceTypeCodes": [
214 "1",
215 "1"
216 ]
217 }
218 ],
219 "non_covered_details": [
220 {
221 "type": "DEDUCTIBLE",
222 "coverageLevel": "EMPLOYEE_AND_CHILDREN",
223 "unit": "PERCENT",
224 "value": 1.1,
225 "additional_notes": "additional_notes",
226 "service_type_codes": [
227 "1",
228 "1"
229 ]
230 },
231 {
232 "type": "DEDUCTIBLE",
233 "coverageLevel": "EMPLOYEE_AND_CHILDREN",
234 "unit": "PERCENT",
235 "value": 1.1,
236 "additional_notes": "additional_notes",
237 "service_type_codes": [
238 "1",
239 "1"
240 ]
241 }
242 ],
243 "notes": "notes",
244 "autoUpdatedEligibilityCheckId": "autoUpdatedEligibilityCheckId"
245 }
246 },
247 "request_corrections": [
248 {
249 "property": "property",
250 "request_value": "request_value",
251 "corrected_value": "corrected_value"
252 },
253 {
254 "property": "property",
255 "request_value": "request_value",
256 "corrected_value": "corrected_value"
257 }
258 ]
259}

Sends real-time eligibility checks to payers through Stedi.

Was this page helpful?
Previous

Batch

Next
Built with

Authentication

AuthorizationBearer

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
get_existing_check_initiated_afterdatetimeOptional

If not provided, this endpoint will run a fresh eligibility check. If provided, it will return an existing successful eligibility check if one exists that was initiated after provided date with the same parameters (Date of Service, Payer ID, Provider, Subscriber, Dependent, and Encounter).

sourcestringOptional
portal_passwordstringOptional
The password that the provider uses to log in to the payer's portal. This is not commonly used.
portal_usernamestringOptional
The username that the provider uses to log in to the payer's portal. This is not commonly used.

Response

This endpoint returns an object.
responseany
batch_idstring
errorslist of objects
requestobject
An object representing the data for an eligibility request.
parsed_responseobject
request_correctionslist of objects