{ "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.\n**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**\n\nThe human friendly unique code of the Insurer who should receive this claim.\n\n*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.**\nThis is the unique code/ID with which you(The Insurer) identify the provider within your database.\n**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.\nPass 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.**\n\nAutomatically creates a new record for the enrollee if the insurance number doesn't match an existing record.\n\nFirst_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**\n**Always false for HMO / Insurer integrations**\n\nDetermines whether the claim should be created as a draft (true) or submitted to the HMO immediately (false) after successful creation.\nCreating 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**\n\nUnique identifier for the claim as is on the source system. E.g it’s ID", "type": "string" }, "auto_vet": { "description": "**Insurer / HMO integrations only.**\n\nWhen 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.**\n\nWhen 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.\n**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.\n\n**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**\n\nThe 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**\n\nThe 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.\n\nThis implements a range filtering on the claims when set to an object with keys of 'start' and 'end' bearing date values.\nSetting 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.\n\nThis implements a range filtering on the claims when set to an object with keys of 'start' and 'end' bearing date values.\nSetting 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.\n\nThis implements a range filtering on the claims when set to an object with keys of 'start' and 'end' bearing date values.\nSetting 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.\n\nThis implements a range filtering on the claims when set to an object with keys of 'start' and 'end' bearing date values.\nSetting 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.\n\nThis implements a range filtering on the claims when set to an object with keys of 'start' and 'end' bearing date values.\nSetting 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.\n\nThis implements a range filtering on the claims when set to an object with keys of 'start' and 'end' bearing date values.\nSetting 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.\nNote: 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**\n**Better used together with the 'per_page' param**\n\nThis 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**\n\nThis 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.\n\nThe 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.\n\nPARTIALLY_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.\n\nPARTIALLY_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.\n\n**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**\n\nThe 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**\n\nThe 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.\n\nThe 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.\n\nThis implements a range filtering on the PA Requests when set to an object with keys of 'start' and 'end' bearing date values.\nSetting 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.\n\nThis implements a range filtering on the PA Requests when set to an object with keys of 'start' and 'end' bearing date values.\nSetting 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.\n\nThis implements a range filtering on the PA Requests when set to an object with keys of 'start' and 'end' bearing date values.\nSetting 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.\n\nThis implements a range filtering on the PA Requests when set to an object with keys of 'start' and 'end' bearing date values.\nSetting 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**\n**Better used together with the 'per_page' param**\n\nThis 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**\n\nThis 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.\n\nSupported values include `cares`, `items`, and nested item relations like `items.tariffItem`.\nBenefit 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, null ] }, "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**\n\nThe human friendly unique code of the Insurer who should receive this PA request.\n\n*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.**\nThis is the unique code/ID with which you(The Insurer) identify the provider within your database.\n**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.\nPass 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.**\n\nAutomatically creates a new record for the enrollee if the insurance number doesn't match an existing record.\n\nfirst_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.**\nOnly HMOs can approve or reject a Pa request on creation", "type": "boolean", "default": false }, "reject_reason": { "description": "**Insurer / HMO integrations only.**\nOnly HMOs can reject a Pa request on creation and supply reason for rejection", "type": "string" } }, "type": "object" } }, "ref": { "description": "**Required for insurer / HMO integrations**\n\nUnique 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.\n\nSend 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.\n\nSend 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).\n\nSend 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\n 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.\n\n**Note:** This feature is only available to HMOs/Insurers.\n\nThe 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.\n\nThis request will only succeed when:\n- the enrollee belongs to the authenticated Insurer/HMO\n- the provider is linked to the authenticated Insurer/HMO\n- check-in is enabled for the Insurer/HMO\n- 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.\n\n**Note:** This feature is only available to HMOs/Insurers.\n\nThis 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.\n\nThe 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.\n\nSame-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.\n\nThis request will succeed when:\n- the enrollee belongs to the authenticated Insurer/HMO\n- the provider is linked to the authenticated Insurer/HMO\n- check-in is enabled for the Insurer/HMO\n- 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**\n**Better used together with the 'per_page' param**\n\nThis 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**\n\nThis 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.\n\nThe 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**\n**Better used together with the 'per_page' param**\n\nThis 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**\n\nThis 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.\n\nIf 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).\n`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": [ ] } ] }