Open APIs

Our Open APIs (REST Web Hooks) allow you to integrate NoahFace with your existing IT systems and applications. For example, you could:

  • Interface with a payroll, access control, student management, or membership system that we do not currently support.
  • Control and record access to your business applications (ie: provide a secure and convenient login mechanism).
  • Control and record access to specialist machines (lathes, etc), vehicles (trucks, forklifts, trains, etc), or a key safe.

The opportunities are endless.

User Synchronisation

NoahFace can automatically retrieve your list of users from an existing IT system so you don't need to import/export users or manually maintain them in two places. To do this, you simply implement our User Synchronisation API (a REST Web Hook), and configure NoahFace to call it.

User Synchronisation API

Your implementation of the User Synchronisation API should return JSON data. The JSON data should contain a single element called Users, which is an array of all of your users. Each user can contain any of the following elements:

  • SyncGuid. The unique identifier of the user in your user directory. This can be alphanumeric and is the only mandatory element.
  • Name. The preferred name of the user, which if present is displayed on the recognition screen.
  • FirstName. The first name of the user.
  • LastName. The last name of the user.
  • UserNumber. The business-defined number for the user, such as an employee number or membership number. This element must be numeric.
  • UserType. The business-defined type of user, which is used for categorisation.
  • Country. The country code for the user's phone number (eg: 1 = USA, 44 = UK, 61 = Australia).
  • Mobile. The mobile phone number of the user. This can be used to send passcode notifications.
  • Email. The email address of the user. This can be used to send passcode notifications.
  • CardNumber. The access card number of the user, which is used in secure access control applications.
  • Site. The name of the primary site the user belongs to, which is used for categorisation.
  • Groups. The list of groups the user belongs to, which can be used to restrict access through access rules. The synchronisation process will automatically add users to the specified groups if they exist (it will not automatically create groups).
  • Details. A dictionary of custom attributes for the user, which can be used by the Task Tracking and Clock In/Out screens.
  • Expiry. The expiry date of the user, after which they will not be permitted to use NoahFace.
  • Role. The role the user has within the organisation (eg: Administrator, Manager, Viewer). You should omit this attribute, or leave it blank, for regular users.

Only the SyncGuid and at least one of the Name and FirstName elements are mandatory for each user.

Example JSON

The following is an example of the JSON that your API should return.

{ 
    "Users" : [           
        {  
            "SyncGuid"   : "12345",
            "FirstName"  : "Samara",  
            "LastName"   : "Smith", 
            "UserNumber" : "1001" 
        },
        {
            "SyncGuid"   : "55555", 
            "Name"       : "Jimmy", 
            "FirstName"  : "James",  
            "LastName"   : "Smith", 
            "UserNumber" : "1002",
            "UserType"   : "Contractor", 
            "Country"    : "61", 
            "Mobile"     : "0414736887",  
            "Email"      : "james@gmail.com", 
            "Site"       : "Sydney",
            "Groups"     : ["Finance", "Management"],
            "CardNumber" : "",
            "Expiry"     : "2020-12-31",
            "Role"       : "Manager"
        }
    ]
}

Configuration

To enable user synchronisation, simply add a synchronisation instance, select 'Custom' as the type of synchronisation, and specifying your API endpoint details (see example below).

Individual User Synchronisation

NoahFace can synchronously update an individual user while they are recording an event (eg: while they are attempting to clock in for work). This is used, for example, to ensure that a user's expiry date is up to date before denying them access based on their currently recorded expiry date.

To support individual user synchronisation, your user list url should accept an optional query parameter of syncguid, and when this query parameter is present, it should only return the user with that guid.

{ 
    "Users" : [           
        {  
            "SyncGuid"   : "12345",
            "FirstName"  : "Samara",  
            "LastName"   : "Smith", 
            "Expiry" : "2020-12-31" 
        }
    ]
}

Supporting individual user synchronisation is entirely optional; if you don't need this feature, you do not need to support this query parameter.

Error Handling

Your API should return an HTTP response code of 200 on success, and an appropriate response code on failure (eg: 404 if the specified User list url is incorrect, 401 if access was unauthorised, etc).

Event Notification

NoahFace can forward user events to your applications or IT systems. To do this, you simply implement our Event Notification API (a REST Web Hook), and configure NoahFace to call it when a user records an event.

Event Notification API

