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
        • GETGet all encounters
        • GETGet encounter
        • POSTCreate institutional or professional encounter
        • POSTCreate professional encounter
        • POSTCreate institutional or professional encounter from pre-encounter patient and appointment
        • POSTCreate professional encounter from pre-encounter patient and appointment
        • PATCHUpdate institutional or professional encounter
        • PATCHUpdate professional encounter
Contact Sales
LogoLogo
API ReferenceEncountersV4

Get all encounters

GET
/api/encounters/v4
GET
/api/encounters/v4
$curl -G https://api.joincandidhealth.com/api/encounters/v4 \
> -H "Authorization: Bearer <token>" \
> -d limit=100 \
> -d claim_status=biller_received \
> --data-urlencode sort=created_at:asc \
> -d page_token=eyJ0b2tlbiI6IjEiLCJwYWdlX3Rva2VuIjoiMiJ9 \
> -d date_of_service_min=2019-08-24 \
> -d date_of_service_max=2019-08-25 \
> --data-urlencode primary_payer_names=Medicare,Medicaid \
> -d search_term=doe \
> -d external_id=123456 \
> --data-urlencode diagnoses_updated_since=2019-08-24T14:15:22Z
1{
2 "items": [
3 {
4 "benefits_assigned_to_provider": true,
5 "billable_status": "BILLABLE",
6 "billing_provider": {
7 "address": {
8 "address1": "123 Main St",
9 "city": "New York",
10 "state": "NY",
11 "zip_code": "10001",
12 "zip_plus_four_code": "1234",
13 "address2": "Apt 1"
14 },
15 "npi": "1234567890",
16 "provider_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
17 "first_name": "John",
18 "last_name": "Doe",
19 "organization_name": "Organization Name",
20 "tax_id": "123456789",
21 "taxonomy_code": "207Q00000X"
22 },
23 "claims": [
24 {
25 "claim_id": "DD9D7F82-37B5-449D-AA63-26925398335B",
26 "status": "biller_received",
27 "service_lines": [
28 {
29 "created_at": "2023-01-01T00:00:00Z",
30 "service_line_id": "CED00F23-6E68-4678-9DBC-F5AA2969A565",
31 "procedure_code": "99213",
32 "quantity": "1",
33 "units": "MJ",
34 "claim_id": "026A1FB8-748E-4859-A2D7-3EA9E07D25AE",
35 "date_of_service_range": {
36 "start_date": "2023-01-01",
37 "end_date": "2023-01-03"
38 },
39 "date_of_service": "2023-01-01",
40 "modifiers": [
41 "22"
42 ],
43 "charge_amount_cents": 10000,
44 "allowed_amount_cents": 8000,
45 "insurance_balance_cents": 0,
46 "patient_balance_cents": 2000,
47 "paid_amount_cents": 8000,
48 "patient_responsibility_cents": 2000,
49 "diagnosis_id_zero": "4AC84BCD-12F5-4F86-A57B-E06749127C98",
50 "diagnosis_id_one": "EEA5CA5A-8B43-45FD-8CBD-C6CC1103E759",
51 "diagnosis_id_two": "5C4AA029-2DB9-4202-916E-E93C708F65FF",
52 "diagnosis_id_three": "81795126-A3AC-443C-B47E-7259A16AB4A2",
53 "service_line_era_data": {
54 "remittance_advice_remark_codes": [
55 "N362"
56 ],
57 "service_line_adjustments": [
58 {
59 "created_at": "2023-01-01T00:00:00Z",
60 "adjustment_group_code": "CO",
61 "adjustment_reason_code": "CO",
62 "adjustment_amount_cents": 1000,
63 "adjustment_note": "test_note"
64 }
65 ]
66 },
67 "service_line_manual_adjustments": [
68 {
69 "created_at": "2023-01-01T00:00:00Z",
70 "adjustment_group_code": "CO",
71 "adjustment_reason_code": "CO",
72 "adjustment_amount_cents": 1000,
73 "adjustment_note": "test_note"
74 }
75 ],
76 "related_invoices": [
77 {
78 "id": "901BE2F1-41BC-456E-9987-4FE2F84F9D75",
79 "created_at": "2023-01-01T00:00:00Z",
80 "updated_at": "2023-01-01T00:00:00Z",
81 "organzation_id": "F13F73D4-4344-46EA-9D93-33BCFFBB9F36",
82 "source_id": "9B626577-8808-4F28-9ED1-F0DFF0D49BBC",
83 "source_customer_id": "624D1972-8C69-4C2F-AEFA-10856F734DB3",
84 "patient_external_id": "10FED4D6-4C5A-48DF-838A-EEF45A74788D",
85 "due_date": "2023-10-10",
86 "status": "draft",
87 "items": [
88 {
89 "service_line_id": "CED00F23-6E68-4678-9DBC-F5AA2969A565",
90 "amount_cents": 500
91 }
92 ],
93 "note": "test_note",
94 "url": "https://example.com",
95 "customer_invoice_url": "https://example.com"
96 }
97 ],
98 "denial_reason": {
99 "reason": "Authorization Required"
100 },
101 "place_of_service_code": "01",
102 "end_date_of_service": "2023-01-03",
103 "test_results": [
104 {
105 "value": 51,
106 "result_type": "HEMOGLOBIN"
107 },
108 {
109 "value": 110,
110 "result_type": "LDL"
111 }
112 ]
113 }
114 ],
115 "eras": [
116 {
117 "check_date": "2023-10-12",
118 "check_number": "CHK12345",
119 "era_id": "4D844EF1-2253-43CD-A4F1-6DB7E65CB54B"
120 }
121 ],
122 "clearinghouse": "Change Healthcare",
123 "clearinghouse_claim_id": "5BA7C3AB-2BC2-496C-8B10-6CAC73D0729D",
124 "payer_claim_id": "9BB9F259-9756-4F16-8F53-9DBB9F7EB1BB"
125 }
126 ],
127 "clinical_notes": [
128 {
129 "category": "clinical",
130 "notes": [
131 "Patient complained of mild chest pain."
132 ],
133 "notes_structured": [
134 {
135 "text": "Mild chest pain since morning.",
136 "author_name": "John Doe",
137 "timestamp": "2023-01-01T00:00:00Z",
138 "author_npi": "1234567890"
139 }
140 ]
141 }
142 ],
143 "created_at": "2023-01-01T00:00:00Z",
144 "diagnoses": [
145 {
146 "code": "I10",
147 "code_type": "ABF",
148 "created_at": "2023-01-01T00:00:00Z",
149 "diagnosis_id": "5C770E00-4BBF-42AF-A73F-99C5E91FC0DB",
150 "encounter_id": "3F63985B-51A4-4DD4-9418-7D50B2520792",
151 "updated_at": "2023-01-01T00:00:00Z",
152 "name": "John Doe"
153 }
154 ],
155 "encounter_id": "B2506E84-4470-4CBA-8A68-6883367739E1",
156 "external_id": "5C21490F-A9C0-45F4-B5DB-136E3AEC617A",
157 "owner_of_next_action": "CANDID",
158 "patient": {
159 "address": {
160 "address1": "123 Main St",
161 "city": "New York",
162 "state": "NY",
163 "zip_code": "10001",
164 "address2": "Apt 1",
165 "zip_plus_four_code": "1234"
166 },
167 "auto_charge_consent": true,
168 "date_of_birth": "2000-01-01",
169 "email_consent": true,
170 "external_id": "49460F77-6456-41F1-AC6D-0AED08614D39",
171 "first_name": "John",
172 "gender": "male",
173 "individual_id": "93DDBEBF-4956-4482-9A6C-21499B7E4E5D",
174 "last_name": "Doe",
175 "non_insurance_payers_info": [
176 {
177 "non_insurance_payer": {
178 "non_insurance_payer_id": "EB7623AB-D5BC-4B25-B257-2B8FCEC578DE",
179 "name": "Sunrise Foundation",
180 "enabled": true,
181 "clinical_trials": [],
182 "description": "Sunrise Foundation is a non-profit organization that provides financial assistance to patients in need.",
183 "category": "Foundation",
184 "address": {
185 "address1": "123 Main St",
186 "city": "San Francisco",
187 "state": "CA",
188 "zip_code": "94105"
189 }
190 },
191 "clinical_trial_info": [],
192 "member_id": "123456789"
193 }
194 ],
195 "phone_consent": true,
196 "phone_numbers": [
197 {
198 "number": "1234567890",
199 "type": "Home"
200 }
201 ],
202 "non_insurance_payers": [
203 {
204 "non_insurance_payer_id": "EB7623AB-D5BC-4B25-B257-2B8FCEC578DE",
205 "name": "Sunrise Foundation",
206 "enabled": true,
207 "clinical_trials": [],
208 "description": "Sunrise Foundation is a non-profit organization that provides financial assistance to patients in need.",
209 "category": "Foundation",
210 "address": {
211 "address1": "123 Main St",
212 "city": "San Francisco",
213 "state": "CA",
214 "zip_code": "94105"
215 }
216 }
217 ],
218 "email": "johndoe@joincandidhealth.com"
219 },
220 "patient_authorized_release": true,
221 "patient_histories": [
222 {
223 "category": "present_illness",
224 "questions": [
225 {
226 "id": "6E7FBCE4-A8EA-46D0-A8D8-FF83CA3BB176",
227 "text": "Do you have any allergies?",
228 "responses": [
229 {
230 "response": "No allergies",
231 "follow_ups": [
232 {
233 "id": "4F3D57F9-AC94-49D6-87E4-E804B709917A",
234 "text": "Do you have any allergies?",
235 "response": "No allergies"
236 }
237 ]
238 }
239 ]
240 }
241 ]
242 }
243 ],
244 "patient_payments": [
245 {
246 "patient_payment_id": "CF237BE1-E793-4BBF-8958-61D5179D1D0D",
247 "organization_id": "0788CA2A-B20D-4B8E-B8D4-07FA0B3B4907",
248 "source_internal_id": "D1A76039-D5C5-4323-A2FC-B7C8B6AEF6A4",
249 "source": "MANUAL_ENTRY",
250 "amount_cents": 2000,
251 "payment_timestamp": "2023-01-01T00:00:00Z",
252 "status": "PENDING",
253 "payment_name": "John Doe",
254 "payment_note": "test payment note",
255 "patient_external_id": "B7437260-D6B4-48CF-B9D7-753C09F34E76",
256 "encounter_external_id": "0F26B9C3-199F-4CBB-A166-B87EA7C631BB",
257 "service_line_id": "B557DC86-C629-478C-850A-02D45AC11783"
258 }
259 ],
260 "provider_accepts_assignment": true,
261 "rendering_provider": {
262 "address": {
263 "address1": "123 Main St",
264 "city": "New York",
265 "state": "NY",
266 "zip_code": "10001",
267 "zip_plus_four_code": "1234",
268 "address2": "Apt 1"
269 },
270 "npi": "1234567890",
271 "provider_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
272 "first_name": "John",
273 "last_name": "Doe",
274 "organization_name": "Organization Name",
275 "tax_id": "123456789",
276 "taxonomy_code": "207Q00000X"
277 },
278 "responsible_party": "INSURANCE_PAY",
279 "service_facility": {
280 "service_facility_id": "2861487B-232C-4DED-A874-616A5DB0688F",
281 "organization_name": "Test Organization",
282 "address": {
283 "address1": "123 Main St",
284 "city": "New York",
285 "state": "NY",
286 "zip_code": "10001",
287 "zip_plus_four_code": "1234",
288 "address2": "Apt 1"
289 }
290 },
291 "submission_origin": "CANDID",
292 "tags": [
293 {
294 "color": "black",
295 "creator_id": "00EB5A46-35C6-441B-9751-AF307AEF5888",
296 "description": "to indicate claims where a void claim has been submitted",
297 "tag_id": "void-claim-submitted"
298 }
299 ],
300 "url": "https://example.com",
301 "schema_instances": [
302 {
303 "schema_id": "ec096b13-f80a-471d-aaeb-54b021c9d582",
304 "content": {
305 "provider_category": "internist",
306 "is_urgent_care": true,
307 "bmi": 24.2,
308 "age": 38
309 }
310 }
311 ],
312 "admission_date": "2023-01-01",
313 "appointment_type": "Routine Checkup",
314 "billing_notes": [
315 {
316 "billing_note_id": "99882EEA-936F-4E71-BC4F-520E4D14E3E2",
317 "created_at": "2023-01-01T00:00:00Z",
318 "encounter_id": "8BCFB6A8-2876-4111-9E3F-602B541FCF62",
319 "text": "Patient was billed for an MRI.",
320 "author_auth0_id": "F0DE3BF9-F9A1-4FA7-BF6B-28C0B46BADD8",
321 "author_name": "John Doe"
322 }
323 ],
324 "coding_attribution": "CANDID",
325 "date_of_service": "2023-01-01",
326 "discharge_date": "2023-01-05",
327 "end_date_of_service": "2023-01-05",
328 "existing_medications": [
329 {
330 "name": "Lisinopril",
331 "rx_cui": "860975",
332 "dosage": "10mg",
333 "dosage_form": "Tablet",
334 "frequency": "Once Daily",
335 "as_needed": true
336 }
337 ],
338 "guarantor": {
339 "address": {
340 "address1": "123 Main St",
341 "city": "New York",
342 "state": "NY",
343 "zip_code": "10001",
344 "address2": "Apt 1",
345 "zip_plus_four_code": "1234"
346 },
347 "auto_charge_consent": true,
348 "email_consent": true,
349 "external_id": "49460F77-6456-41F1-AC6D-0AED08614D39",
350 "first_name": "John",
351 "guarantor_id": "8BBDBE63-58D3-4D40-98C9-40403C050977",
352 "last_name": "Doe",
353 "phone_consent": true,
354 "phone_numbers": [
355 {
356 "number": "1234567890",
357 "type": "Home"
358 }
359 ],
360 "date_of_birth": "2000-01-01",
361 "email": "johndoe@joincandidhealth.com"
362 },
363 "interventions": [
364 {
365 "name": "Physical Therapy Session",
366 "category": "lifestyle",
367 "description": "A session focused on improving muscular strength, flexibility, and range of motion post-injury.",
368 "medication": {
369 "name": "Lisinopril",
370 "rx_cui": "860975",
371 "dosage": "10mg",
372 "dosage_form": "Tablet",
373 "frequency": "Once Daily",
374 "as_needed": true
375 },
376 "labs": [
377 {
378 "name": "Genetic Health Labs",
379 "code": "GH12345",
380 "code_type": "quest"
381 }
382 ]
383 }
384 ],
385 "next_responsible_party": "primary",
386 "onset_of_current_illness_or_symptom_date": "2023-01-01",
387 "organization_id": "6df0c51d-2b4c-4af8-acc1-5c0b589e9b26",
388 "pay_to_address": {
389 "address1": "123 Main St",
390 "city": "New York",
391 "state": "NY",
392 "zip_code": "10001",
393 "zip_plus_four_code": "1234",
394 "address2": "Apt 1"
395 },
396 "place_of_service_code": "01",
397 "place_of_service_code_as_submitted": "01",
398 "prior_authorization_number": "PA1234567",
399 "referring_provider": {
400 "address": {
401 "address1": "123 Main St",
402 "city": "New York",
403 "state": "NY",
404 "zip_code": "10001",
405 "zip_plus_four_code": "1234",
406 "address2": "Apt 1"
407 },
408 "npi": "1234567890",
409 "provider_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
410 "first_name": "John",
411 "last_name": "Doe",
412 "organization_name": "Organization Name",
413 "tax_id": "123456789",
414 "taxonomy_code": "207Q00000X"
415 },
416 "service_authorization_exception_code": "1",
417 "subscriber_primary": {
418 "first_name": "John",
419 "gender": "male",
420 "individual_id": "797348A9-E7E8-4E59-8628-95390D079C0B",
421 "insurance_card": {
422 "insurance_card_id": "CA5B7711-4419-4161-9B7C-3494AC40C8D4",
423 "member_id": "E85313B4-0FFC-4119-8042-8161A4ECFF0A",
424 "payer_id": "836DDAA6-863F-4020-ACCA-205A689F0002",
425 "payer_name": "John Doe",
426 "group_number": "ABC12345",
427 "image_url_back": "https://s3.amazonaws.com/back.jpg",
428 "image_url_front": "https://s3.amazonaws.com/front.jpg",
429 "insurance_type": "12",
430 "plan_name": "Silver PPO Plan",
431 "plan_type": "09",
432 "rx_bin": "610014",
433 "rx_pcn": "MEDDPRIME"
434 },
435 "last_name": "Doe",
436 "patient_relationship_to_subscriber_code": "01",
437 "address": {
438 "address1": "123 Main St",
439 "city": "New York",
440 "state": "NY",
441 "zip_code": "10001",
442 "address2": "Apt 1",
443 "zip_plus_four_code": "1234"
444 },
445 "date_of_birth": "2000-01-01"
446 },
447 "subscriber_secondary": {
448 "first_name": "John",
449 "gender": "male",
450 "individual_id": "797348A9-E7E8-4E59-8628-95390D079C0B",
451 "insurance_card": {
452 "insurance_card_id": "CA5B7711-4419-4161-9B7C-3494AC40C8D4",
453 "member_id": "E85313B4-0FFC-4119-8042-8161A4ECFF0A",
454 "payer_id": "836DDAA6-863F-4020-ACCA-205A689F0002",
455 "payer_name": "John Doe",
456 "group_number": "ABC12345",
457 "image_url_back": "https://s3.amazonaws.com/back.jpg",
458 "image_url_front": "https://s3.amazonaws.com/front.jpg",
459 "insurance_type": "12",
460 "plan_name": "Silver PPO Plan",
461 "plan_type": "09",
462 "rx_bin": "610014",
463 "rx_pcn": "MEDDPRIME"
464 },
465 "last_name": "Doe",
466 "patient_relationship_to_subscriber_code": "01",
467 "address": {
468 "address1": "123 Main St",
469 "city": "New York",
470 "state": "NY",
471 "zip_code": "10001",
472 "address2": "Apt 1",
473 "zip_plus_four_code": "1234"
474 },
475 "date_of_birth": "2000-01-01"
476 },
477 "synchronicity": "Synchronous",
478 "work_queue_id": "12",
479 "work_queue_membership_activated_at": "2023-01-01T00:00:00Z"
480 }
481 ]
482}
Was this page helpful?
Previous

