Skip to main content

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​

ParameterTypeRequiredDescriptionAccepted Values
policy_no *stringYesUnique policy numberAlphanumeric string (e.g., POL-2024-001)
start_date *stringYesPolicy start dateISO date
end_date *stringYesPolicy end dateISO date
created_date *stringYesDate the policy was createdISO date
status *stringYesPolicy statusEnum: ACTIVE, INACTIVE, EXPIRED
ph_erp_id *stringYesERP ID of the policy holder that owns this policyAlphanumeric string
add_patient_to_policyobjectNoNested object to simultaneously add a patient to the policySee nested object below

add_patient_to_policy nested object:

ParameterTypeRequiredDescriptionAccepted Values
member_id *stringYesMember ID of the patient to addAlphanumeric string
network_codestringNoCode of the network to associateAlphanumeric string
category_code *stringYesCategory code for the patient within the policyAlphanumeric string
start_date *stringYesPatient-policy start dateISO date
end_date *stringYesPatient-policy end dateISO date

Code Examples​

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"
    }
  }'

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​
FieldTypeDescription
policy_nostringThe policy number of the created policy
start_datestringPolicy start date
end_datestringPolicy end date
created_datestringDate the policy was created
statusstringPolicy status
ph_erp_idstringERP ID of the policy holder
codenumberHTTP status code (201)
messagestringSuccess message

Error Responses​

Error Codes​
Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400Request validation failed -- see the details array for field-level errors
401 Unauthorized401Missing or invalid access-key
E_EPH_01404Policy holder not found
E_EPA_01404Patient not found
E_EPA_015404Network not found
E_EPA_069409Policy 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​

ParameterTypeRequiredDescriptionAccepted Values
ph_erp_id *stringYesERP ID of the policy holderAlphanumeric string
policy_no *stringYesPolicy number of the policy to updateAlphanumeric string

Request Body​

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

ParameterTypeRequiredDescriptionAccepted Values
start_datestringNoUpdated start dateISO date
end_datestringNoUpdated end dateISO date
statusstringNoUpdated policy statusEnum: ACTIVE, INACTIVE, EXPIRED
plan_codestringNoPlan code to associate with the policyAlphanumeric string

Code Examples​

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"
  }'

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​
FieldTypeDescription
policy_nostringThe policy number
start_datestringPolicy start date
end_datestringUpdated policy end date
created_datestringDate the policy was created
statusstringCurrent policy status
ph_erp_idstringERP ID of the policy holder
codenumberHTTP status code (200)
messagestringSuccess message

Error Responses​

Error Codes​
Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400Request validation failed -- see the details array for field-level errors
401 Unauthorized401Missing or invalid access-key
E_EPH_01404Policy holder not found
E_EPA_014404Policy 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​

ParameterTypeRequiredDescriptionAccepted Values
ph_erp_id *stringYesERP ID of the policy holderAlphanumeric string
policy_no *stringYesPolicy numberAlphanumeric string
member_id *stringYesMember ID of the patientAlphanumeric string

Code Examples​

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"

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​
FieldTypeDescription
member_idstringMember ID of the patient
category_codestringCategory code for the patient within the policy
amount_eligiblenumberTotal amount eligible under the policy
amount_exgratianumberTotal ex-gratia amount available
amount_utilizednumberTotal amount utilized by the patient
benefit_consumptionarrayArray of benefit consumption objects
benefit_consumption[].benefit_codestringBenefit code
benefit_consumption[].limitnumberMaximum limit for the benefit
benefit_consumption[].utilizednumberAmount utilized for the benefit
sub_benefit_consumptionarrayArray of sub-benefit consumption objects
sub_benefit_consumption[].sub_benefit_codestringSub-benefit code
sub_benefit_consumption[].limitnumberMaximum limit for the sub-benefit
sub_benefit_consumption[].utilizednumberAmount utilized for the sub-benefit

Error Responses​

Error Codes​
Error CodeHTTP StatusDescription
401 Unauthorized401Missing or invalid access-key
E_EPH_01404Policy holder not found
E_EPA_014404Policy not found
E_EPA_01404Patient 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​

ParameterTypeRequiredDescriptionAccepted Values
policy_no *stringYesPolicy numberAlphanumeric string
ph_erp_id *stringYesERP ID of the policy holderAlphanumeric string
patients *arrayYesArray of patient objects to add to the policySee patient object below

Patient object:

