@healthcloudai/hc-sdk 3.14.0 → 3.16.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.
Files changed (35) hide show
  1. package/dist/index.cjs +132 -72
  2. package/dist/index.d.cts +577 -261
  3. package/dist/index.d.ts +577 -261
  4. package/dist/index.js +132 -72
  5. package/docs/clients/AthenaHealthClient.md +1 -1
  6. package/docs/clients/PatientClient.md +5 -0
  7. package/docs/docs-manifest.json +16 -3
  8. package/docs/examples/index.md +6 -1
  9. package/docs/index.md +6 -1
  10. package/docs/models/ApplyPatientFlagsRequest.md +18 -0
  11. package/docs/models/AssignImpiloDeviceRequest.md +17 -0
  12. package/docs/models/AssignImpiloDeviceResponse.md +20 -0
  13. package/docs/models/AthenaLabResult.md +2 -0
  14. package/docs/models/FlagOperationError.md +18 -0
  15. package/docs/models/FlagOperationReceipt.md +20 -0
  16. package/docs/models/GetDefaultProviderResponse.md +2 -0
  17. package/docs/models/ImpiloDeviceItem.md +23 -0
  18. package/docs/models/ListImpiloDevicesResponse.md +18 -0
  19. package/docs/models/UnknownFlagOperation.md +18 -0
  20. package/docs/models/_InsuranceOcrResult.md +1 -0
  21. package/docs/models/index.md +8 -0
  22. package/docs/operations/connectors.athenaAddLabResultDocument.md +2 -2
  23. package/docs/operations/connectors.athenaGetLabResult.md +2 -0
  24. package/docs/operations/connectors.athenaListLabResults.md +2 -0
  25. package/docs/operations/patient.addInsurance.md +48 -16
  26. package/docs/operations/patient.applyPatientFlagsOperation.md +152 -0
  27. package/docs/operations/patient.assignImpiloDevice.md +112 -0
  28. package/docs/operations/patient.assistantOcrInsurance.md +64 -13
  29. package/docs/operations/patient.checkPatientInsuranceEligibility.md +133 -38
  30. package/docs/operations/patient.getDefaultProvider.md +2 -0
  31. package/docs/operations/patient.getPatientFlagsOperation.md +150 -0
  32. package/docs/operations/patient.importImpiloVitals.md +129 -0
  33. package/docs/operations/patient.listImpiloDevices.md +100 -0
  34. package/docs/operations/patient.submitPatientIntake.md +13 -1
  35. package/package.json +1 -1
@@ -0,0 +1,23 @@
1
+ # ImpiloDeviceItem
2
+
3
+ Model ID: `ImpiloDeviceItem`
4
+
5
+ No description.
6
+
7
+ Type: `object`
8
+
9
+ ## Fields
10
+
11
+ | Field | Type | Required | Format | Allowed values | Default | Nullable | Description |
12
+ |---|---|---:|---|---|---|---:|---|
13
+ | `id` | `integer|null` | No | | | | Yes | Impilo item ID. |
14
+ | `item_class` | `string|null` | No | | | | Yes | Device class (e.g. CELLULAR, BLUETOOTH). |
15
+ | `manufacturer` | `string|null` | No | | | | Yes | Manufacturer name. |
16
+ | `model` | `string|null` | No | | | | Yes | Device model. |
17
+ | `name` | `string|null` | No | | | | Yes | Device name. |
18
+ | `reading_type` | `string|null` | No | | | | Yes | Type of reading the device captures. |
19
+ | `sku` | `string|null` | No | | | | Yes | Stock-keeping unit. |
20
+
21
+ ## Example
22
+
23
+ None declared in canonical OpenAPI.
@@ -0,0 +1,18 @@
1
+ # ListImpiloDevicesResponse
2
+
3
+ Model ID: `ListImpiloDevicesResponse`
4
+
5
+ No description.
6
+
7
+ Type: `object`
8
+
9
+ ## Fields
10
+
11
+ | Field | Type | Required | Format | Allowed values | Default | Nullable | Description |
12
+ |---|---|---:|---|---|---|---:|---|
13
+ | `devices` | array of [`ImpiloDeviceItem`](./ImpiloDeviceItem.md) | Yes | | | | No | Available Impilo device types. |
14
+ | `total` | `integer` | Yes | | | | No | Total number of device types. |
15
+
16
+ ## Example
17
+
18
+ None declared in canonical OpenAPI.
@@ -0,0 +1,18 @@
1
+ # UnknownFlagOperation
2
+
3
+ Model ID: `UnknownFlagOperation`
4
+
5
+ No description.
6
+
7
+ Type: `object`
8
+
9
+ ## Fields
10
+
11
+ | Field | Type | Required | Format | Allowed values | Default | Nullable | Description |
12
+ |---|---|---:|---|---|---|---:|---|
13
+ | `idempotency_key` | `string` | Yes | | | | No | |
14
+ | `status` | `string` | Yes | | | | No | |
15
+
16
+ ## Example
17
+
18
+ None declared in canonical OpenAPI.
@@ -16,6 +16,7 @@ Type: `object`
16
16
  | `InsurerName` | `string` | Yes | | | | No | Issuing carrier name, or empty string if not legible. |
