NCHECK BIO ATTENDANCE API

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

  1. Users/Employees

  2. User Biometrics data

  3. Event logs

API key and secret code

All API calls are authenticated with key and secret created as mentioned in the Generate API access credinitals 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 Figure 451 Authentication token.

_images/image983.PNG

Figure 451 Authentication token

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,

  1. Admin

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

  2. Admin audit

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

Add/Update user

  1. Request: /api/ncheck/user

  2. Method: POST

  3. Body: user/employe as a json object with following information’s. Table 136 Required parameters in the API body to add/update useris showing required parameters in the request. Figure 452 Request body of the add/update user API is showing an example of the response body

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

    _images/image985.PNG

    Figure 452 Request body of the add/update user API

  4. Response: Response is a JSON Object with following information. Figure 453 7.3 Response of the add/update user API is showing the example response of the request.

    1. statusCode: String type parameter to show the status of the request. All status codes are showing in following table

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

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

    3. returnValue: Added/edited user details as json object

      _images/image987.PNG

      Figure 453 Response of the add/update user API

Delete User

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

  2. Method: DELETE

  3. Parameters: API parameters to delete user

    Table 138 API parameters for delete user

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Unique identification code for a user

    Required

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

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

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

  2. Method: GET

  3. Parameters

    Table 140 API parameters for get user

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Unique identification code for a user

    Required

  4. Response: Requested user details with the following information.

    1. statusCode: String type parameter to show the status of the request. Status codes are shown in below.

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

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

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

Update Biometric

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

  2. Method: POST

  3. Parameters:

    Table 142 API parameters for update biometric

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Unique identification code for a user

    Required

  4. Body: Biometric details as a JSON array. Table 143 Required parameters in the API body to update biometrics is showing the required parameters for the request. Figure 454 Request body of the update biometric API is showing the example body of the request.

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

    _images/image989.PNG

    Figure 454 Request body of the update biometric API

  5. Response: Response is a JSON Object with below information. Example response has shown in Figure 455 Response of the update biometric API.

    1. statusCode: String parameter which shows the status of the request. Status codes are shown in below.

      Table 144 Possible status codes in the API response for update 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_SUPPORTE

      D Biometric type is unknown

      ENROLLMENT_ERROR

      Enrolling biometric is failed

      ERROR System

      error (Need to check server logs for more informations)

      SUCCESS

      Successful

    2. statusDescription: Detail of the status as a String.

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

      1. statusCode: Status of the biometric detail as a String. Status codes are shown in below.

Table 145 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_SUPPORTE

Biometric type is unknown

ENROLLMENT_ERROR

Enrolling biometric is failed

ERROR System

error (Need to check server logs for more informations)

SUCCESS

Successful

  1. statusDescription: Detail of the status as String

  2. returnValue: Null

_images/image991.PNG

Figure 455 Response of the update biometric API

Delete Biometric

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

  2. Method: DELETE

  3. Parameters:

    Table 146 API parameters for delete biometric

    Parameter

    Type

    Description

    Availability

    employeeCode

    string

    Unique identification code for a user

    Required

  4. Response: Json object with below information. Figure 456 Response of the delete biometric API is showing the example response from the request.

    1. statusCode: Request status in String. Available status codes are shown in below.

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

      Successful

    2. statusDescription: Detail of the status as String.

    3. returnValue: Null

      _images/image993.PNG

      Figure 456 Response of the delete biometric API

Add/Update Events

  1. Request: /api/ncheck/event

  2. Method: POST

  3. Body: Attendance events need to be updated as Json Array with below information. Figure 457 7.7 Request body of the add/update events API is showing the example response from the request.

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

    Shiftname.If empty, default shift is selected

    Optional

    tzOffset

    int

    UTC timezone off-set

    Default is 0

    _images/image995.PNG

    Figure 457 Request body of the add/update events API

  4. Response: Added/updated attendance events as Json object as follows. Figure 458 Response of the add/update events API is showing the example response of the request.

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

      Table 149 Possible status codes in the 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

    2. statusDescription: Status description as a String.

    3. returnValue: Request attendance event details as Json array if the request status is Success. The available details are shown in below.

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

        Table 150 Possible status codes in the 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

      2. statusDescription: Status description as a String.

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

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

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

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

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

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

_images/image997.PNG

Figure 458 Response of the add/update events API

Delete Events

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

  2. Method: DELETE

  3. Body: All events need to be deleted as a Json array with below details. Figure 459 Request body of the delete events API is showing the example request body.

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

    _images/image999.PNG

    Figure 459 Request body of the delete events API

  4. Response: Deleted attendance events details as Json array with below details. Figure 460 Response of the delete events API is showing the example response of the request.

    1. statusCode: Request status in String. Available status codes are shown in below.

      Table 152 Possible 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.

    3. returnValue: Selected events details as Json array. The available details are shown in below.

      1. statusCode: Status of the deleted event as a String. Status codes are shown in below.

        Table 153 Possible status codes in the 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

      2. statusDescription: Status description as a String.

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

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

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

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

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

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

_images/image1001.PNG

Figure 460 Response of the delete events API

Get Attendance events

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

  2. Method: GET

  3. Parameters:

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

  4. Response: All attendance events as Json array with below parameters. Figure 461 7.11 Response of the get Attendance events API is showing an example response of the request.

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

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

    2. statusDescription: Detail of the status as String.

    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. Possible status codes are

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

      2. statusDescription: Detail of the status as String.

      3. returnValue: Json object containing event details.

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

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

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

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

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

_images/image1003.PNG

Figure 461 Response of the get Attendance events API