Policy

Manage insurance policies, policy templates (categories, benefits, sub-benefits), patient-policy relationships, and patient benefit consumption. Policies belong to a Policy Holder and can have Members assigned through patient-policy operations. Networks are referenced when linking patients to policies.

Base URL

https://api.{client_namespace}.najeeb.ai/v4.0/health

Authentication

All API requests are authenticated using an API key passed in a dedicated header:

access-key: YOUR_API_KEY

For access key provisioning, please contact Najeeb support.

Policy Management

Create Policy

POST /policy/create

Create a new insurance policy linked to an existing policy holder. Optionally, you can add a patient to the policy in the same request using the add_patient_to_policy nested object.

Prerequisites

A Policy Holder must exist before creating a policy. If you include add_patient_to_policy, the referenced Member and Network must also exist.

Request Body

Parameter	Type	Required	Description	Accepted Values
`policy_no` *	string	Yes	Unique policy number	Alphanumeric string (e.g., `POL-2024-001`)
`start_date` *	string	Yes	Policy start date	ISO date
`end_date` *	string	Yes	Policy end date	ISO date
`created_date` *	string	Yes	Date the policy was created	ISO date
`status` *	string	Yes	Policy status	Enum: `ACTIVE`, `INACTIVE`, `EXPIRED`
`ph_erp_id` *	string	Yes	ERP ID of the policy holder that owns this policy	Alphanumeric string
`add_patient_to_policy`	object	No	Nested object to simultaneously add a patient to the policy	See nested object below

add_patient_to_policy nested object:

Parameter	Type	Required	Description	Accepted Values
`member_id` *	string	Yes	Member ID of the patient to add	Alphanumeric string
`network_code`	string	No	Code of the network to associate	Alphanumeric string
`category_code` *	string	Yes	Category code for the patient within the policy	Alphanumeric string
`start_date` *	string	Yes	Patient-policy start date	ISO date
`end_date` *	string	Yes	Patient-policy end date	ISO date

Code Examples

cURL
JavaScript
Python

curl -X POST \
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/create" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_no": "POL-2024-001",
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "created_date": "2024-01-01",
    "status": "ACTIVE",
    "ph_erp_id": "PH-ERP-12345",
    "add_patient_to_policy": {
      "member_id": "MEMBER001",
      "network_code": "NET-001",
      "category_code": "A",
      "start_date": "2024-01-01",
      "end_date": "2024-12-31"
    }
  }'