17
17
  | `LastName` | `string` | Yes | | | | No | Cardholder's last name, or empty string if not legible. |
18
18
  | `MemberID` | `string` | Yes | | | | No | Member/subscriber ID, or empty string if not legible. |
19
+ | `PayerID` | `string` | Yes | | | | No | Stedi payer id (primary Payer ID, Stedi payer ID or alias) as printed on the card, or AI-matched from the carrier name against the bundled Stedi payers catalogue; empty string when neither yields a usable id. |
19
20
  | `PlanName` | `string` | Yes | | | | No | Plan or product name, or empty string if not present. |
20
21
  | `RxBIN` | `string` | Yes | | | | No | 6-digit Rx BIN, or empty string if not present. |
21
22
  | `RxGRP` | `string` | Yes | | | | No | Rx group, or empty string if not present. |
@@ -33,9 +33,12 @@
33
33
  - [AppleAuthGenerateClientSecretRequest](AppleAuthGenerateClientSecretRequest.md)
34
34
  - [AppleAuthGenerateClientSecretResponse](AppleAuthGenerateClientSecretResponse.md)
35
35
  - [AppleIdTokenClaims](AppleIdTokenClaims.md)
36
+ - [ApplyPatientFlagsRequest](ApplyPatientFlagsRequest.md)
36
37
  - [Appointment](Appointment.md)
37
38
  - [ErrorResponse](appointments.ErrorResponse.md)
38
39
  - [AppointmentStatus](AppointmentStatus.md)
40
+ - [AssignImpiloDeviceRequest](AssignImpiloDeviceRequest.md)
41
+ - [AssignImpiloDeviceResponse](AssignImpiloDeviceResponse.md)
39
42
  - [AssistantAction](AssistantAction.md)
40
43
  - [AssistantChatRequest](AssistantChatRequest.md)
41
44
  - [AssistantChatResponse](AssistantChatResponse.md)
@@ -573,6 +576,8 @@
573
576
  - [FieldAgentVerifyEmailRequest](fieldagent.VerifyEmailRequest.md)
574
577
  - [FieldAgentVerifySmsRequest](fieldagent.VerifySmsRequest.md)
575
578
  - [FieldAgentProfileResponse](FieldAgentProfileResponse.md)
579
+ - [FlagOperationError](FlagOperationError.md)
580
+ - [FlagOperationReceipt](FlagOperationReceipt.md)
576
581
  - [Gender](Gender.md)
577
582
  - [GenderIdentity](GenderIdentity.md)
578
583
  - [GetAgentAgentResponse](GetAgentAgentResponse.md)
@@ -1098,6 +1103,7 @@
1098
1103
  - [ImpiloCreatePatientRequest](ImpiloCreatePatientRequest.md)