ParameterTypeRequiredDescriptionAccepted Values
cardstringNoCard numberAlphanumeric string
member_id *stringYesMember ID of the patientAlphanumeric string
namestringNoPatient nameString, 1-255 characters
emailstringNoPatient email addressValid email format
relationstringNoRelationship to policy holderEnum: SELF, FATHER, MOTHER, SON, DAUGHTER, SISTER, HUSBAND, WIFE, WIFE_WITHOUT_MATERNITY, MOTHER_MB, SENIOR_EMPLOYEE, FEMALE_EMPLOYEE_WITH_MAT, CHILD, SPOUSE, EMPLOYEE, OTHER
national_idstringNoNational ID numberAlphanumeric string
visit_visa_numberstringNoVisit visa numberAlphanumeric string
passportstringNoPassport numberAlphanumeric string
phone_numberstringNoPhone numberString (e.g., +966555555555)
addressstringNoPatient addressString, max 500 characters
gender *stringYesPatient genderEnum: MALE, FEMALE
marital_status *stringYesMarital statusEnum: SINGLE, MARRIED, ENGAGED, UNKNOWN, WIDOWED, DIVORCED, SEPARATED
nationalitystringNoPatient nationalityString
date_of_birth *stringYesDate of birthISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
network_codestringNoNetwork code to associateAlphanumeric string
is_vipbooleanNoVIP flagtrue, false (default: false)
insured_notesstringNoNotes about the insured patientString, max 500 characters
category_code *stringYesCategory code for the patientAlphanumeric string
additional_datestringNoAdditional date (e.g., policy addition date)ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
effective_start_date *stringYesCoverage start dateISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
effective_end_date *stringYesCoverage end dateISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ

Code Examples​

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"
      }
    ]
  }'

Response​

Success Response (200 OK)​

Returns a summary of the bulk operation results.

Error Responses​

Error Codes​
Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400Request validation failed -- see the details array for field-level errors
401 Unauthorized401Missing or invalid access-key
E_EPA_014404Policy not found
E_EPA_015404Network not found
E_EPA_01404Patient not found
E_EPA_069409Patient 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 -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"
      }
    ]
  }'

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​
FieldTypeDescription
job_idstringUnique identifier for the queued job
messagestringConfirmation message
Webhook Delivery

Register a Webhook to receive the results of the async bulk operation once processing is complete.

Error Responses​

Error Codes​
Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400Request validation failed -- see the details array for field-level errors
401 Unauthorized401Missing or invalid access-key
E_EPA_014404Policy not found
E_EPA_015404Network not found
E_EPA_01404Patient 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​

ParameterTypeRequiredDescriptionAccepted Values
ph_erp_id *stringYesERP ID of the policy holderAlphanumeric string
policy_no *stringYesPolicy numberAlphanumeric string
member_id *stringYesMember ID of the patientAlphanumeric string

Request Body​

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

ParameterTypeRequiredDescriptionAccepted Values
network_codestringNoUpdated network codeAlphanumeric string
category_codestringNoUpdated category codeAlphanumeric string
start_datestringNoUpdated start dateISO date
end_datestringNoUpdated end dateISO date
statusstringNoUpdated patient-policy statusEnum: ACTIVE, INACTIVE, EXPIRED

Code Examples​

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"
  }'

Response​

Success Response (200 OK)​

Returns the updated patient-policy data.

Error Responses​

Error Codes​
Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400Request validation failed -- see the details array for field-level errors
401 Unauthorized401Missing or invalid access-key
E_EPH_01404Policy holder not found
E_EPA_014404Policy not found
E_EPA_01404Patient 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​

ParameterTypeRequiredDescriptionAccepted Values
ph_erp_id *stringYesERP ID of the policy holderAlphanumeric string
policy_no *stringYesPolicy numberAlphanumeric string
category_code *stringYesUnique code for the categoryAlphanumeric string
amount_eligible *numberYesMaximum amount eligible under this categoryDecimal, minimum 0

Code Examples​

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
  }'

Response​

Success Response (201 Created)​
{
  "code": 201,
  "message": "Created successfully"
}
Response Fields​
FieldTypeDescription
codenumberHTTP status code (201)
messagestringSuccess message

Error Responses​

Error Codes​
Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400Request validation failed -- see the details array for field-level errors
401 Unauthorized401Missing or invalid access-key
E_EPH_01404Policy holder not found
E_EPA_014404Policy 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​