Get encounter

Next
Built with

Authentication

AuthorizationBearer

OAuth authentication of the form <token>.

Query parameters

limitintegerOptional
Maximum number of entities per page, defaults to 100.
claim_statusenumOptional
Indicates the current status of an insurance claim within the billing process.
sortenumOptional

Defaults to created_at:desc.

Allowed values:
page_tokenstringOptional
date_of_service_mindateOptional

Date formatted as YYYY-MM-DD; eg: 2019-08-25.

date_of_service_maxdateOptional

Date formatted as YYYY-MM-DD; eg: 2019-08-25.

primary_payer_namesstringOptional
Comma delimited string.
search_termstringOptional

Filter by any of the following fields: encounter_id, claim_id, patient external_id, patient date of birth, patient first name, patient last name, or encounter external id.

external_idstringOptional

Filter to an exact match on encounter external_id, if one exists.

diagnoses_updated_sincedatetimeOptional

ISO 8601 timestamp; ideally in UTC (although not required): 2019-08-24T14:15:22Z.

tag_idsstringOptional
Filter by name of tags on encounters.
work_queue_idstringOptional
billable_statusenumOptional

Defines if the Encounter is to be billed by Candid to the responsible_party. Examples for when this should be set to NOT_BILLABLE include if the Encounter has not occurred yet or if there is no intention of ever billing the responsible_party.

Allowed values:
responsible_partyenumOptional

Defines the party to be billed with the initial balance owed on the claim. Use SELF_PAY if you intend to bill self pay/cash pay.

Allowed values:
owner_of_next_actionenumOptional
The party who is responsible for taking the next action on an Encounter, as defined by ownership of open Tasks.
Allowed values:
patient_external_idstringOptional
The patient ID from the external EMR platform for the patient
include_merged_patient_databooleanOptional

If true and patient_external_id is set, then also include the encounters of all alternative patients.

Response

This endpoint returns an object.
itemslist of objects
next_page_tokenstring
prev_page_tokenstring

Errors

422
HTTP Request Validations Error
422
Unprocessable Entity Error
500
Internal Error