1099
1104
  - [ImpiloCreateProcurementRequest](ImpiloCreateProcurementRequest.md)
1100
1105
  - [ImpiloDevice](ImpiloDevice.md)
1106
+ - [ImpiloDeviceItem](ImpiloDeviceItem.md)
1101
1107
  - [ImpiloDeviceListResponse](ImpiloDeviceListResponse.md)
1102
1108
  - [ImpiloDeviceValidationResponse](ImpiloDeviceValidationResponse.md)
1103
1109
  - [ImpiloDisableReadingsRequest](ImpiloDisableReadingsRequest.md)
@@ -1221,6 +1227,7 @@
1221
1227
  - [ListFamilyHistoryResponse](ListFamilyHistoryResponse.md)
1222
1228
  - [FunctionalStatusListResponse](ListFunctionalStatusResponse.md)
1223
1229
  - [ListImmunizationsResponse](ListImmunizationsResponse.md)
1230
+ - [ListImpiloDevicesResponse](ListImpiloDevicesResponse.md)
1224
1231
  - [ListKnowledgeResponse](ListKnowledgeResponse.md)
1225
1232
  - [ListMedicalConceptsGetResponse](ListMedicalConceptsGetResponse.md)
1226
1233
  - [ListNotificationsResponse](ListNotificationsResponse.md)
@@ -1867,6 +1874,7 @@
1867
1874
  - [UberGetUndeliveredOrdersResponse](UberGetUndeliveredOrdersResponse.md)
1868
1875
  - [UberUpdateDeliveryRequest](UberUpdateDeliveryRequest.md)
1869
1876
  - [UberWaypoint](UberWaypoint.md)
1877
+ - [UnknownFlagOperation](UnknownFlagOperation.md)
1870
1878
  - [UpdateAddressRequest](UpdateAddressRequest.md)
1871
1879
  - [UpdateAddressResponse](UpdateAddressResponse.md)
1872
1880
  - [UpdateAgentRequest](UpdateAgentRequest.md)
@@ -1,8 +1,8 @@
1
- # Add lab result document (athenahealth)
1
+ # Create a result document, defaulting routing to the tenant provider
2
2
 
3
3
  Operation ID: `connectors.athenaAddLabResultDocument`
4
4
 
5
- Add lab result document via athenahealth. Returns an AthenaOperationResult record.
5
+ Create a result document, defaulting routing to the tenant provider. Provider IDs are Athena-local identifiers, never NPIs. If neither an explicit nor configured provider exists, preserve Athena's default routing. Legacy analyte resultflag/status codes are translated to Athena's abnormalflag/resultstatus text enums, including critical flags HH/LL/AA.
6
6
 
7
7
  ## Public method
8
8
 
@@ -78,6 +78,8 @@ Request model: [`AthenaGetLabResultRequest`](../models/AthenaGetLabResultRequest
78
78
  "loinc": "example-loinc",
79
79
  "observations": [],
80
80
  "order_type": "example-order-type",
81
+ "provider_id": "12345",
82
+ "provider_username": "example-provider-username",
81
83
  "result_category": "example-result-category",
82
84
  "status": "example-status"
83
85
  }
@@ -78,6 +78,8 @@ Request model: [`AthenaListLabResultsRequest`](../models/AthenaListLabResultsReq
78
78
  "loinc": "example-loinc",
79
79
  "observations": [],
80
80
  "order_type": "example-order-type",
81
+ "provider_id": "12345",
82
+ "provider_username": "example-provider-username",
81
83
  "result_category": "example-result-category",
82
84
  "status": "example-status"
83
85
  }
@@ -2,7 +2,7 @@
2
2
 
3
3
  Operation ID: `patient.addInsurance`
4
4
 
