This pages talks about the various accounts used for insurance setup, billing, and payments
Add an insurance client
This endpoint allows a provider to add a corporate at the provider portal
URL: {{base_url}}/v1/providers/b6c0cc80-c5fd-4430-805c-e3591ec9b3cf/clients
Method: POST
{
"company_name": "Baradep",
"tin_number": "782345790",
"address": "Adenta",
"admin_first_name": "Akosua",
"admin_last_name": "Amponsah",
"admin_phoneno": "+233549802569",
"admin_email": "[email protected]",
"authorizedBy": "Paa kwasi Oppong",
"organization_type": "INS"
}
{
"message": "corporate signed up successfully",
"successful": true,
"returnedData": {
"company_name": "Baradep",
"tin_number": "782345790",
"address": "Adenta",
"admin_first_name": "Akosua",
"admin_last_name": "Amponsah",
"admin_phoneno": "+233549802569",
"admin_email": "[email protected]",
"authorizedBy": "Paa kwasi Oppong",
"main_branch_id": 22,
"provider_client_account": {
"id": 19,
"uuid": "f1e1123f-03d4-4dc1-89cd-41f1364a02f8",
"created_at": "2021-09-20T12:46:29.769728Z",
"is_deleted": false,
"modified_at": "2021-09-20T12:46:29.769746Z",
"companyName": "Baradep",
"amount": "0.00",
"creditDurationInDays": null,
"creditStartDate": "2021-09-20T12:46:29.769644Z",
"state": "limited-debit-active",
"authorizedBy": "Paa kwasi Oppong",
"maximum_employees_allowed": null,
"providerId": "b6c0cc80-c5fd-4430-805c-e3591ec9b3cf",
"providerDetails": "b6c0cc80-c5fd-4430-805c-e3591ec9b3cf",
"companyId": 22,
"company": 22
}
}
}
Get all insurance clients
This endpoint allows a provider to get all corporate clients at the provider portal
URL: {{base_url}}/v1/providers/{{provider_id}}clients?organization_type=INS
Method: GET
{
"message": "corporate retrieved successfully",
"success": true,
"data": [
{
"main_branch_id": "abe50894-b288-4554-8ed4-dd1b2e38b9f1",
"uuid": "aad9c9b3-8c9f-4ba7-9058-01ee632932d5",
"created_at": "2021-09-23T10:04:54.453593Z",
"is_deleted": false,
"modified_at": "2021-09-23T10:04:54.453609Z",
"company_name": "Chris ventures Ltd",
"tin_number": null,
"address": "adenta",
"admin_first_name": "Chris",
"admin_last_name": "Dare",
"admin_email": "[email protected]",
"admin_phoneno": "233545465909",
"authorizedBy": null,
"user": 28
},],
"errors": null
Creating insurance client account
This endpoint allows a provider to create a client account for corporates created directly from the corporate portal.
URL: {{base_url}}/v1/providers/b6c0cc80-c5fd-4430-805c-e3591ec9b3cf/client-accounts
Method: POST
{
"owner":"5847a6f2-dc50-4935-b796-098aa07fa791"
}
{
"message":"Account created successfully",
"success": True,
"errors":"",
"data": {
"id":"1",
"uuid":"5847a6f2-dc50-4935-b796-098aa07fa791",
"status":"CLOSED",
"account_type":"corporate-client-account",
"managing_organization":"b6c0cc80-c5fd-4430-805c-e3591ec9b3cf",
"currency":"GHS",
"service_period_start":"2021-09-17T10:50:26.747617Z",
"service_period_end":"2021-09-17T10:50:26.747617Z",
"balance":56.00,
"limit":70.00,
"owner":"5847a6f2-dc50-4935-b796-098aa07fa791"
}
}
Get an insurance provider info
Get an insurance client
URL: v1/providers/59c9e42c-b561-419f-b042-88f3ea861b43/clients/<client_id>
Method: GET
{
"success": true,
"message": "Successfully retrieved manageable organization",
"data": {
"main_branch_id": "8a4a929e-981c-424a-98e9-042702b9ab48",
"uuid": "b6dd667d-b84a-47b0-b662-b66af5b4963a",
"created_at": "2021-09-28T14:26:32.126607Z",
"is_deleted": false,
"modified_at": "2021-09-28T14:26:32.126636Z",
"company_name": "Sheldon ltd",
"tin_number": null,
"address": "adenta",
"admin_first_name": "Akosua",
"admin_last_name": "Jackson",
"admin_email": "[email protected]",
"admin_phoneno": "2335495065299",
"authorizedBy": "[email protected]",
"user": 39
},
"errors": null
}
Get an insurance client account
This endpoint allows a provider to get client accounts by company/owner or managing organisation.
URL: {{base_url}}/v1/providers/b6c0cc80-c5fd-4430-805c-e3591ec9b3cf/client-accounts
Method: GET
Filter fields:
- status
- managing_organization
- owner
- currency
- account_type
{
"message":"Account retrieved successfully",
"success": True,
"errors":"",
"data": [{
"id":"1",
"uuid":"5847a6f2-dc50-4935-b796-098aa07fa791",
"status":"CLOSED",
"account_type":"corporate-client-account",
"managing_organization":"b6c0cc80-c5fd-4430-805c-e3591ec9b3cf",
"currency":"GHS",
"service_period_start":"2021-09-17T10:50:26.747617Z",
"service_period_end":"2021-09-17T10:50:26.747617Z",
"balance":56.00,
"limit":70.00,
"owner":"fd695ebb-5432-4e0d-9d59-5ac095638c0a"
}]
}
Verify insurance client account
This endpoint allows a provider to verify a corporate's client account
URL: {{base_url}}/v1/providers/{{provider_id}}/client-accounts/{{client_id}}/actions
Method: POST
{
"action":"VERIFY"
}
{
"message":"Company verified successfully",
"success": True,
"errors":"",
"data": {
"id":"1",
"uuid":"5847a6f2-dc50-4935-b796-098aa07fa791",
"status":"ACTIVE",
"account_type":"corporate-client-account",
"managing_organization":"b6c0cc80-c5fd-4430-805c-e3591ec9b3cf",
"currency":"GHS",
"service_period_start":"2021-09-17T10:50:26.747617Z",
"service_period_end":"2021-09-17T10:50:26.747617Z",
"balance":56.00,
"limit":70.00,
"owner":"5847a6f2-dc50-4935-b796-098aa07fa791"
}
}
Suspend insurance client account
This endpoint allows a provider to suspend a corporate's client account
URL: {{base_url}}/v1/providers/{{provider_id}}/client-accounts/{{client_id}}/actions
Method: POST
{
"action":"SUSPEND"
}
{
"message":"Company suspended successfully",
"success": True,
"errors":"",
"data": {
"id":"1",
"uuid":"5847a6f2-dc50-4935-b796-098aa07fa791",
"status":"SUSPENDED",
"account_type":"corporate-client-account",
"managing_organization":"b6c0cc80-c5fd-4430-805c-e3591ec9b3cf",
"currency":"GHS",
"service_period_start":"2021-09-17T10:50:26.747617Z",
"service_period_end":"2021-09-17T10:50:26.747617Z",
"balance":56.00,
"limit":70.00,
"owner":"5847a6f2-dc50-4935-b796-098aa07fa791"
}
}
Close insurance client account
This endpoint allows a provider to close a corporate's client account
URL: {{base_url}}/v1/providers/{{provider_id}}/client-accounts/{{client_id}}/actions
Method: POST
{
"action":"CLOSE"
}
{
"message":"Company closed successfully",
"success": True,
"errors":"",
"data": {
"id":"1",
"uuid":"5847a6f2-dc50-4935-b796-098aa07fa791",
"status":"CLOSED",
"account_type":"corporate-client-account",
"managing_organization":"b6c0cc80-c5fd-4430-805c-e3591ec9b3cf",
"currency":"GHS",
"service_period_start":"2021-09-17T10:50:26.747617Z",
"service_period_end":"2021-09-17T10:50:26.747617Z",
"balance":56.00,
"limit":70.00,
"owner":"5847a6f2-dc50-4935-b796-098aa07fa791"
}
}
Give credit to an insurance client
This endpoint allows a provider to record a deposit into a client account.
URL: {{base_url}}/v1/providers/{{provider_id}}/client-accounts/{{client_id}}/actions
Method: POST
{
"action":"CREDIT",
"amount":450,
"currency":"GHS",
"reference":"Akos",
"reference_type":"BANK_TRANSFER",
"comment":""
}
{
"message":"Deposit successful",
"success": True,
"errors":"",
"data": {
"id":"1",
"uuid":"5847a6f2-dc50-4935-b796-098aa07fa791",
"status":"ACTIVE",
"account_type":"corporate-client-account",
"managing_organization":"b6c0cc80-c5fd-4430-805c-e3591ec9b3cf",
"currency":"GHS",
"service_period_start":"2021-09-17T10:50:26.747617Z",
"service_period_end":"2021-09-17T10:50:26.747617Z",
"balance":56.00,
"limit":70.00,
"owner":"5847a6f2-dc50-4935-b796-098aa07fa791"
}
}
Create a health policy
This endpoint allows a provider to create a health policy.
URL: {{base_url}}/v1/providers/{{provider_id}}/client/{{client_id}}/health-policies
Method: POST
{
"name": "Medicaid",
"policy_holders": ["Stanchit Dank", "Name Two"],
"service_categories": [
"consultation", "medication", "hospitalization"
],
"exclusions":{
"medications": [""],
"specialties": [""],
"diagnostic_tests": [""],
"procedures": [""],
"diagnoses": ["ICD-10-CODE"]
}
}
{
"message": "Successfully created health policy",
"success": true,
"data":{
"uuid": "some-unique-uuid",
"name": "Medicaid",
"service_categories": [
"consultation", "medication", "hospitalization"
],
"exclusions":{
"medications": [""],
"specialties": [""],
"diagnostics": [""],
"procedures": [""],
"diagnosis": ["ICD-10-CODE"]
}
},
"errors": null
}
Get insurance health policies
This endpoint allows a provider to get health policies.
URL: {{base_url}}/v1/providers/{{provider_id}}/client/{{client_id}}/health-policies
Method: GET
{
"message": "Retrieved health policies",
"success": true,
"data":[
{
"uuid": "some-unique-uuid",
"name": "Medicaid",
"service_categories": [
"consultation", "medication", "hospitalization"
],
"exclusions":{
"medications": [""],
"specialties": [""],
"diagnostics": [""],
"procedures": [""],
},
"created_at": "2021-10-27T20:20:21.451727Z"
}
],
"errors": null
}
Update insurance health policies
This endpoint allows a provider to update a health policy.
URL: {{base_url}}/v1/providers/{{provider_id}}/client/{{client_id}}/health-policies/{{health_policy_id}}
Method: PATCH
{
"name": "Category 1080",
"policy_holders": [],
"description":"For companies at Zongo",
"service_categories": [],
"exclusions":{
"medications": [],
"specialties": [],
"diagnostic_tests": [],
"procedures": [],
"diagnoses": []
}
}
{
"uuid": "f4bd9ede-cc0c-4b80-a521-59475b9f0ad2",
"name": "Testing",
"description": "For companies at Zongo",
"owner": "b1645ff8-1b0f-44f5-919a-5519fe369a97",
"policy_holders": [
"yes"
],
"service_categories": [],
"exclusions": {
"medications": [
"woeks"
],
"procedures": [],
"diagnostic_tests": [],
"specialties": [],
"diagnoses": []
},
"created_at": "2021-10-27T20:20:21.451727Z"
}
Register a patient as an insurance benefactor/beneficiary
This endpoint allows a provider to register a patient as an insurance policy beneficiary. If the patient cannot be registered as a benefactor because someone with their phone number is listed, they will be registered as a beneficiary
URL: {{base_url}}/v1/providers/{{provider_id}}/clients/{{client_id}}/beneficiaries
Method: POST
{
"managing_organization": "fd695ebb-5432-4e0d-9d59-5ac095638c0a",
"first_name": "Owura Kwaku",
"last_name": "Acheampong",
"health_policy": "policy_name",
"date_of_birth": "2021-09-19",
"address": "Adenta",
"period_start": "",
"period_end": "",
"contribution_type": "COPAY",//COPAY OR COINSURANCE
"contribution_value": 234.00,
"contribution_currency": "GHS",
"mobile": "0594520468",
"email": "[email protected]",
"gender": "male",
"maximum_dependents_allowed": 0,
"card_no":"",
"policy_holder":"",
"mr_number": "some-mr-number",
}
{
"message": "Successfully registered payer beneficiary",
"success": true,
"data": {
"uuid": "uuid",
"managing_organization": "fd695ebb-5432-4e0d-9d59-5ac095638c0a",
"first_name": "Owura Kwaku",
"last_name": "Acheampong",
"health_policy": "policy_name",
"date_of_birth": "2021-09-19",
"address": "Adenta",
"period_start": "",
"period_end": "",
"contribution_type": "co-pay",
"contribution_value": 234.00,
"contribution_currency": "GHS",
"mobile": "0594520468",
"email": "[email protected]",
"gender": "male",
"maximum_dependents_allowed": 0,
"beneficiaries": [
{
"id": "1452",
"uuid": "uuid",
"first_name": "Owura Kwaku",
"last_name": "Acheampong",
"health_policy": "policy_name",
"date_of_birth": "2021-09-19",
"address": "Adenta",
"period_start": "",
"period_end": "",
"contribution_type": "co-pay",
"contribution_value": 234.00,
"contribution_currency": "GHS",
"mobile": "0594520468",
"email": "[email protected]",
"gender": "male",
}
]
},
"errors": null
}
Get insurance beneficiaries
This endpoint allows to get a list of insurance beneficiaries linked managed by a particular client
URL: {{base_url}}/v1/providers/{{provider_id}}/clients/{{client_id}}/beneficiaries
Method: GET
URL args:
provider_id (str) - A uuid of the organization providing health care services
client_id (str) - A uuid of the organization (client) managing the beneficiaries
{
"success": true,
"message": "Operation successful",
"meta": {
"current": 1,
"page_size_query": "page_size",
"next": null,
"previous": null,
"page_size": 50,
"total": 2
},
"results": [
{
"id": 12,
"uuid": "83783295-c587-458d-ac35-f32fcc6e85e3",
"account": 12,
"patient": 12,
"relationship": "SELF",
"first_name": null,
"last_name": null,
"policy_name": null,
"contribution_type": "COPAY",
"out_of_pocket_limit_currency": "GHS",
"contribution_value": "0.00",
"contribution_currency": "GHS",
"birth_date": null,
"card_no": null,
"policy_holder": null,
"period_start": null,
"period_end": null,
"gender": "UNKNOWN"
},
{
"id": 14384,
"uuid": "ab15a0c7-c457-46b6-b0d1-ee5f2e346a62",
"account": 14384,
"patient": 2,
"relationship": "SELF",
"first_name": null,
"last_name": null,
"policy_name": null,
"contribution_type": "COPAY",
"out_of_pocket_limit_currency": "GHS",
"contribution_value": "0.00",
"contribution_currency": "GHS",
"birth_date": null,
"card_no": null,
"policy_holder": null,
"period_start": null,
"period_end": null,
"gender": "UNKNOWN"
}
]
}
Edit an insurance beneficiary
This endpoint allows a provider to edit an insurance beneficiary
URL: {{base_url}}/v1/providers/{{provider_id}}/clients/{{client_id}}/beneficiaries/{{beneficiary_id}}
Method: PATCH
URL args description:
provider_id (str) - A uuid (Organization.uuid) of the healthcare provider
client_id (str) - A uuid (Organization.uuid) for the organization which in this case is an insurance provider
beneficiary_id (str) - A uuid ( PatientAccountBenefactor.uuid) for the PatientAccountBenefactor object
{
"relationship": "DEPENDENT",
"first_name": "Janelle-Baptiste",
"last_name": "Tuyizere",
"policy_name": null,
"contribution_type": "COPAY",
"out_of_pocket_limit_currency": "GHS",
"contribution_value": "10.00",
"contribution_currency": "GHS",
"birth_date": "2020-01-02",
"gender": "MALE"
}
{
"success": true,
"message": "The beneficiary was successfully updated",
"data": {
"id": 14623,
"uuid": "880e773c-1685-4373-b8f2-ef3402698503",
"account": 14596,
"patient": 14497,
"relationship": "DEPENDENT",
"first_name": "Janelle-Baptiste",
"last_name": "Tuyizere",
"policy_name": null,
"contribution_type": "COPAY",
"out_of_pocket_limit_currency": "GHS",
"contribution_value": "15.00",
"contribution_currency": "GHS",
"birth_date": "2020-01-02",
"card_no": "4527",
"policy_holder": "JBapt",
"period_start": "2023-01-04",
"period_end": "2023-01-31",
"gender": "MALE"
},
"errors": null
}
You can update all the following fields:
relationship, first_name, last_name, policy_name, contribution_type, out_of_pocket_limit_currency, contribution_value, contribution_currency, birth_date, card_no, policy_holder, period_start, period_end, gender
View claims
This endpoint allows you to get all bills issued by a provider
URL: {{base_url}}/providers/{{serenity_user_provider_id}}/finance/claims
Method: GET
filter fields:
- patient
- billable_period_start
- payer
{
"success": true,
"message": "Successfully retrieved claims",
"meta": {
"current": 1,
"page_size_query": "page_size",
"next": null,
"previous": null,
"page_size": 50,
"total": 1
},
"results": [
{
"id": 1,
"uuid": "5531d4e6-c3b5-4d14-9294-0f71968c1161",
"created_at": "2021-10-27T14:08:55.630656Z",
"is_deleted": false,
"modified_at": "2021-10-27T14:08:55.630709Z",
"claim_type": "INSTITUTIONAL",
"sub_type": "EMERGENCY",
"use": "CLAIM",
"status": "ACTIVE",
"billable_period_start": "2021-10-27T14:08:55.630245Z",
"billable_period_end": null,
"priority": "NORMAL",
"funds_reserves": "PROVIDER",
"payee_type": "PROVIDER",
"patient": "949b23f5-2079-4480-92fc-dea4c18cc9d7",
"enterer": "25b2bea0-c60d-45b7-bc96-e0136bca18be",
"provider": "b6c0cc80-c5fd-4430-805c-e3591ec9b3cf",
"payer": "a54d1412-feb1-4aa7-b0a5-e4de1f60aa91",
"prescription": null,
"original_prescription": null,
"payee_reference": "8eb044df-3e0d-43fd-8e59-65c0ddbdcf66",
"charge_item": 209
}
]
}
View payer bills
This endpoint allows you to get all bills issued by a provider
URL: {{base_url}}/providers/{{serenity_user_provider_id}}/finance/payer_bills
Method: GET
filter fields:
- patient
- visit
- payer
- patient_name
- cashier
{
"success": true,
"message": "Successfully retrieved payer bills",
"meta": {
"current": 1,
"page_size_query": "page_size",
"next": null,
"previous": null,
"page_size": 50,
"total": 1
},
"results": [
{
"provider": "59c9e42c-b561-419f-b042-88f3ea861b43",
"visit": "e58067aa-fb26-4d25-80ca-562207ec287d",
"payer": "b1645ff8-1b0f-44f5-919a-5519fe369a97",
"patient": "9fb8169c-1b08-4a18-963c-37a524de55a0",
"date_generated": "2021-10-30T18:23:15.194024Z",
"patient_name": "George Grant",
"total_amount": "2000.00",
"cashier": null,
"cashier_name": "N/A (billed unpaid)",
"currency": "GHS",
"payer_bill_claims": [
{
"id": 2,
"uuid": "cf0dca13-0de5-43ef-90d0-6926fb8bb3a9",
"created_at": "2021-10-30T18:23:15.838876Z",
"is_deleted": false,
"modified_at": "2021-10-30T18:23:15.838918Z",
"claim_type": "INSTITUTIONAL",
"sub_type": "EMERGENCY",
"use": "CLAIM",
"status": "ACTIVE",
"billable_period_start": "2021-10-30T18:23:14.485015Z",
"billable_period_end": null,
"priority": "NORMAL",
"funds_reserves": "PROVIDER",
"payee_type": "PROVIDER",
"amount": "500.00",
"currency": "GHS",
"patient": "9fb8169c-1b08-4a18-963c-37a524de55a0",
"enterer": "8ad807ac-d64d-4869-9039-8fb54ad2b713",
"provider": "59c9e42c-b561-419f-b042-88f3ea861b43",
"payer": "b1645ff8-1b0f-44f5-919a-5519fe369a97",
"payer_bill": 1,
"prescription": null,
"original_prescription": null,
"payee_reference": "8ad807ac-d64d-4869-9039-8fb54ad2b713",
"charge_item": 2
}
]