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 Listing 2:.

Listing 2 Authentication token
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.

Access restrictions

API access restrictions can be applied in order to prevent data editing and lost. There are two roles can be assigned to restrict access to API’s as below,

  • Admin

    Admin role has rights to use for all API’s.

  • Admin audit

    Admin.audit role has rights to view all data. Admin audit doesn’t have rights to edit or delete data.

API’s

Add/Update user

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

  • Method: POST

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

    Table 65 Required parameters in the API body to add/update user

    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 Listing 3.

    Listing 3 Request body of the add/update user API
    {
        "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

      Table 66 Possible status codes in the API response for add/update user

      Status 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 Listing 4.

    Listing 4 Response of the add/update user API
    {
        "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: /api/ncheck/<role>/user/<employeeCode>/

  • Method: DELETE

  • Parameters: API parameters to delete user

    Table 67 API parameters for delete user

    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

    Table 68 Possible status codes in the API response for delete user

    Status 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: /api/ncheck/<role>/user?code=<employeeCode>

  • Method: GET

  • Parameters

    Table 69 API parameters for get user

    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

    Table 70 Possible status codes in the API response for get user

    Status 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: /api/ncheck/<role>/biometric/<employeeCode>/

  • Method: POST

  • Parameters:

    Table 71 API parameters for update biometric

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Unique identification code for a user

    Required

  • Body: Biometric details as a JSON array.

    Table 72 Required parameters in the API body to update biometrics

    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 Listing 5.

    Listing 5 Request body of the update biometric API
    [
        {
            "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

      Table 73 Possible status codes in the API response for update biometrics

      Status 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

        Table 74 Possible status codes in the API response for each updating biometric

        Status 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 Listing 6

    Listing 6 Response of the update biometric API
    {
        "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: /api/ncheck/<role>/biometric/<employeeCode>/

  • Method: DELETE

  • Parameters:

    Table 75 API parameters for delete biometric

    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

      Table 76 Possible status codes in the API response for delete biometric

      Status 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 to Listing 7.

    Listing 7 Response of the delete biometric API
    {
        "statusCode":"SUCCESS",
        "statusDescription":"Successfully deleted the person",
        "returnValue":null
    }
    

Add/Update Events

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

  • Method: POST

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

    Table 77 Required parameters in the API body to add/update events

    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 Listing 8.

    Listing 8 Request body of the add/update events API
    [
        {
            "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

      Table 78 Possible status codes in te API response for add/update events

      Status 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

        Table 79 Possible status codes in te API response for each add/update event

        Status 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 as Listing 9

    Listing 9 Response of the add/update events API
    {
        "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: /api/ncheck/<role>/event/<employeeCode>/

  • Method: DELETE

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

    Table 80 Required parameters in the API body to delete events

    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 Listing 10.

    Listing 10 Request body of tthe delete events API
    [
        {
            "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

      Table 81 Possible status codes in te API response for delete events

      Status 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

        Table 82 Possible status codes in te API response for each deleting event

        Status 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 Listing 11.

    Listing 11 Response of tthe delete events API
    {
        "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: /api/ncheck/<role>/event?code=<employeeCode>&from=<fromDateTime>&to=<toDateTime>

  • Method: GET

  • Parameters:

    Table 83 API parameters for get attendance events

    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

      Table 84 Possible status codes in the API response for get attendance events

      Status 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

        Table 85 Possible status codes in the API response for each attendance event

        Status 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 shown in Listing 12.

    Listing 12 Response of the get Attendance events API
    {
        "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
                }
            }
        ]
    }