const response = await fetch(
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/create",
  {
    method: "POST",
    headers: {
      "access-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      policy_no: "POL-2024-001",
      start_date: "2024-01-01",
      end_date: "2024-12-31",
      created_date: "2024-01-01",
      status: "ACTIVE",
      ph_erp_id: "PH-ERP-12345",
      add_patient_to_policy: {
        member_id: "MEMBER001",
        network_code: "NET-001",
        category_code: "A",
        start_date: "2024-01-01",
        end_date: "2024-12-31",
      },
    }),
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/create"

payload = {
    "policy_no": "POL-2024-001",
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "created_date": "2024-01-01",
    "status": "ACTIVE",
    "ph_erp_id": "PH-ERP-12345",
    "add_patient_to_policy": {
        "member_id": "MEMBER001",
        "network_code": "NET-001",
        "category_code": "A",
        "start_date": "2024-01-01",
        "end_date": "2024-12-31",
    },
}

headers = {
    "access-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

Success Response (201 Created)

{
  "policy_no": "POL-2024-001",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "created_date": "2024-01-01",
  "status": "ACTIVE",
  "ph_erp_id": "PH-ERP-12345",
  "code": 201,
  "message": "Created successfully"
}

Response Fields

Field	Type	Description
`policy_no`	string	The policy number of the created policy
`start_date`	string	Policy start date
`end_date`	string	Policy end date
`created_date`	string	Date the policy was created
`status`	string	Policy status
`ph_erp_id`	string	ERP ID of the policy holder
`code`	number	HTTP status code (`201`)
`message`	string	Success message

Error Responses

Error Codes

Error Code	HTTP Status	Description
`E_BAD_REQUEST_400`	400	Request validation failed -- see the `details` array for field-level errors
`401 Unauthorized`	401	Missing or invalid `access-key`
`E_EPH_01`	404	Policy holder not found
`E_EPA_01`	404	Patient not found
`E_EPA_015`	404	Network not found
`E_EPA_069`	409	Policy already exists or patient already has an active policy

Example Error Responses

Bad Request:

{
  "ErrorCode": "E_BAD_REQUEST_400",
  "message": "Bad request",
  "details": [
    "policy_no is required",
    "status must be one of the following values: ACTIVE, INACTIVE, EXPIRED"
  ]
}

Policy Holder Not Found:

{
  "ErrorCode": "E_EPH_01",
  "message": "Policy holder not found",
  "details": []
}

Unauthorized:

{
  "ErrorCode": "API key is required",
  "message": "Unauthorized",
  "details": []
}

Update Policy

PATCH /policy/policy?ph_erp_id=...&policy_no=...

Update core fields of an existing policy such as dates, plan code, or status.

Query Parameters

Parameter	Type	Required	Description	Accepted Values
`ph_erp_id` *	string	Yes	ERP ID of the policy holder	Alphanumeric string
`policy_no` *	string	Yes	Policy number of the policy to update	Alphanumeric string

Request Body

All fields are optional. Only include the fields you want to update.

Parameter	Type	Required	Description	Accepted Values
`start_date`	string	No	Updated start date	ISO date
`end_date`	string	No	Updated end date	ISO date
`status`	string	No	Updated policy status	Enum: `ACTIVE`, `INACTIVE`, `EXPIRED`
`plan_code`	string	No	Plan code to associate with the policy	Alphanumeric string

Code Examples

cURL
JavaScript
Python

curl -X PATCH \
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/policy?ph_erp_id=PH-ERP-12345&policy_no=POL-2024-001" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "end_date": "2025-06-30",
    "status": "ACTIVE"
  }'

const params = new URLSearchParams({
  ph_erp_id: "PH-ERP-12345",
  policy_no: "POL-2024-001",
});

const response = await fetch(
  `https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/policy?${params}`,
  {
    method: "PATCH",
    headers: {
      "access-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      end_date: "2025-06-30",
      status: "ACTIVE",
    }),
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/policy"

params = {
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
}

payload = {
    "end_date": "2025-06-30",
    "status": "ACTIVE",
}

headers = {
    "access-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.patch(url, params=params, json=payload, headers=headers)
print(response.json())

Response

Success Response (200 OK)

{
  "policy_no": "POL-2024-001",
  "start_date": "2024-01-01",
  "end_date": "2025-06-30",
  "created_date": "2024-01-01",
  "status": "ACTIVE",
  "ph_erp_id": "PH-ERP-12345",
  "code": 200,
  "message": "Updated successfully"
}

Response Fields

Field	Type	Description
`policy_no`	string	The policy number
`start_date`	string	Policy start date
`end_date`	string	Updated policy end date
`created_date`	string	Date the policy was created
`status`	string	Current policy status
`ph_erp_id`	string	ERP ID of the policy holder
`code`	number	HTTP status code (`200`)
`message`	string	Success message

Error Responses

Error Codes

Error Code	HTTP Status	Description
`E_BAD_REQUEST_400`	400	Request validation failed -- see the `details` array for field-level errors
`401 Unauthorized`	401	Missing or invalid `access-key`
`E_EPH_01`	404	Policy holder not found
`E_EPA_014`	404	Policy not found

Example Error Responses

Policy Not Found:

{
  "ErrorCode": "E_EPA_014",
  "message": "Policy not found",
  "details": []
}

Get Patient Consumption

GET /policy/patient/consumption/get?ph_erp_id=...&policy_no=...&member_id=...

Retrieve the benefit consumption details for a specific patient under a given policy. Returns the amounts eligible, utilized, ex-gratia, and a breakdown by benefit and sub-benefit.

Query Parameters

Parameter	Type	Required	Description	Accepted Values
`ph_erp_id` *	string	Yes	ERP ID of the policy holder	Alphanumeric string
`policy_no` *	string	Yes	Policy number	Alphanumeric string
`member_id` *	string	Yes	Member ID of the patient	Alphanumeric string

Code Examples

cURL
JavaScript
Python

curl -X GET \
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/patient/consumption/get?ph_erp_id=PH-ERP-12345&policy_no=POL-2024-001&member_id=MEMBER001" \
  -H "access-key: YOUR_API_KEY"

const params = new URLSearchParams({
  ph_erp_id: "PH-ERP-12345",
  policy_no: "POL-2024-001",
  member_id: "MEMBER001",
});

const response = await fetch(
  `https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/patient/consumption/get?${params}`,
  {
    method: "GET",
    headers: {
      "access-key": "YOUR_API_KEY",
    },
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/patient/consumption/get"

params = {
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "member_id": "MEMBER001",
}

headers = {
    "access-key": "YOUR_API_KEY",
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

Response

Success Response (200 OK)

{
  "member_id": "MEMBER001",
  "category_code": "A",
  "amount_eligible": 10000,
  "amount_exgratia": 5000,
  "amount_utilized": 1000,
  "benefit_consumption": [
    {
      "benefit_code": "BEN-001",
      "limit": 5000,
      "utilized": 500
    }
  ],
  "sub_benefit_consumption": [
    {
      "sub_benefit_code": "SUB-BEN-001",
      "limit": 2000,
      "utilized": 200
    }
  ]
}

Response Fields

Field	Type	Description
`member_id`	string	Member ID of the patient
`category_code`	string	Category code for the patient within the policy
`amount_eligible`	number	Total amount eligible under the policy
`amount_exgratia`	number	Total ex-gratia amount available
`amount_utilized`	number	Total amount utilized by the patient
`benefit_consumption`	array	Array of benefit consumption objects
`benefit_consumption[].benefit_code`	string	Benefit code
`benefit_consumption[].limit`	number	Maximum limit for the benefit
`benefit_consumption[].utilized`	number	Amount utilized for the benefit
`sub_benefit_consumption`	array	Array of sub-benefit consumption objects
`sub_benefit_consumption[].sub_benefit_code`	string	Sub-benefit code
`sub_benefit_consumption[].limit`	number	Maximum limit for the sub-benefit
`sub_benefit_consumption[].utilized`	number	Amount utilized for the sub-benefit

Error Responses

Error Codes

Error Code	HTTP Status	Description
`401 Unauthorized`	401	Missing or invalid `access-key`
`E_EPH_01`	404	Policy holder not found
`E_EPA_014`	404	Policy not found
`E_EPA_01`	404	Patient not found

Example Error Responses

Patient Not Found:

{
  "ErrorCode": "E_EPA_01",
  "message": "Patient not found",
  "details": []
}

Patient-Policy Operations

Add Bulk Patients to Policy Synchronously

POST /policy/bulk-patient-to-policy

Synchronously add multiple patients to a policy in a single request. Each entry in the array specifies the patient, network, and category for the assignment.

Performance

For large datasets exceeding +3,000 members members, use the async bulk endpoint instead. The synchronous endpoint is suited for smaller batches.

Request Body

Parameter	Type	Required	Description	Accepted Values
`policy_no` *	string	Yes	Policy number	Alphanumeric string
`ph_erp_id` *	string	Yes	ERP ID of the policy holder	Alphanumeric string
`patients` *	array	Yes	Array of patient objects to add to the policy	See patient object below

Patient object:

Parameter	Type	Required	Description	Accepted Values
`card`	string	No	Card number	Alphanumeric string
`member_id` *	string	Yes	Member ID of the patient	Alphanumeric string
`name`	string	No	Patient name	String, 1-255 characters
`email`	string	No	Patient email address	Valid email format
`relation`	string	No	Relationship to policy holder	Enum: `SELF`, `FATHER`, `MOTHER`, `SON`, `DAUGHTER`, `SISTER`, `HUSBAND`, `WIFE`, `WIFE_WITHOUT_MATERNITY`, `MOTHER_MB`, `SENIOR_EMPLOYEE`, `FEMALE_EMPLOYEE_WITH_MAT`, `CHILD`, `SPOUSE`, `EMPLOYEE`, `OTHER`
`national_id`	string	No	National ID number	Alphanumeric string
`visit_visa_number`	string	No	Visit visa number	Alphanumeric string
`passport`	string	No	Passport number	Alphanumeric string
`phone_number`	string	No	Phone number	String (e.g., `+966555555555`)
`address`	string	No	Patient address	String, max 500 characters
`gender` *	string	Yes	Patient gender	Enum: `MALE`, `FEMALE`
`marital_status` *	string	Yes	Marital status	Enum: `SINGLE`, `MARRIED`, `ENGAGED`, `UNKNOWN`, `WIDOWED`, `DIVORCED`, `SEPARATED`
`nationality`	string	No	Patient nationality	String
`date_of_birth` *	string	Yes	Date of birth	ISO 8601 format: `YYYY-MM-DDTHH:mm:ss.sssZ`
`network_code`	string	No	Network code to associate	Alphanumeric string
`is_vip`	boolean	No	VIP flag	`true`, `false` (default: `false`)
`insured_notes`	string	No	Notes about the insured patient	String, max 500 characters
`category_code` *	string	Yes	Category code for the patient	Alphanumeric string
`additional_date`	string	No	Additional date (e.g., policy addition date)	ISO 8601 format: `YYYY-MM-DDTHH:mm:ss.sssZ`
`effective_start_date` *	string	Yes	Coverage start date	ISO 8601 format: `YYYY-MM-DDTHH:mm:ss.sssZ`
`effective_end_date` *	string	Yes	Coverage end date	ISO 8601 format: `YYYY-MM-DDTHH:mm:ss.sssZ`

Code Examples

cURL
JavaScript
Python

curl -X POST \
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/bulk-patient-to-policy" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_no": "POL-2024-001",
    "ph_erp_id": "PH-ERP-12345",
    "patients": [
      {
        "card": "12345",
        "member_id": "MEMBER001",
        "name": "Alaa",
        "email": "alaa@najeeb.ai",
        "relation": "SELF",
        "national_id": "1234567890",
        "phone_number": "+966555555555",
        "gender": "MALE",
        "marital_status": "SINGLE",
        "nationality": "ARABIC",
        "date_of_birth": "1992-01-01T00:00:00.000Z",
        "network_code": "NET-001",
        "is_vip": false,
        "insured_notes": "Primary beneficiary",
        "category_code": "A",
        "additional_date": "2024-01-01T00:00:00.000Z",
        "effective_start_date": "2024-01-01T00:00:00.000Z",
        "effective_end_date": "2024-12-31T00:00:00.000Z"
      },
      {
        "member_id": "MEMBER002",
        "name": "Sara",
        "relation": "SPOUSE",
        "gender": "FEMALE",
        "marital_status": "MARRIED",
        "date_of_birth": "1995-06-15T00:00:00.000Z",
        "network_code": "NET-001",
        "category_code": "B",
        "effective_start_date": "2024-01-01T00:00:00.000Z",
        "effective_end_date": "2024-12-31T00:00:00.000Z"
      }
    ]
  }'

const response = await fetch(
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/bulk-patient-to-policy",
  {
    method: "POST",
    headers: {
      "access-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      policy_no: "POL-2024-001",
      ph_erp_id: "PH-ERP-12345",
      patients: [
        {
          card: "12345",
          member_id: "MEMBER001",
          name: "Alaa",
          email: "alaa@najeeb.ai",
          relation: "SELF",
          national_id: "1234567890",
          phone_number: "+966555555555",
          gender: "MALE",
          marital_status: "SINGLE",
          nationality: "ARABIC",
          date_of_birth: "1992-01-01T00:00:00.000Z",
          network_code: "NET-001",
          is_vip: false,
          insured_notes: "Primary beneficiary",
          category_code: "A",
          additional_date: "2024-01-01T00:00:00.000Z",
          effective_start_date: "2024-01-01T00:00:00.000Z",
          effective_end_date: "2024-12-31T00:00:00.000Z",
        },
        {
          member_id: "MEMBER002",
          name: "Sara",
          relation: "SPOUSE",
          gender: "FEMALE",
          marital_status: "MARRIED",
          date_of_birth: "1995-06-15T00:00:00.000Z",
          network_code: "NET-001",
          category_code: "B",
          effective_start_date: "2024-01-01T00:00:00.000Z",
          effective_end_date: "2024-12-31T00:00:00.000Z",
        },
      ],
    }),
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/bulk-patient-to-policy"

payload = {
    "policy_no": "POL-2024-001",
    "ph_erp_id": "PH-ERP-12345",
    "patients": [
        {
            "card": "12345",
            "member_id": "MEMBER001",
            "name": "Alaa",
            "email": "alaa@najeeb.ai",
            "relation": "SELF",
            "national_id": "1234567890",
            "phone_number": "+966555555555",
            "gender": "MALE",
            "marital_status": "SINGLE",
            "nationality": "ARABIC",
            "date_of_birth": "1992-01-01T00:00:00.000Z",
            "network_code": "NET-001",
            "is_vip": False,
            "insured_notes": "Primary beneficiary",
            "category_code": "A",
            "additional_date": "2024-01-01T00:00:00.000Z",
            "effective_start_date": "2024-01-01T00:00:00.000Z",
            "effective_end_date": "2024-12-31T00:00:00.000Z",
        },
        {
            "member_id": "MEMBER002",
            "name": "Sara",
            "relation": "SPOUSE",
            "gender": "FEMALE",
            "marital_status": "MARRIED",
            "date_of_birth": "1995-06-15T00:00:00.000Z",
            "network_code": "NET-001",
            "category_code": "B",
            "effective_start_date": "2024-01-01T00:00:00.000Z",
            "effective_end_date": "2024-12-31T00:00:00.000Z",
        },
    ],
}

headers = {
    "access-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

Success Response (200 OK)

Returns a summary of the bulk operation results.

Error Responses

Error Codes

Error Code	HTTP Status	Description
`E_BAD_REQUEST_400`	400	Request validation failed -- see the `details` array for field-level errors
`401 Unauthorized`	401	Missing or invalid `access-key`
`E_EPA_014`	404	Policy not found
`E_EPA_015`	404	Network not found
`E_EPA_01`	404	Patient not found
`E_EPA_069`	409	Patient already assigned to this policy

Example Error Responses

Patient Not Found:

{
  "ErrorCode": "E_EPA_01",
  "message": "Patient not found",
  "details": []
}

Patient Already Assigned:

{
  "ErrorCode": "E_EPA_069",
  "message": "Patient already assigned to this policy",
  "details": []
}

Async Bulk Add Patients to Policy

POST /policy/async-bulk-patient-to-policy

Asynchronously add a large number of patients to a policy, and results are delivered through a registered Webhook. Webhook.

When to Use

Use this endpoint for bulk imports of +3,000 members. For smaller batches, use the synchronous bulk endpoint.

Request Body

Same structure as the bulk endpoint -- a JSON object with policy_no, ph_erp_id, and a patients array.

Code Examples

cURL
JavaScript
Python

curl -X POST \
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/async-bulk-patient-to-policy" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_no": "POL-2024-001",
    "ph_erp_id": "PH-ERP-12345",
    "patients": [
      {
        "member_id": "MEMBER001",
        "name": "Alaa",
        "gender": "MALE",
        "marital_status": "SINGLE",
        "date_of_birth": "1992-01-01T00:00:00.000Z",
        "network_code": "NET-001",
        "category_code": "A",
        "effective_start_date": "2024-01-01T00:00:00.000Z",
        "effective_end_date": "2024-12-31T00:00:00.000Z"
      }
    ]
  }'

const response = await fetch(
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/async-bulk-patient-to-policy",
  {
    method: "POST",
    headers: {
      "access-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      policy_no: "POL-2024-001",
      ph_erp_id: "PH-ERP-12345",
      patients: [
        {
          member_id: "MEMBER001",
          name: "Alaa",
          gender: "MALE",
          marital_status: "SINGLE",
          date_of_birth: "1992-01-01T00:00:00.000Z",
          network_code: "NET-001",
          category_code: "A",
          effective_start_date: "2024-01-01T00:00:00.000Z",
          effective_end_date: "2024-12-31T00:00:00.000Z",
        },
      ],
    }),
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/async-bulk-patient-to-policy"

payload = {
    "policy_no": "POL-2024-001",
    "ph_erp_id": "PH-ERP-12345",
    "patients": [
        {
            "member_id": "MEMBER001",
            "name": "Alaa",
            "gender": "MALE",
            "marital_status": "SINGLE",
            "date_of_birth": "1992-01-01T00:00:00.000Z",
            "network_code": "NET-001",
            "category_code": "A",
            "effective_start_date": "2024-01-01T00:00:00.000Z",
            "effective_end_date": "2024-12-31T00:00:00.000Z",
        },
    ],
}

headers = {
    "access-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

Success Response (202 Accepted)

The job has been queued for background processing.

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Bulk patient import job has been queued. Results will be sent via webhook."
}

Response Fields

Field	Type	Description
`job_id`	string	Unique identifier for the queued job
`message`	string	Confirmation message

Webhook Delivery

Error Responses

Error Codes

Error Code	HTTP Status	Description
`E_BAD_REQUEST_400`	400	Request validation failed -- see the `details` array for field-level errors
`401 Unauthorized`	401	Missing or invalid `access-key`
`E_EPA_014`	404	Policy not found
`E_EPA_015`	404	Network not found
`E_EPA_01`	404	Patient not found

Example Error Responses

Bad Request:

{
  "ErrorCode": "E_BAD_REQUEST_400",
  "message": "Bad request",
  "details": [
    "member_id is required",
    "network_code is required"
  ]
}

Update Patient-Policy

PATCH /policy/patient-policy?ph_erp_id=...&policy_no=...&member_id=...

Update the relationship between a patient and a policy, such as changing the network, category, or coverage dates.

Query Parameters

Parameter	Type	Required	Description	Accepted Values
`ph_erp_id` *	string	Yes	ERP ID of the policy holder	Alphanumeric string
`policy_no` *	string	Yes	Policy number	Alphanumeric string
`member_id` *	string	Yes	Member ID of the patient	Alphanumeric string

Request Body

All fields are optional. Only include the fields you want to update.

Parameter	Type	Required	Description	Accepted Values
`network_code`	string	No	Updated network code	Alphanumeric string
`category_code`	string	No	Updated category code	Alphanumeric string
`start_date`	string	No	Updated start date	ISO date
`end_date`	string	No	Updated end date	ISO date
`status`	string	No	Updated patient-policy status	Enum: `ACTIVE`, `INACTIVE`, `EXPIRED`

Code Examples

cURL
JavaScript
Python

curl -X PATCH \
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/patient-policy?ph_erp_id=PH-ERP-12345&policy_no=POL-2024-001&member_id=MEMBER001" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network_code": "NET-002",
    "end_date": "2025-06-30"
  }'

const params = new URLSearchParams({
  ph_erp_id: "PH-ERP-12345",
  policy_no: "POL-2024-001",
  member_id: "MEMBER001",
});

const response = await fetch(
  `https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/patient-policy?${params}`,
  {
    method: "PATCH",
    headers: {
      "access-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      network_code: "NET-002",
      end_date: "2025-06-30",
    }),
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/patient-policy"

params = {
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "member_id": "MEMBER001",
}

payload = {
    "network_code": "NET-002",
    "end_date": "2025-06-30",
}

headers = {
    "access-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.patch(url, params=params, json=payload, headers=headers)
print(response.json())

Response

Success Response (200 OK)

Returns the updated patient-policy data.

Error Responses

Error Codes

Error Code	HTTP Status	Description
`E_BAD_REQUEST_400`	400	Request validation failed -- see the `details` array for field-level errors
`401 Unauthorized`	401	Missing or invalid `access-key`
`E_EPH_01`	404	Policy holder not found
`E_EPA_014`	404	Policy not found
`E_EPA_01`	404	Patient not found

Example Error Responses

Policy Not Found:

{
  "ErrorCode": "E_EPA_014",
  "message": "Policy not found",
  "details": []
}

Policy Template Operations

Policy templates define the coverage structure for a policy: categories, benefits, and sub-benefits, each with their own limits.

Template Hierarchy

Templates follow a three-level hierarchy: Category > Benefit > Sub-Benefit. A category must exist in the policy before benefits can be added, and a benefit must exist before sub-benefits can be added.

Add Category to Template

POST /policy/template/category

Add a new category with an amount eligible limit to a policy template.

Request Body

Parameter	Type	Required	Description	Accepted Values
`ph_erp_id` *	string	Yes	ERP ID of the policy holder	Alphanumeric string
`policy_no` *	string	Yes	Policy number	Alphanumeric string
`category_code` *	string	Yes	Unique code for the category	Alphanumeric string
`amount_eligible` *	number	Yes	Maximum amount eligible under this category	Decimal, minimum 0

Code Examples

cURL
JavaScript
Python

curl -X POST \
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/template/category" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "category_code": "A",
    "amount_eligible": 50000
  }'

const response = await fetch(
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/template/category",
  {
    method: "POST",
    headers: {
      "access-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ph_erp_id: "PH-ERP-12345",
      policy_no: "POL-2024-001",
      category_code: "A",
      amount_eligible: 50000,
    }),
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/template/category"

payload = {
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "category_code": "A",
    "amount_eligible": 50000,
}

headers = {
    "access-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

Success Response (201 Created)

{
  "code": 201,
  "message": "Created successfully"
}

Response Fields

Field	Type	Description
`code`	number	HTTP status code (`201`)
`message`	string	Success message

Error Responses

Error Codes

Error Code	HTTP Status	Description
`E_BAD_REQUEST_400`	400	Request validation failed -- see the `details` array for field-level errors
`401 Unauthorized`	401	Missing or invalid `access-key`
`E_EPH_01`	404	Policy holder not found
`E_EPA_014`	404	Policy not found

Example Error Responses

Policy Not Found:

{
  "ErrorCode": "E_EPA_014",
  "message": "Policy not found",
  "details": []
}

Add Benefit to Template

POST /policy/template/benefit

Add a benefit with optional sub-benefits to a category in the policy template.

Request Body

Parameter	Type	Required	Description	Accepted Values
`ph_erp_id` *	string	Yes	ERP ID of the policy holder	Alphanumeric string
`policy_no` *	string	Yes	Policy number	Alphanumeric string
`category_code` *	string	Yes	Category code the benefit belongs to	Alphanumeric string
`benefit_code` *	string	Yes	Unique code for the benefit	Alphanumeric string
`benefit_description`	string	No	Description of the benefit	String, max 255 characters
`limit` *	number	Yes	Maximum limit for this benefit	Decimal, minimum 0
`sub_benefits`	array	No	Array of sub-benefit objects to add simultaneously	See sub-benefit object below

sub_benefits nested object:

Parameter	Type	Required	Description	Accepted Values
`sub_benefit_code` *	string	Yes	Unique code for the sub-benefit	Alphanumeric string
`sub_benefit_description`	string	No	Description of the sub-benefit	String, max 255 characters
`limit` *	number	Yes	Maximum limit for this sub-benefit	Decimal, minimum 0

Code Examples

cURL
JavaScript
Python

curl -X POST \
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/template/benefit" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "category_code": "A",
    "benefit_code": "BEN-001",
    "benefit_description": "Outpatient Benefits",
    "limit": 10000,
    "sub_benefits": [
      {
        "sub_benefit_code": "SUB-BEN-001",
        "sub_benefit_description": "Consultation",
        "limit": 3000
      }
    ]
  }'

const response = await fetch(
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/template/benefit",
  {
    method: "POST",
    headers: {
      "access-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ph_erp_id: "PH-ERP-12345",
      policy_no: "POL-2024-001",
      category_code: "A",
      benefit_code: "BEN-001",
      benefit_description: "Outpatient Benefits",
      limit: 10000,
      sub_benefits: [
        {
          sub_benefit_code: "SUB-BEN-001",
          sub_benefit_description: "Consultation",
          limit: 3000,
        },
      ],
    }),
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/template/benefit"

payload = {
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "category_code": "A",
    "benefit_code": "BEN-001",
    "benefit_description": "Outpatient Benefits",
    "limit": 10000,
    "sub_benefits": [
        {
            "sub_benefit_code": "SUB-BEN-001",
            "sub_benefit_description": "Consultation",
            "limit": 3000,
        }
    ],
}

headers = {
    "access-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

Success Response (201 Created)

{
  "code": 201,
  "message": "Created successfully"
}

Response Fields

Field	Type	Description
`code`	number	HTTP status code (`201`)
`message`	string	Success message

Error Responses

Error Codes

Error Code	HTTP Status	Description
`E_BAD_REQUEST_400`	400	Request validation failed -- see the `details` array for field-level errors
`401 Unauthorized`	401	Missing or invalid `access-key`
`E_EPH_01`	404	Policy holder not found
`E_EPA_014`	404	Policy not found

Example Error Responses

Policy Holder Not Found:

{
  "ErrorCode": "E_EPH_01",
  "message": "Policy holder not found",
  "details": []
}

Add Sub-Benefit to Template

POST /policy/template/sub-benefit

Add a sub-benefit to an existing benefit in the policy template.

Request Body

Parameter	Type	Required	Description	Accepted Values
`ph_erp_id` *	string	Yes	ERP ID of the policy holder	Alphanumeric string
`policy_no` *	string	Yes	Policy number	Alphanumeric string
`category_code` *	string	Yes	Category code	Alphanumeric string
`benefit_code` *	string	Yes	Benefit code the sub-benefit belongs to	Alphanumeric string
`benefit_description`	string	No	Description of the benefit	String, max 255 characters
`sub_benefit_code` *	string	Yes	Unique code for the sub-benefit	Alphanumeric string
`sub_benefit_description`	string	No	Description of the sub-benefit	String, max 255 characters
`limit` *	number	Yes	Maximum limit for this sub-benefit	Decimal, minimum 0

Code Examples

cURL
JavaScript
Python

curl -X POST \
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/template/sub-benefit" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "category_code": "A",
    "benefit_code": "BEN-001",
    "benefit_description": "Outpatient Benefits",
    "sub_benefit_code": "SUB-BEN-002",
    "sub_benefit_description": "Laboratory",
    "limit": 2000
  }'

const response = await fetch(
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/template/sub-benefit",
  {
    method: "POST",
    headers: {
      "access-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ph_erp_id: "PH-ERP-12345",
      policy_no: "POL-2024-001",
      category_code: "A",
      benefit_code: "BEN-001",
      benefit_description: "Outpatient Benefits",
      sub_benefit_code: "SUB-BEN-002",
      sub_benefit_description: "Laboratory",
      limit: 2000,
    }),
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/template/sub-benefit"

payload = {
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "category_code": "A",
    "benefit_code": "BEN-001",
    "benefit_description": "Outpatient Benefits",
    "sub_benefit_code": "SUB-BEN-002",
    "sub_benefit_description": "Laboratory",
    "limit": 2000,
}

headers = {
    "access-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

Success Response (201 Created)

{
  "code": 201,
  "message": "Created successfully"
}

Response Fields

Field	Type	Description
`code`	number	HTTP status code (`201`)
`message`	string	Success message

Error Responses

Error Codes

Error Code	HTTP Status	Description
`E_BAD_REQUEST_400`	400	Request validation failed -- see the `details` array for field-level errors
`401 Unauthorized`	401	Missing or invalid `access-key`
`E_EPH_01`	404	Policy holder not found
`E_EPA_014`	404	Policy not found
`E_EBA_01`	404	Benefit not found

Example Error Responses

Benefit Not Found:

{
  "ErrorCode": "E_EBA_01",
  "message": "Benefit not found",
  "details": []
}

Update Category Template

PATCH /policy/template/category

Update the amount eligible limit for an existing category in the policy template.

Request Body

Parameter	Type	Required	Description	Accepted Values
`ph_erp_id` *	string	Yes	ERP ID of the policy holder	Alphanumeric string
`policy_no` *	string	Yes	Policy number	Alphanumeric string
`category_code` *	string	Yes	Category code to update	Alphanumeric string
`amount_eligible` *	number	Yes	Updated maximum amount eligible	Decimal, minimum 0

Code Examples

cURL
JavaScript
Python

curl -X PATCH \
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/template/category" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "category_code": "A",
    "amount_eligible": 75000
  }'

const response = await fetch(
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/template/category",
  {
    method: "PATCH",
    headers: {
      "access-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ph_erp_id: "PH-ERP-12345",
      policy_no: "POL-2024-001",
      category_code: "A",
      amount_eligible: 75000,
    }),
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/template/category"

payload = {
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "category_code": "A",
    "amount_eligible": 75000,
}

headers = {
    "access-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.patch(url, json=payload, headers=headers)
print(response.json())

Response

Success Response (200 OK)

Returns the updated category template data.

Error Responses

Error Codes

Error Code	HTTP Status	Description
`E_BAD_REQUEST_400`	400	Request validation failed -- see the `details` array for field-level errors
`401 Unauthorized`	401	Missing or invalid `access-key`
`E_EPH_01`	404	Policy holder not found
`E_EPA_014`	404	Policy not found

Example Error Responses

Policy Holder Not Found:

{
  "ErrorCode": "E_EPH_01",
  "message": "Policy holder not found",
  "details": []
}

Update Benefit Template

PATCH /policy/template/benefit

Update the limit for an existing benefit in the policy template.

Request Body

Parameter	Type	Required	Description	Accepted Values
`ph_erp_id` *	string	Yes	ERP ID of the policy holder	Alphanumeric string
`policy_no` *	string	Yes	Policy number	Alphanumeric string
`category_code` *	string	Yes	Category code the benefit belongs to	Alphanumeric string
`benefit_code` *	string	Yes	Benefit code to update	Alphanumeric string
`limit` *	number	Yes	Updated maximum limit for the benefit	Decimal, minimum 0

Code Examples

cURL
JavaScript
Python

curl -X PATCH \
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/template/benefit" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "category_code": "A",
    "benefit_code": "BEN-001",
    "limit": 15000
  }'

const response = await fetch(
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/template/benefit",
  {
    method: "PATCH",
    headers: {
      "access-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ph_erp_id: "PH-ERP-12345",
      policy_no: "POL-2024-001",
      category_code: "A",
      benefit_code: "BEN-001",
      limit: 15000,
    }),
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/template/benefit"

payload = {
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "category_code": "A",
    "benefit_code": "BEN-001",
    "limit": 15000,
}

headers = {
    "access-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.patch(url, json=payload, headers=headers)
print(response.json())

Response

Success Response (200 OK)

Returns the updated benefit template data.

Error Responses

Error Codes

Error Code	HTTP Status	Description
`E_BAD_REQUEST_400`	400	Request validation failed -- see the `details` array for field-level errors
`401 Unauthorized`	401	Missing or invalid `access-key`
`E_EPH_01`	404	Policy holder not found
`E_EPA_014`	404	Policy not found
`E_EBA_01`	404	Benefit not found

Example Error Responses

Benefit Not Found:

{
  "ErrorCode": "E_EBA_01",
  "message": "Benefit not found",
  "details": []
}

Update Sub-Benefit Template

PATCH /policy/template/sub-benefit

Update the limit for an existing sub-benefit in the policy template.

Request Body

Parameter	Type	Required	Description	Accepted Values
`ph_erp_id` *	string	Yes	ERP ID of the policy holder	Alphanumeric string
`policy_no` *	string	Yes	Policy number	Alphanumeric string
`category_code` *	string	Yes	Category code	Alphanumeric string
`benefit_code` *	string	Yes	Benefit code the sub-benefit belongs to	Alphanumeric string
`sub_benefit_code` *	string	Yes	Sub-benefit code to update	Alphanumeric string
`limit` *	number	Yes	Updated maximum limit for the sub-benefit	Decimal, minimum 0

Code Examples

cURL
JavaScript
Python

curl -X PATCH \
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/template/sub-benefit" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "category_code": "A",
    "benefit_code": "BEN-001",
    "sub_benefit_code": "SUB-BEN-001",
    "limit": 5000
  }'

const response = await fetch(
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/template/sub-benefit",
  {
    method: "PATCH",
    headers: {
      "access-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ph_erp_id: "PH-ERP-12345",
      policy_no: "POL-2024-001",
      category_code: "A",
      benefit_code: "BEN-001",
      sub_benefit_code: "SUB-BEN-001",
      limit: 5000,
    }),
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/template/sub-benefit"

payload = {
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "category_code": "A",
    "benefit_code": "BEN-001",
    "sub_benefit_code": "SUB-BEN-001",
    "limit": 5000,
}

headers = {
    "access-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.patch(url, json=payload, headers=headers)
print(response.json())

Response

Success Response (200 OK)

Returns the updated sub-benefit template data.

Error Responses

Error Codes

Error Code	HTTP Status	Description
`E_BAD_REQUEST_400`	400	Request validation failed -- see the `details` array for field-level errors
`401 Unauthorized`	401	Missing or invalid `access-key`
`E_EPH_01`	404	Policy holder not found
`E_EPA_014`	404	Policy not found
`E_EBA_01`	404	Benefit not found
`E_EBA_02`	404	Sub-benefit not found

Example Error Responses

Sub-Benefit Not Found:

{
  "ErrorCode": "E_EBA_02",
  "message": "Sub benefit not found",
  "details": []
}

Patient Policy - Operations

Patient consumption endpoints manage per-patient benefit and sub-benefit tracking within a policy. These are used to set up and update the individual consumption records that track how much of each benefit a patient has utilized.

Add Benefit to Patient-Policy

POST /policy/patient/consumption/benefit

Add a benefit entry to a patient's consumption record under a specific policy.

Request Body

Parameter	Type	Required	Description	Accepted Values
`ph_erp_id` *	string	Yes	ERP ID of the policy holder	Alphanumeric string
`policy_no` *	string	Yes	Policy number	Alphanumeric string
`member_id` *	string	Yes	Member ID of the patient	Alphanumeric string
`benefit_code` *	string	Yes	Benefit code to add	Alphanumeric string
`benefit_description`	string	No	Description of the benefit	String, max 255 characters
`limit` *	number	Yes	Benefit limit for this patient	Decimal, minimum 0
`utilized`	number	No	Amount already utilized	Decimal, minimum 0 (default: `0`)

Code Examples

cURL
JavaScript
Python

curl -X POST \
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/patient/consumption/benefit" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "member_id": "MEMBER001",
    "benefit_code": "BEN-001",
    "benefit_description": "Outpatient Benefits",
    "limit": 10000,
    "utilized": 0
  }'

const response = await fetch(
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/patient/consumption/benefit",
  {
    method: "POST",
    headers: {
      "access-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ph_erp_id: "PH-ERP-12345",
      policy_no: "POL-2024-001",
      member_id: "MEMBER001",
      benefit_code: "BEN-001",
      benefit_description: "Outpatient Benefits",
      limit: 10000,
      utilized: 0,
    }),
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/patient/consumption/benefit"

payload = {
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "member_id": "MEMBER001",
    "benefit_code": "BEN-001",
    "benefit_description": "Outpatient Benefits",
    "limit": 10000,
    "utilized": 0,
}

headers = {
    "access-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

Success Response (201 Created)

{
  "code": 201,
  "message": "Created successfully"
}

Response Fields

Field	Type	Description
`code`	number	HTTP status code (`201`)
`message`	string	Success message

Error Responses

Error Codes

Error Code	HTTP Status	Description
`E_BAD_REQUEST_400`	400	Request validation failed -- see the `details` array for field-level errors
`401 Unauthorized`	401	Missing or invalid `access-key`
`E_EPH_01`	404	Policy holder not found
`E_EPA_014`	404	Policy not found
`E_EPA_01`	404	Patient not found
`E_EBA_01`	404	Benefit not found
`E_EPA_069`	409	Benefit consumption already exists for this patient

Example Error Responses

Benefit Not Found:

{
  "ErrorCode": "E_EBA_01",
  "message": "Benefit not found",
  "details": []
}

Conflict:

{
  "ErrorCode": "E_EPA_069",
  "message": "Benefit consumption already exists for this patient",
  "details": []
}

Add Sub-Benefit to Patient-Policy

POST /policy/patient/consumption/sub-benefit

Add a sub-benefit entry to a patient's consumption record under a specific policy.

Request Body

Parameter	Type	Required	Description	Accepted Values
`ph_erp_id` *	string	Yes	ERP ID of the policy holder	Alphanumeric string
`policy_no` *	string	Yes	Policy number	Alphanumeric string
`member_id` *	string	Yes	Member ID of the patient	Alphanumeric string
`benefit_code` *	string	Yes	Parent benefit code	Alphanumeric string
`benefit_description`	string	No	Description of the benefit	String, max 255 characters
`sub_benefit_code` *	string	Yes	Sub-benefit code to add	Alphanumeric string
`sub_benefit_description`	string	No	Description of the sub-benefit	String, max 255 characters
`limit` *	number	Yes	Sub-benefit limit for this patient	Decimal, minimum 0
`utilized`	number	No	Amount already utilized	Decimal, minimum 0 (default: `0`)

Code Examples

cURL
JavaScript
Python

curl -X POST \
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/patient/consumption/sub-benefit" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "member_id": "MEMBER001",
    "benefit_code": "BEN-001",
    "benefit_description": "Outpatient Benefits",
    "sub_benefit_code": "SUB-BEN-001",
    "sub_benefit_description": "Consultation",
    "limit": 3000,
    "utilized": 0
  }'

const response = await fetch(
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/patient/consumption/sub-benefit",
  {
    method: "POST",
    headers: {
      "access-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ph_erp_id: "PH-ERP-12345",
      policy_no: "POL-2024-001",
      member_id: "MEMBER001",
      benefit_code: "BEN-001",
      benefit_description: "Outpatient Benefits",
      sub_benefit_code: "SUB-BEN-001",
      sub_benefit_description: "Consultation",
      limit: 3000,
      utilized: 0,
    }),
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/patient/consumption/sub-benefit"

payload = {
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "member_id": "MEMBER001",
    "benefit_code": "BEN-001",
    "benefit_description": "Outpatient Benefits",
    "sub_benefit_code": "SUB-BEN-001",
    "sub_benefit_description": "Consultation",
    "limit": 3000,
    "utilized": 0,
}

headers = {
    "access-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response

Success Response (201 Created)

{
  "code": 201,
  "message": "Created successfully"
}

Response Fields

Field	Type	Description
`code`	number	HTTP status code (`201`)
`message`	string	Success message

Error Responses

Error Codes

Error Code	HTTP Status	Description
`E_BAD_REQUEST_400`	400	Request validation failed -- see the `details` array for field-level errors
`401 Unauthorized`	401	Missing or invalid `access-key`
`E_EPH_01`	404	Policy holder not found
`E_EPA_014`	404	Policy not found
`E_EPA_01`	404	Patient not found
`E_EBA_01`	404	Benefit not found
`E_EBA_02`	404	Sub-benefit not found
`E_EPA_069`	409	Sub-benefit consumption already exists for this patient

Example Error Responses

Sub-Benefit Not Found:

{
  "ErrorCode": "E_EBA_02",
  "message": "Sub benefit not found",
  "details": []
}

Update Benefit Patient Consumption

PATCH /policy/patient/consumption/benefit

Update a patient's benefit consumption record, such as adjusting the limit or utilized amount.

Request Body

Parameter	Type	Required	Description	Accepted Values
`ph_erp_id` *	string	Yes	ERP ID of the policy holder	Alphanumeric string
`policy_no` *	string	Yes	Policy number	Alphanumeric string
`member_id` *	string	Yes	Member ID of the patient	Alphanumeric string
`benefit_code` *	string	Yes	Benefit code to update	Alphanumeric string
`limit`	number	No	Updated benefit limit	Decimal, minimum 0
`utilized`	number	No	Updated utilized amount	Decimal, minimum 0

Code Examples

cURL
JavaScript
Python

curl -X PATCH \
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/patient/consumption/benefit" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "member_id": "MEMBER001",
    "benefit_code": "BEN-001",
    "limit": 12000,
    "utilized": 2500
  }'

const response = await fetch(
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/patient/consumption/benefit",
  {
    method: "PATCH",
    headers: {
      "access-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ph_erp_id: "PH-ERP-12345",
      policy_no: "POL-2024-001",
      member_id: "MEMBER001",
      benefit_code: "BEN-001",
      limit: 12000,
      utilized: 2500,
    }),
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/patient/consumption/benefit"

payload = {
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "member_id": "MEMBER001",
    "benefit_code": "BEN-001",
    "limit": 12000,
    "utilized": 2500,
}

headers = {
    "access-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.patch(url, json=payload, headers=headers)
print(response.json())

Response

Success Response (200 OK)

Returns the updated benefit consumption data.

Error Responses

Error Codes

Error Code	HTTP Status	Description
`E_BAD_REQUEST_400`	400	Request validation failed -- see the `details` array for field-level errors
`401 Unauthorized`	401	Missing or invalid `access-key`
`E_EPH_01`	404	Policy holder not found
`E_EPA_014`	404	Policy not found
`E_EPA_01`	404	Patient not found
`E_EBA_01`	404	Benefit not found

Example Error Responses

Patient Not Found:

{
  "ErrorCode": "E_EPA_01",
  "message": "Patient not found",
  "details": []
}

Update Sub-Benefit Patient Consumption

PATCH /policy/patient/consumption/sub-benefit

Update a patient's sub-benefit consumption record, such as adjusting the limit or utilized amount.

Request Body

Parameter	Type	Required	Description	Accepted Values
`ph_erp_id` *	string	Yes	ERP ID of the policy holder	Alphanumeric string
`policy_no` *	string	Yes	Policy number	Alphanumeric string
`member_id` *	string	Yes	Member ID of the patient	Alphanumeric string
`benefit_code` *	string	Yes	Parent benefit code	Alphanumeric string
`sub_benefit_code` *	string	Yes	Sub-benefit code to update	Alphanumeric string
`limit`	number	No	Updated sub-benefit limit	Decimal, minimum 0
`utilized`	number	No	Updated utilized amount	Decimal, minimum 0

Code Examples

cURL
JavaScript
Python

curl -X PATCH \
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/patient/consumption/sub-benefit" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "member_id": "MEMBER001",
    "benefit_code": "BEN-001",
    "sub_benefit_code": "SUB-BEN-001",
    "limit": 4000,
    "utilized": 800
  }'

const response = await fetch(
  "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/patient/consumption/sub-benefit",
  {
    method: "PATCH",
    headers: {
      "access-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ph_erp_id: "PH-ERP-12345",
      policy_no: "POL-2024-001",
      member_id: "MEMBER001",
      benefit_code: "BEN-001",
      sub_benefit_code: "SUB-BEN-001",
      limit: 4000,
      utilized: 800,
    }),
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy/patient/consumption/sub-benefit"

payload = {
    "ph_erp_id": "PH-ERP-12345",
    "policy_no": "POL-2024-001",
    "member_id": "MEMBER001",
    "benefit_code": "BEN-001",
    "sub_benefit_code": "SUB-BEN-001",
    "limit": 4000,
    "utilized": 800,
}

headers = {
    "access-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.patch(url, json=payload, headers=headers)
print(response.json())

Response

Success Response (200 OK)

Returns the updated sub-benefit consumption data.

Error Responses

Error Codes

Error Code	HTTP Status	Description
`E_BAD_REQUEST_400`	400	Request validation failed -- see the `details` array for field-level errors
`401 Unauthorized`	401	Missing or invalid `access-key`
`E_EPH_01`	404	Policy holder not found
`E_EPA_014`	404	Policy not found
`E_EPA_01`	404	Patient not found
`E_EBA_01`	404	Benefit not found
`E_EBA_02`	404	Sub-benefit not found

Example Error Responses

Sub-Benefit Not Found:

{
  "ErrorCode": "E_EBA_02",
  "message": "Sub benefit not found",
  "details": []
}

Base URL​

Authentication​

Policy Management​

Create Policy​

Request Body​

Code Examples​

Response​

Success Response (201 Created)​

Response Fields​

Error Responses​

Error Codes​

Example Error Responses​

Update Policy​

Query Parameters​

Request Body​

Code Examples​

Response​

Success Response (200 OK)​

Response Fields​

Error Responses​

Error Codes​

Example Error Responses​

Get Patient Consumption​

Query Parameters​

Code Examples​

Response​

Success Response (200 OK)​

Response Fields​

Error Responses​

Error Codes​

Example Error Responses​

Patient-Policy Operations​

Add Bulk Patients to Policy Synchronously​

Request Body​

Code Examples​

Response​

Success Response (200 OK)​

Error Responses​

Error Codes​

Example Error Responses​

Async Bulk Add Patients to Policy​

Request Body​

Code Examples​

Response​

Success Response (202 Accepted)​

Response Fields​

Error Responses​

Error Codes​

Example Error Responses​

Update Patient-Policy​

Query Parameters​

Request Body​

Code Examples​

Response​

Success Response (200 OK)​

Error Responses​

Error Codes​

Example Error Responses​

Policy Template Operations​

Add Category to Template​

Request Body​

Code Examples​

Response​

Success Response (201 Created)​

Response Fields​

Error Responses​

Error Codes​

Example Error Responses​

Add Benefit to Template​

Request Body​

Code Examples​

Response​

Success Response (201 Created)​

Response Fields​

Error Responses​

Error Codes​

Example Error Responses​

Add Sub-Benefit to Template​

Request Body​

Code Examples​

Base URL

Authentication

Policy Management

Create Policy

Request Body

Code Examples

Response

Success Response (201 Created)

Response Fields

Error Responses

Error Codes

Example Error Responses

Update Policy

Query Parameters

Request Body

Code Examples

Response

Success Response (200 OK)

Response Fields

Error Responses

Error Codes

Example Error Responses

Get Patient Consumption

Query Parameters

Code Examples

Response

Success Response (200 OK)

Response Fields

Error Responses

Error Codes

Example Error Responses

Patient-Policy Operations

Add Bulk Patients to Policy Synchronously

Request Body

Code Examples

Response

Success Response (200 OK)

Error Responses

Error Codes

Example Error Responses

Async Bulk Add Patients to Policy

Request Body

Code Examples

Response

Success Response (202 Accepted)

Response Fields

Error Responses

Error Codes

Example Error Responses

Update Patient-Policy

Query Parameters

Request Body

Code Examples

Response

Success Response (200 OK)

Error Responses

Error Codes

Example Error Responses

Policy Template Operations

Add Category to Template

Request Body

Code Examples

Response

Success Response (201 Created)

Response Fields

Error Responses

Error Codes

Example Error Responses

Add Benefit to Template

Request Body

Code Examples

Response

Success Response (201 Created)

Response Fields

Error Responses

Error Codes

Example Error Responses

Add Sub-Benefit to Template

Request Body

Code Examples