NCHECK API

NCheck API can be used by programmers to retrieve and update attendance system data in NCheck Bio Attendance. It can manage following information.

  1. Users/Employees

  2. Biometrics data

  3. Attendance events

API credentials

API user name and password can be generate by NCheck Bio Attendance server administrator as mentioned in generate API access credentials section. Programmers can use the username and password to generate a session authentication token to use in API method calls. Authentication token expires in one week. Once it expired, the new authentication token can be generated using the same username and password. Refer section Authentication token for more detail about generating authentication token.

Authentication token

Session authentication token is used to authenticate API method calls. Authentication token retrieval request call using C# is shown in Figure 1

_images/image2.PNG

Figure 1 Getting authentication token using C# code

In the code following variables should be replaced with the given values

Table 1 Variables of C# code for getting access token using

Variable

Value

Server_url

The URL of the NCheck Bio Attendance server

User_name

Username for the API

password

Password for the API

If the response is successful, the access token will be extracted from the access_token variable.

API’s

Once the access token has retrieved, API’s can be used to manage data as follows.

  1. User employee data

    NCheck Bio Attendance APIs allows to add. update, delete user/employee and retrieve user/employee data from the system

  2. Biometric data

    Add/delete biometric images (Face, finger, and iris).

  3. Attendance events

    Retrieve/delete user/employee attendance events.

User employee data

NCheck Bio Attendance is providing following APIs to manage user employee data

  1. Add/update user

  2. Delete User

  3. Get user

Add/update user

This API can be used for add news user or change user details as shown in Table 2 .

  1. Request: /api/ncheck/user

  2. Method: POST

  3. Body

    User/employee as a JSON object with following information. Table 2 is showing the parameters required in the json object. Figure 2 is showing the sample JSON object with parameters.

    Table 2 parameters of the JSON object

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    1. Unique identification code for a user.

    2. To update the details, add the employee code of the existing 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

    _images/image4.PNG

    Figure 2 JSON object for the body of add/update user request

  4. Response

    Response is a JSON Object with following information.

    1. statusCode

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

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

    2. statusDescription

      String parameter to show the description of the status code. This is an optional field.

    3. returnValue

      Added/edited user details as json object if the status code is success as shown in Figure 3

      _images/image6.PNG

      Figure 3 Json response for add/update user

Figure 4 is showing sample C# code to add new user.

_images/image8.PNG

Figure 4 C# code to add an employee

Delete User

This API is using to delete an existing user.

  1. Request: /api/ncheck/user/<employeeCode>/

  2. Method: DELETE

  3. Parameters

    API parameters to delete user

    Table 4 API parameters for delete user

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Unique identification code for a user

    Required

  4. Response

    Status codes are shown in Table 5 . If the status code is success, a JSON object will be received with the deleted person details as shown in Figure 5 .

    Table 5 Status codes in the API response for delete user API

    Status code

    Description

    USER_NOT_AVAILABLE

    User is not found.

    ERROR

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

    SUCCESS

    Successful

    _images/image10.PNG

    Figure 5 JSON response for delete user

Figure 6 Is showing the C# code sample to delete an user.

_images/image12.PNG

Figure 6 C# code sample to delete an employee

Get user

Existing user detail can be retrieved from this API as shown in Figure 7 .

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

  2. Method: GET

  3. Parameters

    Table 6 API parameters for get user

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Unique identification code for a user

    Required

  4. Response

    Table 7 is showing the status code of the API response. Figure 7 is showing the Json object in the response.

    Table 7 Status codes in the API response for get user API

    Status code

    Description

    USER_NOT_AVAILABLE

    User is not found

    ERROR

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

    SUCCESS

    Successful

    _images/image14.PNG

    Figure 7 JSON response for get user API

Figure 8 Is showing the C# sample code to get the user.

_images/image16.PNG

Figure 8 C# code sample to get an employee detail

Biometric data

User/employee biometric data images as face, fingerprint, and iris images can be managed using following APIs.

  1. Update biometric

  2. Delete biometric

Update biometric

User biometric(s) including face, finger and iris can be enrolled using this API.

  1. Request: /api/ncheck/biometric?code=<employeeCode>/

  2. Method: POST

  3. Parameters:

    Table 8 API parameters for update biometric

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Unique identification code for a user

    Required

  4. Body

    JSON Biometric Array with parameters as shown in Table 8 . Example JSON body has shown in Figure 9 .

    Table 9 Parameters in the JSON body to update biometrics API

    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

    _images/image18.PNG

    Figure 9 Biometrics Json array body for update biometric API

  5. Response

    JSON response has shown in Figure 10

    _images/image20.PNG

    Figure 10 Json response for add biometric API

    1. statusCode

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

      Table 10 Status codes in the API response for update biometrics API

      Status code

      Description

      INVALID_PARAMETERS

      No biometric data sent

      USER_NOT_AVAILABLE

      No user available for the given employee code

      SUCCESS

      Successful

    2. statusDescription

      Detail of the status as a String. This is an optional field.

    3. returnValue

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

      1. statusCode

        Status of the enrolled biometric. The status codes are showing in below.

        Table 11 Status codes for individual biometric result in the API response for update biometrics API

        Status code

        Description

        ENROLL_FAILED

        The biometric has enrolled to different user

        FAILED_TO_EXTRACT

        Failed to extract the biometrics

        SUCCESS

        Successful

      2. statusDescription

        Description of the status as a String.

      3. ReturnVale

        This is always null.

