NCheck Bio Attendace server API

NCheck Bio Attendace server 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 credintial section of the NCheck Bio Attendace documentaion.

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 1:.

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

API’s

Add/Update user

  • Request: /api/ncheck/user

  • Method: POST

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

    Table 1 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

    1. 0 for Active

    2. 1 for Disabled

    Optional

    Example user object as Listing 2.

    Listing 2 Request body of the add/update user API
    {
        "employeeCode":"13312",
        "firstName":"Peter",
        "lastName":"Hanzward",
        "loginName":"peter",
        "password":"hasnsward",
        "email":"[email protected]",
        "status":0
    }
    
  • Response: Response is a JSON Object with following informations.

    • statusCode: String type parameter to show the status of the request. This is a required field. Available status code are shown in below.

      Table 2 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. This is an optional field.

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

      Listing 3 Response of the add/update user API
      {
          "statusCode":"SUCCESS",
          "statusDescription":"Successfully updated the person",
          "returnValue":
              {
                  "employeeCode":"13312",
                  "firstName":"Peter",
                  "lastName":"Hanzward",
                  "email":"[email protected]",
                  "status":0,
                  "loginName":"peter",
                  "password":"hasnsward"
              }
      }
      

Delete User

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

  • Method: DELETE

  • Parameters: API parameters to delete user

    Table 3 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. Status codes are shown in below.

    Table 4 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/user?code=<employeeCode>

  • Method: GET

  • Parameters

    Table 5 API parameters for get user

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Unique identification code for a user

    Required

  • Response: Requested user as a JSON Object as mentioned in Add/Update user section. Available status codes are shown in below.

    Table 6 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

Update Biometric

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

  • Method: POST

  • Parameters:

    Table 7 API parameters for update biometric

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Unique identification code for a user

    Required

  • Body: JSON Biometric Array

    Table 8 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 4.

    Listing 4 Request body of the update biometric API
    [
        {
            "modality":"face",
            "image":"/9j/4Sc5RXhpZ…",
            "template":null
        },
        {
            "modality":"face",
            "image":"/9j/4SUxRXhpZgAATU0AKgAA…",
            "template":null
        }
    ]
    
  • Response: Biometric Response JSON Object

    • statusCode: String parameter which shows the status of the request. This is a required field. Status codes are showing in following table.

      Table 9 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. This is an optional field.

    • 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. This is a required field. Status codes are shown in below.

        Table 10 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. This is an optional field.

      • returnValue: Null

    Example response as Listing 5

    Listing 5 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/biometric/<employeeCode>/

  • Method: DELETE

  • Parameters:

    Table 11 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. This is a required field. Available status codes are shown in below.

      Table 12 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. This is a required field.

    • returnValue: Null

    Example response similar to Listing 6.

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

Add/Update Events

  • Request: /api/ncheck/event

  • Method: POST

  • Body: JSON Attendance Event Array with following infromation.

    Table 13 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 7.

    Listing 7 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: Attendance Event Response JSON Object with below information.

    • statusCode: Request status in String. This is a required field. Available status codes are shown in below.

      Table 14 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. This is a required field.

    • returnValue: Individual biometric result array if the response is Success. The available details are shown in below.

      • statusCode: Status of the added/updated event as a String. This is a required field. Status codes are follows.

        Table 15 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. This is a required field.

      • returnValue: Attendance event detail as a Json object with below details if the response is Success.

        • 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 8

    Listing 8 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/event/<employeeCode>/

  • Method: DELETE

  • Body: JSON Attendance Event Array as mentioned in Add/Update Events section.

    Example should be similar as Listing 9.

    Listing 9 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: Attendance Event Response JSON Object

    • statusCode: Request status in String. This is a required field. Available status codes are shown in below.

      Table 16 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. This is a required field.

    • returnValue: Selected events details as Json array if the reponse status code is Success. The available details are

      • statusCode: Status of the deleted event as a String. This is a required field. Status codes as follows.

        Table 17 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. This is a required field

      • returnValue: Event detail as a Json object with below details if the status code is success.

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

    Listing 10 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/event?code=<employeeCode>&from=<fromDateTime>&to=<toDateTime>

  • Method: GET

  • Parameters:

    Table 18 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. This is a required field. Available status codes are shown in below.

      Table 19 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. This is a required field

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

      • statusCode: Status of the event detail as String. This is a required field. Status codes are shown in below

        Table 20 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. This is a required field

      • returnValue: Json object containing event details if the status code is Success.

        • 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 11.

    Listing 11 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
                }
            }
        ]
    }
    

Work hour report

  • Request: /api/ncheck/report/workhour? from=<fromDateTime>&to=<toDateTime>&grouptype=<groupType>&groupcodes=<groupCodes>&shiftname=<shiftName>&pagenumber=<pageNumber>&pagesize=<pageSize>

  • Method: GET

  • Parameters:

    Table 21 API parameters for get attendance events

    Parameter

    Type

    Description

    Availability

    fromDateTime

    string

    Formatted date time string as yyyy-MM-dd HH:mm:ss

    Required

    toDateTime

    string

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

    Required

    groupType

    string

    Work hour group type (DAILY, WEEKLY, MONTHLY)

    Optional ( Default value: DAILY)

    groupCodes

    string

    Comma separated values of group codes

    Optional

    shiftName

    string

    Shift filter

    Optional

    pageNumber

    int

    Page number

    Optional

    pageSize

    int

    Page number

    Optional

  • Response: Work hour report response JSON object

    • statusCode: Status of the event detail as String. This is a required field. Possible status codes are shown in below.

      Table 22 Possible status codes in the API response for Work hour report

      Status code

      Description

      INVALID_PARAMETERS

      Invalid Parameters

      ERROR

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

      SUCCESS

      Successful

    • statusDescription: Detail of the status as String. This is a required field.

    • returnValue: Report data array as Array[Object] if the status code is success.

      Table 23 Return values of work hour report API

      Parameter

      Type

      Description

      Availability

      employeeCode

      string

      Employee code

      Required

      firstName

      string

      First name of the employee

      Required

      employeeCode

      string

      Employee code

      lastName

      string

      Last name of the employee

      customdata

      Object

      Custom data

      If available

      shiftWorkTime

      workTime

      inOutTime

      productiveWorkTime

      overtime

      earlyArrival

      lateArrival

      earlyDepature

      lateDepature

      totalUnProductiveTime

      totalBreakHours

      actualBreakHours

      firstCheckin

      string

      Formatted date time string as yyyy-MM-dd HH:mm:ss

      lastCheckin

      string

      Formatted date time string as yyyy-MM-dd HH:mm:ss

      tzOffset

      int

      UTC timezone offset

      Default 0

    Listing 12 Response of the get Attendance events API
    {
    "statusCode":"SUCCESS",
    "statusDescription":"Get events successful",
    "returnValue":[
        {
            "employeeCode":"13312",
            "firstName": "first_name",
            "lastName": "last_name",
            "customdata": {},
            "shiftHours": 86399,
            "shiftWorkHours": 86399,
            "workHours": 37800,
            "inOuttime": 37800,
            "productiveHours": 37800,
            "productiveWorkHours": 37800,
            "overtime": 0,
            "earlyArrival": 0,
            "lateArrival": 30600,
            "earlyDepature": 17999,
            "lateDepature": 0,
            "totalUnProductiveHours": 48599,
            "actualBreakHours": 0,
            "firstCheckin": "2020-04-24 08:30:00",
            "lastCheckout": "2020-04-24 19:00:00",
            "tzOffset":0
        }
    ]}