CBTHost - API Documentation

CBTHost API Documentation

Programmatically access exam results with our secure REST API endpoints

API Overview

The CBT Host API allows authorized users to retrieve exam results for individual students or entire exams. All API access requires authentication via specific headers.

Single Result Endpoint

GET https://cbthost.com/api/result

Retrieve a specific student's exam result using headers for authentication.

Returns detailed information about a single student
Uses headers for authentication (cbt-pass-code and test-id)
Returns JSON response with student details and scores

Mass Results Endpoint

GET https://cbthost.com/api/result/{cbt-pass-code}

Retrieve all student results for a specific exam identified by its passcode in the URL.

Returns all student results for an exam
Passcode is included directly in the URL path
Returns JSON response with student array and summary

Authentication

All API requests require authentication using specific headers. The authentication method differs between endpoints.

Header-Based Authentication

Include the following headers in your API requests:

Endpoint	Header	Description	Example	Required
Single Result	cbt-pass-code	Student's unique CBT pass code	cbthost-pssi-0069	Required
Single Result	test-id	Identifier for the CBT test	solomonpolycap3@gmail.com	Required
Both Endpoints	Accept	Ensures JSON output	application/json	Required

Important: Missing or invalid credentials will return a 401 Unauthorized response. For the Mass Results API, the passcode is included directly in the URL path instead of headers.

Single Student Result

Retrieve a specific student's exam result using headers for authentication.

GET https://cbthost.com/api/result

Required Headers

Header	Description	Example	Required
cbt-pass-code	Student's unique CBT pass code	cbthost-pssi-0069	Required
test-id	Identifier for the CBT test	solomonpolycap3@gmail.com	Required
Accept	Ensures JSON output	application/json	Required

Response Format

{
  "status": "success",
  "data": {
    "cbt_test_id": "solomonpolycap3@gmail.com",
    "cbt_test_info": "solomonpolycap3@gmail.com",
    "cbt_pass_code": "cbthost-pssi-0069",
    "cbt_total_score": 5
  }
}

Error Responses

400 Bad Request

{
  "serverstatus": 400,
  "message": "Missing required headers: cbt_pass_code, test_id"
}

404 Not Found

{
  "serverstatus": 404,
  "message": "cbt pass code is invalid, or no record found"
}

Mass Results

Retrieve all student results for a specific exam by including the passcode directly in the URL.

GET https://cbthost.com/api/result/{cbt-pass-code}

Required Headers

Header	Description	Example	Required
Accept	Ensures JSON output	application/json	Required

Response Format

{
  "status": "success",
  "data": [
    {
      "cbt_pass_code": "cbthost-pssi-0069",
      "cbt_test_id": "solomonpolycap3@gmail.com",
      "cbt_total_score": 5
    },
    {
      "cbt_pass_code": "cbthost-pssi-0070",
      "cbt_test_id": "solomonpolycap3@gmail.com",
      "cbt_total_score": 8
    }
  ]
}

Error Responses

404 Not Found

{
  "status": "error",
  "message": "No results found for this test ID"
}

API Examples

Implementation examples in popular programming languages and tools

JavaScript

Python

PHP

Java

cURL

Postman

// Single Result API using Fetch
const fetchSingleResult = async () => {
  const url = 'https://cbthost.com/api/result';
  
  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'Accept': 'application/json',
      'cbt-pass-code': 'cbthost-pssi-0069',
      'test-id': 'solomonpolycap3@gmail.com'
    }
  });
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  const data = await response.json();
  console.log('Student Result:', data);
};

// Mass Results API using Fetch
const fetchMassResults = async () => {
  const passcode = 'cbthost-pssi-0069';
  const url = `https://cbthost.com/api/result/${passcode}`;
  
  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'Accept': 'application/json'
    }
  });
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  const data = await response.json();
  console.log('Mass Results:', data);
};

// Call the functions
fetchSingleResult();
fetchMassResults();

import requests

# Single result example
def get_single_result():
    url = 'https://cbthost.com/api/result'
    
    headers = {
        'Accept': 'application/json',
        'cbt-pass-code': 'cbthost-pssi-0069',
        'test-id': 'solomonpolycap3@gmail.com'
    }
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        print(f"Student Result: {data}")
    else:
        print(f"Error: {response.status_code} - {response.text}")

# Mass results example
def get_mass_results():
    passcode = 'cbthost-pssi-0069'
    url = f'https://cbthost.com/api/result/{passcode}'
    
    headers = {
        'Accept': 'application/json'
    }
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        print(f"Total Results: {len(data['data'])}")
        
        for result in data['data']:
            print(f"Student: {result['cbt_test_id']}, Score: {result['cbt_total_score']}")
    else:
        print(f"Error: {response.status_code} - {response.text}")

# Execute the functions
if __name__ == '__main__':
    get_single_result()
    get_mass_results()