ParameterTypeRequiredDescriptionAccepted Values
ph_erp_id *stringYesERP ID of the policy holderAlphanumeric string
policy_no *stringYesPolicy numberAlphanumeric string
category_code *stringYesCategory code the benefit belongs toAlphanumeric string
benefit_code *stringYesUnique code for the benefitAlphanumeric string
benefit_descriptionstringNoDescription of the benefitString, max 255 characters
limit *numberYesMaximum limit for this benefitDecimal, minimum 0
sub_benefitsarrayNoArray of sub-benefit objects to add simultaneouslySee sub-benefit object below

sub_benefits nested object:

ParameterTypeRequiredDescriptionAccepted Values
sub_benefit_code *stringYesUnique code for the sub-benefitAlphanumeric string
sub_benefit_descriptionstringNoDescription of the sub-benefitString, max 255 characters
limit *numberYesMaximum limit for this sub-benefitDecimal, minimum 0

Code Examples​

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
      }
    ]
  }'

Response​

Success Response (201 Created)​
{
  "code": 201,
  "message": "Created successfully"
}
Response Fields​
FieldTypeDescription
codenumberHTTP status code (201)
messagestringSuccess message

Error Responses​

Error Codes​
Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400Request validation failed -- see the details array for field-level errors
401 Unauthorized401Missing or invalid access-key
E_EPH_01404Policy holder not found
E_EPA_014404Policy 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​

ParameterTypeRequiredDescriptionAccepted Values
ph_erp_id *stringYesERP ID of the policy holderAlphanumeric string
policy_no *stringYesPolicy numberAlphanumeric string
category_code *stringYesCategory codeAlphanumeric string
benefit_code *stringYesBenefit code the sub-benefit belongs toAlphanumeric string
benefit_descriptionstringNoDescription of the benefitString, max 255 characters
sub_benefit_code *stringYesUnique code for the sub-benefitAlphanumeric string
sub_benefit_descriptionstringNoDescription of the sub-benefitString, max 255 characters
limit *numberYesMaximum limit for this sub-benefitDecimal, minimum 0

Code Examples​

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
  }'

Response​

Success Response (201 Created)​
{
  "code": 201,
  "message": "Created successfully"
}
Response Fields​
FieldTypeDescription
codenumberHTTP status code (201)
messagestringSuccess message

Error Responses​

Error Codes​
Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400Request validation failed -- see the details array for field-level errors
401 Unauthorized401Missing or invalid access-key
E_EPH_01404Policy holder not found
E_EPA_014404Policy not found
E_EBA_01404Benefit 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​

ParameterTypeRequiredDescriptionAccepted Values
ph_erp_id *stringYesERP ID of the policy holderAlphanumeric string
policy_no *stringYesPolicy numberAlphanumeric string
category_code *stringYesCategory code to updateAlphanumeric string
amount_eligible *numberYesUpdated maximum amount eligibleDecimal, minimum 0

Code Examples​

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
  }'

Response​

Success Response (200 OK)​

Returns the updated category template data.

Error Responses​

Error Codes​
Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400Request validation failed -- see the details array for field-level errors
401 Unauthorized401Missing or invalid access-key
E_EPH_01404Policy holder not found
E_EPA_014404Policy 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​

ParameterTypeRequiredDescriptionAccepted Values
ph_erp_id *stringYesERP ID of the policy holderAlphanumeric string
policy_no *stringYesPolicy numberAlphanumeric string
category_code *stringYesCategory code the benefit belongs toAlphanumeric string
benefit_code *stringYesBenefit code to updateAlphanumeric string
limit *numberYesUpdated maximum limit for the benefitDecimal, minimum 0

Code Examples​

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
  }'

Response​

Success Response (200 OK)​

Returns the updated benefit template data.

Error Responses​

Error Codes​
Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400Request validation failed -- see the details array for field-level errors
401 Unauthorized401Missing or invalid access-key
E_EPH_01404Policy holder not found
E_EPA_014404Policy not found
E_EBA_01404Benefit 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​

ParameterTypeRequiredDescriptionAccepted Values
ph_erp_id *stringYesERP ID of the policy holderAlphanumeric string
policy_no *stringYesPolicy numberAlphanumeric string
category_code *stringYesCategory codeAlphanumeric string
benefit_code *stringYesBenefit code the sub-benefit belongs toAlphanumeric string
sub_benefit_code *stringYesSub-benefit code to updateAlphanumeric string
limit *numberYesUpdated maximum limit for the sub-benefitDecimal, minimum 0

Code Examples​

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
  }'

Response​

Success Response (200 OK)​

Returns the updated sub-benefit template data.

Error Responses​

Error Codes​
Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400Request validation failed -- see the details array for field-level errors
401 Unauthorized401Missing or invalid access-key
E_EPH_01404Policy holder not found
E_EPA_014404Policy not found
E_EBA_01404Benefit not found
E_EBA_02404Sub-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​

