@healthcloudai/hc-sdk 3.26.0 → 3.28.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.cjs +78 -3
- package/dist/index.d.cts +869 -338
- package/dist/index.d.ts +869 -338
- package/dist/index.js +78 -3
- package/docs/clients/PatientClient.md +1 -0
- package/docs/docs-manifest.json +9 -3
- package/docs/examples/index.md +1 -0
- package/docs/index.md +1 -0
- package/docs/models/CheckInEncounterResponse.md +1 -1
- package/docs/models/CheckInsuranceBenefitsRequest.md +19 -0
- package/docs/models/CheckInsuranceBenefitsResponse.md +28 -0
- package/docs/models/GetEncounterResponse.md +1 -1
- package/docs/models/InsuranceBenefit.md +27 -0
- package/docs/models/ProviderEncounterRecord.md +3 -1
- package/docs/models/ProviderIntakeContent.md +25 -0
- package/docs/models/ProviderIntakeSubmission.md +29 -0
- package/docs/models/ProviderPatientRecordResources.md +1 -1
- package/docs/models/ProviderQueueEncounter.md +1 -0
- package/docs/models/UpdateEncounterClinicalNoteRequest.md +2 -1
- package/docs/models/fieldagent.Encounter.md +1 -1
- package/docs/models/index.md +5 -0
- package/docs/models/patient.Encounter.md +1 -1
- package/docs/models/provider.Encounter.md +1 -1
- package/docs/operations/patient.checkPatientInsuranceBenefits.md +209 -0
- package/docs/operations/patient.listPatientInsuranceClaims.md +3 -1
- package/docs/operations/provider.claimEncounter.md +2 -0
- package/docs/operations/provider.getEncounter.md +2 -0
- package/docs/operations/provider.getEncounterQueue.md +1 -0
- package/docs/operations/provider.getPatientRecord.md +54 -0
- package/docs/operations/provider.listEncounters.md +2 -0
- package/docs/operations/provider.signEncounter.md +2 -0
- package/docs/operations/provider.updateEncounterClinicalNote.md +2 -0
- package/docs/operations/provider.updateEncounterDiagnoses.md +2 -0
- package/docs/operations/provider.updateEncounterStatus.md +2 -0
- package/package.json +1 -1
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
# Check reported insurance benefits
|
|
2
|
+
|
|
3
|
+
Operation ID: `patient.checkPatientInsuranceBenefits`
|
|
4
|
+
|
|
5
|
+
Check reported copay, coinsurance, deductible and out-of-pocket benefits for one X12 STC. Requires a PATIENT-pool Bearer JWT; identity and tenant come from the token. Uses saved name/DOB and exactly one active primary self Coverage. The Stedi key and requesting NPI are resolved server-side. Calls Stedi POST /2026-06-01/eligibility-check once with a 12-second timeout and no redirects. Omit service_date for the payer current date. No STC 30 fallback or inferred amounts. Entries retain plan, coverage level, network, period and benefit dates; null amounts remain unknown. coinsurance_fraction is a decimal fraction (0.2 means 20%). additional_conditions flags payer restrictions that require review; free-form payer messages are not exposed. Reported network applicability does not verify clinician participation, and benefits are not a final price. Persist request_id and the exact request body. A FHIR Task is conditionally created before Stedi I/O. Replay returns the saved result without another Stedi call; a changed body returns 409. An uncertain write remains pending and needs reconciliation; never automatically generate a new ID after a timeout or pending result, since that could cause another billable vendor check.
|
|
6
|
+
|
|
7
|
+
## Public method
|
|
8
|
+
|
|
9
|
+
`checkInsuranceBenefits`
|
|
10
|
+
|
|
11
|
+
Signature: `patient.checkInsuranceBenefits(request)`
|
|
12
|
+
|
|
13
|
+
Return type: `Promise<CheckInsuranceBenefitsResponse>`
|
|
14
|
+
|
|
15
|
+
## Authentication
|
|
16
|
+
|
|
17
|
+
Classification: **AUTHENTICATED**
|
|
18
|
+
|
|
19
|
+
Schemes: `bearerAuth`
|
|
20
|
+
|
|
21
|
+
## Prerequisites
|
|
22
|
+
|
|
23
|
+
- A PATIENT-pool access token and exactly one saved active primary self Coverage with complete saved demographics.
|
|
24
|
+
- The server's Stedi key and tenant-specific requesting NPI are configured; neither is a request parameter.
|
|
25
|
+
|
|
26
|
+
## HTTP
|
|
27
|
+
|
|
28
|
+
`POST /insurance/benefits/check`
|
|
29
|
+
|
|
30
|
+
## Path parameters
|
|
31
|
+
|
|
32
|
+
None.
|
|
33
|
+
|
|
34
|
+
## Query parameters
|
|
35
|
+
|
|
36
|
+
None.
|
|
37
|
+
|
|
38
|
+
## Body parameters
|
|
39
|
+
|
|
40
|
+
| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|
|
41
|
+
|---|---|---:|---|---|---|---:|---|
|
|
42
|
+
| `body` | [`CheckInsuranceBenefitsRequest`](../models/CheckInsuranceBenefitsRequest.md) | Yes | | | | No | |
|
|
43
|
+
|
|
44
|
+
Request model: [`CheckInsuranceBenefitsRequest`](../models/CheckInsuranceBenefitsRequest.md)
|
|
45
|
+
|
|
46
|
+
## Request example
|
|
47
|
+
|
|
48
|
+
None declared in canonical OpenAPI.
|
|
49
|
+
|
|
50
|
+
## Success responses
|
|
51
|
+
|
|
52
|
+
| Status | Shape | Content type | Description |
|
|
53
|
+
|---|---|---|---|
|
|
54
|
+
| `200` | [`CheckInsuranceBenefitsResponse`](../models/CheckInsuranceBenefitsResponse.md) | application/json | Persisted result. Inspect status/reason: completed is a reported result, unavailable is not ineligible coverage. |
|
|
55
|
+
| `202` | [`CheckInsuranceBenefitsResponse`](../models/CheckInsuranceBenefitsResponse.md) | application/json | Outcome pending. Replay the same request ID/body; no automatic vendor re-dispatch. |
|
|
56
|
+
|
|
57
|
+
## Success response examples
|
|
58
|
+
|
|
59
|
+
### 200
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
{
|
|
63
|
+
"benefits": [
|
|
64
|
+
{
|
|
65
|
+
"additional_conditions": false,
|
|
66
|
+
"benefit_end": "2026-01-01",
|
|
67
|
+
"benefit_start": "2026-01-01",
|
|
68
|
+
"benefit_type": "copay",
|
|
69
|
+
"coverage_level": "CHILDREN_ONLY",
|
|
70
|
+
"network": "IN_NETWORK",
|
|
71
|
+
"plan_index": 0,
|
|
72
|
+
"service_type_code": "string",
|
|
73
|
+
"time_period": "HOUR"
|
|
74
|
+
}
|
|
75
|
+
],
|
|
76
|
+
"check_id": "00000000-0000-0000-0000-000000000000",
|
|
77
|
+
"checked_at": "2026-01-01T09:00:00Z",
|
|
78
|
+
"coverage_id": "string",
|
|
79
|
+
"endpoint_version": "2026-06-01",
|
|
80
|
+
"interpretation": "reported_benefits_not_final_price",
|
|
81
|
+
"network_determination": "unknown",
|
|
82
|
+
"reason": "active_coverage",
|
|
83
|
+
"service_date": "2026-01-01",
|
|
84
|
+
"service_type_code": "string",
|
|
85
|
+
"source": "stedi",
|
|
86
|
+
"status": "completed"
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### 202
|
|
91
|
+
|
|
92
|
+
```json
|
|
93
|
+
{
|
|
94
|
+
"benefits": [
|
|
95
|
+
{
|
|
96
|
+
"additional_conditions": false,
|
|
97
|
+
"benefit_end": "2026-01-01",
|
|
98
|
+
"benefit_start": "2026-01-01",
|
|
99
|
+
"benefit_type": "copay",
|
|
100
|
+
"coverage_level": "CHILDREN_ONLY",
|
|
101
|
+
"network": "IN_NETWORK",
|
|
102
|
+
"plan_index": 0,
|
|
103
|
+
"service_type_code": "string",
|
|
104
|
+
"time_period": "HOUR"
|
|
105
|
+
}
|
|
106
|
+
],
|
|
107
|
+
"check_id": "00000000-0000-0000-0000-000000000000",
|
|
108
|
+
"checked_at": "2026-01-01T09:00:00Z",
|
|
109
|
+
"coverage_id": "string",
|
|
110
|
+
"endpoint_version": "2026-06-01",
|
|
111
|
+
"interpretation": "reported_benefits_not_final_price",
|
|
112
|
+
"network_determination": "unknown",
|
|
113
|
+
"reason": "active_coverage",
|
|
114
|
+
"service_date": "2026-01-01",
|
|
115
|
+
"service_type_code": "string",
|
|
116
|
+
"source": "stedi",
|
|
117
|
+
"status": "completed"
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Common errors
|
|
122
|
+
|
|
123
|
+
| Status | Shape | Content type | Description |
|
|
124
|
+
|---|---|---|---|
|
|
125
|
+
| `401` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | Authorization required — missing, invalid, expired, or non-patient Bearer JWT |
|
|
126
|
+
| `404` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | The authenticated patient has no FHIR Patient record |
|
|
127
|
+
| `409` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | The request ID already belongs to a different body |
|
|
128
|
+
| `422` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | Invalid UUID, STC or ISO date, missing required fields, non-object body or extra fields |
|
|
129
|
+
| `503` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | The durable check journal is unavailable. Replay the same request ID/body. |
|
|
130
|
+
|
|
131
|
+
## Error examples
|
|
132
|
+
|
|
133
|
+
### 401 — Missing or invalid access token
|
|
134
|
+
|
|
135
|
+
```json
|
|
136
|
+
{
|
|
137
|
+
"error": "Authorization required"
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### 404 — Patient not found
|
|
142
|
+
|
|
143
|
+
```json
|
|
144
|
+
{
|
|
145
|
+
"error": "Patient not found"
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### 409 — Changed request body
|
|
150
|
+
|
|
151
|
+
```json
|
|
152
|
+
{
|
|
153
|
+
"error": "request_id was already used for a different check"
|
|
154
|
+
}
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### 422 — Invalid request
|
|
158
|
+
|
|
159
|
+
```json
|
|
160
|
+
{
|
|
161
|
+
"error": "Invalid insurance benefits request"
|
|
162
|
+
}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### 503 — Storage unavailable
|
|
166
|
+
|
|
167
|
+
```json
|
|
168
|
+
{
|
|
169
|
+
"error": "Insurance benefits service is unavailable"
|
|
170
|
+
}
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
## NodeJS / TypeScript implementation
|
|
174
|
+
|
|
175
|
+
```ts
|
|
176
|
+
import { HCSDK } from "@healthcloudai/hc-sdk";
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
```ts
|
|
180
|
+
const request = "<REQUEST>";
|
|
181
|
+
|
|
182
|
+
const result = await patient.checkInsuranceBenefits(request);
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
## cURL
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
curl -X POST \
|
|
189
|
+
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
|
|
190
|
+
-H 'Content-Type: application/json' \
|
|
191
|
+
-d '<REQUEST_BODY_JSON>' \
|
|
192
|
+
'https://dev-api-patient.health.cloud/insurance/benefits/check'
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
## Notes
|
|
196
|
+
|
|
197
|
+
- npm: patient.checkInsuranceBenefits(request). Python: patient.check_insurance_benefits(request). Persist the request_id and exact body before sending.
|
|
198
|
+
- HTTP 202 is a typed pending outcome. Replay the original ID/body to read the saved result. Never automatically generate another ID after a timeout, pending result or uncertain storage failure.
|
|
199
|
+
- Entries preserve individual/family, network applicability, annual/remaining period and plan separately. Missing amounts are unknown, not zero. coinsurance_fraction of 0.20 means 20%.
|
|
200
|
+
- Reported benefits do not establish a final patient charge or clinician network participation. additional_conditions flags payer restrictions that require review.
|
|
201
|
+
- Omit service_date for the payer's current date. Standard Stedi medical mock requests support only service_type_code 30 and require the published exact test subscriber values and a test-mode key.
|
|
202
|
+
|
|
203
|
+
## Prepared Test Console scenario
|
|
204
|
+
|
|
205
|
+
No canonical scenario is currently associated.
|
|
206
|
+
|
|
207
|
+
## Real response
|
|
208
|
+
|
|
209
|
+
No approved real integration response is currently published. Unapproved candidates are never rendered as examples.
|
|
@@ -173,7 +173,9 @@ curl -X GET \
|
|
|
173
173
|
|
|
174
174
|
## Notes
|
|
175
175
|
|
|
176
|
-
|
|
176
|
+
- npm: patient.listInsuranceClaims(query). Python: patient.list_insurance_claims(page_size=..., page_token=...). Existing Patient SDK methods and patient-owned FHIR Claim linkage are reused.
|
|
177
|
+
- Stedi statuses pass through unchanged: SUBMITTED, RECEIVED, ACCEPTED, REJECTED, PROCESSED, DENIED and UNKNOWN. PROCESSED means adjudicated and does not establish payment.
|
|
178
|
+
- No paid amount or patient responsibility is inferred from missing claim data. An empty owned collection is a successful response and does not establish a live Stedi claim-status readback.
|
|
177
179
|
|
|
178
180
|
## Prepared Test Console scenario
|
|
179
181
|
|
|
@@ -132,8 +132,10 @@ None declared in canonical OpenAPI.
|
|
|
132
132
|
"period_start": "2026-01-01T09:00:00Z",
|
|
133
133
|
"priority_code": "string",
|
|
134
134
|
"priority_display": "string",
|
|
135
|
+
"provider_notes": "string",
|
|
135
136
|
"reason_code": "string",
|
|
136
137
|
"reason_display": "string",
|
|
138
|
+
"reported_symptoms": "string",
|
|
137
139
|
"service_provider_display": "string",
|
|
138
140
|
"service_provider_id": "string",
|
|
139
141
|
"service_type_code": "string",
|
|
@@ -130,8 +130,10 @@ None declared in canonical OpenAPI.
|
|
|
130
130
|
"period_start": "2026-01-01T09:00:00Z",
|
|
131
131
|
"priority_code": "string",
|
|
132
132
|
"priority_display": "string",
|
|
133
|
+
"provider_notes": "string",
|
|
133
134
|
"reason_code": "string",
|
|
134
135
|
"reason_display": "string",
|
|
136
|
+
"reported_symptoms": "string",
|
|
135
137
|
"service_provider_display": "string",
|
|
136
138
|
"service_provider_id": "string",
|
|
137
139
|
"service_type_code": "string",
|
|
@@ -339,8 +339,62 @@ None declared in canonical OpenAPI.
|
|
|
339
339
|
],
|
|
340
340
|
"intake_submissions": [
|
|
341
341
|
{
|
|
342
|
+
"content": {
|
|
343
|
+
"allergies": [],
|
|
344
|
+
"conditions": [
|
|
345
|
+
{
|
|
346
|
+
"categories": [],
|
|
347
|
+
"clinical_status": "active",
|
|
348
|
+
"description": "string",
|
|
349
|
+
"problem_id": "00000000-0000-0000-0000-000000000000",
|
|
350
|
+
"verification_status": "confirmed"
|
|
351
|
+
}
|
|
352
|
+
],
|
|
353
|
+
"family_history": [],
|
|
354
|
+
"gyn_history": [
|
|
355
|
+
{
|
|
356
|
+
"history_id": "00000000-0000-0000-0000-000000000000"
|
|
357
|
+
}
|
|
358
|
+
],
|
|
359
|
+
"immunizations": [
|
|
360
|
+
{
|
|
361
|
+
"immunization_id": "00000000-0000-0000-0000-000000000000",
|
|
362
|
+
"reactions": [],
|
|
363
|
+
"reason_codes": [],
|
|
364
|
+
"status": "completed",
|
|
365
|
+
"vaccine_name": "string"
|
|
366
|
+
}
|
|
367
|
+
],
|
|
368
|
+
"medications": [],
|
|
369
|
+
"perinatal_history": [
|
|
370
|
+
{
|
|
371
|
+
"history_id": "00000000-0000-0000-0000-000000000000"
|
|
372
|
+
}
|
|
373
|
+
],
|
|
374
|
+
"procedures": [
|
|
375
|
+
{
|
|
376
|
+
"body_sites": [],
|
|
377
|
+
"complications": [],
|
|
378
|
+
"description": "string",
|
|
379
|
+
"procedure_id": "00000000-0000-0000-0000-000000000000",
|
|
380
|
+
"reported": false,
|
|
381
|
+
"status": "completed"
|
|
382
|
+
}
|
|
383
|
+
],
|
|
384
|
+
"social_history": [
|
|
385
|
+
{
|
|
386
|
+
"occupational_exposures": [],
|
|
387
|
+
"substances": [],
|
|
388
|
+
"travel_history": []
|
|
389
|
+
}
|
|
390
|
+
]
|
|
391
|
+
},
|
|
392
|
+
"content_complete": true,
|
|
342
393
|
"created_at": "2026-01-01T09:00:00Z",
|
|
343
394
|
"invalid_entries": {},
|
|
395
|
+
"sections": [
|
|
396
|
+
"string"
|
|
397
|
+
],
|
|
344
398
|
"storage_status": "pending",
|
|
345
399
|
"submission_id": "00000000-0000-0000-0000-000000000000",
|
|
346
400
|
"unknown_fields": [
|
|
@@ -132,8 +132,10 @@ None declared in canonical OpenAPI.
|
|
|
132
132
|
"period_start": "2026-01-01T09:00:00Z",
|
|
133
133
|
"priority_code": "string",
|
|
134
134
|
"priority_display": "string",
|
|
135
|
+
"provider_notes": "string",
|
|
135
136
|
"reason_code": "string",
|
|
136
137
|
"reason_display": "string",
|
|
138
|
+
"reported_symptoms": "string",
|
|
137
139
|
"service_provider_display": "string",
|
|
138
140
|
"service_provider_id": "string",
|
|
139
141
|
"service_type_code": "string",
|
|
@@ -131,8 +131,10 @@ None declared in canonical OpenAPI.
|
|
|
131
131
|
"period_start": "2026-01-01T09:00:00Z",
|
|
132
132
|
"priority_code": "string",
|
|
133
133
|
"priority_display": "string",
|
|
134
|
+
"provider_notes": "string",
|
|
134
135
|
"reason_code": "string",
|
|
135
136
|
"reason_display": "string",
|
|
137
|
+
"reported_symptoms": "string",
|
|
136
138
|
"service_provider_display": "string",
|
|
137
139
|
"service_provider_id": "string",
|
|
138
140
|
"service_type_code": "string",
|
|
@@ -138,8 +138,10 @@ Request model: [`UpdateEncounterClinicalNoteRequest`](../models/UpdateEncounterC
|
|
|
138
138
|
"period_start": "2026-01-01T09:00:00Z",
|
|
139
139
|
"priority_code": "string",
|
|
140
140
|
"priority_display": "string",
|
|
141
|
+
"provider_notes": "string",
|
|
141
142
|
"reason_code": "string",
|
|
142
143
|
"reason_display": "string",
|
|
144
|
+
"reported_symptoms": "string",
|
|
143
145
|
"service_provider_display": "string",
|
|
144
146
|
"service_provider_id": "string",
|
|
145
147
|
"service_type_code": "string",
|
|
@@ -143,8 +143,10 @@ Request model: [`UpdateEncounterDiagnosesRequest`](../models/UpdateEncounterDiag
|
|
|
143
143
|
"period_start": "2026-01-01T09:00:00Z",
|
|
144
144
|
"priority_code": "string",
|
|
145
145
|
"priority_display": "string",
|
|
146
|
+
"provider_notes": "string",
|
|
146
147
|
"reason_code": "string",
|
|
147
148
|
"reason_display": "string",
|
|
149
|
+
"reported_symptoms": "string",
|
|
148
150
|
"service_provider_display": "string",
|
|
149
151
|
"service_provider_id": "string",
|
|
150
152
|
"service_type_code": "string",
|
|
@@ -137,8 +137,10 @@ Request model: [`UpdateEncounterStatusRequest`](../models/UpdateEncounterStatusR
|
|
|
137
137
|
"period_start": "2026-01-01T09:00:00Z",
|
|
138
138
|
"priority_code": "string",
|
|
139
139
|
"priority_display": "string",
|
|
140
|
+
"provider_notes": "string",
|
|
140
141
|
"reason_code": "string",
|
|
141
142
|
"reason_display": "string",
|
|
143
|
+
"reported_symptoms": "string",
|
|
142
144
|
"service_provider_display": "string",
|
|
143
145
|
"service_provider_id": "string",
|
|
144
146
|
"service_type_code": "string",
|
package/package.json
CHANGED