EncountersV4

Get all encounters

GET
https://api.joincandidhealth.com/api/encounters/v4

Query parameters

limit
optional integer
Maximum number of entities per page, defaults to 100.
claim_status
optional enum
Indicates the current status of an insurance claim within the billing process.
sort
optional enum
Defaults to created_at:desc.
Allowed values: created_at:asccreated_at:descdate_of_service:ascdate_of_service:desc
page_token
optional string
date_of_service_min
optional string
Date formatted as YYYY-MM-DD; eg: 2019-08-25.
date_of_service_max
optional string
Date formatted as YYYY-MM-DD; eg: 2019-08-25.
primary_payer_names
optional string
Comma delimited string.
search_term
optional string
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_id
optional string
Filter to an exact match on encounter external_id, if one exists.
diagnoses_updated_since
optional datetime
ISO 8601 timestamp; ideally in UTC (although not required): 2019-08-24T14:15:22Z.
tag_ids
optional string
Filter by name of tags on encounters.
work_queue_id
optional string
billable_status
optional enum
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: BILLABLENOT_BILLABLE
responsible_party
optional enum
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: INSURANCE_PAYSELF_PAYUNKNOWN
owner_of_next_action
optional enum
The party who is responsible for taking the next action on an Encounter, as defined by ownership of open Tasks.
Allowed values: CANDIDCUSTOMERCODERNONE

Response