5
- Create a new FHIR Coverage resource for the authenticated patient. Requires a patient Bearer JWT.
5
+ Create a new FHIR Coverage resource for the authenticated patient. Requires a patient Bearer JWT. Supply payer_name and member_id; priority defaults to primary and relationship defaults to self. state is an optional vendor/payer matching hint. A plausible payer_id is used unchanged; a missing or implausible ID is resolved from payer_name against the Stedi catalogue. If neither path yields an ID, return 422 before writing Coverage. HTTP 201 confirms HealthCloud storage, not active eligibility or successful vendor synchronization. Call patient.checkPatientInsuranceEligibility separately. A 400 can occur after Coverage was written; read saved insurance before retrying to avoid duplicate submissions. Error text is descriptive and may vary; branch on HTTP status and structured outcome fields.
6
6
 
7
7
  ## Public method
8
8
 
@@ -60,25 +60,48 @@ Request model: [`AddInsuranceRequest`](../models/AddInsuranceRequest.md)
60
60
 
61
61
  | Status | Shape | Content type | Description |
62
62
  |---|---|---|---|
63
- | `201` | [`AddInsuranceResponse`](../models/AddInsuranceResponse.md) | application/json | Coverage created |
63
+ | `201` | [`AddInsuranceResponse`](../models/AddInsuranceResponse.md) | application/json | Coverage saved. coverages_created is the number created; patient_id is the patient identifier and fhir_patient_id is its deprecated alias. Only the vendor that ran has non-null athena_* or openloop_* fields. The corresponding *_insurance_status is linked (synchronized), failed (see *_insurance_error), skipped_no_match (no catalogue match), or skipped_not_linked (integration unavailable/misconfigured). Both vendor statuses are null when no vendor link applies; the internal skipped_no_vendor status is not emitted. *_best_match contains the selected plan or null. These secondary failures still return 201; do not automatically resubmit Coverage. When image is supplied, fhir_document_reference_id identifies the saved card or is null if saving it failed. athena_insurance_card_status is linked, failed, skipped_no_insurance_id, or skipped_insurance_not_linked. With no image both card fields are null. Card failures do not undo the saved Coverage. |
64
64
 
65
65
  ## Success response examples
66
66
 
67
- ### 201
67
+ ### 201 — Coverage saved even though vendor synchronization failed
68
68
 
69
69
  ```json
70
70
  {
71
- "athena_best_match": {},
72
- "athena_insurance_card_status": "string",
73
- "athena_insurance_error": "string",
74
- "athena_insurance_status": "string",
75
- "coverages_created": 0,
76
- "fhir_document_reference_id": "string",
77
- "fhir_patient_id": "string",
78
- "openloop_best_match": {},
79
- "openloop_insurance_error": "string",
80
- "openloop_insurance_status": "string",
81
- "patient_id": "string"
71
+ "athena_best_match": {
72
+ "insurance_package_id": "1352",
73
+ "insurance_type": null,
74
+ "name": "Example Plan",
75
+ "state": null
76
+ },
77
+ "athena_insurance_card_status": "skipped_insurance_not_linked",
78
+ "athena_insurance_error": "unexpected error — see server logs",
79
+ "athena_insurance_status": "failed",
80
+ "coverages_created": 1,
81
+ "fhir_document_reference_id": "card-example-001",
82
+ "fhir_patient_id": "patient-example-001",
83
+ "openloop_best_match": null,
84
+ "openloop_insurance_error": null,
85
+ "openloop_insurance_status": null,
86
+ "patient_id": "patient-example-001"
87
+ }
88
+ ```
89
+
90
+ ### 201 — Coverage saved without an Athena/OpenLoop mirror
91
+
92
+ ```json
93
+ {
94
+ "athena_best_match": null,
95
+ "athena_insurance_card_status": null,
96
+ "athena_insurance_error": null,
97
+ "athena_insurance_status": null,
98
+ "coverages_created": 1,
99
+ "fhir_document_reference_id": null,
100
+ "fhir_patient_id": "patient-example-001",
101
+ "openloop_best_match": null,
102
+ "openloop_insurance_error": null,
103
+ "openloop_insurance_status": null,
104
+ "patient_id": "patient-example-001"
82
105
  }
83
106
  ```
84
107
 