<?php
// Single result example
function getSingleResult() {
    $url = 'https://cbthost.com/api/result';
    
    $headers = [
        'Accept: application/json',
        'cbt-pass-code: cbthost-pssi-0069',
        'test-id: solomonpolycap3@gmail.com'
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    
    $response = curl_exec($ch);
    
    if (curl_errno($ch)) {
        echo 'Error:' . curl_error($ch);
    } else {
        $data = json_decode($response, true);
        echo "Student Result: " . print_r($data, true) . "\n";
    }
    
    curl_close($ch);
}

// Mass results example
function getMassResults() {
    $passcode = 'cbthost-pssi-0069';
    $url = "https://cbthost.com/api/result/$passcode";
    
    $headers = [
        'Accept: application/json'
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    
    $response = curl_exec($ch);
    
    if (curl_errno($ch)) {
        echo 'Error:' . curl_error($ch);
    } else {
        $data = json_decode($response, true);
        echo "Total Results: " . count($data['data']) . "\n";
        
        foreach ($data['data'] as $result) {
            echo $result['cbt_test_id'] . ': ' . $result['cbt_total_score'] . "\n";
        }
    }
    
    curl_close($ch);
}

// Call the functions
getSingleResult();
getMassResults();
?>

import java.net.HttpURLConnection;
import java.net.URL;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import org.json.JSONObject;
import org.json.JSONArray;

public class CBTHostAPI {
    
    // Single result example
    public static void getSingleResult() {
        try {
            String apiUrl = "https://cbthost.com/api/result";
            
            URL url = new URL(apiUrl);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("GET");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("cbt-pass-code", "cbthost-pssi-0069");
            conn.setRequestProperty("test-id", "solomonpolycap3@gmail.com");
            
            int responseCode = conn.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) {
                BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
                String inputLine;
                StringBuilder response = new StringBuilder();
                
                while ((inputLine = in.readLine()) != null) {
                    response.append(inputLine);
                }
                in.close();
                
                JSONObject data = new JSONObject(response.toString());
                System.out.println("Student Result: " + data.toString());
            } else {
                System.out.println("GET request failed. Response Code: " + responseCode);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
    
    // Mass results example
    public static void getMassResults() {
        try {
            String passcode = "cbthost-pssi-0069";
            String apiUrl = "https://cbthost.com/api/result/" + passcode;
            
            URL url = new URL(apiUrl);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("GET");
            conn.setRequestProperty("Accept", "application/json");
            
            int responseCode = conn.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) {
                BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
                String inputLine;
                StringBuilder response = new StringBuilder();
                
                while ((inputLine = in.readLine()) != null) {
                    response.append(inputLine);
                }
                in.close();
                
                JSONObject data = new JSONObject(response.toString());
                JSONArray results = data.getJSONArray("data");
                System.out.println("Total Results: " + results.length());
                
                for (int i = 0; i < results.length(); i++) {
                    JSONObject result = results.getJSONObject(i);
                    System.out.println(result.getString("cbt_test_id") + ": " + 
                                       result.getInt("cbt_total_score"));
                }
            } else {
                System.out.println("GET request failed. Response Code: " + responseCode);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
    
    public static void main(String[] args) {
        getSingleResult();
        getMassResults();
    }
}

# Single Result Fetch API
curl -X GET "https://cbthost.com/api/result" \
  -H "Accept: application/json" \
  -H "cbt-pass-code: cbthost-pssi-0069" \
  -H "test-id: solomonpolycap3@gmail.com"

# Mass Result Fetch API
curl -X GET "https://cbthost.com/api/result/cbthost-pssi-0069" \
  -H "Accept: application/json"

Single Result API Setup:
----------------------
Method: GET
URL: https://cbthost.com/api/result
Headers:
  - Accept: application/json
  - cbt-pass-code: cbthost-pssi-0069
  - test-id: solomonpolycap3@gmail.com
Body: None (use headers only)

Mass Results API Setup:
---------------------
Method: GET
URL: https://cbthost.com/api/result/cbthost-pssi-0069
Headers:
  - Accept: application/json
Body: None (use headers only)

Developer Resources

Tools and resources to help you integrate with our API

GitHub Repository

Download plugins and SDKs for both online and offline software

View on GitHub

Video Tutorials

Watch step-by-step integration guides

Watch Tutorials

API Testing Tool

Test API endpoints directly in your browser

Try API Tester

Need Help?

Our support team is ready to assist you with API integration

Email Support

Get personalized assistance via email

Contact Us

WhatsApp

Quick responses via WhatsApp

Message Us

Technical Support

Submit a ticket for personalized assistance

Submit Ticket

Still Have Questions?

If you don't understand any part of the documentation or need clarification on implementation, don't hesitate to reach out directly.

Email Us WhatsApp