Figure 11 is showing a sample C# code to update biometrics.

_images/image22.PNG

Figure 11 C# code sample to update biometrics

Delete biometric

All user biometric(s) can be deleted using this API.

  1. Request: /api/ncheck/biometric/<employeeCode>/

  2. Method: DELETE

  3. Parameters:

    Table 12 parameters for delete biometric

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Unique identification code for a user

    Required

  4. Response:

    JSON response is shown in Figure 12

    _images/image24.PNG

    Figure 12 JSON response for delete biometric API

    1. statusCode

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

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

    2. statusDescription

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

    3. returnValue: Null

Figure 13 is showing the C# code sample for delete user biometric(s).

_images/image26.PNG

Figure 13 C# code sample to delete biometrics

Attendance events

User/employee attendance data can be managed using following APIs

  1. Get attendance events

  2. Add events

  3. Delete events

Get attendance events

Get attendance event details of selected user for a given time range.

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

  2. Method: GET

  3. Parameters:

    Table 14 parameters for get attendance events API

    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

  4. Response

    All attendance events as Json array with below parameters.

    _images/image28.PNG

    Figure 14 JSON response for get attendance events API

    1. statusCode

      Status of the requested event details as String. This is a required field. Available status codes are shown in below.

      Table 15 Status codes in the response for get attendance events API

      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

    2. statusDescription

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

    3. returnValue

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

      1. statusCode

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

        Table 16 Status codes for each individual attendance records in the get attendance events API

        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

      2. statusDescription

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

      3. returnValue

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

        1. employeeCode

          Employee code of the user as String

        2. inTime

          Checked-in time as a date time string, formatted in yyyy-MM-dd HH:mm:ss

        3. outTime

          Checked-out time as a date time string, formatted in yyyy-MM-dd HH:mm:ss

        4. Shift

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

        5. tzOffset

          UTC timezone offset int. Default is 0.

Figure 15 Is showing the C# sample for get attendance events for a user

_images/image30.PNG

Figure 15 C# code sample for get attendance events

Add events

This API can be used for adding attendance event for user(s).

  1. Request: /api/ncheck/event/

  2. Method: POST

  3. Body

    JSON array object with adding event(s) details as shown in Figure 16 .

    1. employeeCode

      Employee code the user needs to delete the attendance events

    2. inTime

      Checked-in time as a date time string, formatted in yyyy-MM-dd HH:mm:ss

    3. outTime

      Checked-out time as a date time string, formatted in yyyy-MM-dd HH:mm:ss

    4. Shift

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

    5. tzOffset

      UTC timezone offset as an integer. Default is 0.

      _images/image32.PNG

      Figure 16 JSON body for add events API

  4. Response

    Response JSON Object with the status of the individual attendance events as JSON objects as shown in Figure 17

    _images/image34.PNG

    Figure 17 JSON response for add events API

    1. statusCode

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

      Table 17 Status codes in the API response for add 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

    2. statusDescription

      Status description as a String. This is a required field.

    3. returnValue

      Selected events details as Json array if the response status code is Success. The available details are

      1. statusCode

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

        Table 18 Status codes for individual attendance 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

      2. statusDescription

        Status description as a String. This is a required field

      3. returnValue

        Added event detail as a JSON object.

Figure 18 is showing a C# code sample for delete events

_images/image36.PNG

Figure 18 C# code sample to add events

Delete events

This API can be used for deleting attendance event from a user.

  1. Request: /api/ncheck/event/

  2. Method: DELETE

  3. Body

    JSON array object with deleting event(s) details as shown in Figure 19 .

    1. employeeCode

      Employee code the user need to delete the attendance events

    2. inTime

      Checked-in time as a date time string, formatted in yyyy-MM-dd HH:mm:ss

    3. outTime

      Checked-out time as a date time string, formatted in yyyy-MM-dd HH:mm:ss

    4. Shift

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

    5. tzOffset

      UTC timezone offset as an integer. Default is 0.

      _images/image38.PNG

      Figure 19 JSON body for delete events API

  4. Response

    Attendance Event Response JSON Object with the status of the individual attendance events as JSON objects as shown in

    _images/image40.PNG

    Figure 20 JSON response for delete events API

    1. statusCode

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

      Table 19 Status codes in the 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

    2. statusDescription

      Status description as a String. This is a required field.

    3. returnValue

      Selected events details as Json array if the response status code is Success. The available details are

      1. statusCode

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

        Table 20 Status codes for individual attendance 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

      2. statusDescription

        Status description as a String. This is a required field

      3. returnValue

        Deleted event detail as a JSON object.

Figure 21 Is showing a C# code sample for delete events

_images/image42.PNG

Figure 21 C# code sample to delete events