Open APIs

Our Open APIs 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.

There are three primary interfaces as follows:

Each of these interfaces are explained in detail in the following sections.

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 top level 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. Max length = 100.
  • Name. The preferred name of the user, which if present is displayed on the recognition screen. Max length = 100.
  • FirstName. The first name of the user. Max length = 40.
  • LastName. The last name of the user. Max length = 40.
  • UserNumber. The business-defined number for the user, such as an employee number or membership number. This element can be alphanumeric, but must be numeric if it is to be used for user identification. Max length = 40.
  • UserType. The business-defined type of user (eg: Manufacturing, Service, Management, Cleaning, etc). This can be used to drive conditional data entry in the Clock In/Out screen.
  • Language. The preferred language of the user (eg: English, Spanish, French).
  • 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. Max length = 100.
  • CardNumber. The access card number of the user, which is used in secure access control applications. Max length = 20.
  • Site. The name of the primary site the user belongs to, which is used for categorisation.
  • ShiftStart. The start time for the user's shift today (or next shift if they have multiple shifts today). Format = HH:MM.
  • EndShift. The end time for the user's shift today (or next shift if they have multiple shifts today). Format = HH:MM.
  • 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). Max length for each group name = 40.
  • Details. A dictionary of custom attributes for the user, which can be used to drive the list of tasks in the Task Tracking screen or a selectable list of projects or work types in the Clock In/Out screen. Max length = 1024.
  • Expiry. The expiry date of the user, after which they will not be permitted to use NoahFace. Format = YYYY-MM-DD.
  • 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. However, the more attributes you return the more functionality you will have available to you within NoahFace.

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"
        }
    ]
}

Global Lists

Your JSON data can optionally contain a second top level element called Lists, which is an array of global lookup list entries. For example, you might return a list of projects and a list of work types. These lists can then be presented in the NoahFace App to allow users to select the project they are working on or the type of work they are performing. Each list entry can contain the following elements:

  • List. The number of the global list that the list entry belongs to.
  • Name. The display name for the list entry.
  • Value. The unique (within the list) identifier for the list entry.
  • Code. A short code associated with the list entry (eg: a project code or job number).
  • Parent. For hierarchical lists, the unique identifier of the entry's parent.

The first three elements (ie: List, Name, and Value) are mandatory for each list entry, and the remaining elements are optional.

Example JSON

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

{ 
    "Users" : [           
        ....
    ],
    "Lists" : [
            {"List" : 1, "Value" : "100", "Name" : "Airport"}, 
            {"List" : 1, "Value" : "101", "Name" : "Tower One"}, 
            {"List" : 1, "Value" : "102", "Name" : "Wharf"}, 
            {"List" : 2, "Value" : "200", "Name" : "Design"}, 
            {"List" : 2, "Value" : "201", "Name" : "Construction"}, 
            {"List" : 2, "Value" : "202", "Name" : "Maintenance"} 
    ]
}

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.

Performance and Error Handling

It is critical that you return your list of users quickly (ie: ideally sub-second, and a maximum of 10 seconds in all circumstances). If you need to make many API calls to a 3rd party system to collect your user data, you should prefetch this data in the background (storing it locally), and your API should simply return the prefetched data to NoahFace.

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

Security

Your implementation of the User Synchronisation 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 HTTPS so your data and credentials are encrypted. We strongly recommend you configure your end points to use TLS 1.2 or higher.

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). See the Event Types section below for more information.
  • detail. Additional details associated with the event (eg: a job number, a task type, etc). See the Event Details section below for more information.
  • 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.
  • sentiment. The sentiment value (1..5) if using sentiment analysis.

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.

{  
    "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",
    "usertype"   : "Engineer",
    "cardnum"    : "",
    "temperature": 36.9,
    "elevated"   : false
}

Event Types

Each event includes an event type attribute. The full list of possible event type values is as follows:

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

Different event types are generated by different screen types. For example, if your are using the Clock In/Out screen, the only event types you will receive are: register, clockin, clockout, startbreak, endbreak, and accessdenied, and if you are using the Task Tracking screen, the only event types you will receive are: register, starttask, clockout, and accessdenied. You can generally ignore register and accessdenied type events.

Event Details

Each event contains an event detail attribute. This is populated with any data that is collected with the event. For example:

  • If you are using the Clock In/Out screen, the detail attribute in clockin type events might be populated with a project name (assuming you have configured the Clock in/Out screen so that users have to select from a list of projects).
  • If you are using the Task Tracking screen, the detail attribute in starttask type events will be populated with the name of the task just started.
  • If you are using the Job Tracking screen, the detail attribute in startjob type events will be populated with the job number just started.

Processing the detail attribute can therefore help you automate cost allocation.

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.

Performance and Error Handling

It is critical that you process Cloud notifications quickly (ie: ideally sub-second, and a maximum of 10 seconds in all circumstances). If you have processing work to do, you must store the notification data, return success, and then perform your processing in the background.

Your API should return an HTTP response code of 200 on success (ie: you have received the data, validated security, and do not need it sent again), 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.

Performance and Error Handling

It is critical that you process local notifications quickly (ie: less than a second) in all circumstances, as local event forwarding is synchronous (ie: users are waiting for the response).

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. There is no retry mechanism for local notifications.

Security

Your implementation of the Notification 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 HTTPS so your data and credentials are encrypted. We strongly recommend you configure your end points to use TLS 1.2 or higher.

Custom Screens