@@ -89,14 +112,15 @@ Request model: [`AddInsuranceRequest`](../models/AddInsuranceRequest.md)
89
112
  | `400` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | Bad request — required fields missing or FHIR rejected the coverage |
90
113
  | `401` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | Authorization required — missing, invalid, expired, or non-patient Bearer JWT |
91
114
  | `404` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | The authenticated patient has no FHIR Patient record |
115
+ | `422` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | No usable payer ID was supplied or resolved; no Coverage is written |
92
116
 
93
117
  ## Error examples
94
118
 
95
- ### 400 — Required insurance fields are missing
119
+ ### 400 — Member ID missing after payer resolution succeeded
96
120
 
97
121
  ```json
98
122
  {
99
- "error": "'payer_name'"
123
+ "error": "'member_id'"
100
124
  }
101
125
  ```
102
126
 
@@ -116,6 +140,14 @@ Request model: [`AddInsuranceRequest`](../models/AddInsuranceRequest.md)
116
140
  }
117
141
  ```
118
142
 
143
+ ### 422 — Provide a payer ID or a recognizable payer name
144
+
145
+ ```json
146
+ {
147
+ "error": "An insurance payer id is required: send the PayerID returned by /assistant/ocr-insurance, a payer_id as printed on the card, or a payer_name that matches a Stedi payer."
148
+ }
149
+ ```
150
+
119
151
  ## NodeJS / TypeScript implementation
120
152
 
121
153
  ```ts
