NCheck Bio Attendance API

NCheck Bio Attendance API Provides APIs to manage information in the following entities.

  • Users/Employees

  • User Biometrics data

  • Event logs

API key and secret code

All API calls are authenticated with key and secret created as mentioned in the generate API access credentials section in NCheck Bio Attendance server.

Authentication token

All API calls use OAuth2 authentication token to authenticate. The authentication token can be retrieved using OAuth2 resource owner password grant flow. Authentication request can be prepared as below.

serverUrl =”https://localhost:8443” key=”1ZNIOZOYOY”;
secret=”JYUH5K368YNIP5LXAS1Z”;
req =Request(serverUrl + "/oauth/token");
req.Method = "POST";
req.Headers["Authorization"] = "Basic " + Base64String(("ncheck:");
req.ContentType = "application/x-www-form-urlencoded";
var body = "grant_type=password&username=" + key + "&password=" + secret;
req.ContentLength = body.Length;

Response will be a json object with the access_token value for successful call. Received access token should be used to authenticate API calls.

API’s

Add/Update user

  • Request: /ncheck/api/user

  • Method: POST

  • Body: user/employe as a json object with following informations.

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Unique identification code for a user

    Required

    firstName

    string

    First name of the user

    Required

    lastName

    string

    Last name of the user

    Required

    email

    string

    Email address

    Optional

    loginName

    string

    Login name for the user. Login cannot change on update

    Optional

    password

    string

    Password of the user. Password cannot be changed on update

    Optional

    status

    string

    Status of the user as 0 for Active, 1 for Disabled

    Optional

    Example user object as follows.

    {
        "employeeCode":"13312",
        "firstName":"Peter",
        "lastName":"Hanzward",
        "loginName":"peter",
        "password":"hasnsward",
        "email":"peter@hanzward.com",
        "status":0
    }
    
  • Response: Response is a JSON Object with following informations.

    • statusCode: String type parameter to show the status of the request. Available status code are

      Error code

      Description

      INVALID_EMAIL

      Email address is invalid

      FIRST_NAME_EMPTY

      First name is empty

      Last_NAME_EMPTY

      Last name is empty

      INVALID_EMPCODE

      Employee code is already used

      ERROR

      System error (Need to check server logs for more details)

      SUCCESS

      Successful

    • statusDescription: String parameter to show the description of the status code.

    • returnValue: Added/edited user details as json object if the status code is success as shown in below code snippet.

    {
        "statusCode":"SUCCESS",
        "statusDescription":"Successfully updated the person",
        "returnValue":
            {
                "employeeCode":"13312",
                "firstName":"Peter",
                "lastName":"Hanzward",
                "email":"peter@hanzward.com",
                "status":0,
                "loginName":"peter",
                "password":"hasnsward"
            }
    }
    

Delete User

  • Request: /ncheck/api/user/<employeeCode>/

  • Method: DELETE

  • Parameters:

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Unique identification code for a user

    Required

  • Response: Deleted user as a JSON Object as mentioned in Add/Update user section. The possible status codes are

    Error code

    Description

    USER_NOT_AVAILABLE

    User is not found.

    ERROR

    System error (Need to check server logs for more information)

    SUCCESS

    Successful

Get user

  • Request: /ncheck/api/user?code=<employeeCode>

  • Method: GET

  • Parameters

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Unique identification code for a user

    Required

  • Response: Requested user details with the following information.

    • statusCode: String type parameter to show the status of the request. Available status codes are

    Error code

    Description

    USER_NOT_AVAILABLE

    User is not found

    ERROR

    System error (Need to check server logs for more details)

    SUCCESS

    Successful

    • statusDescription: String parameter to show the description of the status code.

    • returnValue: Request user details as json object if the status code is success.

Update Biometric

  • Request: /ncheck/api/biometric/<employeeCode>/

  • Method: POST

  • Parameters:

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Unique identification code for a user

    Required

  • Body: Biometric details as a JSON array.

    Parameter

    Type

    Description

    Availability

    modality

    string

    Biometric modality ( face, finger, iris)

    Required

    image

    byte[]

    Biometric raw Image.

    Optional

    template

    byte[]

    Biometric template. Required is no image.

    Optional

    Example request body as follows.

    [
        {
            "modality":"face",
            "image":"/9j/4Sc5RXhpZ…",
            "template":null
        },
        {
            "modality":"face",
            "image":"/9j/4SUxRXhpZgAATU0AKgAA…",
            "template":null
        }
    ]
    
  • Response: Response is a JSON Object with below information.

    • statusCode: String parameter which shows the status of the request. Status codes are

      Error code

      Description

      INVALID_PARAMETERS

      Invalid data is found.

      USER_NOT_AVAILABLE

      User is not found

      FAILED_TO_EXTRACT

      Biometric feature extraction is failed

      BIOMETRIC_TYPE_NOT_SUPPORTED

      Biometric type is unknown

      ENROLLMENT_ERROR

      Enrolling biometric is failed

      ERROR System

      error (Need to check server logs for more informations)

      SUCCESS

      Successful

    • statusDescription: Detail of the status as a String.

    • returnValue: Individual biometric result array as a Json object for successful requests with the following information.

      • statusCode: Status of the biometric detail as a String. Status codes are

        Error code

        Description

        INVALID_PARAMETERS

        Invalid data is found.

        USER_NOT_AVAILABLE

        User is not found

        FAILED_TO_EXTRACT

        Biometric feature extraction is failed

        BIOMETRIC_TYPE_NOT_SUPPORTED

        Biometric type is unknown

        ENROLLMENT_ERROR

        Enrolling biometric is failed

        ERROR System

        error (Need to check server logs for more informations)

        SUCCESS

        Successful

      • statusDescription: Detail of the status as String

      • returnValue: Null

    Example response as follows

    {
        "statusCode":"SUCCESS",
        "statusDescription":"Successfully enrolled biometrics",
        "returnValue":
        [
            {
            "statusCode":"SUCCESS",
            "statusDescription":"Successfully enrolled biometrics",
            "returnValue":null
            },
            {
            "statusCode":"SUCCESS",
            "statusDescription":"Successfully enrolled biometrics",
            "returnValue":null
            }
        ]
    }
    

Delete Biometric

  • Request: /ncheck/api/biometric/<employeeCode>/

  • Method: DELETE

  • Parameters:

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Unique identification code for a user

    Required

  • Response: Json object with below information.

    • statusCode: Request status in String. Available status codes are

      Error code

      Description

      USER_NOT_AVAILABLE

      User is not found

      ERROR

      System error (Need to check server logs for more details)

      SUCCESS

      Successfull

    • statusDescription: Detail of the status as String.

    • returnValue: Null

    Example response similar below.

    {
        "statusCode":"SUCCESS",
        "statusDescription":"Successfully deleted the person",
        "returnValue":null
    }
    

Add/Update Events

  • Request: /ncheck/api/event

  • Method: POST

  • Body: Attendance events need to be updated as Json Array with below information.

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Biometric modality ( face, finger, iris)

    Required

    inTime

    string

    Formatted date time string as yyyy-MMdd HH:mm:ss

    Optional

    outTime

    string

    Formatted date time string as yyyy-MMdd HH:mm:ss

    Optional if inTime is available

    shift

    string

    Shift name. If empty, default shift is selected

    Optional

    tzOffset

    int

    UTC timezone offset

    Default is 0

    Json array should be like below.

    [
        {
            "employeeCode":"13312",
            "inTime":"2019-06-17 08:30:50",
            "outTime":"2019-06-17 16:37:24",
            "shiftName":"Day Shift",
            "tzOffset":0
        },
        {
            "employeeCode":"13312",
            "inTime":"2019-06-18 08:38:20",
            "outTime":"2019-06-18 17:12:20",
            "shiftName":"Day Shift",
            "tzOffset":0
        }
    ]
    
  • Response: Added/updated attendance events as Json object as follows.

    • statusCode: Request status in String. Available status codes are

      Error code

      Description

      INVALID_PARAMETERS

      Matching event cannot be found

      USER_NOT_AVAILABLE

      User is not found

      ERROR

      System error (Need to check server logs for more details)

      SUCCESS

      Successful

    • statusDescription: Status description as a String.

    • returnValue: Request attendance event details as Json array if the request status is Success. The available details are

      • statusCode: Status of the added/updated event as a String. Status codes would be

        Error code

        Description

        INVALID_PARAMETERS

        Matching event cannot be found

        USER_NOT_AVAILABLE

        User is not found

        ERROR

        System error (Need to check server logs for more details)

        SUCCESS

        Successful

      • statusDescription: Status description as a String.

      • returnValue: Attendance event detail as a Json object with below details.

        • employeeCode: Biometric modality ( face, finger, iris) as String

        • inTime: Formatted date time string as yyyy-MMdd HH:mm:ss as String

        • outTime: Formatted date time string as yyyy-MMdd HH:mm:ss as String. Optional if inTime is not available.

        • shift: Shift name as String. If empty, default shift is selected.

        • tzOffset: UTC timezone offset int. Deafult is 0.

    Example response would be

    {
        "statusCode":"SUCCESS",
        "statusDescription":"Successfully updated event logs",
        "returnValue":
        [
            {
                "statusCode":"SUCCESS",
                "statusDescription":"Successfully updated checkin checkout events",
                "returnValue":{
                    "employeeCode":"13312",
                    "inTime":"2019-06-17 08:30:50",
                    "outTime":"2019-06-17 16:37:24",
                    "shiftName":"Day Shift",
                    "tzOffset":0
                }
            },
            {
                "statusCode":"SUCCESS",
                "statusDescription":"Successfully updated checkin checkout events",
                "returnValue":{
                    "employeeCode":"13312",
                    "inTime":"2019-06-18 08:38:20",
                    "outTime":"2019-06-18 17:12:10",
                    "shiftName":"Day Shift",
                    "tzOffset":0
                }
            }
        ]
    }
    

Delete Events

  • Request: /ncheck/api/event/<employeeCode>/

  • Method: DELETE

  • Body: All events need to be deleted as a Json array with below details.

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Biometric modality ( face, finger, iris)

    Required

    inTime

    string

    Formatted date time string as yyyy-MMdd HH:mm:ss

    Optional

    outTime

    string

    Formatted date time string as yyyy-MMdd HH:mm:ss

    Optional if inTime is available

    shift

    string

    Shift name. If empty, default shift is selected

    Optional

    tzOffset

    int

    UTC timezone offset

    Default 0

    Example should be similar as below.

    [
        {
            "employeeCode":"13312",
            "inTime":"2019-06-17 08:30:50",
            "outTime":"2019-06-17 16:37:24",
            "shiftName":"Day Shift",
            "tzOffset":0
        },
        {
            "employeeCode":"13312",
            "inTime":"2019-06-18 08:38:20",
            "outTime":"2019-06-18 17:12:20",
            "shiftName":"Day Shift",
            "tzOffset":0
        }
    ]
    
  • Response: Deleted attendance events details as Json array with below details.

    • statusCode: Request status in String. Available status codes are

      Error code

      Description

      INVALID_PARAMETERS

      Matching event cannot be found

      USER_NOT_AVAILABLE

      User is not found

      ERROR

      System error (Need to check server logs for more details)

      SUCCESS

      Successful

    • statusDescription: Status description as a String.

    • returnValue: Selected events details as Json array. The available details are

      • statusCode: Status of the deleted event as a String. Status codes would be

        Error code

        Description

        INVALID_PARAMETERS

        Matching event cannot be found

        USER_NOT_AVAILABLE

        User is not found

        ERROR

        System error (Need to check server logs for more details)

        SUCCESS

        Successful

      • statusDescription: Status description as a String.

      • returnValue: Event detail as a Json object with below details.

        • employeeCode: Biometric modality ( face, finger, iris) as String

        • inTime: Formatted date time string as yyyy-MMdd HH:mm:ss as String

        • outTime: Formatted date time string as yyyy-MMdd HH:mm:ss as String. Optional if inTime is not available.

        • shift: Shift name as String. If empty, default shift is selected.

        • tzOffset: UTC timezone offset int. Default is 0.

    Example response as follows.

    {
        "statusCode":"SUCCESS",
        "statusDescription":" Deleting events successful",
        "returnValue":[
            {
                "statusCode":"SUCCESS",
                "statusDescription":" Successfully deleted the attendance event ",
                "returnValue":{
                    "employeeCode":"13312",
                    "inTime":"2019-06-17 08:30:50",
                    "outTime":"2019-06-17 16:37:24",
                    "shiftName":"Day Shift",
                    "tzOffset":0
                }
            },
            {
                "statusCode":"SUCCESS",
                "statusDescription":" Successfully deleted the attendance event",
                "returnValue":{
                    "employeeCode":"13312",
                    "inTime":"2019-06-18 08:38:20",
                    "outTime":"2019-06-18 17:12:10",
                    "shiftName":"Day Shift",
                    "tzOffset":0
                }
            }
        ]
    }
    

Get Attendance events

  • Request: /ncheck/api/event?code=<employeeCode>&from=<fromDateTime>&to=<toDateTime>

  • Method: GET

  • Parameters:

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Unique identification code for a user

    Optional

    toDateTime

    string

    Formatted date time string as yyyy-MMdd HH:mm:ss

    Required

    toDateTime

    string

    Formatted date time string as yyyy-MMdd HH:mm:ss

    Required

  • Response: All attendance events as Json array with below parameters.

    • statusCode: Status of the requested event details as String. Available status codes are

      Error code

      Description

      USER_NOT_AVAILABLE

      User is not found

      INVALID_TIME_FORMAT

      Date format is invalid

      ERROR

      System error (Need to check server logs for more details)

      SUCCESS

      Successful

    • statusDescription: Detail of the status as String.

    • returnValue: Requested event details as Json array if the status code is Success with below information.

      • statusCode: Status of the event detail as String. Possible status codes are

        Error code

        Description

        USER_NOT_AVAILABLE

        User is not found

        INVALID_TIME_FORMAT

        Date format is invalid

        ERROR

        System error (Need to check server logs for more details)

        SUCCESS

        Successful

      • statusDescription: Detail of the status as String.

      • returnValue: Json object containing event details.

        • employeeCode: Biometric modality ( face, finger, iris) as String

        • inTime: Formatted date time as yyyy-MMdd HH:mm:ss as String. This is optional

        • outTime: Formatted date time as yyyy-MMdd HH:mm:ss as String. Optional if inTime is not available.

        • shift: Shift name as String. If empty, default shift is selected.

        • tzOffset: UTC timezone offset int. Deafult is 0.

    Example response is showing below.

    {
        "statusCode":"SUCCESS",
        "statusDescription":"Successfully updated event logs",
        "returnValue":[
            {
                "statusCode":"SUCCESS",
                "statusDescription":"Successfully updated checkin checkout events",
                "returnValue":{
                    "employeeCode":"13312",
                    "inTime":"2019-06-17 08:30:50",
                    "outTime":"2019-06-17 16:37:24",
                    "shiftName":"Day Shift",
                    "tzOffset":0
                }
            },
            {
                "statusCode":"SUCCESS",
                "statusDescription":"Successfully updated checkin checkout events",
                "returnValue":{
                    "employeeCode":"13312",
                    "inTime":"2019-06-18 08:38:20",
                    "outTime":"2019-06-18 17:12:10",
                    "shiftName":"Day Shift",
                    "tzOffset":0
                }
            }
        ]
    }