NoahFace can display a custom screen whenever a user is identified, which gives you complete flexibility in the user experience you deliver to your users. Custom screens also allow you to integrate tightly with other systems, displaying information sourced from them, and even update them. For example, you might want to support complex searching on a project database, or display detailed information about an employee's current shift.

To implement a custom screen, you simply design it using HTML, host it on your Web server, and configure NoahFace to call it.

Configuring your Custom Screen

Configure your Access Point Type to use a Screen Type of Custom, and then specify any of the following Screen Details options:

  • url. The address of your custom screen.
  • cache. Whether you want your custom screen to be retrieved from cache always, never, or using the default caching policy. Specifying a cache=always will enable your custom screen to be used offline, without a network connection, even if your Web server does not indicate that it can be cached.
  • mode. Specify mode=auto if you want NoahFace to automatically log an event, or mode=manual if you want your custom screen to control if and when an event is logged.
  • query. Specify query=true if you want your custom screen to be passed data via query parameters.

For example, you might specify the following Screen Details options:

        url=https://acme.com/noahface/myscreen.html, cache=always

Client-Side Data Access

NoahFace passes data to your Web page via a custom JSON object called NoahFace. This object contains the following elements:

  • org. The name of the organisation.
  • site. The name of the site.
  • device. The name of the device.
  • devid. The device identifier.
  • facility. The facility code of the organisation or site.
  • 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.
  • name. The preferred name of the user.
  • firstname. The first name of the user.
  • lastname. The last name of the user.
  • usertype. The type of user.
  • language. The preferred language of the user.
  • cardnum. The card number of the user.
  • access. If you have specified mode=auto, then this will contain one of the following values: success, failure, or warning.
  • temperature. If you are using a temperature screening kiosk, this will contain the measured temperature.
  • elevated. If you are using a temperature screening kiosk, this will indicate whether the temperature was elevated.
  • eventtype. The type of the last event for this user (if any).
  • eventtime. The time of the last event for this user (if any).
  • eventdetails. The details of the last event for this user (if any).
  • utc. The current time in the UTC timezone.
  • time. The current time in the local timezone.

You can access these elements from Javascript using standard dot notation (eg: NoahFace.firstname) as needed.

Server-Side Data Access

NoahFace can also pass data to your Web page via query parameters. This is useful if you want to perform integration at the server rather than in the client. To enable server-side data access, specify the query=true configuration option in your access point type.

Note that if you implement server-side data access, your custom screen will not be able to be used offline, so it is important you have an extremely reliable network connection.

Calling Back to NoahFace

Your custom screen can call back to NoahFace to perform the following functions:

  • logevent. Log an event to the NoahFace event log. You can optionally specify the event type and event details to be recorded.
  • success. Display the animated green tick and return to the home screen.
  • failure. Display the animated red cross and return to the home screen.
  • warning. Display the animated red exclamation mark and return to the home screen.
  • cancel. Return to the home screen.
  • notme. Disassociate the matched biometrics and user.

To make a call back to NoahFace, simply post a message to the NoahFace interface, passing it a JSON object containing the appropriate action element. For example:

        window.webkit.messageHandlers.NoahFace.postMessage({"action":"success"});

Note that you would generally only call back to NoahFace if you are using mode=manual, because in the default mode=auto, events are automatically logged.

Example

The following HTML illustrates how to access data from NoahFace as well as how to call back to NoahFace to log events:

<!DOCTYPE html>
<HTML>
    <HEAD>
        <STYLE>
            body {margin: auto; width: 90%; text-align: center;}
            img {display: block; margin-left: auto; margin-right: auto; width: 60%;}
            h1 {color:#1b1919; font-size:50px; padding-top:10%;}
            h2 {color:#1b1919;font-size:50px; padding-bottom:5%;}
            p {color:#1b1919; font-size:28px;}
            .column {float: left; width: 33.33%; margin: auto;}
        </STYLE>
        <SCRIPT>
            function log(mood) {
               if (window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.NoahFace) {
                   window.webkit.messageHandlers.NoahFace.postMessage({"action":"logevent", "type":"present", "details":mood});
                   window.webkit.messageHandlers.NoahFace.postMessage({"action":"success"});
                }
            }
            function prepare() {
               document.getElementById("greeting").innerHTML = "Hi " + NoahFace.firstname + ",";
            }
            window.onload = prepare;
        </SCRIPT>
    </HEAD>
    <BODY>
        <H1 id=greeting class=title></H1>
        <H2 class=title>How Do You Feel Today?</H2>
        <DIV class="row">
           <DIV class="column"><IMG src=https://assets-global.website-files.com/5a7d17188f34de0001ef34a0/6120287ad948ede0b4484273_Bad.png onclick="log('Bad')"><P>Bad</P></DIV>
            <DIV class="column"><IMG src=https://assets-global.website-files.com/5a7d17188f34de0001ef34a0/6120287ae809149f1b0f5368_Meh.png onclick="log('Meh')"><P>Meh</P></DIV>
            <DIV class="column"><IMG src=https://assets-global.website-files.com/5a7d17188f34de0001ef34a0/6120287a8276a4f0a35f6d5c_Good.png onclick="log('Good')"><P>Good</P></DIV>
        </DIV>
    </BODY>
</HTML>

This will result in the following screen being displayed, and when a user presses one of the icons, an event will be logged to NoahFace recording the corresponding mood:

Privacy
Legal
Terms of Use
Contact Us
© NoahFace 2018
.