Your implementation of the Event Notification API should expect to receive the following elements:

  • eventid. The unique identifier of the event.
  • utc. The time of the event in the UTC timezone.
  • time. The time of the event in the local timezone.
  • org. The name of the organisation where the event was recorded.
  • site. The name of the site where the event was recorded.
  • device. The name of the device where the event was recorded.
  • devid. The identifier of the device where the event was recorded (if defined).
  • type. The type of event (eg: access granted, clock in, start task, etc).
  • detail. Additional details associated with the event (eg: a job number, a task type, etc).
  • method. The method used to identify the user (eg: face, passcode, etc)
  • userid. The unique identifier of the user from your user directory (ie: SyncGuid).
  • number. The business-defined number for the recognised user, such as an employee number or membership number.
  • firstname. The first name of the recognised user.
  • lastname. The last name of the recognised user.
  • usertype. The type of the recognised user.
  • cardnum. The card number of the recognised user which is used in secure access control applications.
  • latitude. The latitude of the geo-location recorded. Available for mobile clocking events only.
  • longitude. The longitude of the geo-location recorded. Available for mobile clocking events only.
  • accuracy. The accuracy (in metres) of the geo-location recorded. Available for mobile clocking events only.
  • altitude. The altitude (in metres) of the geo-location recorded. Available for mobile clocking events only.
  • temperature. The temperature of the recognised user. Available only if using temperature screening.
  • elevated. Whether the temperature was consider elevated. Available only if using temperature screening.

The full list of possible event types is as follows:

  • register
  • clockin
  • clockout
  • starttask
  • accessgranted
  • accessdenied
  • startjob
  • stopjob
  • present

Your API can be designed to be called using an HTTP GET, PUT, or POST method. If you use GET, the event data will be sent in query parameters. If you specify PUT or POST, the event data will be sent in JSON format (see example below).

Example JSON

The following is an example of the JSON that your API should expect. All elements will be present even if they are empty.

{  
    "eventid"    : "109997645",
    "utc"        : "2018-12-21 21:03:47",
    "time"       : "2018-12-22 08:03:47",  
    "org"        : "Acme Corporation", 
    "site"       : "Sydney", 
    "device"     : "Time Clock",
    "devid"      : "",
    “type”       : "clockin”, 
    ”detail”     : "", 
    “method”     : "face",
    "userid"     : "12345",
    “number”     : "1001”, 
    “firstname”  : "Samara”,
    “lastname”   : "Smith”,
    "cardnum"    : "",
    "temperature": 36.9,
    "elevated"   : false
}

Cloud Event Notifications

You can forward user events either from the Cloud or locally from the NoahFace App. Forwarding user events from the Cloud is usually used for integration with payroll systems.

To forward user events from the Cloud, simply add a notification, select 'Custom' as the type, and specifying your API endpoint details (see example below). Once you have done this, associate this notification with an access point type, and create your access point.

Error Handling for Cloud Event Notifications

Your API should return an HTTP response code of 200 on success, and an appropriate response code on failure (eg: 404 if the specified  url is incorrect, 403 if access was unauthorised, etc). If you return anything other than 200 (or your API cannot be reached), then NoahFace will attempt to re-send the event the following number of hours in the future:

          2 ^ (number of failed attempts - 1)

So, the first retry will be after 1 hour, the second retry will be after an additional 2 hours, the third retry will be after an additional 4 hours, etc. This will continue until your API returns success, or until 90 days has passed.

Local Event Notifications

You can forward user events either from the Cloud or locally from the NoahFace App. Forwarding user events locally from the NoahFace App is usually used for integration with local hardware (eg: unlocking a door or printing labels). You can also use local event forwarding to retrieve and display real time messages to users.

To forward user events locally from the NoahFace App, select your access point type, select 'Web Server' as the Receiver type, and specifying your API endpoint details (see example below). Once you have done this, create your access point.

Error Handling for Local Event Notifications

Your API should return an HTTP response code of 200 on success, and an appropriate response code on failure (eg: 404 if the specified url is incorrect, 403 if access was unauthorised, etc). You can optionally return a custom HTTP response header of X-NOAHFACE-MESSAGE to display a message to the user. It is critical that your network connection is reliable and that your API returns quickly (ie: ideally in less than a second), as local event forwarding is synchronous.

Security

Your implementation of the NoahFace APIs should enforce one of the following authentication methods:

  • Basic Security. You provide a username and password which is passed in the Authorization header of each HTTP request.
  • Token Security. You provide a bearer token which is passed in the Authorization header of each HTTP request.

If your implementation of the NoahFace APIs is being designed to service multiple organisations, you should use different credentials for each organisation so you can access the appropriate data in your IT system or application.

Regardless of which authentication method you choose, all API calls are over SSL so your data and credentials are encrypted.

Privacy
Legal
Terms of Use
Contact Us
© NoahFace 2018
.