API Documentation

Author: Madhushan Udeshike

Email: madushan.u@arpico.com

Phone: 0112564260

Department: IT

Version: 1.0.0

Create Date: 2025-02-05

Overview

This API provides endpoints for retrieving and updating payroll data. It supports both live and sandbox environments. The API uses Digest Authentication for security and requires specific headers for each request.

Authentication

The API uses Digest Authentication to secure endpoints. Clients must provide valid credentials in the Authorization header.

Credentials

Users

Example

Authorization: Digest username="admin", realm="Protected Area", nonce="...", uri="/v1/endpoint", response="..."

Endpoints

1. Retrieve Data

Endpoint

  • Live: POST /v1/endpoint
  • Sandbox: POST /v1/sandbox/endpoint

Headers

Header Description
user The username of the requester. Must be one of the allowed users.
created Timestamp of the request in Asia/Colombo timezone (e.g., 2025-10-09T12:11:10+05:30).

Response

{
  "code": "S200",
  "message": "Success",
  "data": [
    {
      "Title": "STRING",
      "Calling_name": "STRING",
      "Surname": "STRING",
      "Maiden_name": "STRING",
      "Name_with_initials": "STRING",
      "Names_denoted_by_initials": "STRING",
      "Full_name": "STRING",
      "Other_names": "STRING",
      "EPF_No": "STRING",
      "ID_Number": "STRING",
      "ID_date": "STRING (ISO 8601 format or empty)",
      "Date_of_birth": "STRING (ISO 8601 format)",
      "Place_of_birth": "STRING",
      "Gender": "STRING",
      "Nationality": "STRING",
      "Religion": "STRING",
      "Blood_group": "STRING",
      "Marital_status": "STRING",
      "Date_of_marriage": "STRING (ISO 8601 format or empty)",
      "Date_of_divorce": "STRING (ISO 8601 format or empty)",
      "Salary_grade": "STRING",
      "Corporate_title": "STRING",
      "Designation": "STRING",
      "Centre": "STRING",
      "Date_of_join": "STRING (ISO 8601 format)",
      "Confirmation_Status": "STRING (likely '0' or '1')",
      "Date_of_confirmation": "STRING (ISO 8601 format or empty)",
      "Date_of_resignation": "OBJECT (Buffer with `data` array)",
      "Date_of_retirement": "OBJECT (Buffer with `data` array representing a date)",
      "Hours_of_work": "STRING",
      "Location_code": "STRING",
      "Employment_type": "STRING",
      "Contract_start_date": "STRING (ISO 8601 format or empty)",
      "Contract_end_date": "STRING (ISO 8601 format or empty)",
      "Date_of_contract_to_date": "STRING (ISO 8601 format or empty)",
      "Barcode_no": "STRING",
      "Payroll_no": "STRING",
      "Staff_category_code": "NULL",
      "Category_code": "STRING",
      "GP_code": "NULL",
      "HR_active": "STRING ('0' or '1')",
      "Payroll_active": "STRING ('0' or '1')",
      "Attendance_active": "STRING ('0' or '1')",
      "Hierarchy_name_1": "STRING",
      "Hierarchy_name_2": "STRING",
      "Hierarchy_name_3": "STRING",
      "Hierarchy_name_4": "STRING",
      "Hierarchy_name_5": "STRING",
      "Hierarchy_name_6": "STRING",
      "Tax_on_tax": "STRING",
      "Tax_ID_no": "STRING",
      "EPF_eligible": "STRING ('0' or '1')",
      "EPF_employee_amount": "STRING (decimal in string format)",
      "EPF_employer_amount": "STRING (decimal in string format)",
      "ETF_eligible": "STRING ('0' or '1')",
      "etfno": "STRING",
      "etfcom": "STRING (decimal in string format)",
      "ETF_date": "STRING (ISO 8601 format or empty)",
      "MSPS_eligible": "STRING",
      "MSPS_employer_amount": "STRING (decimal in string format)",
      "MSPS_employee_amount": "STRING (decimal in string format)",
      "Permanent_address_1": "STRING",
      "Permanent_address_2": "STRING",
      "Permanent_address_3": "STRING",
      "Permanent_city": "STRING",
      "homtel": "STRING",
      "mobile": "STRING",
      "fax_no": "STRING",
      "Permanent_email": "STRING",
      "Permanent_country": "STRING",
      "Permanent_province": "STRING",
      "Permanent_district": "STRING",
      "Permanent_electorate": "STRING",
      "Temporary_address_1": "STRING",
      "Temporary_address_2": "STRING",
      "Temporary_address_3": "STRING",
      "Temporary_city": "STRING",
      "Temporary_postal_code": "STRING",
      "Temporary_telephone_no": "STRING",
      "Temporary_mobile_no": "STRING",
      "Temporary_fax_no": "STRING",
      "Temporary_email": "STRING",
      "Temporary_country": "STRING",
      "Temporary_province": "STRING",
      "Temporary_district": "STRING",
      "Temporary_electorate": "STRING",
      "Office_phone_no": "STRING",
      "Office_extension": "STRING",
      "Office_email": "STRING",
      "Payment_type": "STRING",
      "Employee_display_number": "STRING",
      "Employee_display_name": "STRING"
    }
  ]
}