@@ -0,0 +1,152 @@
1
+ # Apply a keyed patient flag patch
2
+
3
+ Operation ID: `patient.applyPatientFlagsOperation`
4
+
5
+ Commits the exact approved boolean patch and its receipt atomically. Repeating a key returns the original patch without reapplying it. Tenant and patient come only from the verified patient login. On an unknown outcome, look up the original key before proceeding.
6
+
7
+ ## Public method
8
+
9
+ `applyPatientFlagsOperation`
10
+
11
+ Signature: `patient.applyPatientFlagsOperation(request)`
12
+
13
+ Return type: `Promise<FlagOperationReceipt>`
14
+
15
+ ## Authentication
16
+
17
+ Classification: **AUTHENTICATED**
18
+
19
+ Schemes: `bearerAuth`
20
+
21
+ ## Prerequisites
22
+
23
+ None documented.
24
+
25
+ ## HTTP
26
+
27
+ `POST /patients/flags/operations`
28
+
29
+ ## Path parameters
30
+
31
+ None.
32
+
33
+ ## Query parameters
34
+
35
+ None.
36
+
37
+ ## Body parameters
38
+
39
+ | Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
40
+ |---|---|---:|---|---|---|---:|---|
41
+ | `body` | [`ApplyPatientFlagsRequest`](../models/ApplyPatientFlagsRequest.md) | Yes | | | | No | |
42
+
43
+ Request model: [`ApplyPatientFlagsRequest`](../models/ApplyPatientFlagsRequest.md)
44
+
45
+ ## Request example
46
+
47
+ None declared in canonical OpenAPI.
48
+
49
+ ## Success responses
50
+
51
+ | Status | Shape | Content type | Description |
52
+ |---|---|---|---|
53
+ | `200` | [`FlagOperationReceipt`](../models/FlagOperationReceipt.md) | application/json | Original committed flag patch, correlated to the operation key |
54
+
55
+ ## Success response examples
56
+
57
+ None declared in canonical OpenAPI.
58
+
59
+ ## Common errors
60
+
61
+ | Status | Shape | Content type | Description |
62
+ |---|---|---|---|
63
+ | `401` | [`FlagOperationError`](../models/FlagOperationError.md) | application/json | Patient login required |
64
+ | `403` | [`FlagOperationError`](../models/FlagOperationError.md) | application/json | Verified tenant required |
65
+ | `404` | [`FlagOperationError`](../models/FlagOperationError.md) | application/json | Patient or receipt not found; a missing receipt does not prove failure |
66
+ | `409` | [`FlagOperationError`](../models/FlagOperationError.md) | application/json | Key reused for different content, or transaction rejected by version contention |
67
+ | `422` | [`FlagOperationError`](../models/FlagOperationError.md) | application/json | Invalid operation key or flag patch |
68
+ | `503` | [`FlagOperationError`](../models/FlagOperationError.md) | application/json | Storage unavailable or outcome unknown; reconcile the original key |
69
+
70
+ ## Error examples
71
+
72
+ ### 401
73
+
74
+ ```json
75
+ {
76
+ "error": "string"
77
+ }
78
+ ```
79
+
80
+ ### 403
81
+
82
+ ```json
83
+ {
84
+ "error": "string"
85
+ }
86
+ ```
87
+
88
+ ### 404
89
+
90
+ ```json
91
+ {
92
+ "error": "string"
93
+ }
94
+ ```
95
+
96
+ ### 409
97
+
98
+ ```json
99
+ {
100
+ "error": "string"
101
+ }
102
+ ```
103
+
104
+ ### 422
105
+
106
+ ```json
107
+ {
108
+ "error": "string"
109
+ }
110
+ ```
111
+
112
+ ### 503
113
+
114
+ ```json
115
+ {
116
+ "error": "string"
117
+ }
118
+ ```
119
+
120
+ ## NodeJS / TypeScript implementation
121
+
122
+ ```ts
123
+ import { HCSDK } from "@healthcloudai/hc-sdk";
124
+ ```
125
+
126
+ ```ts
127
+ const request = "<REQUEST>";
128
+
129
+ const result = await patient.applyPatientFlagsOperation(request);
130
+ ```
131
+
132
+ ## cURL
133
+
134
+ ```bash
135
+ curl -X POST \
136
+ -H 'Authorization: Bearer <ACCESS_TOKEN>' \
137
+ -H 'Content-Type: application/json' \
138
+ -d '<REQUEST_BODY_JSON>' \
139
+ 'https://dev-api-patient.health.cloud/patients/flags/operations'
140
+ ```
141
+
142
+ ## Notes
143
+
144
+ None.
145
+
146
+ ## Prepared Test Console scenario
147
+
148
+ No canonical scenario is currently associated.
149
+
150
+ ## Real response
151
+
152
+ No approved real integration response is currently published. Unapproved candidates are never rendered as examples.
@@ -0,0 +1,112 @@
1
+ # Assign Impilo device to patient
2
+
3
+ Operation ID: `patient.assignImpiloDevice`
4
+
5
+ Order an Impilo RPM device for the authenticated patient. Accepts an `item_id` in the request body, verifies the item is orderable, and places an order through the Impilo API. The device is assigned to the patient automatically upon fulfillment. Requires a patient Bearer JWT.
6
+
7
+ ## Public method
8
+
9
+ `assignImpiloDevice`
10
+
11
+ Signature: `patient.assignImpiloDevice(itemId)`
12
+
13
+ Return type: `Promise<JsonValue>`
14
+
15
+ ## Authentication
16
+
17
+ Classification: **AUTHENTICATED**
18
+
19
+ Schemes: `bearerAuth`
20
+
21
+ ## Prerequisites
22
+
23
+ None documented.
24
+
25
+ ## HTTP
26
+
27
+ `POST /patients/vitals/deviceassign/impilo`
28
+
29
+ ## Path parameters
30
+
31
+ None.
32
+
33
+ ## Query parameters
34
+
35
+ None.
36
+
37
+ ## Body parameters
38
+
39
+ | Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
40
+ |---|---|---:|---|---|---|---:|---|
41
+ | `body` | [`AssignImpiloDeviceRequest`](../models/AssignImpiloDeviceRequest.md) | No | | | | No | |
42
+
43
+ Request model: [`AssignImpiloDeviceRequest`](../models/AssignImpiloDeviceRequest.md)
44
+
45
+ ## Request example
46
+
47
+ ```json
48
+ {
49
+ "item_id": 1
50
+ }
51
+ ```
52
+
53
+ ## Success responses
54
+
55
+ | Status | Shape | Content type | Description |
56
+ |---|---|---|---|
57
+ | `200` | [`AssignImpiloDeviceResponse`](../models/AssignImpiloDeviceResponse.md) | application/json | Impilo device assignment result |
58
+
59
+ ## Success response examples
60
+
61
+ ### 200
62
+
63
+ ```json
64
+ {
65
+ "device_id": 1,
66
+ "item_name": "Blood Pressure Monitor",
67
+ "message": "Order 1 placed — device will be assigned on fulfillment",
68
+ "status": "ok"
69
+ }
70
+ ```
71
+
72
+ ## Common errors
73
+
74
+ None declared in canonical OpenAPI.
75
+
76
+ ## Error examples
77
+
78
+ None declared in canonical OpenAPI.
79
+
80
+ ## NodeJS / TypeScript implementation
81
+
82
+ ```ts
83
+ import { HCSDK } from "@healthcloudai/hc-sdk";
84
+ ```
85
+
86
+ ```ts
87
+ const itemId = 1;
88
+
89
+ const result = await patient.assignImpiloDevice(itemId);
90
+ ```
91
+
92
+ ## cURL
93
+
94
+ ```bash
95
+ curl -X POST \
96
+ -H 'Authorization: Bearer <ACCESS_TOKEN>' \
97
+ -H 'Content-Type: application/json' \
98
+ -d '{"item_id":1}' \
99
+ 'https://dev-api-patient.health.cloud/patients/vitals/deviceassign/impilo'
100
+ ```
101
+
102
+ ## Notes
103
+
104
+ None.
105
+
106
+ ## Prepared Test Console scenario
107
+
108
+ No canonical scenario is currently associated.
109
+
110
+ ## Real response
111
+
112
+ No approved real integration response is currently published. Unapproved candidates are never rendered as examples.
@@ -2,7 +2,7 @@
2
2
 
