Candid Health Encounters API
Create and manage professional and institutional encounter records including diagnoses, service lines, encounter attachments, providers, and supplemental information for claims billing.
OpenAPI Specification
openapi: 3.1.0
info:
title: API Reference
version: 1.0.0
paths:
/eligibility-checks/v1:
post:
operationId: post
summary: Post
description: Sends real-time eligibility checks to payers through Stedi.
tags:
- >-
subpackage_pre-encounter.subpackage_pre-encounter/eligibilityChecks.subpackage_pre-encounter/eligibilityChecks/v1
parameters:
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/eligibilityChecks/v1:EligibilityResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/eligibilityChecks/v1:EligibilityRequest'
/eligibility-checks/v1/batch:
post:
operationId: batch
summary: Batch
description: Sends a batch of eligibility checks to payers through Stedi.
tags:
- >-
subpackage_pre-encounter.subpackage_pre-encounter/eligibilityChecks.subpackage_pre-encounter/eligibilityChecks/v1
parameters:
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/eligibilityChecks/v1:BatchEligibilityResponse'
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/type_pre-encounter/eligibilityChecks/v1:EligibilityRequest'
/eligibility-checks/v1/batch/{batch_id}:
get:
operationId: poll-batch
summary: Poll Batch
description: Polls the status of a batch eligibility check.
tags:
- >-
subpackage_pre-encounter.subpackage_pre-encounter/eligibilityChecks.subpackage_pre-encounter/eligibilityChecks/v1
parameters:
- name: batch_id
in: path
required: true
schema:
type: string
- name: page_token
in: query
required: false
schema:
$ref: '#/components/schemas/type_pre-encounter/common:PageToken'
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/eligibilityChecks/v1:EligibilityCheckPage'
/eligibility-checks/v1/payer/search:
get:
operationId: payer-search
summary: Payer Search
description: Searches for payers that match the query parameters.
tags:
- >-
subpackage_pre-encounter.subpackage_pre-encounter/eligibilityChecks.subpackage_pre-encounter/eligibilityChecks/v1
parameters:
- name: page_size
in: query
required: false
schema:
type: integer
- name: page_token
in: query
required: false
schema:
$ref: '#/components/schemas/type_pre-encounter/common:PageToken'
- name: query
in: query
required: false
schema:
type: string
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/eligibilityChecks/v1:PayerSearchResponse'
/eligibility-checks/v1/recommendation:
get:
operationId: recommendation
summary: Recommendation
description: >-
Gets recommendation for eligibility checks based on filters. This endpoint will retrieve all the latest
eligibility recommendations for each
eligibility recommendation type for the given filters. If you want to get a specific recommendation type, you
can use the `type` query parameter.
tags:
- >-
subpackage_pre-encounter.subpackage_pre-encounter/eligibilityChecks.subpackage_pre-encounter/eligibilityChecks/v1
parameters:
- name: filters
in: query
required: false
schema:
$ref: '#/components/schemas/type_pre-encounter/common:FilterQueryString'
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/type_pre-encounter/eligibilityChecks/v1:EligibilityRecommendation'
post:
operationId: create-recommendation
summary: Create Recommendation
description: Create an eligibiilty recommendation based on the request.
tags:
- >-
subpackage_pre-encounter.subpackage_pre-encounter/eligibilityChecks.subpackage_pre-encounter/eligibilityChecks/v1
parameters:
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/eligibilityChecks/v1:EligibilityRecommendation'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/eligibilityChecks/v1:PostEligibilityRecommendationRequest'
/eligibility-checks/v1/recommendation/{recommendation_id}/{version}/vote:
put:
operationId: vote-recommendation
summary: Vote Recommendation
description: >-
Submit user feedback on an eligibility recommendation. The path must contain the next version number to prevent
race conditions. For example, if the current version of the recommendation is n, you will need to send a request
to this endpoint with `/{recommendation_id}/{n+1}/vote` to update the vote.
tags:
- >-
subpackage_pre-encounter.subpackage_pre-encounter/eligibilityChecks.subpackage_pre-encounter/eligibilityChecks/v1
parameters:
- name: recommendation_id
in: path
required: true
schema:
type: string
- name: version
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/eligibilityChecks/v1:EligibilityRecommendation'
'404':
description: Error response with status 404
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- NotFoundError
content:
$ref: '#/components/schemas/type_pre-encounter/common:ErrorBase4xx'
required:
- errorName
- content
'409':
description: Error response with status 409
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- VersionConflictError
content:
$ref: '#/components/schemas/type_pre-encounter/common:VersionConflictErrorBody'
required:
- errorName
- content
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/eligibilityChecks/v1:Vote'
/eligibility-checks/v1/get-multi/:
get:
operationId: get-multi
summary: Get Multi
tags:
- >-
subpackage_pre-encounter.subpackage_pre-encounter/eligibilityChecks.subpackage_pre-encounter/eligibilityChecks/v1
parameters:
- name: page_token
in: query
required: false
schema:
$ref: '#/components/schemas/type_pre-encounter/common:PageToken'
- name: limit
in: query
required: false
schema:
type: integer
- name: subscriber_member_id
in: query
required: false
schema:
type: string
- name: payer_id
in: query
required: false
schema:
type: string
- name: provider_npi
in: query
required: false
schema:
type: string
- name: date_of_service
in: query
required: false
schema:
type: string
- name: initiated_at_min
in: query
required: false
schema:
type: string
format: date-time
- name: initiated_at_max
in: query
required: false
schema:
type: string
format: date-time
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/eligibilityChecks/v1:EligibilityCheckPage'
/appointments/v1:
post:
operationId: create
summary: Create
description: Adds an appointment. VersionConflictError is returned when the placer_appointment_id is already in use.
tags:
- subpackage_pre-encounter.subpackage_pre-encounter/appointments.subpackage_pre-encounter/appointments/v1
parameters:
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/appointments/v1:Appointment'
'404':
description: Error response with status 404
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- NotFoundError
content:
$ref: '#/components/schemas/type_pre-encounter/common:ErrorBase4xx'
required:
- errorName
- content
'409':
description: Error response with status 409
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- VersionConflictError
content:
$ref: '#/components/schemas/type_pre-encounter/common:VersionConflictErrorBody'
required:
- errorName
- content
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/appointments/v1:MutableAppointment'
/appointments/v1/visits:
get:
operationId: get-visits
summary: Get Visits
description: >-
Gets all Visits within a given time range. The return list is ordered by start_time ascending.
**IMPORTANT:** This endpoint requires a date filter on `appointment.startTimestamp` to ensure acceptable query
performance.
Without date filtering, the query can take 50+ seconds on large datasets due to grouping and aggregation
operations.
Example filters:
- `appointment.startTimestamp|gt|2024-01-01` - appointments after January 1, 2024
- `appointment.startTimestamp|eq|2024-12-08` - appointments on December 8, 2024
- `appointment.startTimestamp|lt|2024-12-31` - appointments before December 31, 2024
You can combine the date filter with other filters using commas:
- `appointment.startTimestamp|gt|2024-01-01,appointment.status|eq|PENDING`
tags:
- subpackage_pre-encounter.subpackage_pre-encounter/appointments.subpackage_pre-encounter/appointments/v1
parameters:
- name: page_token
in: query
required: false
schema:
$ref: '#/components/schemas/type_pre-encounter/common:PageToken'
- name: limit
in: query
required: false
schema:
type: integer
- name: sort_field
in: query
description: Defaults to appointment.start_time.
required: false
schema:
$ref: '#/components/schemas/type_pre-encounter/lists/v1:SortFieldString'
- name: sort_direction
in: query
description: Defaults to ascending.
required: false
schema:
$ref: '#/components/schemas/type_pre-encounter/common:SortDirection'
- name: filters
in: query
description: |-
**Required:** Must include a date filter on appointment.startTimestamp (using gt, lt, or eq operators).
Example: appointment.startTimestamp|gt|2024-01-01
required: false
schema:
$ref: '#/components/schemas/type_pre-encounter/common:FilterQueryString'
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/appointments/v1:VisitsPage'
'400':
description: Error response with status 400
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- BadRequestError
content:
$ref: '#/components/schemas/type_pre-encounter/common:ErrorBase4xx'
required:
- errorName
- content
/appointments/v1/{id}:
get:
operationId: get
summary: Get
description: Gets an appointment.
tags:
- subpackage_pre-encounter.subpackage_pre-encounter/appointments.subpackage_pre-encounter/appointments/v1
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/type_pre-encounter/common:AppointmentId'
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/appointments/v1:Appointment'
'404':
description: Error response with status 404
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- NotFoundError
content:
$ref: '#/components/schemas/type_pre-encounter/common:ErrorBase4xx'
required:
- errorName
- content
/appointments/v1/{id}/history:
get:
operationId: get-history
summary: Get History
description: Gets an appointment along with it's full history. The return list is ordered by version ascending.
tags:
- subpackage_pre-encounter.subpackage_pre-encounter/appointments.subpackage_pre-encounter/appointments/v1
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/type_pre-encounter/common:AppointmentId'
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/type_pre-encounter/appointments/v1:Appointment'
'404':
description: Error response with status 404
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- NotFoundError
content:
$ref: '#/components/schemas/type_pre-encounter/common:ErrorBase4xx'
required:
- errorName
- content
/appointments/v1/{id}/{version}:
put:
operationId: update
summary: Update
description: >-
Updates an appointment. The path must contain the next version number to prevent race conditions. For example,
if the current version of the appointment is n, you will need to send a request to this endpoint with
`/{id}/n+1` to update the appointment. Updating historic versions is not supported.
tags:
- subpackage_pre-encounter.subpackage_pre-encounter/appointments.subpackage_pre-encounter/appointments/v1
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/type_pre-encounter/common:AppointmentId'
- name: version
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/appointments/v1:Appointment'
'404':
description: Error response with status 404
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- NotFoundError
content:
$ref: '#/components/schemas/type_pre-encounter/common:ErrorBase4xx'
required:
- errorName
- content
'409':
description: Error response with status 409
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- VersionConflictError
content:
$ref: '#/components/schemas/type_pre-encounter/common:VersionConflictErrorBody'
required:
- errorName
- content
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/appointments/v1:MutableAppointment'
delete:
operationId: deactivate
summary: Deactivate
description: >-
Sets an appointment as deactivated. The path must contain the most recent version to prevent race conditions.
Deactivating historic versions is not supported. Subsequent updates via PUT to the appointment will "reactivate"
the appointment and set the deactivated flag to false.
tags:
- subpackage_pre-encounter.subpackage_pre-encounter/appointments.subpackage_pre-encounter/appointments/v1
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/type_pre-encounter/common:AppointmentId'
- name: version
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Successful response
'404':
description: Error response with status 404
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- NotFoundError
content:
$ref: '#/components/schemas/type_pre-encounter/common:ErrorBase4xx'
required:
- errorName
- content
'409':
description: Error response with status 409
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- VersionConflictError
content:
$ref: '#/components/schemas/type_pre-encounter/common:VersionConflictErrorBody'
required:
- errorName
- content
/appointments/v1/updates/scan:
get:
operationId: scan
summary: Scan
description: >-
Scans up to 100 appointment updates. The since query parameter is inclusive, and the result list is ordered by
updatedAt ascending.
tags:
- subpackage_pre-encounter.subpackage_pre-encounter/appointments.subpackage_pre-encounter/appointments/v1
parameters:
- name: since
in: query
required: true
schema:
type: string
format: date-time
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/type_pre-encounter/appointments/v1:Appointment'
/coverages/v1/:
post:
operationId: create
summary: Create
description: >-
Creates a new Coverage. A Coverage provides the high-level identifiers and descriptors of a specific insurance
plan for a specific individual - typically the information you can find on an insurance card. Additionally a
coverage will include detailed benefits information covered by the specific plan for the individual.
tags:
- subpackage_pre-encounter.subpackage_pre-encounter/coverages.subpackage_pre-encounter/coverages/v1
parameters:
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/coverages/v1:Coverage'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/coverages/v1:MutableCoverage'
get:
operationId: get-multi
summary: Get Multi
description: Returns a list of Coverages based on the search criteria.
tags:
- subpackage_pre-encounter.subpackage_pre-encounter/coverages.subpackage_pre-encounter/coverages/v1
parameters:
- name: patient_id
in: query
required: false
schema:
type: string
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/type_pre-encounter/coverages/v1:Coverage'
/coverages/v1//{id}/{version}:
put:
operationId: update
summary: Update
description: >-
Updates a Coverage. The path must contain the next version number to prevent race conditions. For example, if
the current version of the coverage is n, you will need to send a request to this endpoint with `/{id}/n+1` to
update the coverage. Updating historic versions is not supported.
tags:
- subpackage_pre-encounter.subpackage_pre-encounter/coverages.subpackage_pre-encounter/coverages/v1
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/type_pre-encounter/common:CoverageId'
- name: version
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/coverages/v1:Coverage'
'404':
description: Error response with status 404
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- NotFoundError
content:
$ref: '#/components/schemas/type_pre-encounter/common:ErrorBase4xx'
required:
- errorName
- content
'409':
description: Error response with status 409
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- VersionConflictError
content:
$ref: '#/components/schemas/type_pre-encounter/common:VersionConflictErrorBody'
required:
- errorName
- content
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/coverages/v1:MutableCoverage'
/coverages/v1//get-multi-paginated:
get:
operationId: get-multi-paginated
summary: Get Multi Paginated
description: Returns a page of Coverages based on the search criteria.
tags:
- subpackage_pre-encounter.subpackage_pre-encounter/coverages.subpackage_pre-encounter/coverages/v1
parameters:
- name: patient_id
in: query
required: false
schema:
type: string
- name: payer_plan_group_id
in: query
required: false
schema:
type: string
- name: page_token
in: query
required: false
schema:
$ref: '#/components/schemas/type_pre-encounter/common:PageToken'
- name: limit
in: query
description: Must be between 0 and 1000. Defaults to 100
required: false
schema:
type: integer
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/coverages/v1:CoveragesPage'
'400':
description: Error response with status 400
content:
application/json:
schema:
type: object
properties:
errorName:
type: string
enum:
- BadRequestError
content:
$ref: '#/components/schemas/type_pre-encounter/common:ErrorBase4xx'
required:
- errorName
- content
/coverages/v1//{id}:
get:
operationId: get
summary: Get
description: gets a specific Coverage
tags:
- subpackage_pre-encounter.subpackage_pre-encounter/coverages.subpackage_pre-encounter/coverages/v1
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/type_pre-encounter/common:CoverageId'
- name: Authorization
in: header
description: OAuth authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_pre-encounter/coverages/v1:Coverage'
/coverages/v1//{id}/history:
get:
operationId: get-history
summary: Get History
description: |-
Gets a coverage's history. Full history is returned if no filters are
defined. The return list is ordered by version, defaulting to ascending.
tags:
- subpackage_pre-encounter.subpackage_pre-encounter/coverages.subpackage_pre-encounter/coverages/v1
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/type_pre-encounter/common:CoverageId'
- name: start
in: query
required: false
schema:
type: string
format: date
- name: end
in: query
required: false
schema:
type: string
format: date
- name: non_auto_updated_coverages_only
in: query
description: If true, only returns coverages that have NOT been auto-updated by the system.
required: false
schema:
type: boolean
- name: sort_direction
in: query
description: Defaults to ascending. Sorts by version.
required: false
schema:
$ref: '#/componen
# --- truncated at 32 KB (1218 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/candid-health/refs/heads/main/openapi/candid-health-openapi.yml