Developer REST API Integrations

Developer API Documentation

Specs for programmatic student credential verification and detailed academic result query.

⚡ Overview

AKTU DOB Finder provides RESTful endpoints for external systems. Developers can programmatically lookup academic results (without DOBs), query class roll numbers, or retrieve validated student DOBs via secure, whitelisted calls.

1. Result API (Public Search)

Use this endpoint to fetch student profiles and academic semesters. If the student is not in the database, it utilizes a fast DOB bypass mechanism to scrap the portal. Note: **The student DOB is omitted from this payload for compliance.**

POST/api/search

Request Headers

Content-Type: application/json

JSON Body Parameters

Parameter	Type	Requirement
rollNumber	string	Required

Example Payload

{
  "rollNumber": "2200650100100"
}

Implementation Code Examples

request.sh

123

curl -X POST http://localhost:4321/api/search \
  -H "Content-Type: application/json" \
  -d '{"rollNumber": "2200650100100"}'

const rollNumber = "2200650100100";

fetch('http://localhost:4321/api/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ rollNumber })
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));

import requests

url = "http://localhost:4321/api/search"
payload = {"rollNumber": "2200650100100"}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "http://localhost:4321/api/search"
	payload := map[string]string{"rollNumber": "2200650100100"}
	jsonValue, _ := json.Marshal(payload)

	resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonValue))
	if err != nil {
		fmt.Printf("Request failed: %s\n", err)
		return
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://localhost:4321/api/search");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setDoOutput(true);

            String jsonInputString = "{\"rollNumber\": \"2200650100100\"}";

            try (OutputStream os = conn.getOutputStream()) {
                byte[] input = jsonInputString.getBytes("utf-8");
                os.write(input, 0, input.length);
            }

            int code = conn.getResponseCode();
            Scanner scanner = new Scanner(conn.getInputStream());
            StringBuilder response = new StringBuilder();
            while (scanner.hasNext()) {
                response.append(scanner.nextLine());
            }
            scanner.close();
            System.out.println("Response: " + response.toString());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Response Schema (200 OK)

{
  "success": true,
  "name": "SHIVAM DIXIT",
  "rollNumber": "2200650100100",
  "course": "B.Tech (CS)",
  "cgpa": "8.06",
  "status": "PASS",
  "semesters": [
    {
      "sem": "Semester 1",
      "sgpa": "8.23",
      "status": "PASS",
      "subjects": [
        { "code": "BAS102", "name": "Chemistry", "grade": "B" }
      ]
    }
  ]
}

Response Schema (404 Not Found)

{
  "success": false,
  "error": "Could not able to fetch now try later",
  "code": 404
}

2. Roll Number Finder API (Public Search)

Query student lists and matching results by admission filters (year, college code, branch code) and optionally search by student name.

POST/api/find-roll

Request Headers

Content-Type: application/json

JSON Body Parameters

Parameter	Type	Requirement
admissionYear	string	Required (e.g. "22")
collegeCode	string	Required (e.g. "065")
branchCode	string	Required (e.g. "010")
name	string	Optional

Example Payload

{
  "admissionYear": "22",
  "collegeCode": "065",
  "branchCode": "010",
  "name": "SHIVAM"
}

Implementation Code Examples

request.sh

123

curl -X POST http://localhost:4321/api/find-roll \
  -H "Content-Type: application/json" \
  -d '{"admissionYear": "22", "collegeCode": "065", "branchCode": "010", "name": "SHIVAM"}'

const payload = {
  admissionYear: "22",
  collegeCode: "065",
  branchCode: "010",
  name: "SHIVAM"
};

fetch('http://localhost:4321/api/find-roll', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));

import requests

