API Documentation

Introduction

The Tezz Corp Biometric API allows you to integrate our biometric attendance system into your applications. With our API, you can manage users, devices, and attendance records, and generate reports.

Base URL

https://api.tezzcorp.com/v1

API Versions

The current version of the API is v1. We recommend specifying the API version in the URL to ensure compatibility with your application.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Authentication

The Biometric API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard.

Authentication is performed via HTTP Bearer Auth. Provide your API key as the bearer token value.

Example Request

curl -X GET "https://api.tezzcorp.com/v1/users" \
-H "Authorization: Bearer YOUR_API_KEY"

Keep your API keys secure! Do not share them in publicly accessible areas such as GitHub, client-side code, etc.

Endpoints

The API provides the following endpoints for managing your biometric attendance system:

Users

Endpoints for managing users in your biometric system.

GET /users

Returns a list of all users.

Query Parameters

Parameter Type Description
limit integer Maximum number of users to return. Default is 20.
offset integer Number of users to skip. Default is 0.

Example Request

curl -X GET "https://api.tezzcorp.com/v1/users?limit=10&offset=0" \
-H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "usr_123456789",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+919876543210",
      "department": "IT",
      "created_at": "2023-01-15T10:30:00Z",
      "updated_at": "2023-01-15T10:30:00Z"
    },
    {
      "id": "usr_987654321",
      "name": "Jane Smith",
      "email": "jane.smith@example.com",
      "phone": "+919876543211",
      "department": "HR",
      "created_at": "2023-01-16T11:45:00Z",
      "updated_at": "2023-01-16T11:45:00Z"
    }
  ],
  "meta": {
    "total": 45,
    "limit": 10,
    "offset": 0
  }
}
POST /users

Creates a new user.

Request Body

Parameter Type Description
name string Required. The user's full name.
email string Required. The user's email address.
phone string Required. The user's phone number.
department string Optional. The user's department.

Example Request

curl -X POST "https://api.tezzcorp.com/v1/users" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+919876543210",
  "department": "IT"
}'

Example Response

{
  "data": {
    "id": "usr_123456789",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+919876543210",
    "department": "IT",
    "created_at": "2023-01-15T10:30:00Z",
    "updated_at": "2023-01-15T10:30:00Z"
  }
}

Devices

Endpoints for managing biometric devices.

GET /devices

Returns a list of all registered devices.

Example Request

curl -X GET "https://api.tezzcorp.com/v1/devices" \
-H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "dev_123456789",
      "name": "Main Entrance",
      "serial_number": "BIO-FP-001",
      "type": "fingerprint",
      "status": "active",
      "location": "Office Building - Ground Floor",
      "last_sync": "2023-01-15T10:30:00Z",
      "created_at": "2023-01-01T09:00:00Z",
      "updated_at": "2023-01-15T10:30:00Z"
    },
    {
      "id": "dev_987654321",
      "name": "Back Entrance",
      "serial_number": "BIO-FP-002",
      "type": "fingerprint",
      "status": "active",
      "location": "Office Building - Back Door",
      "last_sync": "2023-01-15T10:35:00Z",
      "created_at": "2023-01-01T09:15:00Z",
      "updated_at": "2023-01-15T10:35:00Z"
    }
  ]
}

Attendance

Endpoints for managing attendance records.

POST /attendance

Records a new attendance entry.

Request Body

Parameter Type Description
user_id string Required. The ID of the user.
device_id string Required. The ID of the device.
type string Required. Either "check_in" or "check_out".
timestamp string Optional. ISO 8601 formatted timestamp. Defaults to current time.

Example Request

curl -X POST "https://api.tezzcorp.com/v1/attendance" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "user_id": "usr_123456789",
  "device_id": "dev_123456789",
  "type": "check_in",
  "timestamp": "2023-01-15T09:00:00Z"
}'

Example Response

