Lookup API Documentation

Overview

The Lookup API provides secure access to candidate and practitioner records with robust authentication, rate limiting, and permission-based access control.

Important: All API requests require a valid API key and are subject to rate limiting based on your subscription plan.

Key Features

🔐 Secure Authentication: API key-based authentication with IP restrictions
⚡ Rate Limiting: Configurable rate limits per API key
🎯 Granular Permissions: Fine-grained access control
🔍 Powerful Search: Multi-criteria search capabilities
📊 Usage Analytics: Track API usage and performance

Authentication

All API requests require a valid API key sent in the request headers.

Required Headers

X-API-Key: your_api_key_here

Alternative Header Names

API-Key
X-Secret-Key
Secret-Key

API Key Format

ak_[32_character_hash]_[timestamp]

Example

ak_abc123def456ghi789jkl012mno345_1640995200

Security Note: Keep your API keys secure and never expose them in client-side code. Use HTTPS for all requests.

Rate Limiting

API requests are rate-limited per API key based on your subscription plan. Rate limits reset every minute (60-second windows).

Rate Limit Information

Plan	Requests per Minute	Burst Allowance
Basic	60	10
Professional	300	50
Enterprise	1000	200

Rate Limit Exceeded Response

{
  "status": false,
  "message": "Rate limit exceeded. 60/60 requests used. Resets at: 2024-01-15 14:31:00",
  "data": null
}

API Endpoints

GET POST /candidate/{identifier}

Get Candidate

Retrieve a single candidate record by indexing number or ID.

Parameters

Parameter	Type	Required	Description
identifier	string	Yes	Candidate indexing number or ID
include_photo	boolean	No	Include base64 encoded photo

Required Permissions

candidate.read - Basic candidate data
candidate.photo - Include passport photo

curl -X GET \
  -H "X-API-Key: ak_abc123def456_1640995200" \
  "https://app.chprbn.gov.ng/api/v1/mobile/lookup/candidate/12345?include_photo=true"

{
  "status": true,
  "message": "Candidate found successfully",
  "data": {
    "id": 12345,
    "indexing": "CBT/2024/12345",
    "firstname": "John",
    "surname": "Doe",
    "othernames": "Michael",
    "fullname": "John Michael Doe",
    "gender": "Male",
    "dob": "1995-06-15",
    "email": "john.doe@example.com",
    "lga_id": 123,
    "cadre_id": 5,
    "institution_id": 10,
    "photo": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
    "cadre": {
      "id": 5,
      "name": "Nursing",
      "code": "NUR",
      "description": "Nursing Cadre"
    },
    "created_at": "2024-01-01 10:00:00",
    "updated_at": "2024-01-15 14:30:00"
  }
}

GET POST /practitioner/{identifier}

Get Practitioner

Retrieve a single practitioner record by license number or ID.

Parameters

Parameter	Type	Required	Description
identifier	string	Yes	License number or practitioner ID
include_photo	boolean	No	Include passport photo
include_permissions	boolean	No	Include user permissions

curl -X GET \
  -H "X-API-Key: ak_abc123def456_1640995200" \
  "https://app.chprbn.gov.ng/api/v1/mobile/lookup/practitioner/LIC123456?include_permissions=true"

{
  "status": true,
  "message": "Practitioner found successfully",
  "data": {
    "id": 67890,
    "license_no": "LIC123456",
    "firstname": "Jane",
    "surname": "Smith",
    "othernames": "Elizabeth",
    "fullname": "Jane Elizabeth Smith",
    "gender": "Female",
    "email": "jane.smith@example.com",
    "phone": "+2348012345678",
    "status": "active",
    "license_issue_date": "2023-01-15",
    "license_expiry_date": "2025-01-14",
    "photo": "https://example.com/photos/jane.jpg",
    "permissions": ["attendance.mobile.login", "assessment.read"],
    "created_at": "2023-05-10 09:15:00",
    "updated_at": "2024-01-10 16:45:00"
  }
}

GET POST /candidates/search

Search Candidates

Search for candidates using multiple criteria.

Search Parameters

Parameter	Type	Description
firstname	string	First name (partial match)
surname	string	Surname (partial match)
indexing	string	Exact indexing number
cadre_id	integer	Cadre ID
institution_id	integer	Institution ID
gender	string	Gender (Male/Female)
limit	integer	Results limit (max 100, default 50)

curl -X POST \
  -H "X-API-Key: ak_abc123def456_1640995200" \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "John",
    "cadre_id": 5,
    "limit": 20
  }' \
  "https://app.chprbn.gov.ng/api/v1/mobile/lookup/candidates/search"

{
  "status": true,
  "message": "Search completed successfully",
  "data": {
    "total": 15,
    "candidates": [
      {
        "id": 12345,
        "indexing": "CBT/2024/12345",
        "firstname": "John",
        "surname": "Doe",
        "othernames": "Michael",
        "fullname": "John Michael Doe",
        "gender": "Male",
        "cadre_id": 5,
        "institution_id": 10,
        "cadre": {
          "id": 5,
          "name": "Nursing",
          "code": "NUR"
        }
      }
    ]
  }
}

GET POST /practitioners/search

Search Practitioners

Search for practitioners using multiple criteria.

curl -X GET \
  -H "X-API-Key: ak_abc123def456_1640995200" \
  "https://app.chprbn.gov.ng/api/v1/mobile/lookup/practitioners/search?surname=Smith&status=active&limit=10"