2. Update Data

Endpoint

  • Live: PUT /v1/update
  • Sandbox: PUT /v1/sandbox/update

Request Body

{
  "status": "S200",
  "data": [
    {
      "payrollno": "STRING",
      "status": "STRING",
      "reason": "STRING",
      "lockin": "INTEGER (Unix timestamp)"
    }
  ]
}

Error Codes

Code Description
E400 Invalid request or missing required fields.
E401 Unauthorized user or invalid credentials.
E403 Missing user header.
E404 Missing created header.
E405 Invalid created header format.
E406 Request time is out of bounds (±60 minutes).
E500 Database error.
S200 Success.
S204 No data found.
S207 Partial success (some records failed to insert).

Examples

1. Retrieve Data Example

POST /v1/sandbox/endpoint HTTP/1.1
Host: localhost:3000
Authorization: Digest username="admin", realm="Protected Area", nonce="...", uri="/v1/sandbox/endpoint", response="..."
user: testuser
created: 2025-10-09T12:11:08+05:30
Content-Type: application/json

Example Response

{
    "code": "S200",
    "message": "Success",
    "data": [
        {
            "Title": "Mr.",
            "Calling_name": "Priyantha",
            "Surname": "Wittahachchi",
            "Maiden_name": "",
            "Name_with_initials": "R.P. Wittahachchi",
            "Names_denoted_by_initials": "Ranjith Priyantha Wittahachchi",
            "Full_name": "Ranjith Priyantha Wittahachchi",
            "Other_names": "Ranjith",
            "EPF_No": "",
            "ID_Number": "663280120V",
            "ID_date": "",
            "Date_of_birth": "1966-11-22T18:30:00.000Z",
            "Place_of_birth": "",
            "Gender": "Male",
            "Nationality": "",
            "Religion": "Buddhism",
            "Blood_group": " ",
            "Marital_status": "Unmarried",
            "Date_of_marriage": "",
            "Date_of_divorce": "",
            "Salary_grade": "EXE",
            "Corporate_title": "Executive",
            "Designation": "Factory Manager",
            "Centre": "PRODUCTION",
            "Date_of_join": "2024-11-30T18:30:00.000Z",
            "Confirmation_Status": "0",
            "Date_of_confirmation": "",
            "Date_of_resignation": {
                "type": "Buffer",
                "data": []
            },
            "Date_of_retirement": {
                "type": "Buffer",
                "data": [
                    50,
                    48,
                    50,
                    52,
                    45,
                    49,
                    50,
                    45,
                    48,
                    49
                ]
            },
            "Hours_of_work": "",
            "Location_code": "",
            "Employment_type": "Permanent",
            "Contract_start_date": "",
            "Contract_end_date": "",
            "Date_of_contract_to_date": "",
            "Barcode_no": "0663280120",
            "Payroll_no": "910-000417",
            "Staff_category_code": null,
            "Category_code": "Executive",
            "GP_code": null,
            "HR_active": "1",
            "Payroll_active": "1",
            "Attendance_active": "1",
            "Hierarchy_name_1": "RICHARD PIERIS & COMPANY PLC",
            "Hierarchy_name_2": "Default",
            "Hierarchy_name_3": "Arpitalian Compact Soles (PVT)LTD",
            "Hierarchy_name_4": "PRODUCTION",
            "Hierarchy_name_5": "",
            "Hierarchy_name_6": "",
            "Tax_on_tax": "",
            "Tax_ID_no": "",
            "EPF_eligible": "0",
            "EPF_employee_amount": "0.00",
            "EPF_employer_amount": "0.00",
            "ETF_eligible": "0",
            "etfno": "058225",
            "etfcom": "0.00",
            "ETF_date": "",
            "MSPS_eligible": "",
            "MSPS_employer_amount": "0",
            "MSPS_employee_amount": "0",
            "Permanent_address_1": "723/44, Lake Terrace,",
            "Permanent_address_2": "Athurugiriya. ",
            "Permanent_address_3": "",
            "Permanent_city": "",
            "homtel": "",
            "mobile": "",
            "fax_no": "",
            "Permanent_email": "",
            "Permanent_country": "Sri Lanka",
            "Permanent_province": "",
            "Permanent_district": "",
            "Permanent_electorate": "",
            "Temporary_address_1": "",
            "Temporary_address_2": "",
            "Temporary_address_3": "",
            "Temporary_city": "",
            "Temporary_postal_code": "",
            "Temporary_telephone_no": "",
            "Temporary_mobile_no": "",
            "Temporary_fax_no": "",
            "Temporary_email": "",
            "Temporary_country": "",
            "Temporary_province": "",
            "Temporary_district": "",
            "Temporary_electorate": "",
            "Office_phone_no": "",
            "Office_extension": "",
            "Office_email": "",
            "Payment_type": "",
            "Employee_display_number": "001693",
            "Employee_display_name": "R.P. Wittahachchi"
        }
    ]
}

