Member (Patient)

The Member module provides endpoints for registering and managing members (patients) within the Najeeb system. Members represent the insured individuals who receive healthcare services. Each member must be associated with a Policy to be eligible for pre-authorization and claims processing.

Base URL

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

معلومات

Replace {client_namespace} with your organization's assigned namespace provided during onboarding.

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.

Create Member

POST /member/create

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
`member_id` *	string	Yes	Unique identifier for the member	Alphanumeric string, 1-255 characters
`national_id` *	string	Yes	National ID of the member	Alphanumeric string, 1-255 characters
`gender` *	string	Yes	Gender of the member	Enum: `MALE`, `FEMALE`
`marital_status` *	string	Yes	Marital status of the member	Enum: `SINGLE`, `MARRIED`, `ENGAGED`, `UNKNOWN`, `WIDOWED`, `DIVORCED`, `SEPARATED`
`date_of_birth` *	string	Yes	Date of birth of the member	ISO 8601 format: `YYYY-MM-DDTHH:mm:ss.sssZ`
`name`	string	No	Full name of the member	String, 1-255 characters
`card`	string	No	Insurance card number	String, 1-255 characters
`email`	string	No	Email address of the member	Valid email format, max 255 characters
`relation`	string	No	Relation to the primary subscriber	Enum: `SELF`, `FATHER`, `MOTHER`, `SON`, `DAUGHTER`, `SISTER`, `HUSBAND`, `WIFE`, `WIFE_WITHOUT_MATERNITY`, `MOTHER_MB`, `SENIOR_EMPLOYEE`, `FEMALE_EMPLOYEE_WITH_MAT`, `CHILD`, `SPOUSE`, `EMPLOYEE`, `OTHER`
`passport`	string	No	Passport number	String, 1-255 characters
`visit_visa_number`	string	No	Visit visa number	String, 1-255 characters
`phone_number`	string	No	Phone number of the member	String, 1-255 characters
`address`	string	No	Residential address	String, 1-255 characters
`nationality`	string	No	Nationality of the member	String, 1-255 characters

Response

Success Response (201 Created)

{
  "member_id": "12345",
  "name": "Alaa",
  "code": 201,
  "message": "Created successfully"
}

Response Fields

Field	Type	Description
`member_id`	string	The unique identifier of the created member
`name`	string	The full name of the member
`code`	number	HTTP status code (`201`)
`message`	string	Success message

Error Responses

Error Response Structure

{
  "ErrorCode": "string",
  "message": "string",
  "details": ["string"]
}

Error Codes

Error Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Request validation failed — see the `details` array for field-level errors
`UNAUTHORIZED`	401	Missing or invalid `access-key`
`CONFLICT`	409	A member with the same identifier already exists

Example Error Responses

Bad Request:

{
  "ErrorCode": "VALIDATION_ERROR",
  "message": "Validation failed",
  "details": ["member_id is required", "gender must be one of: MALE, FEMALE"]
}

Unauthorized:

{
  "ErrorCode": "UNAUTHORIZED",
  "message": "Invalid or missing API key",
  "details": []
}

Conflict:

{
  "ErrorCode": "CONFLICT",
  "message": "Patient already exists",
  "details": ["A member with member_id '12345' already exists"]
}

Code Examples

cURL
JavaScript
Python

curl -X POST "https://api.{client_namespace}.najeeb.ai/v4.0/health/member/create" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "member_id": "12345",
    "national_id": "1234567890",
    "gender": "MALE",
    "marital_status": "SINGLE",
    "date_of_birth": "1990-05-20T00:00:00.000Z",
    "name": "Alaa",
    "card": "CARD-001",
    "email": "alaa@example.com",
    "relation": "SELF",
    "phone_number": "+966500000000",
    "address": "Riyadh, KSA",
    "nationality": "SA"
  }'

const response = await fetch(
  'https://api.{client_namespace}.najeeb.ai/v4.0/health/member/create',
  {
    method: 'POST',
    headers: {
      'access-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      member_id: '12345',
      national_id: '1234567890',
      gender: 'MALE',
      marital_status: 'SINGLE',
      date_of_birth: '1990-05-20T00:00:00.000Z',
      name: 'Alaa',
      card: 'CARD-001',
      email: 'alaa@example.com',
      relation: 'SELF',
      phone_number: '+966500000000',
      address: 'Riyadh, KSA',
      nationality: 'SA',
    }),
  }
);

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

import requests

response = requests.post(
    'https://api.{client_namespace}.najeeb.ai/v4.0/health/member/create',
    headers={
        'access-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'member_id': '12345',
        'national_id': '1234567890',
        'gender': 'MALE',
        'marital_status': 'SINGLE',
        'date_of_birth': '1990-05-20T00:00:00.000Z',
        'name': 'Alaa',
        'card': 'CARD-001',
        'email': 'alaa@example.com',
        'relation': 'SELF',
        'phone_number': '+966500000000',
        'address': 'Riyadh, KSA',
        'nationality': 'SA',
    },
)

result = response.json()
print(result)

Update Member

Update an existing member's information. Only the fields provided in the request body will be updated; all other fields remain unchanged.

PATCH /:member_id

Request Headers

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

Path Parameters

Parameter	Type	Required	Description	Accepted Values
`member_id` *	string	Yes	The unique identifier of the member to update	Alphanumeric string, 1-255 characters

Request Body Parameters

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