{
  "status": true,
  "message": "Search completed successfully",
  "data": {
    "total": 8,
    "practitioners": [
      {
        "id": 67890,
        "license_no": "LIC123456",
        "firstname": "Jane",
        "surname": "Smith",
        "othernames": "Elizabeth",
        "fullname": "Jane Elizabeth Smith",
        "gender": "Female",
        "email": "jane.smith@example.com",
        "phone": "+2348012345678",
        "status": "active",
        "license_issue_date": "2023-01-15",
        "license_expiry_date": "2025-01-14"
      }
    ]
  }
}

Error Handling

Standard Error Format

{
  "status": false,
  "message": "Error description",
  "data": null
}

HTTP Status Codes

Code	Description	Common Causes
200	Success	Request completed successfully
400	Bad Request	Invalid parameters or request format
401	Unauthorized	Invalid or missing API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error

Common Error Messages

Error Message	Solution
"API key is required"	Add X-API-Key header to your request
"Invalid API key"	Check your API key value
"API key has expired"	Request a new API key
"IP address not allowed"	Contact support for IP whitelisting
"Rate limit exceeded"	Wait for rate limit reset or upgrade plan
"Insufficient permissions"	Contact support for permission upgrade

Permissions

The API uses a granular permission system to control access to different endpoints and data types.

Available Permissions

Permission	Description	Endpoints
`*`	Full access to all endpoints	All
`candidate.read`	Get single candidate	/candidate/{identifier}
`candidate.search`	Search candidates	/candidates/search
`candidate.photo`	Access candidate photos	include_photo parameter
`practitioner.read`	Get single practitioner	/practitioner/{identifier}
`practitioner.search`	Search practitioners	/practitioners/search
`practitioner.photo`	Access practitioner photos	include_photo parameter
`practitioner.permissions`	Access practitioner permissions	include_permissions parameter

Note: Permissions are assigned to API keys during creation. Contact support to modify permissions for existing keys.

Code Examples

PHP Example

 'John',
        'limit' => 10
    ]);
    echo "Found " . $results['data']['total'] . " candidates\n";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>

JavaScript (Node.js) Example

const axios = require('axios');

const apiKey = 'ak_abc123def456_1640995200';
const baseUrl = 'https://app.chprbn.gov.ng/api/v1/mobile/lookup/';

const headers = {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
};

// Get candidate
async function getCandidate(identifier, includePhoto = false) {
    try {
        const params = includePhoto ? { include_photo: true } : {};
        const response = await axios.get(
            `${baseUrl}candidate/${identifier}`,
            { headers, params }
        );
        
        if (response.data.status) {
            return response.data.data;
        } else {
            throw new Error(response.data.message);
        }
    } catch (error) {
        throw new Error(`Request failed: ${error.message}`);
    }
}

// Search practitioners
async function searchPractitioners(criteria) {
    try {
        const response = await axios.post(
            `${baseUrl}practitioners/search`,
            criteria,
            { headers }
        );
        
        return response.data;
    } catch (error) {
        throw new Error(`Search failed: ${error.message}`);
    }
}

// Usage
async function main() {
    try {
        const candidate = await getCandidate('12345', true);
        console.log('Found candidate:', candidate.fullname);
        
        const results = await searchPractitioners({
            surname: 'Smith',
            status: 'active',
            limit: 20
        });
        console.log(`Found ${results.data.total} practitioners`);
    } catch (error) {
        console.error('Error:', error.message);
    }
}

main();

Python Example

import requests
import json

API_KEY = 'ak_abc123def456_1640995200'
BASE_URL = 'https://app.chprbn.gov.ng/api/v1/mobile/lookup/'

headers = {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
}

def get_practitioner(identifier, include_photo=False, include_permissions=False):
    """Get practitioner by license number or ID"""
    params = {}
    if include_photo:
        params['include_photo'] = True
    if include_permissions:
        params['include_permissions'] = True
    
    response = requests.get(
        f"{BASE_URL}practitioner/{identifier}",
        headers=headers,
        params=params
    )
    
    if response.status_code == 200:
        data = response.json()
        if data['status']:
            return data['data']
        else:
            raise Exception(data['message'])
    else:
        raise Exception(f"HTTP Error: {response.status_code}")

def search_candidates(criteria):
    """Search candidates"""
    response = requests.post(
        f"{BASE_URL}candidates/search",
        headers=headers,
        json=criteria
    )
    
    return response.json()

# Usage
try:
    practitioner = get_practitioner('LIC123456', include_permissions=True)
    print(f"Found: {practitioner['fullname']}")
    print(f"Email: {practitioner['email']}")
    
    results = search_candidates({
        'firstname': 'John',
        'cadre_id': 5,
        'limit': 20
    })
    print(f"Found {results['data']['total']} candidates")
    
except Exception as e:
    print(f"Error: {e}")

Testing

Rate Limit Testing

Use these endpoints to test rate limiting functionality:

# Test rate limit
curl -H "X-API-Key: your_key" "https://yourapi.com/api/rate-limit/test"

# Check current status
curl -H "X-API-Key: your_key" "https://yourapi.com/api/rate-limit/status"

Sample Test Data

Use these test identifiers for development and testing:

Test Candidates

CBT/2024/12345
CBT/2024/67890
CBT/2024/11111

Test Practitioners

LIC123456
LIC789012
LIC555666

Best Practices:

Always check the status field in responses
Implement exponential backoff for retries
Cache frequently accessed data
Monitor your rate limit usage
Use HTTPS for all requests