3
3
  Operation ID: `patient.assistantOcrInsurance`
4
4
 
5
- Extract insurance-card fields (member id, group number, plan, RxBIN/PCN/GRP, etc.) from a photo of the card's front using a vision-capable LLM. Mirrors the request/error shape of `patient.assistantOcr`. Masked member IDs are verified against high-confidence, explicitly labelled document text; unverifiable IDs return an OCR error rather than a guessed value. No authentication is required.
5
+ Extract insurance-card fields (member id, group number, plan, RxBIN/PCN/GRP, etc.) from a photo of the card's front using a vision-capable LLM. Mirrors the request/error shape of `patient.assistantOcr`. Masked member IDs are verified against high-confidence, explicitly labelled document text; unverifiable IDs return an OCR error rather than a guessed value. No authentication is required. image must be a JPEG/JPG, PNG or WebP base64 data URI, at most 7,500,000 characters including the prefix. HTTP 200 means extraction completed, not that insurance is valid or eligible. All 11 fields are strings; unreadable/missing values are empty strings. PayerID is kept when plausibly printed, otherwise matched from InsurerName against the Stedi catalogue; failed/unconfident matching leaves PayerID empty without failing OCR. Pass PayerID as payer_id on insurance submit, or allow submit to resolve it from payer_name. Error text may vary, including model-provided explanations.
6
6
 
7
7
  ## Public method
8
8
 