Parameter	Type	Required	Description	Accepted Values
`member_id`	string	No	Unique identifier for the member	Alphanumeric string, 1-255 characters
`national_id`	string	No	National ID of the member	Alphanumeric string, 1-255 characters
`gender`	string	No	Gender of the member	Enum: `MALE`, `FEMALE`
`marital_status`	string	No	Marital status of the member	Enum: `SINGLE`, `MARRIED`, `ENGAGED`, `UNKNOWN`, `WIDOWED`, `DIVORCED`, `SEPARATED`
`date_of_birth`	string	No	Date of birth of the member	ISO 8601 format: `YYYY-MM-DDTHH:mm:ss.sssZ`
`name`	string	No	Full name of the member	String, 1-255 characters
`card`	string	No	Insurance card number	String, 1-255 characters
`email`	string	No	Email address of the member	Valid email format, max 255 characters
`relation`	string	No	Relation to the primary subscriber	Enum: `SELF`, `FATHER`, `MOTHER`, `SON`, `DAUGHTER`, `SISTER`, `HUSBAND`, `WIFE`, `WIFE_WITHOUT_MATERNITY`, `MOTHER_MB`, `SENIOR_EMPLOYEE`, `FEMALE_EMPLOYEE_WITH_MAT`, `CHILD`, `SPOUSE`, `EMPLOYEE`, `OTHER`
`passport`	string	No	Passport number	String, 1-255 characters
`visit_visa_number`	string	No	Visit visa number	String, 1-255 characters
`phone_number`	string	No	Phone number of the member	String, 1-255 characters
`address`	string	No	Residential address	String, 1-255 characters
`nationality`	string	No	Nationality of the member	String, 1-255 characters

Response

Success Response (200 OK)

{
  "member_id": "12345",
  "national_id": "1234567890",
  "gender": "MALE",
  "marital_status": "MARRIED",
  "date_of_birth": "1990-05-20T00:00:00.000Z",
  "name": "Alaa Updated",
  "card": "CARD-001",
  "email": "alaa.updated@example.com",
  "relation": "SELF",
  "phone_number": "+966511111111",
  "address": "Riyadh, KSA",
  "nationality": "SA",
  "code": 200,
  "message": "Updated successfully"
}

Response Fields

Field	Type	Description
`member_id`	string	The unique identifier of the member
`national_id`	string	National ID of the member
`gender`	string	Gender of the member
`marital_status`	string	Marital status of the member
`date_of_birth`	string	Date of birth in ISO 8601 format
`name`	string	Full name of the member
`card`	string	Insurance card number
`email`	string	Email address of the member
`relation`	string	Relation to the primary subscriber
`phone_number`	string	Phone number of the member
`address`	string	Residential address
`nationality`	string	Nationality of the member
`code`	number	HTTP status code (`200`)
`message`	string	Success message

Error Responses

Error Response Structure

{
  "ErrorCode": "string",
  "message": "string",
  "details": ["string"]
}

Error Codes

Error Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Request validation failed — see the `details` array for field-level errors
`UNAUTHORIZED`	401	Missing or invalid `access-key`
`NOT_FOUND`	404	No member found with the specified `member_id`

Example Error Responses

Bad Request:

{
  "ErrorCode": "VALIDATION_ERROR",
  "message": "Validation failed",
  "details": ["gender must be one of: MALE, FEMALE"]
}

Unauthorized:

{
  "ErrorCode": "UNAUTHORIZED",
  "message": "Invalid or missing API key",
  "details": []
}

Not Found:

{
  "ErrorCode": "NOT_FOUND",
  "message": "Member not found",
  "details": ["No member found with member_id '99999'"]
}

Code Examples

cURL
JavaScript
Python

curl -X PATCH "https://api.{client_namespace}.najeeb.ai/v4.0/health/member/12345" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alaa Updated",
    "email": "alaa.updated@example.com",
    "phone_number": "+966511111111",
    "marital_status": "MARRIED"
  }'

const memberId = '12345';

const response = await fetch(
  `https://api.{client_namespace}.najeeb.ai/v4.0/health/member/${memberId}`,
  {
    method: 'PATCH',
    headers: {
      'access-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Alaa Updated',
      email: 'alaa.updated@example.com',
      phone_number: '+966511111111',
      marital_status: 'MARRIED',
    }),
  }
);

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

import requests

member_id = '12345'

response = requests.patch(
    f'https://api.{{client_namespace}}.najeeb.ai/v4.0/health/member/{member_id}',
    headers={
        'access-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'name': 'Alaa Updated',
        'email': 'alaa.updated@example.com',
        'phone_number': '+966511111111',
        'marital_status': 'MARRIED',
    },
)

result = response.json()
print(result)

Base URL​

Authentication​

Create Member​

Request Headers​

Request Body Parameters​

Response​

Success Response (201 Created)​

Response Fields​

Error Responses​

Error Response Structure​

Error Codes​

Example Error Responses​

Code Examples​

Update Member​

Request Headers​

Path Parameters​

Request Body Parameters​

Response​

Success Response (200 OK)​

Response Fields​

Error Responses​

Error Response Structure​

Error Codes​

Example Error Responses​

Code Examples​

Base URL

Authentication

Create Member

Request Headers

Request Body Parameters

Response

Success Response (201 Created)

Response Fields

Error Responses

Error Response Structure

Error Codes

Example Error Responses

Code Examples

Update Member

Request Headers

Path Parameters

Request Body Parameters

Response

Success Response (200 OK)

Response Fields

Error Responses

Error Response Structure

Error Codes

Example Error Responses

Code Examples