Medical Provider

Manage medical provider records (hospitals, clinics, labs, pharmacies) in the system. Providers are referenced when creating Prior Authorizations and can be associated with Networks.

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 Medical Provider

POST /medical-provider/create

Register a new medical provider in the system.

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
name *	string	Yes	Provider name	String, 1-255 characters
nphies_id	string	No	NPHIES ID	String, 1-50 characters
phone_number	string	No	Phone number	String, 1-50 characters
city *	string	Yes	City name	String, 1-100 characters
cchi_no *	string	Yes	CCHI number	String, 1-50 characters
type	string	No	Provider type	Enum: CLINIC, POLYCLINIC, DENTAL_CLINIC, HOSPITAL, PHARMACY, PHYSIOTHERAPY, LABS, OPTICAL_CENTER, AMBULANCE_SERVICES, ONE_DAY_SURGERY_CENTER
lng	string	No	Longitude	String, 1-50 characters
lat	string	No	Latitude	String, 1-50 characters

Example Request

cURL

curl -X POST "https://api.{client_namespace}.najeeb.ai/v4.0/health/medical-provider/create" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Al Noor Hospital",
    "nphies_id": "NP-98765",
    "phone_number": "+966501234567",
    "city": "Riyadh",
    "cchi_no": "1234567890",
    "type": "HOSPITAL",
    "lng": "46.6753",
    "lat": "24.7136"
  }'

JavaScript

const response = await fetch(
  'https://api.{client_namespace}.najeeb.ai/v4.0/health/medical-provider/create',
  {
    method: 'POST',
    headers: {
      'access-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Al Noor Hospital',
      nphies_id: 'NP-98765',
      phone_number: '+966501234567',
      city: 'Riyadh',
      cchi_no: '1234567890',
      type: 'HOSPITAL',
      lng: '46.6753',
      lat: '24.7136',
    }),
  }
);

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

Python

import requests

response = requests.post(
    'https://api.{client_namespace}.najeeb.ai/v4.0/health/medical-provider/create',
    headers={
        'access-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'name': 'Al Noor Hospital',
        'nphies_id': 'NP-98765',
        'phone_number': '+966501234567',
        'city': 'Riyadh',
        'cchi_no': '1234567890',
        'type': 'HOSPITAL',
        'lng': '46.6753',
        'lat': '24.7136',
    },
)

data = response.json()
print(data)

Response

Success Response (201 Created)

{
  "internal_id": 1,
  "cchi_no": "1234567890",
  "code": 201,
  "message": "Created successfully"
}

Response Fields

Field	Type	Description
internal_id	number	Internal identifier assigned to the provider
cchi_no	string	The CCHI number of the created provider
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
E_BAD_REQUEST_400	400	Request validation failed — see details for errors
401 Unauthorized	401	Missing or invalid access-key
E_EMP_02	409	CCHI number already in use
E_CITY_01	404	City not found

Example Error Responses

Bad Request:

{
  "ErrorCode": "E_BAD_REQUEST_400",
  "message": "Bad request",
  "details": [
    "name must be a string",
    "type must be one of the following values: HOSPITAL, CLINIC, LAB, PHARMACY"
  ]
}

Unauthorized:

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

Conflict:

{
  "ErrorCode": "E_EMP_02",
  "message": "Medical provider with this CCHI number already exists",
  "details": []
}

City Not Found:

{
  "ErrorCode": "E_CITY_01",
  "message": "City not found",
  "details": []
}

Update Medical Provider

PATCH /medical-provider/:cchi_no

Update an existing medical provider. Only the fields you include in the request body will be updated.

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
cchi_no *	string	Yes	CCHI number of the provider to update	String, 1-50 characters

Request Body Parameters

All fields are optional (partial update).

Parameter	Type	Required	Description	Accepted Values
name	string	No	Provider name	String, 1-255 characters
nphies_id	string	No	NPHIES ID	String, 1-50 characters
phone_number	string	No	Phone number	String, 1-50 characters
city	string	No	City name	String, 1-100 characters
type	string	No	Provider type	Enum:
lng	string	No	Longitude	String, 1-50 characters
lat	string	No	Latitude	String, 1-50 characters

Example Request

cURL

curl -X PATCH "https://api.{client_namespace}.najeeb.ai/v4.0/health/medical-provider/1234567890" \
  -H "access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Al Noor General Hospital",
    "phone_number": "+966509876543",
    "type": "HOSPITAL"
  }'

JavaScript

const cchiNo = '1234567890';

const response = await fetch(
  `https://api.{client_namespace}.najeeb.ai/v4.0/health/medical-provider/${cchiNo}`,
  {
    method: 'PATCH',
    headers: {
      'access-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Al Noor General Hospital',
      phone_number: '+966509876543',
      type: 'HOSPITAL',
    }),
  }
);

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

Python

import requests

cchi_no = '1234567890'

response = requests.patch(
    f'https://api.{{client_namespace}}.najeeb.ai/v4.0/health/medical-provider/{cchi_no}',
    headers={
        'access-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'name': 'Al Noor General Hospital',
        'phone_number': '+966509876543',
        'type': 'HOSPITAL',
    },
)

data = response.json()
print(data)

Response

Success Response (200 OK)

{
  "internal_id": 1,
  "name": "Al Noor General Hospital",
  "nphies_id": "NP-98765",
  "phone_number": "+966509876543",
  "city": "Riyadh",
  "cchi_no": "1234567890",
  "type": "HOSPITAL",
  "lng": "46.6753",
  "lat": "24.7136",
  "code": 200,
  "message": "Updated successfully"
}

Response Fields

Field	Type	Description
internal_id	number	Internal identifier of the provider
name	string	Provider name
nphies_id	string	NPHIES ID
phone_number	string	Phone number
city	string	City name
cchi_no	string	CCHI number
type	string	Provider type
lng	string	Longitude
lat	string	Latitude
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
E_BAD_REQUEST_400	400	Request validation failed — see details for errors
401 Unauthorized	401	Missing or invalid access-key
E_EMP_01	404	Provider with given CCHI number not found
E_EMP_02	409	Duplicate CCHI unique constraint violation

Example Error Responses

Bad Request:

{
  "ErrorCode": "E_BAD_REQUEST_400",
  "message": "Bad request",
  "details": [
    "type must be one of the following values: HOSPITAL, CLINIC, LAB, PHARMACY"
  ]
}

Unauthorized:

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

Provider Not Found:

{
  "ErrorCode": "E_EMP_01",
  "message": "Medical provider not found",
  "details": []
}

Conflict:

{
  "ErrorCode": "E_EMP_02",
  "message": "Duplicate CCHI",
  "details": []
}