url = "http://localhost:4321/api/find-roll"
payload = {
    "admissionYear": "22",
    "collegeCode":    "065",
    "branchCode":     "010",
    "name":           "SHIVAM"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "http://localhost:4321/api/find-roll"
	payload := map[string]string{
		"admissionYear": "22",
		"collegeCode":    "065",
		"branchCode":     "010",
		"name":           "SHIVAM",
	}
	jsonValue, _ := json.Marshal(payload)

	resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonValue))
	if err != nil {
		fmt.Printf("Request failed: %s\n", err)
		return
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://localhost:4321/api/find-roll");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setDoOutput(true);

            String jsonInputString = "{"
                + "\"admissionYear\": \"22\","
                + "\"collegeCode\": \"065\","
                + "\"branchCode\": \"010\","
                + "\"name\": \"SHIVAM\""
                + "}";

            try (OutputStream os = conn.getOutputStream()) {
                byte[] input = jsonInputString.getBytes("utf-8");
                os.write(input, 0, input.length);
            }

            int code = conn.getResponseCode();
            Scanner scanner = new Scanner(conn.getInputStream());
            StringBuilder response = new StringBuilder();
            while (scanner.hasNext()) {
                response.append(scanner.nextLine());
            }
            scanner.close();
            System.out.println("Response: " + response.toString());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Response Schema (200 OK)

{
  "success": true,
  "matchCount": 1,
  "students": [
    {
      "name": "SHIVAM DIXIT",
      "rollNumber": "2200650100100",
      "fatherName": "RAM DIXIT",
      "gender": "MALE"
    }
  ]
}

Response Schema (400 Bad Request)

{
  "success": false,
  "error": "Missing required search parameters in payload.",
  "code": 400
}

3. DOB Finder API (Private/Whitelisted)

This endpoint validates client IPs/domains and runs a calendar brute-forcing loop to discover a student's date of birth. Whitelisted hosts are defined via server environment variables (`ALLOWED_HOSTS` and `ALLOWED_DOMAINS`).

⚠️Authentication Key Required

Unlike the public Search API, the DOB Finder API requires a whitelisted X-API-Key header to prevent abuse. Requests sent without a valid key will receive a 403 Forbidden response.

🔑 Request API Key Access

POST/api/dob

Request Headers

Content-Type: application/json

X-API-Key: YOUR_API_KEY_HERE

Referer: https://yourdomain.com

JSON Body Parameters

Parameter	Type	Default / Bounds
rollNumber	string	Required
startYear	number	Default: 2000 (Min: 1999)
endYear	number	Default: 2006 (Max: 2010)

Example Payload

{
  "rollNumber": "2200650100100",
  "startYear": 2001,
  "endYear": 2005
}

Implementation Code Examples

request.sh

1234

curl -X POST http://localhost:4321/api/dob \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -d '{"rollNumber": "2200650100100", "startYear": 2001, "endYear": 2005}'

const rollNumber = "2200650100100";

fetch('http://localhost:4321/api/dob', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY_HERE'
  },
  body: JSON.stringify({
    rollNumber,
    startYear: 2001,
    endYear: 2005
  })
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));

import requests

url = "http://localhost:4321/api/dob"
payload = {
    "rollNumber": "2200650100100",
    "startYear": 2001,
    "endYear": 2005
}
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY_HERE"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "http://localhost:4321/api/dob"
	payload := map[string]interface{}{
		"rollNumber": "2200650100100",
		"startYear":  2001,
		"endYear":    2005,
	}
	jsonValue, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonValue))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-API-Key", "YOUR_API_KEY_HERE")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Printf("Request failed: %s\n", err)
		return
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://localhost:4321/api/dob");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("X-API-Key", "YOUR_API_KEY_HERE");
            conn.setDoOutput(true);

            String jsonInputString = "{"
                + "\"rollNumber\": \"2200650100100\","
                + "\"startYear\": 2001,"
                + "\"endYear\": 2005"
                + "}";

            try (OutputStream os = conn.getOutputStream()) {
                byte[] input = jsonInputString.getBytes("utf-8");
                os.write(input, 0, input.length);
            }

            int code = conn.getResponseCode();
            Scanner scanner = new Scanner(conn.getInputStream());
            StringBuilder response = new StringBuilder();
            while (scanner.hasNext()) {
                response.append(scanner.nextLine());
            }
            scanner.close();
            System.out.println("Response: " + response.toString());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Response Schema (200 OK)

{
  "success": true,
  "name": "SHIVAM DIXIT",
  "rollNumber": "2200650100100",
  "dob": "14/04/2003"
}

Forbidden Schema (403 Error)

{
  "success": false,
  "error": "Forbidden. Client IP or domain not whitelisted.",
  "code": 403
}

Developer API Documentation

⚡ Overview

1. Result API (Public Search)

Request Headers

JSON Body Parameters

Example Payload

Implementation Code Examples

Response Schema (200 OK)

Response Schema (404 Not Found)

2. Roll Number Finder API (Public Search)

Request Headers

JSON Body Parameters

Example Payload

Implementation Code Examples

Response Schema (200 OK)

Response Schema (400 Bad Request)

3. DOB Finder API (Private/Whitelisted)

Request Headers

JSON Body Parameters

Example Payload

Implementation Code Examples

Response Schema (200 OK)

Forbidden Schema (403 Error)

Support on Ko-fi

Roll Number Assistant