Policy Holder

important

Policy holders must be created before creating policies. The ph_erp_id is used to link policies to their holder.

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.

API Endpoints

Create Policy Holder

POST /policy-holder/create

Creates a new policy holder record.

Request Headers

Header	Type	Required	Description
access-key	string	Yes	API key for authentication
Content-Type	string	Yes	Must be application/json

Request Body Parameters

Parameter	Type	Required	Description	Accepted Values
ph_erp_id *	string	Yes	ERP code of the policy holder. Must be unique across the system.	Alphanumeric string, 1-50 characters
name *	string	Yes	Name of the policy holder.	String, 1-255 characters
insurance_type	string	Yes	Insurance type of the policy holder.	Enum: NORMAL, VIP, VVIP
province	string	No	Province of the policy holder.	String, 1-255 characters
registration_number	string	No	Registration number. Must be unique if provided.	String, 1-255 characters

Response

Success Response (201 Created)

{
  "ERPCode": "PH-ERP-12345",
  "code": 201,
  "message": "Created successfully"
}

Response Fields

Field	Type	Description
ERPCode	string	ERP code of the created policy holder
code	number	HTTP status code (201)
message	string	Success message

Error Responses

Error Response Structure

{
  "code": "number",
  "message": "string"
}

Error Codes

Error Code	HTTP Status	Description
400	400	Request validation failed — required fields missing or invalid
409	409	Conflict — duplicate ERP code, name, or registration number

Example Error Responses

Bad Request:

{
  "code": 400,
  "message": "Validation error: 'name' is required"
}

Conflict:

{
  "code": 409,
  "message": "Duplicate ERP code: PH-ERP-12345 already exists"
}

Conflict Reasons

A 409 Conflict error is returned when:

• A policy holder with the same ph_erp_id already exists
• A policy holder with the same name already exists
• A policy holder with the same registration_number already exists

Code Examples

cURL

curl -X POST "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy-holder/create" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ph_erp_id": "PH-ERP-12345",
    "name": "Acme Insurance Holdings",
    "insurance_type": "NORMAL",
    "province": "Riyadh",
    "registration_number": "REG-2024-001"
  }'

JavaScript

const response = await fetch(
  'https://api.{client_namespace}.najeeb.ai/v4.0/health/policy-holder/create',
  {
    method: 'POST',
    headers: {
      'access-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      ph_erp_id: 'PH-ERP-12345',
      name: 'Acme Insurance Holdings',
      insurance_type: 'NORMAL',
      province: 'Riyadh',
      registration_number: 'REG-2024-001',
    }),
  }
);

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

Python

import requests

response = requests.post(
    'https://api.{client_namespace}.najeeb.ai/v4.0/health/policy-holder/create',
    headers={
        'access-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'ph_erp_id': 'PH-ERP-12345',
        'name': 'Acme Insurance Holdings',
        'insurance_type': 'NORMAL',
        'province': 'Riyadh',
        'registration_number': 'REG-2024-001',
    },
)

result = response.json()
print(result)

Update Policy Holder

PATCH /policy-holder/update

Updates an existing policy holder identified by its ERP code.

Request Headers

Header	Type	Required	Description
access-key	string	Yes	API key for authentication
Content-Type	string	Yes	Must be application/json

Request Body Parameters

Parameter	Type	Required	Description	Accepted Values
identifier *	string	Yes	ERP code of the policy holder to update.	Alphanumeric string, 1-50 characters
name	string	No	Updated name of the policy holder.	String, 1-255 characters
province	string	No	Updated province.	String, 1-255 characters
registration_number	string	No	Updated registration number. Must be unique if provided.	String, 1-255 characters
insurance_type	string	No	Updated insurance type.	Enum: NORMAL, VIP, VVIP

Response

Success Response (200 OK)

{
  "message": "Policy holder updated successfully",
  "data": {
    "ph_erp_id": "PH-ERP-12345",
    "name": "Acme Insurance Holdings International",
    "insurance_type": "NORMAL",
    "province": "Jeddah",
    "registration_number": "REG-2024-001"
  }
}

Response Fields

Field	Type	Description
message	string	Success message
data	object	Updated policy holder object
data.ph_erp_id	string	ERP code of the policy holder
data.name	string	Name of the policy holder
data.insurance_type	string	Insurance type
data.province	string	Province
data.registration_number	string	Registration number

Error Responses

Error Response Structure

{
  "code": "number",
  "message": "string"
}

Error Codes

Error Code	HTTP Status	Description
400	400	Request validation failed — invalid field values
404	404	Policy holder not found for the provided identifier
409	409	Conflict — updated values conflict with an existing policy holder

Example Error Responses

Bad Request:

{
  "code": 400,
  "message": "Validation error: 'identifier' is required"
}

Not Found:

{
  "code": 404,
  "message": "Policy holder not found"
}

Conflict:

{
  "code": 409,
  "message": "Duplicate name: a policy holder with this name already exists"
}

Code Examples

cURL

curl -X PATCH "https://api.{client_namespace}.najeeb.ai/v4.0/health/policy-holder/update" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "PH-ERP-12345",
    "name": "Acme Insurance Holdings International",
    "province": "Jeddah"
  }'

JavaScript

const response = await fetch(
  'https://api.{client_namespace}.najeeb.ai/v4.0/health/policy-holder/update',
  {
    method: 'PATCH',
    headers: {
      'access-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      identifier: 'PH-ERP-12345',
      name: 'Acme Insurance Holdings International',
      province: 'Jeddah',
    }),
  }
);

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

Python

import requests

response = requests.patch(
    'https://api.{client_namespace}.najeeb.ai/v4.0/health/policy-holder/update',
    headers={
        'access-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'identifier': 'PH-ERP-12345',
        'name': 'Acme Insurance Holdings International',
        'province': 'Jeddah',
    },
)

result = response.json()
print(result)