{
  "data": {
    "id": "att_123456789",
    "user_id": "usr_123456789",
    "device_id": "dev_123456789",
    "type": "check_in",
    "timestamp": "2023-01-15T09:00:00Z",
    "created_at": "2023-01-15T09:00:05Z"
  }
}

Reports

Endpoints for generating attendance reports.

GET /reports/attendance

Generates an attendance report for a specified time period.

Query Parameters

Parameter Type Description
start_date string Required. Start date in YYYY-MM-DD format.
end_date string Required. End date in YYYY-MM-DD format.
user_id string Optional. Filter by user ID.
department string Optional. Filter by department.
format string Optional. Response format: "json" (default), "csv", or "pdf".

Example Request

curl -X GET "https://api.tezzcorp.com/v1/reports/attendance?start_date=2023-01-01&end_date=2023-01-31&department=IT" \
-H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": {
    "report_id": "rep_123456789",
    "start_date": "2023-01-01",
    "end_date": "2023-01-31",
    "department": "IT",
    "generated_at": "2023-02-01T10:00:00Z",
    "summary": {
      "total_users": 15,
      "total_days": 31,
      "working_days": 22,
      "average_attendance": 95.5
    },
    "users": [
      {
        "id": "usr_123456789",
        "name": "John Doe",
        "department": "IT",
        "attendance": {
          "present_days": 21,
          "absent_days": 1,
          "late_days": 2,
          "early_departure_days": 1,
          "attendance_percentage": 95.45
        }
      },
      // More users...
    ]
  }
}

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of an API request.

Code Description
200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
403 - Forbidden The API key doesn't have permissions to perform the request.
404 - Not Found The requested resource doesn't exist.
429 - Too Many Requests Too many requests hit the API too quickly.
500, 502, 503, 504 - Server Errors Something went wrong on our end.

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "The request was unacceptable, often due to missing a required parameter.",
    "param": "user_id",
    "type": "validation_error"
  }
}

Rate Limits

The API has rate limits to prevent abuse and ensure stability. The current rate limits are:

Plan Rate Limit
Basic 100 requests per minute
Premium 500 requests per minute
Enterprise 1000 requests per minute

Rate limit information is included in the response headers:

  • X-RateLimit-Limit: The maximum number of requests you're permitted to make per minute.
  • X-RateLimit-Remaining: The number of requests remaining in the current rate limit window.
  • X-RateLimit-Reset: The time at which the current rate limit window resets in UTC epoch seconds.

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your biometric system.

Available Events

Event Description
user.created Triggered when a new user is created.
user.updated Triggered when a user is updated.
attendance.created Triggered when a new attendance record is created.
device.status_changed Triggered when a device's status changes.

Setting Up Webhooks

You can set up webhooks in the Dashboard under the Webhooks section.

Webhook Payload

{
  "id": "evt_123456789",
  "type": "attendance.created",
  "created_at": "2023-01-15T09:00:05Z",
  "data": {
    "id": "att_123456789",
    "user_id": "usr_123456789",
    "device_id": "dev_123456789",
    "type": "check_in",
    "timestamp": "2023-01-15T09:00:00Z"
  }
}

SDKs & Libraries

We provide official SDKs for the following languages:

PHP

Our PHP SDK makes it easy to integrate with the Biometric API in your PHP applications.

View on GitHub

JavaScript

Our JavaScript SDK works in both Node.js and browser environments.

View on GitHub

Python

Our Python SDK is compatible with Python 3.6+ and includes async support.

View on GitHub

Java

Our Java SDK is compatible with Java 8+ and includes Spring Boot integration.

View on GitHub

Code Examples

Recording Attendance in PHP


require 'vendor/autoload';

use BthDevelopers\BiometricApi\Client;

// Initialize the client with your API key
$client = new Client('YOUR_API_KEY');