2. Update Data Example

PUT /v1/sandbox/update HTTP/1.1
Host: localhost:3000
Authorization: Digest username="admin", realm="Protected Area", nonce="...", uri="/v1/sandbox/update", response="..."
user: testuser
created: 2025-10-09T12:11:08+05:30
Content-Type: application/json

{
  "status": "S200",
  "data": [
    {
      "payrollno": "015-123456",
      "status": "Success",
      "reason": "Processed successfully",
      "lockin": 1696156800
    }
  ]
}

Response 1: Success

{
  "code": "S200",
  "message": "All records inserted successfully",
  "inserted": 1
}

Response 2: Partial Success (No records inserted)

{
    "code": "S207",
    "message": "Partial Success",
    "inserted": 0,
    "errors": [
        {
            "payrollno": "015-123456",
            "error": "Duplicate entry '015-123456' for key 'PRIMARY'"
        },
        {
            "payrollno": "012-345678",
            "error": "Duplicate entry '012-345678' for key 'PRIMARY'"
        }
    ]
}

Response 3: Partial Success (Some records inserted)

{
    "code": "S207",
    "message": "Partial Success",
    "inserted": 1,
    "errors": [
        {
            "payrollno": "012-345678",
            "error": "Duplicate entry '012-345678' for key 'PRIMARY'"
        }
    ]
}

Response 4: Success (Multiple records inserted)

{
    "code": "S200",
    "message": "All records inserted successfully",
    "inserted": 2
}

Notes