openapi: 3.0.0 info: title: Curacel Health Developer API description: "Welcome to the Curacel Health API Reference! \nThis API is designed to streamline and enhance your health insurance processing experience.\n\nWith these API endpoints, you would be able to create health insurance claims on our platform.\n\nThese can be used by\n\n- EMR (electronic medical records) systems to submit claims to health insurers (HMOs)\n- Health insurer ERPs to push claims to Curacel for auto adjudication\n" contact: email: support@curacel.ai license: name: Curacel Terms And Agreement url: https://curacel.co/terms-and-conditions.php version: 1.0.0 servers: - url: https://api.health.curacel.co/api description: Production - url: https://api.sandbox.claims.curacel.co/api description: Sandbox paths: "/v1/auth/login": post: tags: - Auth summary: Generate a temporal access token description: Generate temporal access token using a specific user's credentials security: [] operationId: login requestBody: description: User credentials to be used for login required: true content: application/json: schema: type: object required: - email - password properties: email: description: The email of the organization user as registered in the records. type: string format: email password: description: The password of the organization user as registered in the records. type: string format: password sub_account_id: type: number description: |- The ID of the sub-account to be used for this login. This is only required when the user's organization has multiple sub-accounts. **NB: The list of available sub-accounts for a user's organization (if applicable and available) can be retrieved by making the request without this parameter (sub_account_id).** responses: '200': description: Success content: application/json: schema: oneOf: - type: object properties: sub_account_id_required: type: boolean description: This is set to true if user's organization has multiple sub-accounts that can be accessed and a sub-account ID was not given in the request body. sub_accounts: type: array description: An array of available sub-accounts for the user's organization. items: type: object properties: id: type: integer description: The ID of the organization sub-account. name: type: string description: The name of the organization sub-account. - type: object properties: token: type: string description: The access token to be used for subsequent requests. format: token '400': description: Bad request, Invalid email or password '401': description: Unauthorized, Invalid credentials specified '403': description: Forbidden Request "/v1/claims": post: tags: - Claims summary: Create a claim operationId: claims requestBody: description: Claims Information required: true content: application/json: schema: type: object required: - enrollee - encounter_date - diagnoses - items properties: hmo_code: description: |- **Required only for Provider / EMR integrations** The human friendly unique code of the Insurer who should receive this claim. *See insurer list endpoint for available Insurers* type: string hmo_id: description: The ID of the Insurer who should receive this claim. *Used when hmo_code is not supplied* type: number provider_code: description: |- **Required for Insurer / HMO integrations only.** This is the unique code/ID with which you(The Insurer) identify the provider within your database. **NB: This code must be attached to the provider on your curacel account.** type: string enrollee: description: Specifies the Enrollee / Patient for whom this claim is created properties: insurance_no: description: The insurance number of the enrollee as supplied by the HMO. This would be validated against existing insurance numbers. type: string first_name: description: The name to be saved for floating enrollee. type: string last_name: description: The name to be saved for floating enrollee. type: string is_floating: description: |- Floating enrollees are those whose insurance numbers are not yet registered with Curacel. Pass this as true when this is the case and the insurance number will no longer be validated (Avoid using this as much as possible) type: boolean default: false create_if_not_found: type: boolean description: |- **Insurer / HMO integrations only.** Automatically creates a new record for the enrollee if the insurance number doesn't match an existing record. First_name and last_name should be supplied if this is true as they would be used to create the record. default: false type: object encounter_date: description: The date of the patient’s visit to the provider. type: string format: date admission_date: description: If the patient was admitted, date admission started. type: string format: date discharge_date: description: If the patient was admitted, date of discharge. type: string format: date diagnoses: description: The collection of diagnoses that should be attached to this claim. properties: icd_codes: description: "(Recommended)If ICD10 codes are available, an array of the icd10 codes which represent the diagnoses concerned. E.g [‘b54’, ‘k27’]" type: array items: type: string names: description: Where ICD codes are not available, the names / descriptions of the diagnoses can be used as an alternative to identify them. type: array items: type: string type: object pa_code: description: Pre-authorization code for the claim. type: string items: description: Collection of all the line items that make up the claim. type: array items: properties: description: description: Description of the service rendered to the enrollee. type: string ref: description: Optional unique identifier for this claim line item on your system. When supplied, Curacel stores it as the item reference and returns it as `items[n].ref` in claim webhook and claim retrieval payloads. type: string unit_price_billed: description: Unit price of the item type: number format: double qty: description: Qty of the item. Would be automatically multiplied with unit price to derive sub_total for the item type: integer tariff_code: description: If the tariff code as agreed between the hospital and HMO is available, this can be supplied to aid precise validation of the tariff. type: string tariff_id: description: If the unique ID of the tariff on Curacel for the service is available, supply it to aid validation type: integer prior_adjudication: description: Optional prior adjudication decision for pre-adjudicated line items (available for HMOs/integrations with `hmo.prior-adjudication` feature enabled). Pre-adjudicated items skip AutoVet recommendation generation while retaining full claim context for LLM vetting. type: object properties: status: type: string enum: - APPROVED - DECLINED - ADJUSTED description: Prior decision status. source: type: string description: Source system or HMO name for the prior decision (e.g. AXA). approved_qty: type: number description: Prior approved quantity for the line item. approved_amount: type: number description: Prior approved amount for the line item. reason: type: string description: Clinical or administrative reason for the prior decision. type: object is_draft: description: |- **Applies only to Provider / EMR integrations** **Always false for HMO / Insurer integrations** Determines whether the claim should be created as a draft (true) or submitted to the HMO immediately (false) after successful creation. Creating as a draft would make it possible to review and edit the claim on the curacel platform before final submission to the HMO. type: boolean default: true ref: description: |- **Required for insurer / HMO integrations** Unique identifier for the claim as is on the source system. E.g it’s ID type: string auto_vet: description: |- **Insurer / HMO integrations only.** When true, the claim would be passed through the Curacel auto-vetting engine after successful creation. type: boolean default: false create_missing_tariffs: description: |- **Insurer / HMO integrations only.** When true, new tariffs would be automatically created for items that have no match. They would be created under the account of the provider to which the claim belongs. type: boolean default: false attachments: type: array description: |- An optional array of IDs of previously/already created attachments. **Supplied Attachments must be owned by caller's organization.** items: type: integer description: ID of an already created attachment owned/created by user organization. responses: '200': description: Success content: application/json: schema: type: object properties: id: type: integer description: The ID of the created claim. '400': description: Bad Request '401': description: Unauthenticated '403': description: Forbidden '404': description: not found get: tags: - Claims summary: Fetch a List of Claims description: Get list of Claims for Insurer or hospital operationId: listClaims parameters: - in: query name: status schema: type: string enum: - approved - pending - rejected - partially_approved description: |- The status of the claim. **Note: 'partially_approved' points to claims that have been approved but whose approved amount is less than the total amount.** - in: query name: with_fields schema: type: string description: When present, value should be comma seperated names of field the user would like returned with the response. - in: query name: is_submitted schema: type: boolean description: This parameter is applicable to Providers/Hospitals only. It filters the claims based on if they have been submitted or drafted claims. Returns all claims when absent. - in: query name: is_vetted schema: type: boolean description: This parameter is used to filter the claims based on if they have been vetted or not. - in: query name: is_synced schema: type: boolean description: This parameter is used to filter the claims based on if they have been synced with external db or not. - in: query name: insurer_id schema: type: integer description: |- **Applicable if fetching list as a provider/hospital** The ID of the Insurer that owns the created claims. - in: query name: provider_id schema: type: integer description: |- **Applicable if fetching list as an Insurer** The ID of the hospital that created the claims - in: query name: enrollee_id schema: type: integer description: The ID of the enrollee the claims were created for. - in: query name: client_id schema: type: integer description: The ID of the client linked to enrollees whose claims should be returned. - in: query name: insurance_no schema: type: string description: The insurance number of the enrollee the claims were created for. This is **only** considered when no value is provided for enrollee_id - in: query name: created_at schema: oneOf: - type: object properties: start: type: string format: date end: type: string format: date - type: string format: date description: |- Filter returned claims by the creation date. This implements a range filtering on the claims when set to an object with keys of 'start' and 'end' bearing date values. Setting it to a single date string also filters the claims with a direct comparison to the value given. - in: query name: submitted_at schema: oneOf: - type: object properties: start: type: string format: date end: type: string format: date - type: string format: date description: |- Filter returned claims by the submission date. This implements a range filtering on the claims when set to an object with keys of 'start' and 'end' bearing date values. Setting it to a single date string also filters the claims with a direct comparison to the value given. - in: query name: vetted_at schema: oneOf: - type: object properties: start: type: string format: date end: type: string format: date - type: string format: date description: |- Filter returned claims by the vetting date. This implements a range filtering on the claims when set to an object with keys of 'start' and 'end' bearing date values. Setting it to a single date string also filters the claims with a direct comparison to the value given. - in: query name: encounter_date schema: oneOf: - type: object properties: start: type: string format: date end: type: string format: date - type: string format: date description: |- Filter returned claims by the encounter date. This implements a range filtering on the claims when set to an object with keys of 'start' and 'end' bearing date values. Setting it to a single date string also filters the claims with a direct comparison to the value given. - in: query name: synced_at schema: oneOf: - type: object properties: start: type: string format: date end: type: string format: date - type: string format: date description: |- Filter returned claims by the synced date if available. This implements a range filtering on the claims when set to an object with keys of 'start' and 'end' bearing date values. Setting it to a single date string also filters the claims with a direct comparison to the value given. - in: query name: updated_at schema: oneOf: - type: object properties: start: type: string format: date end: type: string format: date - type: string format: date description: |- Filter returned claims by the last updated date. This implements a range filtering on the claims when set to an object with keys of 'start' and 'end' bearing date values. Setting it to a single date string also filters the claims with a direct comparison to the value given. - in: query name: updated_from schema: type: string format: date-time description: |- Return only claims strictly after this updated_at timestamp. Useful for incremental sync. Note: results are ordered by updated_at and limited internally to protect performance. - in: query name: page schema: type: integer description: |- **The presence of this param would return results in paginated format** **Better used together with the 'per_page' param** This is used to indicate the offset from which results are fetched in paginated format. - in: query name: per_page schema: type: integer description: |- **Better used together with the 'page' param** This is used to indicate the how many results are to be in an offset for pagination. - in: query name: for_export schema: type: boolean enum: - 1 - 0 description: Used to fetch an exported list of Claims requests in Excel format. Can be used in conjunction with other filters to achieve results. - in: query name: search schema: type: string description: |- This is used to search for claims by the key word supplied to it. The search is applied to the enrollee firstname, lastname, and insurance number as well as diagnoses icd codes and names. responses: '200': description: Success content: application/json: schema: type: object properties: page: type: integer per_page: type: integer total: type: integer data: type: array items: type: object properties: id: type: integer ref: type: string description: This is the hmo_erp_id when user is an Insurer, and provider_ref when user is a provider. pile_id: type: integer insurer: type: object description: Present only when user is a provider/hospital. properties: id: type: integer code: type: string name: type: string provider: type: object description: Present only when user is an Insurer properties: id: type: integer code: type: string name: type: string enrollee: type: object properties: id: type: integer description: This is absent if is_floating is truthy. insurance_no: type: string firstname: type: string lastname: type: string is_floating: type: boolean client: type: object nullable: true description: Present when the claim enrollee is attached to a client. properties: id: type: integer name: type: string email: type: string nullable: true phone: type: string nullable: true policy_number: type: string nullable: true hmo_id: type: integer enrollment_date: type: string format: date nullable: true encounter_date: type: string format: date created_at: type: string format: date updated_at: type: string format: date-time submitted_at: type: string format: date vetted_at: type: string format: date diagnoses: type: array items: type: object properties: id: type: integer icd_code: type: string name: type: string amount_billed: type: number format: double amount_approved: type: number format: double status: type: string description: |- Status includes: PENDING, APPROVED, PARTIALLY_APPROVED, REJECTED. PARTIALLY_APPROVED represents when total amount is not equal to the amount approved but not equal to zero(0). attachments: type: array items: type: object properties: id: type: integer title: type: string file_type: type: string filename: type: string description: This is the uploaded filename. file_url: type: string description: The file URL on Storage. thumbnail_url: type: string description: "**Images Only** Auto-generated URL that utilizes Cloudinary transformations to give a thumbnail of the image attachment, 150px by 150px dimensions." preview_url: type: string description: "**Images Only** Similar to thumbnail URL, but no width specified, only a reduced height to produce a smaller-sized image that can be suitable for previewing the attachment in a modal before the full file is downloaded." items: type: array items: type: object properties: ref: type: string description: This is the hmo_erp_id of the Insurer the claim and claim item belongs. description: type: string unit_price_billed: type: number format: double unit_price_approved: type: number format: double qty_billed: type: integer qty_approved: type: integer sub_total_billed: type: number format: double sub_total_approved: type: number format: double comments: type: array items: type: string status: type: string description: 'Status includes: PENDING, APPROVED, PARTIALLY_APPROVED, REJECTED.' benefit: "$ref": "#/components/schemas/BenefitSummary" '401': description: Unauthenticated '404': description: Not Found '422': description: Unprocessable Entity "/v1/claims/{id}": get: tags: - Claims summary: Get the details of a single claim description: Get the details of a claim for an Insurer or provider/hospital. operationId: getSingleClaim parameters: - in: path name: id required: true schema: type: number description: The id of the claim you want to get - in: query name: with_fields schema: type: string description: When present, value should be comma seperated names of field the user would like returned with the response. responses: '200': description: Success content: application/json: schema: type: object properties: id: type: integer ref: type: string description: This is the hmo_erp_id when user is an Insurer, and provider_ref when user is a provider. pile_id: type: integer insurer: type: object description: Present only when user is a provider/hospital. properties: id: type: integer code: type: string name: type: string provider: type: object description: Present only when user is an Insurer properties: id: type: integer code: type: string name: type: string enrollee: type: object properties: id: type: integer description: This is absent if is_floating is truthy. insurance_no: type: string firstname: type: string lastname: type: string is_floating: type: boolean encounter_date: type: string format: date created_at: type: string format: date updated_at: type: string format: date-time submitted_at: type: string format: date vetted_at: type: string format: date diagnoses: type: array items: type: object properties: id: type: integer icd_code: type: string name: type: string amount_billed: type: number format: double amount_approved: type: number format: double status: type: string description: |- Status includes: PENDING, APPROVED, PARTIALLY_APPROVED, REJECTED. PARTIALLY_APPROVED represents when total amount is not equal to the amount approved but not equal to zero(0). attachments: type: array items: type: object properties: id: type: integer title: type: string file_type: type: string filename: type: string description: This is the uploaded filename. file_url: type: string description: The file URL on Storage. thumbnail_url: type: string description: "**Images Only** Auto-generated URL that utilizes Cloudinary transformations to give a thumbnail of the image attachment, 150px by 150px dimensions." preview_url: type: string description: "**Images Only** Similar to thumbnail URL, but no width specified, only a reduced height to produce a smaller-sized image that can be suitable for previewing the attachment in a modal before the full file is downloaded." items: type: array items: type: object properties: ref: type: string description: This is the hmo_erp_id of the Insurer the claim and claim item belongs. description: type: string unit_price_billed: type: number format: double unit_price_approved: type: number format: double qty_billed: type: integer qty_approved: type: integer sub_total_billed: type: number format: double sub_total_approved: type: number format: double comments: type: array items: type: string status: type: string description: 'Status includes: PENDING, APPROVED, PARTIALLY_APPROVED, REJECTED.' benefit: "$ref": "#/components/schemas/BenefitSummary" '401': description: Unauthenticated '403': description: Forbidden '422': description: Unprocessable Entity "/v1/claims/{claim_id}/attachments": put: tags: - Claims summary: Link attachments to an existing Claim. description: Links created organization attachments to claims owned by the organization. operationId: linkAttachment parameters: - in: path name: claim_id description: The ID of the claim belonging to user organization. required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: type: object required: - ids properties: ids: type: array description: An array of the IDs for the Attachments to be linked to the Claim. Must be owned by your organization. items: type: integer responses: '200': description: Success content: application/json: schema: type: object properties: message: type: string attachments: type: array description: An array of ID belonging to all Attachments connected to the Claim. items: type: integer '400': description: Bad Request '401': description: Unauthenticated '403': description: Forbidden '422': description: Unprocessable Entity '500': description: Server Error "/v1/piles/{pileId}/mark-as-paid": post: summary: Mark a pile as paid description: Marks a specific pile as paid for an insurer. operationId: markPileAsPaid tags: - Piles parameters: - name: pileId in: path required: true description: The ID of the pile to be marked as paid schema: type: string requestBody: required: false content: application/json: schema: type: object properties: metadata: type: object description: Metadata containing any additional information about the payment made responses: '200': description: Pile marked as paid successfully content: application/json: schema: type: object properties: message: type: string '400': description: Bad Request content: application/json: schema: type: object properties: message: type: string '404': description: Pile not found content: application/json: schema: type: object properties: message: type: string '500': description: Internal Server Error content: application/json: schema: type: object properties: message: type: string "/v1/pa-requests": get: tags: - Pre-authorization Requests summary: List PA Requests description: Get list of Pre-authorization requests for Insurer or hospital operationId: listPa parameters: - in: query name: status schema: type: string enum: - approved - pending - rejected - partially_approved description: |- The status of the PA requests. **Note: 'partially_approved' points to PA Requests that have been approved but whose approved amount is less than the total amount.** - in: query name: enrollee_id schema: type: integer description: The ID of the enrollee the PA requests were created for - in: query name: insurance_no schema: type: string description: The insurance number of the enrollee the PA requests were created for. This is **only** considered when no value is provided for enrollee_id - in: query name: provider_id schema: type: integer description: |- **Applicable if fetching list as an Insurer** The ID of the hospital that created the PA requests - in: query name: insurer_id schema: type: integer description: |- **Applicable if fetching list as a provider/hospital** The ID of the Insurer that owns the created PA requests - in: query name: search schema: type: string description: |- This is used to search for claims by the key word supplied to it. The search is applied to the enrollee firstname, lastname, and insurance number, the PA codes, as well as diagnoses icd codes and names. - in: query name: is_handled schema: type: boolean description: This parameter is used to filter the PA Requests based on if an action has been performed on it. - in: query name: is_closed schema: type: boolean description: This parameter is used to filter the PA Requests based on if it has been either approved or rejected as the final action. - in: query name: is_synced schema: type: boolean description: This parameter is used to filter the PA Requests based on if they have been synced with external db or not. - in: query name: created_at schema: oneOf: - type: object properties: start: type: string format: date end: type: string format: date - type: string format: date description: |- Filter returned PA Requests by the creation date. This implements a range filtering on the PA Requests when set to an object with keys of 'start' and 'end' bearing date values. Setting it to a single date string also filters the PA Requests with a direct comparison to the value given. - in: query name: handled_at schema: oneOf: - type: object properties: start: type: string format: date end: type: string format: date - type: string format: date description: |- Filter returned PA Requests by the handled date. This implements a range filtering on the PA Requests when set to an object with keys of 'start' and 'end' bearing date values. Setting it to a single date string also filters the PA Requests with a direct comparison to the value given. - in: query name: closed_at schema: oneOf: - type: object properties: start: type: string format: date end: type: string format: date - type: string format: date description: |- Filter returned PA Requests by the closed date or date by which is was either approved or rejected. This implements a range filtering on the PA Requests when set to an object with keys of 'start' and 'end' bearing date values. Setting it to a single date string also filters the PA Requests with a direct comparison to the value given. - in: query name: synced_at schema: oneOf: - type: object properties: start: type: string format: date end: type: string format: date - type: string format: date description: |- Filter returned PA Requests by the synced date if available. This implements a range filtering on the PA Requests when set to an object with keys of 'start' and 'end' bearing date values. Setting it to a single date string also filters the PA Requests with a direct comparison to the value given. - in: query name: for_export schema: type: boolean enum: - 1 - 0 description: Used to fetch an exported list of PA requests in Excel format. Can be used in conjunction with other filters to achieve results. - in: query name: page schema: type: integer description: |- **The presence of this param would return results in paginated format** **Better used together with the 'per_page' param** This is used to indicate the offset from which results are fetched in paginated format. - in: query name: per_page schema: type: integer description: |- **Better used together with the 'page' param** This is used to indicate the how many results are to be in an offset for pagination. - in: query name: with schema: type: string description: |- Optional comma-separated relations to include in each PA record. Supported values include `cares`, `items`, and nested item relations like `items.tariffItem`. Benefit summaries on `cares[]` and `items[]` are returned when those relations are included. responses: '200': description: Success content: application/json: schema: type: object properties: page: type: integer per_page: type: integer total: type: integer data: type: array items: type: object properties: insurer: type: object properties: id: type: integer code: type: string name: type: string provider: type: object properties: id: type: integer code: type: string name: type: string code: type: string pr_code: type: string description: Prescription referral code (PR-XXXXX) if this PA is linked to an encounter. created_at: type: string format: date opened_at: type: string format: date closed_at: type: string format: date encounter_date: type: string format: date nullable: true description: Calendar date the patient was seen. Null when not supplied on the PA. admission_start: type: string format: date nullable: true description: Calendar date the admission started, if the PA covers an admission. Null otherwise. admission_end: type: string format: date nullable: true description: Calendar date the admission ended (discharge date), if the PA covers an admission. Null otherwise. id: type: integer enrollee: type: object properties: id: type: integer description: This is absent if is_floating is truthy. insurance_no: type: string firstname: type: string lastname: type: string is_floating: type: boolean is_approved: type: boolean enum: - true - false - rejection_reason: type: string total_amount_requested: type: number format: double cares: type: array description: Returned when `with=cares` is supplied. items: type: object properties: id: type: integer name: type: string benefit: "$ref": "#/components/schemas/BenefitSummary" items: type: array description: Returned when `with=items` is supplied. items: type: object properties: tariff_item: type: object description: Returned when the tariff relation is loaded for the item. properties: id: type: integer amount: type: number desc: type: string benefit: "$ref": "#/components/schemas/BenefitSummary" '401': description: Unauthenticated '404': description: Not Found post: tags: - Pre-authorization Requests summary: Create a Pre-authorization request operationId: Create Pa requestBody: description: Pre-authorization Information required: true content: application/json: schema: type: object required: - enrollee - diagnoses - items properties: hmo_code: description: |- **Required only for Provider / EMR integrations** The human friendly unique code of the Insurer who should receive this PA request. *See insurer list endpoint for available Insurers* type: string hmo_id: description: The ID of the Insurer who should receive this pa request. *Used when hmo_code is not supplied* type: number provider_code: description: |- **Required for Insurer / HMO integrations only.** This is the unique code/ID with which you(The Insurer) identify the provider within your database. **NB: This code must be attached to the provider on your curacel account.** type: string enrollee: description: Specifies the Enrollee / Patient for whom this pa request is created properties: insurance_no: description: The insurance number of the enrollee as supplied by the HMO. This would be validated against existing insurance numbers. type: string first_name: description: The name to be saved for floating enrollee. type: string last_name: description: The name to be saved for floating enrollee. type: string sex: description: The sex/gender to be saved for floating enrollee. type: string enum: - M - F is_floating: description: |- Floating enrollees are those whose insurance numbers are not yet registered with Curacel. Pass this as true when this is the case and the insurance number will no longer be validated (Avoid using this as much as possible) type: boolean default: false create_if_not_found: type: boolean description: |- **Insurer / HMO integrations only.** Automatically creates a new record for the enrollee if the insurance number doesn't match an existing record. first_name, last_name and sex should be supplied if this is true as they would be used to create the record. default: false type: object diagnoses: description: The collection of diagnoses that should be attached to this PA request. properties: icd_codes: description: "(Recommended)If ICD10 codes are available, an array of the icd10 codes which represent the diagnoses concerned. E.g [‘b54’, ‘k27’]" type: array items: type: string names: description: Where ICD codes are not available, the names / descriptions of the diagnoses can be used as an alternative to identify them. type: array items: type: string type: object items: description: Collection of all the line items that make up the pa request. type: array items: properties: description: description: Description of the service rendered to the enrollee. type: string unit_price_billed: description: Unit price of the item type: number format: double qty: description: Qty of the item. Would be automatically multiplied with unit price to derive sub_total for the item type: integer tariff_code: description: If the tariff code as agreed between the hospital and HMO is available, this can be supplied to aid precise validation of the tariff. type: string tariff_id: description: If the unique ID of the tariff on Curacel for the service is available, supply it to aid validation type: integer is_approved: description: |- **Insurer / HMO integrations only.** Only HMOs can approve or reject a Pa request on creation type: boolean default: false reject_reason: description: |- **Insurer / HMO integrations only.** Only HMOs can reject a Pa request on creation and supply reason for rejection type: string type: object ref: description: |- **Required for insurer / HMO integrations** Unique identifier for the pa request as is on the source system. E.g it’s ID type: string encounter_date: description: |- (Optional) Calendar date on which the patient was seen. Send as `YYYY-MM-DD`. Must not be in the future. When the patient was admitted, this value must also fall within `[admission_start, admission_end]`. type: string format: date nullable: true admission_start: description: |- (Optional) If the patient was admitted, the calendar date the admission started. Send as `YYYY-MM-DD`. Must not be in the future. type: string format: date nullable: true admission_end: description: |- (Optional) If the patient was admitted, the calendar date the admission ended (discharge date). Send as `YYYY-MM-DD`. Must not be in the future and must be on or after `admission_start` when both are supplied. type: string format: date nullable: true responses: '201': description: Success content: application/json: schema: type: object properties: message: type: string description: The success message data: type: object description: Created pre-authorization information properties: id: type: integer description: The ID of the created pre-authorization request. ref: type: string description: Unique identifier for the pre-authorization request as is on the source system. E.g it’s ID '400': description: Bad Request '401': description: Unauthenticated '403': description: Forbidden '404': description: not found "/v1/pa-requests/{id}": get: tags: - Pre-authorization Requests summary: Get PA Request Details description: Fetch detailed information about a specific pre-authorization request operationId: getPaRequestDetail parameters: - in: path name: id required: true schema: type: integer description: The ID of the PA request to retrieve - in: query name: for_claim schema: type: boolean description: When true, includes tariff items, diagnoses, and care details - in: query name: for_edit schema: type: boolean description: When true, includes HMO, enrollee, items, and diagnoses details - in: query name: activity_export schema: type: boolean description: When true, returns activities data for export - in: query name: pa_management_permission schema: type: boolean description: When true, initializes PA request chat - in: query name: for_auto_vet schema: type: boolean description: When true, includes auto-vet recommendation data and additional relations responses: '200': description: Success content: application/json: schema: type: object properties: id: type: integer code: type: string pr_code: type: string description: Prescription referral code (PR-XXXXX) if this PA is linked to an encounter. pa_code_with_submitted_claims: type: boolean encounter_date: type: string format: date nullable: true description: Calendar date the patient was seen. Null when not supplied on the PA. admission_start: type: string format: date nullable: true description: Calendar date the admission started, if the PA covers an admission. Null otherwise. admission_end: type: string format: date nullable: true description: Calendar date the admission ended (discharge date), if the PA covers an admission. Null otherwise. provider: type: object properties: id: type: integer name: type: string hmo: type: object properties: id: type: integer name: type: string enrollee: type: object properties: id: type: integer firstname: type: string lastname: type: string insurance_no: type: string hmo_plan: type: object properties: id: type: integer name: type: string diagnoses: type: array items: type: object properties: id: type: integer icd_code: type: string name: type: string cares: type: array items: type: object properties: id: type: integer name: type: string benefit: "$ref": "#/components/schemas/BenefitSummary" items: type: array items: type: object properties: tariff_item: type: object properties: id: type: integer amount: type: number desc: type: string benefit: "$ref": "#/components/schemas/BenefitSummary" auto_vet_recommendation: type: object description: Only visible when for_auto_vet is true activities: type: array items: type: object description: Activity log entries for the PA request '403': description: Forbidden - User does not have permission to view this PA request '404': description: PA Request not found "/v1/enrollees": post: tags: - Enrollees summary: Create/Update An Enrollee description: Create or Update A Single Enrollee. **Note:** This feature is only available to HMOs/Insurers. operationId: create_enrollee requestBody: required: true content: application/json: schema: required: - insurance_no - firstname - lastname - status type: object properties: insurance_no: type: string description: |- The insurance number of the enrollee. This must be a unique value. alternate_insurance_no: type: string description: An alternate insurance number for the enrollee. firstname: type: string description: The first name of the enrollee. lastname: type: string description: The last name of the enrollee. phone: type: string description: The phone number of the enrollee. email: type: string description: The email address of the enrollee. format: email sex: type: string description: The gender of the enrollee. address: type: string description: The address of the enrollee. birthdate: type: string description: The birthdate of the enrollee. format: date status: type: string description: 'The status of the enrollee. The code is what is expected. Possible values are: AA (ACTIVE), IA (IN-ACTIVE), SX (SUSPENDED), XX (TERMINATED), PP (PENDING), WP (WAITING PERIOD).' enum: - AA - IA - SX - XX - PP - WP parent_insurance_no: type: string description: The insurance number of the principal enrollee if the enrollee is a dependant. parent_relationship: type: string description: The relationship between the enrollee and the principal enrollee. photo_base64_string: type: string description: A base64 encoded image string. plan: description: The Insurance plan for the enrollee. type: object properties: id: type: integer description: The Id as exists on curacel, ignore if you don't have it. code: type: string description: The unique identifier of this plan on your Insurer ERP. Required if 'name' is absent. name: type: string description: Name of the plan. Required if 'code' is absent. create_if_not_found: type: boolean description: Create the plan record if it doesn't exist. Code and name must be supplied if true. client_id: type: integer description: The id of the HMO client. primary_provider_id: type: integer description: The id of the primary provider. primary_provider_code: type: string description: The code of the primary provider. middle_name: type: string description: The middle name of the enrollee. staff_number: type: string description: The staff number of the enrollee. parent: description: The principal enrollee to which a dependant is attached. type: object properties: id: type: integer description: The id of the principal enrollee. Either this id or principal's insurance no is required to create a dependant enrollee. insurance_no: type: string description: The insurance number of the principal enrollee. This must be a unique value. Either this or principal ID is required to create a dependant enrollee. parameters: - in: query name: update_if_exists description: If true, update an existing enrollee with the same insurance number. If false, return a duplicate validation message. required: false schema: type: boolean responses: '201': description: Success content: application/json: schema: properties: enrollee_id: type: integer type: object '400': description: Bad Request '401': description: Unauthenticated '403': description: Forbidden '422': description: Unprocessable Entity '500': description: Server Error "/v1/enrollees/{enrollee_id}/facial-verification-url": post: tags: - Enrollees summary: Generate Facial Verification URL description: |- Generate and return a short-lived facial verification launch URL for an enrollee. **Note:** This feature is only available to HMOs/Insurers. The returned `qr_url` keeps the existing implementation shape and may be opened directly in a browser or in-app webview by the calling HMO application to initiate the hosted facial verification check-in flow. This request will only succeed when: - the enrollee belongs to the authenticated Insurer/HMO - the provider is linked to the authenticated Insurer/HMO - check-in is enabled for the Insurer/HMO - QR verification is enabled for the Insurer/HMO operationId: generate_facial_verification_url parameters: - name: enrollee_id in: path required: true description: The ID of the enrollee for whom the facial verification URL should be generated. schema: type: integer format: int64 requestBody: required: true content: application/json: schema: type: object required: - provider_id properties: provider_id: type: integer description: The ID of the provider context to associate with the facial verification flow. The provider must be linked to the authenticated Insurer/HMO. expiry_in_minutes: type: integer description: Optional number of minutes before the generated URL expires. Defaults to 10 minutes when omitted. minimum: 1 responses: '200': description: Success content: application/json: schema: type: object properties: qr_url: type: string description: The generated facial verification URL. It keeps the existing implementation format, including the query parameters `token`, `expires`, and `provider`. '400': description: Bad Request (for example, check-in is not enabled for the Insurer/HMO) '401': description: Unauthenticated '403': description: Forbidden (for example, provider not linked to Insurer/HMO or QR verification feature not enabled) '404': description: Not Found (for example, enrollee not found within the authenticated Insurer/HMO scope) '422': description: Unprocessable Entity "/v1/enrollees/{enrollee_id}/override-check-ins": post: tags: - Enrollees summary: Create Override Check-In description: |- Confirm an HMO-verified check-in for an enrollee at a provider. **Note:** This feature is only available to HMOs/Insurers. This endpoint is the HMO's own check-in method. Calling it asserts that the HMO has independently confirmed or verified the enrollee through their own channels and is recording that confirmation as a valid check-in for the enrollee at the specified provider. The resulting check-in is recorded with `auth_type = Override`, alongside the other verification methods (OTP, facial recognition, fingerprint). Receiving this request is the HMO's confirmation; no further approval step is required. The `reason` field captures the HMO's verification context for audit. Same-day idempotency: if a check-in already exists for the `(enrollee, provider, today)`, the existing check-in is returned with HTTP `200` and no new records are created. This request will succeed when: - the enrollee belongs to the authenticated Insurer/HMO - the provider is linked to the authenticated Insurer/HMO - check-in is enabled for the Insurer/HMO - the HMO check-in API feature is enabled for the Insurer/HMO operationId: create_override_check_in parameters: - name: enrollee_id in: path required: true description: The ID of the enrollee the override check-in is for. schema: type: integer format: int64 requestBody: required: true content: application/json: schema: type: object required: - provider_id - reason properties: provider_id: type: integer description: The ID of the provider the check-in is being recorded against. The provider must be linked to the authenticated Insurer/HMO. reason: type: string maxLength: 500 description: Free-text context describing how the HMO verified the enrollee (for example, the verification method used, a reference number, or the staff member that confirmed). Stored on the override record for audit. responses: '201': description: The HMO-confirmed check-in was recorded. content: application/json: schema: type: object properties: data: type: object properties: check_in_id: type: integer override_request_id: type: integer enrollee_id: type: integer provider_id: type: integer auth_type: type: string confirmed_at: type: string format: date-time '200': description: An existing same-day check-in was returned. No new records were created. content: application/json: schema: type: object properties: data: type: object properties: check_in_id: type: integer override_request_id: type: integer nullable: true enrollee_id: type: integer provider_id: type: integer auth_type: type: string confirmed_at: type: string format: date-time '400': description: Bad Request (for example, check-in is not enabled for the Insurer/HMO) '401': description: Unauthenticated '403': description: Forbidden (for example, the HMO check-in API feature is not enabled for the Insurer/HMO) '404': description: Not Found (for example, enrollee not found within the authenticated Insurer/HMO scope) '422': description: Unprocessable Entity (for example, missing or invalid `provider_id` or `reason`) '429': description: Too Many Requests "/v1/enrollees/single-enrollee": get: tags: - Enrollees summary: Fetch Enrollee Details description: Fetch details of a single enrollee using its id or insurance_no operationId: fetch_single_enrollee parameters: - in: query name: id schema: type: integer description: The id of the enrollee. it is required if the insurance_no is not supplied - in: query name: insurance_no schema: type: string description: The insurance number of the enrollee. it is required if the id is not supplied - in: query name: include_dependants schema: type: boolean description: An optional boolean value to indicate if the dependants of the enrollee should be included in the response. Defaults to false responses: '200': description: Success content: application/json: schema: type: object properties: message: description: Information on response type: string data: description: Information on the enrollee requested type: object properties: id: type: integer description: This is the ID of the enrollee. insurance_no: type: string firstname: type: string lastname: type: string middlename: type: string sex: type: string parent_insurance_no: type: string status: type: string email: type: string phone: type: string plan: type: object description: Enrollees current plan properties: id: type: integer name: type: string company: type: object description: Enrollees company properties: id: type: integer name: type: string valid_until: type: string photo: type: object description: Enrollees profile image properties: preview_url: type: string description: A thumbnail rendering of enrollee photo full_url: type: string description: Enrollee full image primary_provider: type: object description: Enrollees primary provider properties: code: type: string description: Code used to identify the provider for your Insurer id: type: integer name: type: string insurer: type: object description: Enrollees HMO properties: code: type: string description: Code used to identify the Insurer for your provider id: type: integer name: type: string '400': description: Bad Request '401': description: Unauthenticated '403': description: Forbidden '422': description: Unprocessable Entity '500': description: Server Error "/v1/enrollees/single-enrollee/benefits": get: tags: - Enrollees summary: Fetch Enrollee Benefits description: Fetch the plan benefits of a single enrollee operationId: fetchEnrolleeBenefits parameters: - in: query name: id schema: type: integer description: The ID of the enrollee. It is required if the insurance_no is not supplied - in: query name: insurance_no schema: type: string description: The insurance number of the enrollee. It is required if the id is not supplied - in: query name: page schema: type: integer description: |- **The presence of this param would return results in paginated format** **Better used together with the 'per_page' param** This is used to indicate the offset from which results are fetched in paginated format. - in: query name: per_page schema: type: integer description: |- **Better used together with the 'page' param** This is used to indicate the how many results are to be in an offset for pagination. - in: query name: search schema: type: string description: |- This is used to search for benefits attached to enrollee's plan by the key word supplied to it. The search is applied to the benefit's name. responses: '200': description: Success content: application/json: schema: type: object properties: data: description: A paginated array of benefits attached to the enrollee's plan. type: array items: type: object description: Enrollee's Plan benefit properties: id: type: integer type: type: string name: type: string limit_type: type: string limit_value: type: number '400': description: Bad Request '401': description: Unauthenticated '403': description: Forbidden '422': description: Unprocessable Entity '500': description: Server Error "/v1/enrollees/single-enrollee/utilization": get: tags: - Enrollees summary: Sum Of An enrollees Utilization over a period description: Fetch details of a single enrollee utiization using it's id or insurance_no and a period range. operationId: fetch_enrollee_utilization parameters: - in: query name: enrollee_id schema: type: integer description: The id of the enrollee. it is required if the insurance_no is not supplied - in: query name: insurance_no schema: type: string description: The insurance number of the enrollee. it is required if the id is not supplied - in: query name: start_date schema: type: string description: 2023-06-28| This is required and indicates what date to start the summation from and beginning of a range period. - in: query name: end_date schema: type: string description: 2024-10-28| This is required and indicates what date to end the summation from and end of a range period. responses: '200': description: Success content: application/json: schema: type: object properties: message: description: Information on response type: string data: description: Result of request type: array properties: amount: type: integer '401': description: Unauthenticated '403': description: Forbidden '404': description: Not Found "/v1/enrollees/{id}/change-status": put: tags: - Enrollees summary: Change Enrollee Status description: Change the status of an enrollee. **Note:** This feature is only available to HMOs/Insurers. operationId: update_enrollee parameters: - name: id in: path description: Enrollee ID required: true schema: type: integer format: int64 requestBody: required: true content: application/json: schema: required: - status properties: status: type: string description: 'The new status of the enrollee. The code is what is expected. Possible values are: AA (ACTIVE), IA (IN-ACTIVE), SX (SUSPENDED), XX (TERMINATED), PP (PENDING), WP (WAITING PERIOD).' enum: - AA - IA - SX - XX - PP - WP effective_from: type: string description: The date when the new status should take effect. If null, the new status takes effect immediately." format: date responses: '200': description: Success content: application/json: schema: properties: enrollee_id: type: integer '401': description: Unauthenticated '403': description: Forbidden '422': description: Unprocessable Entity "/v1/attachments": post: tags: - Attachments summary: Create an Attachment operationId: createAttachment requestBody: description: Attachment data to be used for creation required: true content: multipart/form-data: schema: type: object required: - file properties: title: type: string description: The title or name of the file. file: type: string format: binary description: The file upload to be stored as an attachment. responses: '201': description: Success content: application/json: schema: type: object properties: id: type: integer title: type: string file_type: type: string filename: type: string description: This is the uploaded filename. file_url: type: string description: The file URL on Storage. thumbnail_url: type: string description: "**Images Only** Auto-generated URL that utilizes Cloudinary transformations to give a thumbnail of the image attachment, 150px by 150px dimensions." preview_url: type: string description: "**Images Only** Similar to thumbnail URL, but no width specified, only a reduced height to produce a smaller-sized image that can be suitable for previewing the attachment in a modal before the full file is downloaded." '400': description: Bad Request '401': description: Unauthenticated '403': description: Forbidden '422': description: Unprocessable Entity '500': description: Server Error "/v1/attachments/{id}": delete: tags: - Attachments summary: Delete an Attachment operationId: deleteAttachment parameters: - in: path name: id required: true description: The ID of any of your Attachments you wish to delete. schema: type: number - in: query name: force description: Indicates if Attachment should be deleted irrespective of it being attached to another entity. schema: type: boolean default: false responses: '200': description: Success content: application/json: {} '400': description: Bad Request '401': description: Unauthenticated '403': description: Forbidden '422': description: Unprocessable Entity "/v1/clients": get: tags: - Insurer Clients summary: List All Active Insurer Clients description: Get list of active insurer clients. **Note:** This feature is only available to HMOs/Insurers. operationId: get_clients parameters: - in: query name: page schema: type: integer description: |- **The presence of this param would return results in paginated format** **Better used together with the 'per_page' param** This is used to indicate the offset from which results are fetched in paginated format. - in: query name: per_page schema: type: integer description: |- **Better used together with the 'page' param** This is used to indicate the how many results are to be in an offset for pagination. responses: '200': description: Success content: application/json: schema: type: array items: type: object properties: id: type: integer description: The client ID. name: type: string description: The client name. address: type: string nullable: true description: The client address. phone: type: string nullable: true description: The client phone number. email: type: string description: The client email address. is_active: type: integer description: The client active status (1 for active). '400': description: Bad Request '401': description: Unauthenticated '403': description: Forbidden '404': description: Not Found post: tags: - Insurer Clients summary: Add an Insurer Client operationId: create_client requestBody: required: true content: application/json: schema: required: - name - email - status - hmo_plan_ids type: object properties: name: type: string description: The name of the Client. phone: type: string description: The phone number of the Client. email: type: string description: The email address of the Client. address: type: string description: The address of the Client. city: type: string description: The city of the Client. selected_lga_id: type: integer description: The ID of the Local Government Area of the Client. selected_state_id: type: integer description: The ID of the State of the Client. selected_country_id: type: integer description: The ID of the Country of the Client. status: type: string description: 'The status of the Client. Possible values are: active, inactive, terminated.' enum: - active - inactive - terminated client_code: type: string description: Client code for the insurer client record. id_from_hmo: type: string description: Optional insurer-provided reference ID for the client. hmo_plan_ids: type: array description: This is an array HMO/Insurer Plan IDs associated with the Client. items: type: integer registration_date: type: string description: The date of registration of the Client, in the format YYYY-MM-DD. other_business_type: type: string description: The relationship between the enrollee and the principal enrollee. other_business_sector: type: string description: A base64 encoded image string. generate_credentials: type: boolean description: If true, a new user account would also be created for the with a temporary password. Credentials would be forwarded in a mail notification. responses: '201': description: Success Message '400': description: Bad Request '401': description: Unauthenticated '403': description: Forbidden '422': description: Unprocessable Entity "/v1/clients/enrollees/attach": post: tags: - Insurer Clients summary: Attach Enrollees to an Insurer Client operationId: attach_enrollees requestBody: required: true content: application/json: schema: required: - client_id - enrollee_id type: object properties: client_id: type: integer description: The ID of the Insurer Client to attach the enrollees to. enrollee_id: type: array description: The ID(s) of the Enrollees to attach to the Insurer Client. Accepts an integer for a single enrollee, and an array for bulk enrollees. For example 1 (integer - for single enrollee), [1, 2, 3] (array - for bulk enrollees). items: type: integer responses: '200': description: Success Message '400': description: Bad Request '401': description: Unauthenticated '403': description: Forbidden '422': description: Unprocessable Entity "/v1/hmos": get: tags: - Insurers summary: List all insurers. description: Get a list of insurers attached to the current organization. **Note:** This feature is only available to Healthcare Providers/EMRs. operationId: list-of-insurers responses: '200': description: Success content: application/json: {} '401': description: Unauthenticated '404': description: Not found "/v1/encounters": get: tags: - Encounters summary: List encounters description: Fetch a paginated list of encounters for the authenticated Insurer/HMO. operationId: list-encounters parameters: - in: query name: enrollee_id schema: type: integer description: Filter encounters by enrollee ID. - in: query name: status schema: type: string enum: - all - active - completed - declined description: Filter encounters by status. Use `all` to disable status filtering. - in: query name: start_date schema: type: string format: date description: Filter encounters from this encounter_date (inclusive). - in: query name: end_date schema: type: string format: date description: Filter encounters up to this encounter_date (inclusive). Must be after or equal to start_date. - in: query name: date_range schema: type: string enum: - all - 7days - 30days - custom description: Shortcut for date filtering. Use `custom` together with start_date/end_date. - in: query name: search schema: type: string description: Search term (e.g., PR code, enrollee fields, provider name depending on server-side implementation). - in: query name: page schema: type: integer description: Page number (pagination). - in: query name: per_page schema: type: integer description: Number of records per page (pagination). responses: '200': description: Success content: application/json: schema: type: object properties: current_page: type: integer per_page: type: integer total: type: integer data: type: array items: type: object properties: id: type: integer req_id: type: string hmo_id: type: integer provider_id: type: integer enrollee_id: type: integer encounter_date: type: string format: date status: type: string prescriptions_count: type: integer enrollee: type: object properties: id: type: integer firstname: type: string lastname: type: string insurance_no: type: string provider: type: object properties: id: type: integer name: type: string hmo: type: object properties: id: type: integer name: type: string prescriptions: type: array description: Present only for prescriptions that have been dispensed (fully or partially), included to support "Dispensed by" display. items: type: object properties: id: type: integer status: type: string dispensed_by: type: integer nullable: true dispensed_by_user: type: object nullable: true properties: id: type: integer provider: type: object nullable: true properties: id: type: integer name: type: string '401': description: Unauthenticated '403': description: Forbidden (feature not enabled for this Insurer/HMO) '404': description: Not found "/v1/encounters/{id}": get: tags: - Encounters summary: Get encounter detail description: |- Fetch encounter detail by numeric ID or PR reference. If the value is not numeric and does not start with `PR-`, the server will prepend `PR-` automatically. operationId: get-encounter-detail parameters: - name: id in: path required: true description: Encounter numeric ID or PR reference (e.g. `123` or `PR-ABCDE` or `ABCDE`). schema: type: string responses: '200': description: Success content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: id: type: integer req_id: type: string hmo_id: type: integer provider_id: type: integer enrollee_id: type: integer encounter_date: type: string format: date status: type: string enrollee: type: object properties: id: type: integer firstname: type: string lastname: type: string insurance_no: type: string sex: type: string nullable: true birthdate: type: string format: date nullable: true age: type: integer nullable: true provider: type: object properties: id: type: integer name: type: string hmo: type: object properties: id: type: integer name: type: string currency: type: string prescriptions: type: array items: type: object properties: id: type: integer name: type: string quantity: type: number format: double unit_price: type: number format: double total_amount: type: number format: double approved_amount: type: number format: double nullable: true co_payment_value: type: number format: double nullable: true co_payment_amount: type: number format: double nullable: true status: type: string dispensed_by_user: type: object nullable: true properties: id: type: integer provider: type: object nullable: true properties: id: type: integer name: type: string pa_requests: type: array items: type: object properties: id: type: integer code: type: string '401': description: Unauthenticated '403': description: Forbidden (feature not enabled for this Insurer/HMO) '404': description: Not found "/v1/providers": get: summary: Get Providers operationId: get_providers description: Retrieve a list of providers available to clients. tags: - Providers security: - bearerAuth: [] parameters: - in: query name: page schema: type: integer required: true - in: query name: per_page schema: type: integer required: true responses: '200': description: A JSON array of providers content: application/json: schema: type: array items: type: object properties: id: type: integer name: type: string state: type: string email: type: string phone: type: string address: type: string "/v1/providers/{id}": get: summary: Get Provider Details operationId: get_provider_details description: Retrieve detailed information about a single provider. tags: - Providers security: - bearerAuth: [] parameters: - name: id in: path required: true description: The provider ID. schema: type: integer responses: '200': description: A single provider object content: application/json: schema: type: object properties: id: type: integer name: type: string email: type: string phone: type: string address: type: string state: type: string category: type: object properties: id: type: integer name: type: string "/v1/plans": post: summary: Create Insurer Plan operationId: create_insurer_plan description: Create a new insurer plan in the authenticated user's organization. tags: - Insurer Plans security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: type: string description: Freeform description of the plan. color: type: string description: Optional UI color tag (e.g. "#2E86AB"). id_from_hmo: type: string description: External identifier/code for the plan in the HMO’s ERP. price: type: number format: double description: Commercial price/premium of the plan. has_all_providers: type: boolean description: If true, plan is available to all providers. parent_id: type: integer description: Parent plan id. Must belong to the authenticated HMO. tariff_band_id: type: integer description: Default tariff band id. Must belong to the authenticated HMO. meta: type: object description: Arbitrary JSON metadata for extensibility. dependant_limit: type: integer minimum: 0 description: Maximum number of dependants covered by this plan. cover_dependants: type: boolean description: Requires HMO feature access. If provided without dependant_limit, defaults to 1 when true and 0 when false. amount_limit: type: number format: double minimum: 0 description: Plan-level total amount limit/cap. co_payment_value: type: number format: double minimum: 0 description: Copayment value (amount or percent based on product rules). vat_value: type: number format: double minimum: 0 description: VAT value (amount or percent based on product rules). responses: '200': description: Plan created successfully content: application/json: schema: type: object properties: saved: type: object description: The created plan properties: id: type: integer hmo_id: type: integer name: type: string description: type: string color: type: string id_from_hmo: type: string price: type: number format: double has_all_providers: type: boolean parent_id: type: integer nullable: true tariff_band_id: type: integer nullable: true meta: type: object dependant_limit: type: integer cover_dependants: type: boolean amount_limit: type: number format: double co_payment_value: type: number format: double vat_value: type: number format: double created_at: type: string format: date-time updated_at: type: string format: date-time message: type: string '400': description: Invalid request, name and hmo are required '401': description: Unauthenticated '500': description: Plan could not be created, contact support "/v1/plans/{planId}/benefits": get: summary: Get Plan Benefits operationId: get_plan_benefits description: Retrieve the list of benefits attached to a given plan. Supports filtering and pagination. tags: - Insurer Plans security: - bearerAuth: [] parameters: - name: planId in: path required: true schema: type: integer description: The unique ID of the HMO plan. - name: page in: query required: false schema: type: integer description: Page number for pagination. - name: per_page in: query required: false schema: type: integer description: Number of items per page. - name: search in: query required: false schema: type: string description: Keyword for searching by benefit/care name/type/group. responses: '200': description: List of plan benefits content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: integer hmo_plan_id: type: integer care_id: type: integer nullable: true care_group_id: type: integer nullable: true care_type_id: type: integer nullable: true claim_category: type: string nullable: true for_diagnoses: type: boolean name: type: string nullable: true created_at: type: string format: date-time nullable: true updated_at: type: string format: date-time nullable: true deleted_at: type: string format: date-time nullable: true limit_type: type: string limit_value: type: number waiting_period: type: integer nullable: true meta: type: object nullable: true enrollee_type: type: string nullable: true gender: type: string nullable: true enum: - M - F description: Gender restriction on the benefit. `M` or `F`. `null` means the benefit applies to all genders. The API never returns `A`. allowed_care_type_ids: type: array nullable: true items: type: integer covered: type: boolean benefit_wallets_count: type: integer care: type: object nullable: true properties: id: type: integer name: type: string care_group: type: object nullable: true care_type: type: object nullable: true plan: type: object properties: id: type: integer name: type: string cover_dependants: type: integer '401': description: Unauthenticated '404': description: Plan not found "/v1/plans/{planId}/benefits/diagnoses": post: summary: Attach diagnoses-based Plan Benefit operationId: attach_diagnoses_plan_benefit description: Attach a diagnoses-based benefit to a plan by specifying ICD code ranges and optional allowed care types. tags: - Insurer Plans security: - bearerAuth: [] parameters: - name: planId in: path required: true schema: type: integer description: The unique ID of the HMO plan. requestBody: required: true content: application/json: schema: type: object required: - name - diagnoses_icd_codes properties: name: type: string description: Name of the diagnoses-based benefit. diagnoses_icd_codes: type: array description: List of ICD codes or ranges to attach to the plan as a benefit. items: type: string allowed_care_types: type: array nullable: true description: Optional list of allowed care type IDs for this diagnoses benefit. items: type: integer responses: '200': description: Diagnoses-based benefit attached successfully content: application/json: schema: type: object properties: message: type: string '400': description: Missing or invalid parameters '401': description: Unauthenticated '404': description: Plan not found "/v1/plans/{planId}/benefits/care-group": post: summary: Attach Care Groups to Plan Benefits operationId: attach_care_group_plan_benefits description: Attach one or more care groups to a plan as benefits. tags: - Insurer Plans security: - bearerAuth: [] parameters: - name: planId in: path required: true schema: type: integer description: The unique ID of the HMO plan. requestBody: required: true content: application/json: schema: type: object required: - care_group_ids properties: care_group_ids: type: array description: List of care group IDs to attach to the plan. items: type: integer responses: '200': description: Care groups attached successfully content: application/json: schema: type: object properties: message: type: string '400': description: Invalid parameters '401': description: Unauthenticated '404': description: Plan not found "/v1/plans/{planId}/benefits/care-type": post: summary: Attach Care Type to Plan Benefits operationId: attach_care_type_plan_benefit description: Attach a care type to a plan as a benefit, optionally specifying excluded care IDs. tags: - Insurer Plans security: - bearerAuth: [] parameters: - name: planId in: path required: true schema: type: integer description: The unique ID of the HMO plan. requestBody: required: true content: application/json: schema: type: object required: - care_type_id properties: care_type_id: type: integer description: ID of the care type to attach. excluded_care_ids: type: array nullable: true description: Optional list of care item IDs to exclude from this care type benefit. items: type: integer responses: '200': description: Care type attached successfully content: application/json: schema: type: object properties: message: type: string '400': description: Invalid parameters or care IDs not under the care type '401': description: Unauthenticated '404': description: Plan not found "/v1/plans/{planId}/benefits/claim-category": post: summary: Attach Claim Category Plan Benefit operationId: attach_claim_category_plan_benefit description: Attach a claim-category based benefit to a plan with a specific category amount. tags: - Insurer Plans security: - bearerAuth: [] parameters: - name: planId in: path required: true schema: type: integer description: The unique ID of the HMO plan. requestBody: required: true content: application/json: schema: type: object required: - category_type - category_amount properties: category_type: type: string description: Claim category type (e.g., inpatient, outpatient). category_amount: type: number format: double description: Monetary amount for the claim category benefit. responses: '200': description: Claim category benefit attached successfully content: application/json: schema: type: object properties: message: type: string '400': description: Invalid claim category or amount '401': description: Unauthenticated '404': description: Plan not found "/v1/plans/{planId}/benefits/{benefitId}": put: summary: Update Plan Benefit operationId: update_plan_benefit description: Update the configuration of a specific plan benefit (limits, enrollee type, coverage, etc.). tags: - Insurer Plans security: - bearerAuth: [] parameters: - name: planId in: path required: true schema: type: integer description: The unique ID of the HMO plan. - name: benefitId in: path required: true schema: type: integer description: The unique ID of the plan benefit. requestBody: required: true content: application/json: schema: type: object properties: limit_type: type: string nullable: true description: Type of limit applied to the benefit. limit_value: type: number format: double nullable: true description: Numeric value of the limit. waiting_period: type: integer nullable: true description: Waiting period in days. enrollee_type: type: string nullable: true description: Enrollee type the benefit applies to. gender: type: string nullable: true enum: - M - F - A description: |- Gender the benefit applies to. `M` (male), `F` (female), or `A` (all genders). `A` is stored as no gender restriction. Omit this field, or send JSON null, to leave the stored value unchanged — that is not the same as all genders. Sending `A` is the only way to widen a gendered benefit back to all genders. covered: type: boolean nullable: true description: Whether the benefit is currently covered. co_payment_value: type: number format: double nullable: true description: Co-payment percentage value for the benefit. responses: '200': description: Plan benefit updated successfully content: application/json: schema: type: object properties: message: type: string data: type: array items: type: object '400': description: Validation or business rule error while updating the benefit '401': description: Unauthenticated '404': description: Plan or benefit not found delete: summary: Delete Plan Benefit operationId: delete_plan_benefit description: Delete a specific plan benefit from a plan. tags: - Insurer Plans security: - bearerAuth: [] parameters: - name: planId in: path required: true schema: type: integer description: The unique ID of the HMO plan. - name: benefitId in: path required: true schema: type: integer description: The unique ID of the plan benefit. responses: '200': description: Plan benefit deleted successfully content: application/json: schema: type: object properties: message: type: string '400': description: Unable to delete benefit '401': description: Unauthenticated '404': description: Plan or benefit not found "/v1/plans/{planId}/benefits/import": post: summary: Import Plan Benefits operationId: import_plan_benefits description: Copy all benefits from one plan into another plan owned by the same HMO. tags: - Insurer Plans security: - bearerAuth: [] parameters: - name: planId in: path required: true schema: type: integer description: The ID of the destination plan that will receive the copied benefits. requestBody: required: true content: application/json: schema: type: object required: - from_plan_id properties: from_plan_id: type: integer description: The ID of the source plan whose benefits will be copied. responses: '200': description: Benefits imported successfully content: application/json: schema: type: object properties: message: type: string '400': description: Invalid request or no new benefits to copy '401': description: Unauthenticated '404': description: Plan not found "/v1/cares/care-types/{careTypeId}/items": get: summary: List Care Items by Care Type operationId: list_care_type_items description: Retrieve a list of care items belonging to the specified care type. Supports keyword search, filtering, exclusion, and more. tags: - Cares security: - bearerAuth: [] parameters: - name: careTypeId in: path required: true schema: type: integer description: The unique ID of the care type. - name: search in: query required: false schema: type: string description: Keyword to filter care item names. - name: exclude_names in: query required: false schema: type: array items: type: string style: form explode: false description: List of care item names to exclude. Comma-separated values. - name: v in: query required: false schema: type: string description: Filter care items by `cve_version`. - name: parents_only in: query required: false schema: type: boolean description: Include only items with children. - name: only_children_of in: query required: false schema: type: integer description: Include only children of a particular care item. - name: used_in_band_ids in: query required: false schema: type: string description: Filter care items by associated tariff band IDs. Comma-separated values. responses: '200': description: Array of care items for the specified care type content: application/json: schema: type: array items: type: object properties: id: type: integer name: type: string type_id: type: integer updated_at: type: string format: date-time '404': description: Care type not found components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API KEY from your account dashboard schemas: BenefitSummary: type: object nullable: true description: Summary of the matched plan benefit for the returned care or treatment item. properties: id: type: integer description: The unique ID of the matched plan benefit. label: type: string nullable: true description: Human-readable label for the matched benefit. source_type: type: string nullable: true description: Indicates how the benefit was matched. enum: - care - care_group - care_type - diagnosis care_group: "$ref": "#/components/schemas/BenefitCareGroupSummary" BenefitCareGroupSummary: type: object nullable: true description: Care group metadata when the matched benefit comes from a care-group rule. properties: id: type: integer nullable: true name: type: string nullable: true security: - bearerAuth: []