This endpoint return an object.
items
list of objects
next_page_token
optional string
prev_page_token
optional string
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 \
-d sort=created_at:asc \
-d page_token=eyJ0b2tlbiI6IjEiLCJwYWdlX3Rva2VuIjoiMiJ9 \
-d date_of_service_min=2019-08-24 \
-d date_of_service_max=2019-08-25 \
-d primary_payer_names=Medicare,Medicaid \
-d search_term=doe \
-d external_id=123456 \
-d diagnoses_updated_since=2019-08-24T14:15:22Z
Response
{
"items": [
{
"benefits_assigned_to_provider": true,
"billable_status": "BILLABLE",
"billing_provider": {
"address": {
"address1": "123 Main St",
"city": "New York",
"state": "NY",
"zip_code": "10001",
"zip_plus_four_code": "1234",
"address2": "Apt 1"
},
"npi": "1234567890",
"provider_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
"first_name": "John",
"last_name": "Doe",
"organization_name": "Organization Name",
"tax_id": "123456789",
"taxonomy_code": "207Q00000X"
},
"claims": [
{
"claim_id": "DD9D7F82-37B5-449D-AA63-26925398335B",
"status": "biller_received",
"service_lines": [
{
"service_line_id": "CED00F23-6E68-4678-9DBC-F5AA2969A565",
"procedure_code": "99213",
"quantity": "1",
"units": "MJ",
"claim_id": "026A1FB8-748E-4859-A2D7-3EA9E07D25AE",
"date_of_service_range": {
"start_date": "2023-01-01",
"end_date": "2023-01-03"
},
"modifiers": [
"22"
],
"charge_amount_cents": 10000,
"allowed_amount_cents": 8000,
"insurance_balance_cents": 0,
"patient_balance_cents": 2000,
"paid_amount_cents": 8000,
"patient_responsibility_cents": 2000,
"diagnosis_id_zero": "4AC84BCD-12F5-4F86-A57B-E06749127C98",
"diagnosis_id_one": "EEA5CA5A-8B43-45FD-8CBD-C6CC1103E759",
"diagnosis_id_two": "5C4AA029-2DB9-4202-916E-E93C708F65FF",
"diagnosis_id_three": "81795126-A3AC-443C-B47E-7259A16AB4A2",
"service_line_era_data": {
"service_line_adjustments": [
{
"created_at": "2023-01-01T00:00:00Z",
"adjustment_group_code": "CO",
"adjustment_reason_code": "CO",
"adjustment_amount_cents": 1000,
"adjustment_note": "test_note"
}
],
"remittance_advice_remark_codes": [
"N362"
]
},
"service_line_manual_adjustments": [
{
"created_at": "2023-01-01T00:00:00Z",
"adjustment_group_code": "CO",
"adjustment_reason_code": "CO",
"adjustment_amount_cents": 1000,
"adjustment_note": "test_note"
}
],
"related_invoices": [
{
"id": "901BE2F1-41BC-456E-9987-4FE2F84F9D75",
"created_at": "2023-01-01T00:00:00Z",
"updated_at": "2023-01-01T00:00:00Z",
"organzation_id": "F13F73D4-4344-46EA-9D93-33BCFFBB9F36",
"source_id": "9B626577-8808-4F28-9ED1-F0DFF0D49BBC",
"source_customer_id": "624D1972-8C69-4C2F-AEFA-10856F734DB3",
"patient_external_id": "10FED4D6-4C5A-48DF-838A-EEF45A74788D",
"due_date": "2023-10-10",
"status": "draft",
"items": [
{
"service_line_id": "CED00F23-6E68-4678-9DBC-F5AA2969A565",
"amount_cents": 500
}
],
"note": "test_note",
"url": "https://example.com",
"customer_invoice_url": "https://example.com"
}
],
"denial_reason": {
"reason": "Authorization Required"
},
"place_of_service_code": "01"
}
],
"eras": [
{
"check_date": "2023-10-12",
"check_number": "CHK12345",
"era_id": "4D844EF1-2253-43CD-A4F1-6DB7E65CB54B"
}
],
"clearinghouse": "Change Healthcare",
"clearinghouse_claim_id": "5BA7C3AB-2BC2-496C-8B10-6CAC73D0729D",
"payer_claim_id": "9BB9F259-9756-4F16-8F53-9DBB9F7EB1BB"
}
],
"clinical_notes": [
{
"category": "clinical",
"notes": [
"Patient complained of mild chest pain."
],
"notes_structured": [
{
"text": "Mild chest pain since morning.",
"author_name": "John Doe",
"timestamp": "2023-01-01T00:00:00Z",
"author_npi": "1234567890"
}
]
}
],
"date_of_service": "2023-01-01",
"diagnoses": [
{
"code": "I10",
"code_type": "ABF",
"created_at": "2023-01-01T00:00:00Z",
"diagnosis_id": "5C770E00-4BBF-42AF-A73F-99C5E91FC0DB",
"encounter_id": "3F63985B-51A4-4DD4-9418-7D50B2520792",
"updated_at": "2023-01-01T00:00:00Z",
"name": "John Doe"
}
],
"encounter_id": "B2506E84-4470-4CBA-8A68-6883367739E1",
"external_id": "5C21490F-A9C0-45F4-B5DB-136E3AEC617A",
"owner_of_next_action": "CANDID",
"patient": {
"address": {
"address1": "123 Main St",
"city": "New York",
"state": "NY",
"zip_code": "10001",
"address2": "Apt 1",
"zip_plus_four_code": "1234"
},
"date_of_birth": "2000-01-01",
"email_consent": true,
"external_id": "49460F77-6456-41F1-AC6D-0AED08614D39",
"first_name": "John",
"gender": "male",
"individual_id": "93DDBEBF-4956-4482-9A6C-21499B7E4E5D",
"last_name": "Doe",
"phone_consent": true,
"phone_numbers": [
{
"number": "1234567890",
"type": "Home"
}
],
"email": "johndoe@joincandidhealth.com"
},
"patient_authorized_release": true,
"patient_histories": [
{
"category": "present_illness",
"questions": [
{
"id": "6E7FBCE4-A8EA-46D0-A8D8-FF83CA3BB176",
"text": "Do you have any allergies?",
"responses": [
{
"response": "No allergies",
"follow_ups": [
{
"id": "4F3D57F9-AC94-49D6-87E4-E804B709917A",
"text": "Do you have any allergies?",
"response": "No allergies"
}
]
}
]
}
]
}
],
"patient_payments": [
{
"patient_payment_id": "CF237BE1-E793-4BBF-8958-61D5179D1D0D",
"organization_id": "0788CA2A-B20D-4B8E-B8D4-07FA0B3B4907",
"source_internal_id": "D1A76039-D5C5-4323-A2FC-B7C8B6AEF6A4",
"source": "MANUAL_ENTRY",
"amount_cents": 2000,
"payment_timestamp": "2023-01-01T00:00:00Z",
"status": "PENDING",
"payment_name": "John Doe",
"payment_note": "test payment note",
"patient_external_id": "B7437260-D6B4-48CF-B9D7-753C09F34E76",
"encounter_external_id": "0F26B9C3-199F-4CBB-A166-B87EA7C631BB",
"service_line_id": "B557DC86-C629-478C-850A-02D45AC11783"
}
],
"provider_accepts_assignment": true,
"rendering_provider": {
"address": {
"address1": "123 Main St",
"city": "New York",
"state": "NY",
"zip_code": "10001",
"zip_plus_four_code": "1234",
"address2": "Apt 1"
},
"npi": "1234567890",
"provider_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
"first_name": "John",
"last_name": "Doe",
"organization_name": "Organization Name",
"tax_id": "123456789",
"taxonomy_code": "207Q00000X"
},
"responsible_party": "INSURANCE_PAY",
"service_facility": {
"service_facility_id": "2861487B-232C-4DED-A874-616A5DB0688F",
"organization_name": "Test Organization",
"address": {
"address1": "123 Main St",
"city": "New York",
"state": "NY",
"zip_code": "10001",
"zip_plus_four_code": "1234",
"address2": "Apt 1"
}
},
"submission_origin": "CANDID",
"tags": [
{
"color": "black",
"creator_id": "00EB5A46-35C6-441B-9751-AF307AEF5888",
"description": "to indicate claims where a void claim has been submitted",
"tag_id": "void-claim-submitted"
}
],
"url": "https://example.com",
"admission_date": "2023-01-01",
"appointment_type": "Routine Checkup",
"billing_notes": [
{
"billing_note_id": "99882EEA-936F-4E71-BC4F-520E4D14E3E2",
"created_at": "2023-01-01T00:00:00Z",
"encounter_id": "8BCFB6A8-2876-4111-9E3F-602B541FCF62",
"text": "Patient was billed for an MRI.",
"author_auth0_id": "F0DE3BF9-F9A1-4FA7-BF6B-28C0B46BADD8",
"author_name": "John Doe"
}
],
"coding_attribution": "CANDID",
"discharge_date": "2023-01-05",
"end_date_of_service": "2023-01-05",
"existing_medications": [
{
"name": "Lisinopril",
"rx_cui": "860975",
"dosage": "10mg",
"dosage_form": "Tablet",
"frequency": "Once Daily",
"as_needed": true
}
],
"guarantor": {
"email_consent": true,
"external_id": "49460F77-6456-41F1-AC6D-0AED08614D39",
"first_name": "John",
"guarantor_id": "8BBDBE63-58D3-4D40-98C9-40403C050977",
"last_name": "Doe",
"phone_consent": true,
"phone_numbers": [
{
"number": "1234567890",
"type": "Home"
}
],
"address": {
"address1": "123 Main St",
"city": "New York",
"state": "NY",
"zip_code": "10001",
"address2": "Apt 1",
"zip_plus_four_code": "1234"
},
"date_of_birth": "2000-01-01",
"email": "johndoe@joincandidhealth.com"
},
"interventions": [
{
"name": "Physical Therapy Session",
"category": "lifestyle",
"description": "A session focused on improving muscular strength, flexibility, and range of motion post-injury.",
"medication": {
"name": "Lisinopril",
"rx_cui": "860975",
"dosage": "10mg",
"dosage_form": "Tablet",
"frequency": "Once Daily",
"as_needed": true
},
"labs": [
{
"name": "Genetic Health Labs",
"code": "GH12345",
"code_type": "quest"
}
]
}
],
"onset_of_current_illness_or_symptom_date": "2023-01-01",
"pay_to_address": {
"address1": "123 Main St",
"city": "New York",
"state": "NY",
"zip_code": "10001",
"zip_plus_four_code": "1234",
"address2": "Apt 1"
},
"place_of_service_code": "01",
"place_of_service_code_as_submitted": "01",
"prior_authorization_number": "PA1234567",
"referring_provider": {
"address": {
"address1": "123 Main St",
"city": "New York",
"state": "NY",
"zip_code": "10001",
"zip_plus_four_code": "1234",
"address2": "Apt 1"
},
"npi": "1234567890",
"provider_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
"first_name": "John",
"last_name": "Doe",
"organization_name": "Organization Name",
"tax_id": "123456789",
"taxonomy_code": "207Q00000X"
},
"service_authorization_exception_code": "1",
"subscriber_primary": {
"first_name": "John",
"gender": "male",
"individual_id": "797348A9-E7E8-4E59-8628-95390D079C0B",
"insurance_card": {
"insurance_card_id": "CA5B7711-4419-4161-9B7C-3494AC40C8D4",
"member_id": "E85313B4-0FFC-4119-8042-8161A4ECFF0A",
"payer_id": "836DDAA6-863F-4020-ACCA-205A689F0002",
"payer_name": "John Doe",
"group_number": "ABC12345",
"image_url_back": "https://s3.amazonaws.com/back.jpg",
"image_url_front": "https://s3.amazonaws.com/front.jpg",
"insurance_type": "12",
"plan_name": "Silver PPO Plan",
"plan_type": "09",
"rx_bin": "610014",
"rx_pcn": "MEDDPRIME"
},
"last_name": "Doe",
"patient_relationship_to_subscriber_code": "01",
"address": {
"address1": "123 Main St",
"city": "New York",
"state": "NY",
"zip_code": "10001",
"address2": "Apt 1",
"zip_plus_four_code": "1234"
},
"date_of_birth": "2000-01-01"
},
"subscriber_secondary": {
"first_name": "John",
"gender": "male",
"individual_id": "797348A9-E7E8-4E59-8628-95390D079C0B",
"insurance_card": {
"insurance_card_id": "CA5B7711-4419-4161-9B7C-3494AC40C8D4",
"member_id": "E85313B4-0FFC-4119-8042-8161A4ECFF0A",
"payer_id": "836DDAA6-863F-4020-ACCA-205A689F0002",
"payer_name": "John Doe",
"group_number": "ABC12345",
"image_url_back": "https://s3.amazonaws.com/back.jpg",
"image_url_front": "https://s3.amazonaws.com/front.jpg",
"insurance_type": "12",
"plan_name": "Silver PPO Plan",
"plan_type": "09",
"rx_bin": "610014",
"rx_pcn": "MEDDPRIME"
},
"last_name": "Doe",
"patient_relationship_to_subscriber_code": "01",
"address": {
"address1": "123 Main St",
"city": "New York",
"state": "NY",
"zip_code": "10001",
"address2": "Apt 1",
"zip_plus_four_code": "1234"
},
"date_of_birth": "2000-01-01"
},
"synchronicity": "Synchronous",
"vitals": {
"height_in": 70,
"weight_lbs": 165,
"blood_pressure_systolic_mmhg": 115,
"blood_pressure_diastolic_mmhg": 85,
"body_temperature_f": 98
},
"work_queue_id": "000856FE-1024-418F-BF96-2E7347AB4520",
"work_queue_membership_activated_at": "2023-01-01T00:00:00Z"
}
]
}