API Reference
Start typing to search…

Insurance clients and payments

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": "akosua1@serenity.com",
    "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": "akosua1@serenity.com",
        "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": "chris@clearspacelabs.com",
            "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": "sheldon@clearspacelabs.com",
        "admin_phoneno": "2335495065299",
        "authorizedBy": "sheldon@clearspacelabs.com",
        "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:

  1. status
  2. managing_organization
  3. owner
  4. currency
  5. 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": "owurakwaku@serenity.com",
    "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": "owurakwaku@serenity.com",
    "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": "owurakwaku@serenity.com",
        "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:

  1. patient
  2. billable_period_start
  3. 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:

  1. patient
  2. visit
  3. payer
  4. patient_name
  5. 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
                }
		]

Updated almost 3 years ago

Updated almost 3 years ago