NCHECK API

NCheck API can be used by programmers to retrieve and update attendance system data in NCheck Bio Attendance Integration Manual. 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 Integration Manual 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

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 Integration Manual 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 Integration Manual 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 Integration Manual 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	Unique identification code for a user. 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 0 for Active 1 for Disabled	Optional

   

   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

      

      Figure 3 Json response for add/update user

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

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

   

   Figure 5 JSON response for delete user

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

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

   

   Figure 7 JSON response for get user API

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

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

   

   Figure 9 Biometrics Json array body for update biometric API

5. Response

   JSON response has shown in Figure 10

   

   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.

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

   

   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).

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.

   

   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

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.

      

      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

   

   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

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.

      

      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

   

   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

Figure 21 C# code sample to delete events

Developer samples

Developer samples can be downloaded from this URL.