ParameterTypeRequiredDescriptionAccepted Values
ph_erp_id *stringYesERP ID of the policy holderAlphanumeric string
policy_no *stringYesPolicy numberAlphanumeric string
member_id *stringYesMember ID of the patientAlphanumeric string
benefit_code *stringYesBenefit code to addAlphanumeric string
benefit_descriptionstringNoDescription of the benefitString, max 255 characters
limit *numberYesBenefit limit for this patientDecimal, minimum 0
utilizednumberNoAmount already utilizedDecimal, minimum 0 (default: 0)

Code Examples​

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
  }'

Response​

Success Response (201 Created)​
{
  "code": 201,
  "message": "Created successfully"
}
Response Fields​
FieldTypeDescription
codenumberHTTP status code (201)
messagestringSuccess message

Error Responses​

Error Codes​
Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400Request validation failed -- see the details array for field-level errors
401 Unauthorized401Missing or invalid access-key
E_EPH_01404Policy holder not found
E_EPA_014404Policy not found
E_EPA_01404Patient not found
E_EBA_01404Benefit not found
E_EPA_069409Benefit 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​

ParameterTypeRequiredDescriptionAccepted Values
ph_erp_id *stringYesERP ID of the policy holderAlphanumeric string
policy_no *stringYesPolicy numberAlphanumeric string
member_id *stringYesMember ID of the patientAlphanumeric string
benefit_code *stringYesParent benefit codeAlphanumeric string
benefit_descriptionstringNoDescription of the benefitString, max 255 characters
sub_benefit_code *stringYesSub-benefit code to addAlphanumeric string
sub_benefit_descriptionstringNoDescription of the sub-benefitString, max 255 characters
limit *numberYesSub-benefit limit for this patientDecimal, minimum 0
utilizednumberNoAmount already utilizedDecimal, minimum 0 (default: 0)

Code Examples​

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
  }'

Response​

Success Response (201 Created)​
{
  "code": 201,
  "message": "Created successfully"
}
Response Fields​
FieldTypeDescription
codenumberHTTP status code (201)
messagestringSuccess message

Error Responses​

Error Codes​
Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400Request validation failed -- see the details array for field-level errors
401 Unauthorized401Missing or invalid access-key
E_EPH_01404Policy holder not found
E_EPA_014404Policy not found
E_EPA_01404Patient not found
E_EBA_01404Benefit not found
E_EBA_02404Sub-benefit not found
E_EPA_069409Sub-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​

ParameterTypeRequiredDescriptionAccepted Values
ph_erp_id *stringYesERP ID of the policy holderAlphanumeric string
policy_no *stringYesPolicy numberAlphanumeric string
member_id *stringYesMember ID of the patientAlphanumeric string
benefit_code *stringYesBenefit code to updateAlphanumeric string
limitnumberNoUpdated benefit limitDecimal, minimum 0
utilizednumberNoUpdated utilized amountDecimal, minimum 0

Code Examples​

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
  }'

Response​

Success Response (200 OK)​

Returns the updated benefit consumption data.

Error Responses​

Error Codes​
Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400Request validation failed -- see the details array for field-level errors
401 Unauthorized401Missing or invalid access-key
E_EPH_01404Policy holder not found
E_EPA_014404Policy not found
E_EPA_01404Patient not found
E_EBA_01404Benefit 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​

ParameterTypeRequiredDescriptionAccepted Values
ph_erp_id *stringYesERP ID of the policy holderAlphanumeric string
policy_no *stringYesPolicy numberAlphanumeric string
member_id *stringYesMember ID of the patientAlphanumeric string
benefit_code *stringYesParent benefit codeAlphanumeric string
sub_benefit_code *stringYesSub-benefit code to updateAlphanumeric string
limitnumberNoUpdated sub-benefit limitDecimal, minimum 0
utilizednumberNoUpdated utilized amountDecimal, minimum 0

Code Examples​

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
  }'

Response​

Success Response (200 OK)​

Returns the updated sub-benefit consumption data.

Error Responses​

Error Codes​
Error CodeHTTP StatusDescription
E_BAD_REQUEST_400400Request validation failed -- see the details array for field-level errors
401 Unauthorized401Missing or invalid access-key
E_EPH_01404Policy holder not found
E_EPA_014404Policy not found
E_EPA_01404Patient not found
E_EBA_01404Benefit not found
E_EBA_02404Sub-benefit not found
Example Error Responses​

Sub-Benefit Not Found:

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