try {
    // Record a check-in
    $attendance = $client->attendance->create([
        'user_id' => 'usr_123456789',
        'device_id' => 'dev_123456789',
        'type' => 'check_in',
        'timestamp' => date('c') // Current time in ISO 8601 format
    ]);
    
    echo "Attendance recorded successfully!\n";
    echo "Attendance ID: " . $attendance->id . "\n";
    echo "User ID: " . $attendance->user_id . "\n";
    echo "Type: " . $attendance->type . "\n";
    echo "Timestamp: " . $attendance->timestamp . "\n";
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Recording Attendance in JavaScript

// Install the SDK: npm install @bthdevelopers/biometric-api-js

const { BiometricApiClient } = require('@bthdevelopers/biometric-api-js');

// Initialize the client with your API key
const client = new BiometricApiClient('YOUR_API_KEY');

// Record a check-in
async function recordAttendance() {
  try {
    const attendance = await client.attendance.create({
      user_id: 'usr_123456789',
      device_id: 'dev_123456789',
      type: 'check_in',
      timestamp: new Date().toISOString()
    });
    
    console.log('Attendance recorded successfully!');
    console.log('Attendance ID:', attendance.id);
    console.log('User ID:', attendance.user_id);
    console.log('Type:', attendance.type);
    console.log('Timestamp:', attendance.timestamp);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

recordAttendance();

Recording Attendance in Python

# Install the SDK: pip install bthdevelopers-biometric-api

from bthdevelopers.biometric_api import BiometricApiClient
from datetime import datetime
import iso8601

# Initialize the client with your API key
client = BiometricApiClient('YOUR_API_KEY')

try:
    # Record a check-in
    attendance = client.attendance.create(
        user_id='usr_123456789',
        device_id='dev_123456789',
        type='check_in',
        timestamp=datetime.now().isoformat()
    )
    
    print('Attendance recorded successfully!')
    print(f'Attendance ID: {attendance.id}')
    print(f'User ID: {attendance.user_id}')
    print(f'Type: {attendance.type}')
    print(f'Timestamp: {attendance.timestamp}')
except Exception as e:
    print(f'Error: {str(e)}')

Recording Attendance in Java

// Add the dependency to your build.gradle:
// implementation 'com.bthdevelopers:biometric-api-java:1.0.0'

import com.bthdevelopers.biometricapi.BiometricApiClient;
import com.bthdevelopers.biometricapi.models.Attendance;
import com.bthdevelopers.biometricapi.requests.AttendanceCreateRequest;

import java.time.Instant;

public class RecordAttendanceExample {
    public static void main(String[] args) {
        // Initialize the client with your API key
        BiometricApiClient client = new BiometricApiClient("YOUR_API_KEY");
        
        try {
            // Record a check-in
            AttendanceCreateRequest request = new AttendanceCreateRequest.Builder()
                .userId("usr_123456789")
                .deviceId("dev_123456789")
                .type("check_in")
                .timestamp(Instant.now().toString())
                .build();
                
            Attendance attendance = client.attendance().create(request);
            
            System.out.println("Attendance recorded successfully!");
            System.out.println("Attendance ID: " + attendance.getId());
            System.out.println("User ID: " + attendance.getUserId());
            System.out.println("Type: " + attendance.getType());
            System.out.println("Timestamp: " + attendance.getTimestamp());
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Changelog

v1.2.0
2023-03-15

Added

  • New endpoint for bulk user import
  • Support for facial recognition devices
  • PDF export for reports

Fixed

  • Issue with timezone handling in attendance records
  • Performance improvements for large data sets
v1.1.0
2023-02-01

Added

  • Webhooks for real-time notifications
  • New report types: monthly and custom date range

Changed

  • Improved error messages for better debugging
  • Updated rate limits for all plans
v1.0.0
2023-01-01

Initial Release

  • Basic CRUD operations for users, devices, and attendance
  • Authentication with API keys
  • Basic reporting functionality

Ready to Integrate Our Biometric API?

Contact us today to get started with our Biometric API and transform your attendance management system.

Get in Touch