@@ -52,25 +52,26 @@ Request model: [`AssistantOcrInsuranceRequest`](../models/AssistantOcrInsuranceR
52
52
 
53
53
  | Status | Shape | Content type | Description |
54
54
  |---|---|---|---|
55
- | `200` | [`AssistantOcrInsuranceResponse`](../models/AssistantOcrInsuranceResponse.md) | application/json | Extracted insurance-card fields |
55
+ | `200` | [`AssistantOcrInsuranceResponse`](../models/AssistantOcrInsuranceResponse.md) | application/json | type=ocr_result, ok=true, fields contains MemberID, GroupNumber, PlanName, InsurerName, FirstName, LastName, EffectiveDate, RxBIN, RxPCN, RxGRP and PayerID. Empty fields require review; an empty PayerID is still a successful extraction. |
56
56
 
57
57
  ## Success response examples
58
58
 
59
- ### 200
59
+ ### 200 — Extraction succeeded but no payer ID could be resolved
60
60
 
61
61
  ```json
62
62
  {
63
63
  "fields": {
64
- "EffectiveDate": "01/01/2025",
65
- "FirstName": "Test",
66
- "GroupNumber": "GRP-example-001",
67
- "InsurerName": "Example Health Plan",
68
- "LastName": "User",
64
+ "EffectiveDate": "",
65
+ "FirstName": "Jane",
66
+ "GroupNumber": "",
67
+ "InsurerName": "Unrecognized Example Carrier",
68
+ "LastName": "Doe",
69
69
  "MemberID": "MEM-example-001",
70
- "PlanName": "Example Health Plan",
71
- "RxBIN": "000000",
72
- "RxGRP": "RX-EXAMPLE",
73
- "RxPCN": "EXAMPLE"
70
+ "PayerID": "",
71
+ "PlanName": "",
72
+ "RxBIN": "",
73
+ "RxGRP": "",
74
+ "RxPCN": ""
74
75
  },
75
76
  "ok": true,
76
77
  "type": "ocr_result"
@@ -81,11 +82,41 @@ Request model: [`AssistantOcrInsuranceRequest`](../models/AssistantOcrInsuranceR
81
82
 
82
83
  | Status | Shape | Content type | Description |
83
84
  |---|---|---|---|
84
- | `400` | `object` | application/json | The image is missing, too large, not a valid data URI, or an unsupported MIME type |
85
+ | `400` | `object` | application/json | type=ocr_error, ok=false: missing/non-string image, data URI over 7,500,000 characters, invalid data URI/base64, empty decoded payload, or unsupported MIME type |
85
86
  | `422` | `object` | application/json | The LLM is not configured, the call failed, the card was not legible, or a masked member ID could not be verified |
86
87
 
87
88
  ## Error examples
88
89
 
90
+ ### 400 — The decoded image is empty
91
+
92
+ ```json
93
+ {
94
+ "error": "Image data URI decoded to an empty payload.",
95
+ "ok": false,
96
+ "type": "ocr_error"
97
+ }
98
+ ```
99
+
100
+ ### 400 — The complete data URI exceeds the size limit
101
+
102
+ ```json
103
+ {
104
+ "error": "Image is too large (7,500,001 bytes). Maximum is 7,500,000 bytes (base64-encoded data URI). Resize or compress the image and try again.",
105
+ "ok": false,
106
+ "type": "ocr_error"
107
+ }
108
+ ```
109
+
110
+ ### 400 — The encoded image is invalid
111
+
112
+ ```json
113
+ {
114
+ "error": "Image data URI contains invalid base64 encoding.",
115
+ "ok": false,
116
+ "type": "ocr_error"
117
+ }
118
+ ```
119
+
89
120
  ### 400 — The image is not a valid base64 data URI
90
121
 
91
122
  ```json
@@ -106,6 +137,26 @@ Request model: [`AssistantOcrInsuranceRequest`](../models/AssistantOcrInsuranceR
106
137
  }
107
138
  ```
108
139
 
140
+ ### 400 — Unsupported image MIME type
141
+
142
+ ```json
143
+ {
144
+ "error": "Unsupported image type 'image/gif'. Allowed: image/jpeg, image/jpg, image/png, image/webp.",
145
+ "ok": false,
146
+ "type": "ocr_error"
147
+ }
148
+ ```
149
+
150
+ ### 422 — A masked member ID could not be reliably verified
151
+
152
+ ```json
153
+ {
154
+ "error": "Could not reliably read the member ID. Please provide a clearer insurance card image.",
155
+ "ok": false,
156
+ "type": "ocr_error"
157
+ }
158
+ ```
159
+
109
160
  ### 422 — The card could not be read
110
161
 
111
162
  ```json