Using the API

NEC ID exposes a secure REST API, allowing users to interact with the NEC ID biometric service over HTTPS. JSON is returned by all API responses including errors and HTTP response status codes are used to designate success and failure.

The platform also provides a means to manage your tenancy configuration via secure REST API, allowing tenants to provision new galleries and applications.

The following documentation details the authentiction and authorisation requirements and the various endpoints.

Download NEC ID API Swagger JSON or YAML

Authentication and Authorisation

NEC ID authentiction requires and AWS Signature Version 4 authorization header to be included with each request. This requires the AccessKey and SecretKey provided in the NEC ID Welcome Pack and the use of the ap-southeast-2 AWS Region and execute-api Service name.

The provided NEC ID SDKs handle the signing process using your parameters and tools such as Postman have an in-built AWS Signature authorisation type.

Alternativly this header can be generated using the Amazon’s authenticating requests guide.

The following is an example of a request with the Authorization and x-amz-date header values. Line breaks are added to this Authorization line for readability.

In addition, an application API Key must be included in requests that pertain to a specific gallery by using the x-api-key header to identify the target application.

Example request:

POST /v1.1/subjects HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-api-key: 73n4n74p1k3y
x-amz-date: 20180816T032046Z
Authorization: AWS4-HMAC-SHA256
Credential=AKIAIOSFODNN8EXAMPLE/20190304/ap-southeast-2/execute-api/aws4_request,
SignedHeaders=content-length;content-type;host;x-amz-date;x-api-key,
Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024

Failure to include a valid Authorization header will result in a 403 forbidden HTTP response status code, with a JSON message describing the issue with the signature.

Example response:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "message": "Signature expired: 20180816T032046Z is now earlier than 20180816T040329Z (20180816T040829Z - 5 min.)"
}

Failure to include a valid API Key via the x-api-key header in particular requests will result in a 403 forbidden HTTP response status codes, with a JSON message of Forbidden.

Example response:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "message": "Forbidden"
}

Biometric REST Endpoints

NEC ID support endpoints for:

  • registering, updating, listing and unregistering subjects;
  • registering, updating, listing and unregistering subject events;
  • performing face extraction, search and verification;
  • creating, renaming, deleting and retrieving tags;
  • performing a bulk subject registration;

Subjects

Manage subjects for search and verification matching.

List Subjects

GET /v1.1/subjects

Retrieve all subjects for a specific gallery.

Example request:

GET /v1.1/subjects HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-api-key: [Application API key]
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]
Query Parameters:
 
  • start – Optional starting index of the request, defaults to 0 if not provided.
  • length – Optional length of the list, defaults to 1000 if not provided. Limited to a maximum of 1000 per request.
  • dir – Optional last updated sort direction (asc or desc). default is asc.
Request Headers:
 
  • Host – api.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-api-key – Application API Key.
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "subjects": [
    {
      "id": "necidguid-fcdf-49eb-9182-5a6825ed2a3b",
      "eventId": "eventguid-caf3-4e0f-92b9-101a9e73a3ee",
      "status": "ACTIVE",
      "lastUpdated": "2018-12-18T00:27:56.427+00:00"
    },
    {
      "id": "necidguid-fcdf-49eb-9182-5a6825ed2a3b",
      "eventId": "eventguid-f99a-41dc-8eb1-cd7b1b3dcdec",
      "status": "DELETED",
      "lastUpdated": "2019-02-28T18:11:49.157+00:00"
    },
    {
      "id": "necidguid-fcdf-49eb-9182-5a6825ed2a3b",
      "eventId": "eventguid-f99a-41dc-8eb1-cd7b1b3dcdec",
      "status": "ACTIVE",
      "lastUpdated": "2019-02-28T18:11:49.174+00:00"
    }
  ],
  "total": 3
}
Response JSON Object:
 
  • subjects (array) – Containing id (string): Subject id, eventId (string): Event id, status (string): Status, lastUpdated (ISO 8601 timestamp): Last Updated Time.
  • total (int) – Total number of events in gallery.
Response Headers:
 
Status Codes:

Note

As a subject can have many events, the subject’s id will be repeated for each of its eventIds. Plus, in order to reuse slots within a gallery, deleted events are flagged with a status of DELETED until the slot is recycled. This means that the list of subjects can include deleted subjects, plus subjects we have been updated, which appear as deleted and active with the same ids.

Register Subject

POST /v1.1/subjects

Registers a new subject.

Example request:

POST /v1.1/subjects HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-api-key: [Application API key]
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]

{
  "face": "[FACE]",
  "tags": [ "passport" ]
}
Request JSON Object:
 
  • face (string) – Base64 encoded image.
  • tags (array) – Optional list of tag names to register against the subject.
Request Headers:
 
  • Host – api.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-api-key – Application API Key.
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "necidguid-fcdf-49eb-9182-5a6825ed2a3b",
  "eventId": "eventguid-caf3-4e0f-92b9-101a9e73a3ee",
  "attributes": {
    "faceArea": {
          "left": "161",
          "top": "156",
          "right": "318",
          "bottom": "313"
    },
    "headArea": {
          "left": "131",
          "top": "86",
          "right": "345",
          "bottom": "343"
    },
    "rightEyeCenter": {
          "x": "195",
          "y": "198"
    },
    "leftEyeCenter": {
          "x": "276",
          "y": "191"
    },
    "frontalFaceScore": "0.569824",
    "faceRoll": "4.93922",
    "facePan": "-9.34863",
    "faceTilt": "7.613",
    "faceScore": "0.999591",
    "faceQualityScore": "0.86541"
  }
}
Response JSON Object:
 
  • id (string) – Subject id.
  • eventId (string) – Event id.
  • attributes – See Face Attributes.
Response Headers:
 
Status Codes:

Update Subject

PUT /v1.1/subjects/(string: subjectId)

Update an existing subject.

Example request:

PUT /v1.1/subjects/necidguid-fcdf-49eb-9182-5a6825ed2a3b HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-api-key: [Application API key]
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]

{
  "face": "[FACE]",
  "tags": [ "passport" ]
}
Parameters:
  • subjectId – Subject id.
Request JSON Object:
 
  • face (string) – Base64 encoded image.
  • tags (array) – Optional list of tag names to register against the subject.
Request Headers:
 
  • Host – api.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-api-key – Application API Key.
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "necidguid-fcdf-49eb-9182-5a6825ed2a3b",
  "eventId": "eventguid-caf3-4e0f-92b9-101a9e73a3ee",
  "attributes": {
    "faceArea": {
          "left": "161",
          "top": "156",
          "right": "318",
          "bottom": "313"
    },
    "headArea": {
          "left": "131",
          "top": "86",
          "right": "345",
          "bottom": "343"
    },
    "rightEyeCenter": {
          "x": "195",
          "y": "198"
    },
    "leftEyeCenter": {
          "x": "276",
          "y": "191"
    },
    "frontalFaceScore": "0.569824",
    "faceRoll": "4.93922",
    "facePan": "-9.34863",
    "faceTilt": "7.613",
    "faceScore": "0.999591",
    "faceQualityScore": "0.86541"
  }
}
Response JSON Object:
 
  • id (string) – Subject id.
  • eventId (string) – Event id.
  • attributes – See Face Attributes.
Response Headers:
 
Status Codes:

Unregister Subject

DELETE /v1.1/subjects/(string: subjectId)

Unregister an existing subject and related events.

Example request:

DELETE /v1.1/subjects/necidguid-fcdf-49eb-9182-5a6825ed2a3b HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-api-key: [Application API key]
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]
Parameters:
  • subjectId – Subject id.
Request Headers:
 
  • Host – api.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-api-key – Application API Key.
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 204 No Content
Content-Type: application/json
Response Headers:
 
Status Codes:

Events

Events provides the ability to register multiple biometrics events for a subject. The API allows you to, list register, update and unregister subject events.

List Events

GET /v1.1/subjects/(string: subjectId)/events

Retrieve all events for a given subject.

Example request:

GET /v1.1/subjects/necidguid-fcdf-49eb-9182-5a6825ed2a3b/events HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-api-key: [Application API key]
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]
Parameters:
  • subjectId – Subject id.
Request Headers:
 
  • Host – api.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-api-key – Application API Key.
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "necidguid-fcdf-49eb-9182-5a6825ed2a3b",
  "events": [
    {
      "id": "eventguid-caf3-4e0f-92b9-101a9e73a3ee"
    },
    {
      "id": "eventguid-f99a-41dc-8eb1-cd7b1b3dcdec"
    }
  ]
}
Response JSON Object:
 
  • id (string) – Subject id.
  • events (array) – Containing id (string): Event id.
Response Headers:
 
Status Codes:

Register Event

POST /v1.1/subjects/(string: subjectId)/events

Register a new event for a given subject.

Example request:

POST /v1.1/subjects/necidguid-fcdf-49eb-9182-5a6825ed2a3b/events HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-api-key: [Application API key]
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]

{
  "face": "[FACE]",
  "tags": [ "licence" ]
}
Request JSON Object:
 
  • face (string) – Base64 encoded image.
  • tags (array) – Optional list of tag names to register against the subject.
Parameters:
  • subjectId – Subject id.
Request Headers:
 
  • Host – api.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-api-key – Application API Key.
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "necidguid-fcdf-49eb-9182-5a6825ed2a3b",
  "eventId": "eventguid-f99a-41dc-8eb1-cd7b1b3dcdec",
  "attributes": {
    "faceArea": {
          "left": "161",
          "top": "156",
          "right": "318",
          "bottom": "313"
    },
    "headArea": {
          "left": "131",
          "top": "86",
          "right": "345",
          "bottom": "343"
    },
    "rightEyeCenter": {
          "x": "195",
          "y": "198"
    },
    "leftEyeCenter": {
          "x": "276",
          "y": "191"
    },
    "frontalFaceScore": "0.569824",
    "faceRoll": "4.93922",
    "facePan": "-9.34863",
    "faceTilt": "7.613",
    "faceScore": "0.999591",
    "faceQualityScore": "0.86541"
  }
}
Response JSON Object:
 
  • id (string) – Subject id.
  • eventId (string) – Event id.
  • attributes – See Face Attributes.
Response Headers:
 
Status Codes:

Update Event

PUT /v1.1/subjects/(string: subjectId)/events/(string: eventId)

Update an existing event for a given subject.

Example request:

PUT /v1.1/subjects/necidguid-fcdf-49eb-9182-5a6825ed2a3b/events/eventguid-f99a-41dc-8eb1-cd7b1b3dcdec HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-api-key: [Application API key]
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]

{
  "face": "[FACE]",
  "tags": [ "licence" ]
}
Request JSON Object:
 
  • face (string) – Base64 encoded image.
  • tags (array) – Optional list of tag names to register against the subject.
Parameters:
  • subjectId – Subject id.
  • eventId – Event id.
Request Headers:
 
  • Host – api.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-api-key – Application API Key.
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "necidguid-fcdf-49eb-9182-5a6825ed2a3b",
  "eventId": "eventguid-f99a-41dc-8eb1-cd7b1b3dcdec",
  "attributes": {
    "faceArea": {
          "left": "161",
          "top": "156",
          "right": "318",
          "bottom": "313"
    },
    "headArea": {
          "left": "131",
          "top": "86",
          "right": "345",
          "bottom": "343"
    },
    "rightEyeCenter": {
          "x": "195",
          "y": "198"
    },
    "leftEyeCenter": {
          "x": "276",
          "y": "191"
    },
    "frontalFaceScore": "0.569824",
    "faceRoll": "4.93922",
    "facePan": "-9.34863",
    "faceTilt": "7.613",
    "faceScore": "0.999591",
    "faceQualityScore": "0.86541"
  }
}
Response JSON Object:
 
  • id (string) – Subject id.
  • eventId (string) – Event id.
  • attributes – See Face Attributes.
Response Headers:
 
Status Codes:

Unregister Event

DELETE /v1.1/subjects/(string: subjectId)/events/(string: eventId)

Unregister an existing event for a given subject.

Example request:

DELETE /v1.1/subjects/necidguid-fcdf-49eb-9182-5a6825ed2a3b/events/eventguid-f99a-41dc-8eb1-cd7b1b3dcdec HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-api-key: [Application API key]
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]
Parameters:
  • subjectId – Subject id.
  • eventId – Event id.
Request Headers:
 
  • Host – api.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-api-key – Application API Key.
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 204 No Content
Content-Type: application/json
Response Headers:
 
Status Codes:

Face

Extract faces, search and verify probe images against registered subjects.

Extract

POST /v1.1/face/extract

Extract face attributes.

Example request:

POST /v1.1/face/extract HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]

{
  "faces": "[FACES]"
}
Request JSON Object:
 
  • faces (string) – Base64 encoded image containing one or more faces.
Request Headers:
 
  • Host – api.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "faces": [
    {
        "attributes": {
            "faceArea": {
                "left": "434",
                "top": "449",
                "right": "503",
                "bottom": "518"
            },
            "headArea": {
                "left": "423",
                "top": "418",
                "right": "515",
                "bottom": "531"
            },
            "rightEyeCenter": {
                "x": "451",
                "y": "464"
            },
            "leftEyeCenter": {
                "x": "487",
                "y": "466"
            },
            "frontalFaceScore": "0.574219",
            "faceRoll": "-3.17983",
            "facePan": "-9.72147",
            "faceTilt": "7.93723",
            "faceScore": "0.999993",
            "faceQualityScore": "0.749248"
        }
    },
    {
        "attributes": {
            "faceArea": {
                "left": "850",
                "top": "416",
                "right": "921",
                "bottom": "486"
            },
            "headArea": {
                "left": "838",
                "top": "383",
                "right": "933",
                "bottom": "500"
            },
            "rightEyeCenter": {
                "x": "866",
                "y": "431"
            },
            "leftEyeCenter": {
                "x": "904",
                "y": "431"
            },
            "frontalFaceScore": "0.574707",
            "faceRoll": "-0",
            "facePan": "8.36667",
            "faceTilt": "1.05248",
            "faceScore": "0.999994",
            "faceQualityScore": "0.764253"
        }
    }
  ]
}
Response JSON Object:
 
Response Headers:
 
Status Codes:
  • 200 OK – Face attributes extracted.

Verify

POST /v1.1/face/verify

Verify a subject, and their one or more events, against a probe.

Example request:

POST /v1.1/face/verify HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-api-key: [Application API key]
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]

{
  "probe": "[PROBE]",
  "id": necidguid-fcdf-49eb-9182-5a6825ed2a3b
}
Request JSON Object:
 
  • probe (string) – Base64 encoded image.
  • id (string) – Subject id.
Request Headers:
 
  • Host – api.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-api-key – Application API Key.
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "necidguid-fcdf-49eb-9182-5a6825ed2a3b",
  "score": 8200
}
Response JSON Object:
 
  • id (string) – Subject id.
  • score (int) – Match score of the subject’s hightest scoring event.
Response Headers:
 
Status Codes:

Tags

Create, update, delete and retrieve tags. Tags provide the ability to tag subjects and events. You can then search for subjects based on these tags.

Tags must be created first, before using them in register and search requests.

List Tags

GET /v1.1/tags

Retrieve all tags for a specific gallery.

Example request:

GET /v1.1/tags HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-api-key: [Application API key]
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]
Request Headers:
 
  • Host – api.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-api-key – Application API Key.
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  "passport",
  "licence"
]
Response JSON Object:
 
  • array – Containing tag names.
Response Headers:
 
Status Codes:

Note

Each gallery has a hard limit of 64 tags

Create Tag

POST /v1.1/tags/(string: name)

Create a tag.

Example request:

POST /v1.1/tags/staff HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-api-key: [Application API key]
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]
Parameters:
  • name – The tag name. Tag name must not be empty and must be unique.
Request Headers:
 
  • Host – api.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-api-key – Application API Key.
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Response Headers:
 
Status Codes:

Update Tag

PUT /v1.1/tags/(string: oldName)

Update a tag.

Example request:

POST /v1.1/tags/licence HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-api-key: [Application API key]
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]

{
  "newName": "identification"
}
Request JSON Object:
 
  • newName (string) – The tag’s new name. Tag name must not be empty and must be unique.
Parameters:
  • oldName – The tag’s current name.
Request Headers:
 
  • Host – api.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-api-key – Application API Key.
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Response Headers:
 
Status Codes:

Delete Tag

DELETE /v1.1/tags/(string: name)

Deletes a tag. Note that existing subjects and events are not updated.

Example request:

DELETE /v1.1/tags/passport HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-api-key: [Application API key]
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]
Parameters:
  • name – The name of the tag to delete.
Request Headers:
 
  • Host – api.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-api-key – Application API Key.
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Response Headers:
 
Status Codes:

Jobs

Jobs allow you to perform bulk operations on your gallery such as bulk registrations.

Bulk Register

POST /v1.1/jobs/bulkregister

Creates a job to run bulk registration against the supplied registrations.

Example request:

POST /v1.1/jobs/bulkregister HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-api-key: [Application API key]
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]

{
  "registrations": [
    {
      "filename": "1.jpg",
      "tags": [ "passport" ]
    },
    {
      "filename": "2.jpg",
      "tags": [ "passport" ]
    }
  ]
}
Request JSON Object:
 
  • registrations (array) – Containing filename (string): Name of file in S3 bucket and tags (array): List of tags.
Request Headers:
 
  • Host – api.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-api-key – Application API Key.
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "batchId": "batchguid-eec5-440a-89fc-60817f5546c8"
}
Response JSON Object:
 
  • batchId (string) – Batch id.
Response Headers:
 
Status Codes:

Bulk Register Progress

GET /v1.1/jobs/bulkregister/(string: batchId)/(string: pagingId)

Retrieves the progress of the batch operation. In the event of the batch operation having more records than the maximum page size (1000), the results will be paged and the lastEvaluatedKey will contain a value that needs to be sent as the pagingId to retrieve the next page of data.

Example request:

GET /v1.1/jobs/bulkregister/batchguid-eec5-440a-89fc-60817f5546c8 HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-api-key: [Application API key]
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]
Parameters:
  • batchId – The batchId of the job.
  • pagingId – (Optional) The lastEvaluatedKey from the previous request.
Request Headers:
 
  • Host – api.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-api-key – Application API Key.
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "batchId": "batchguid-eec5-440a-89fc-60817f5546c8",
  "processsed": [
    {
      "id": "51448BB9-956D-44FD-89AC-A5065D30D084",
      "filename": "1.jpg",
      "attempts": "1",
      "eventId": "eventguid-B190-466E-A1C2-9E85F436775A",
      "subjectId": "necidguid-45EC-4A97-88F0-F064A829FC90",
      "registerStatus": "Success",
      "reason": "",
      "status": "Processed",
      "attributesJson": "..."
    },
    {
      "id": "EFE569DA-AE74-43CC-A75F-BD85B07A7401",
      "filename": "2.jpg",
      "attempts": "1",
      "eventId": "eventguid-F3BE-4428-AAC3-8C9631776364",
      "subjectId": "necidguid-113B-4726-A267-4267816EC8FB",
      "registerStatus": "Failed",
      "reason": "Image too small",
      "status": "Processed",
      "attributesJson": "..."
    }
  ],
  "lastEvaluatedKey": ""
}
Response JSON Object:
 
  • batchId (string) – Batch Id.
  • processed (array) – List of records within the batch with a summary. See Register Request Summaries
  • lastEvaluatedKey (string) – Key to be sent as the pagingId to retrieve the next page of data.
Response Headers:
 
Status Codes:

Register Request Summaries

Object describing a register request summary which contains the subjectId and eventId on success.

id:The operation id. Note this is not the subject or event id.
filename:The filename from the original request.
attempts:The number of attempts.
eventId:The event id on success.
subjectId:The subject id on success.
registerStatus:Once the status is “Processed”, this will have a value of “Success” or “Failed”.
reason:The failure reason on failure.
status:The status of the operation. Either “New” or “Processed”.
attributesJson:The Face Attributes - see Face Attributes.

Face Attributes

Sucessful requests to the register, update and search endpoints will return an attributes property containing a collection of face attributes related to the submitted face or probe image. In the case of extract, the returned faces property contains an array of objects with the attrbiutes property, representing each face found (up to 20 faces) in the submitted faces image.

faceArea:Pixel coordinates (left, top, right and bottom) defining the bounds of the face.
headArea:Pixel coordinates (left, top, right and bottom) defining the bounds of the face.
rightEyeCenter:Pixel coordinates (x and y) of the centre of the right eye.
rightEyeCenter:Pixel coordinates (x and y) of the centre of the left eye.
faceScore:Measure of likeness to a face.
frontalFaceScore:
 Degree of frontal view of face.
faceQualityScore:
 Estimated overall quality of face.
faceRoll:Roll angle of face in degrees.
facePan:Pan angle of face in degrees.
faceTilt:Tilt angle of face in degrees.

Note

The overall faceQualityScore should be used to determine the quality of the face prior to registration.

Tenant Management REST Endpoints

NEC ID support endpoints for:

  • creating and deleting galleries and applications with which to access them;

Galleries

Manage tenant galleries.

List Galleries

GET /api/galleries

Retrieve all galleries.

Example request:

GET /api/galleries HTTP/1.1
Host: portal.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]
Request Headers:
 
  • Host – portal.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "galleries": [
    {
      "id": "galleryguid-327D-4D31-8E25-35891A034220",
      "name": "Staff",
      "description": "Staff",
      "size": 10000,
      "count": 3891
    },
    {
      "id": "galleryguid-5570-4f20-a95c-8e50e0bca0cb",
      "name": "Y9Students",
      "description": "Year 9 students",
      "size": 1000,
      "count": 873
    },
    {
      "id": "galleryguid-b751-4b5e-9e4d-cc1a314788db",
      "name": "Visitors",
      "description": "Visitors",
      "size": 10000,
      "count": 431
    }
  ]
}
Response JSON Object:
 
  • galleries (array) – Containing id (string): Gallery id, name (string): Name, description (string): Description, size (int): Size, count (int): Count.
Response Headers:
 
Status Codes:

Applications

Manage tenant applications.

List Applications

GET /api/applications

Retrieve all applications.

Example request:

GET /api/applications HTTP/1.1
Host: portal.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]
Request Headers:
 
  • Host – portal.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "applications": [
    {
      "id": "applicationId01",
      "name": "HR System",
      "apiKey": [Application API key]
    },
    {
      "id": "applicationId02",
      "name": "Building Access System",
      "apiKey": [Application API key]
    }
  ]
}
Response JSON Object:
 
  • applications (array) – Containing id (string): Application id, name (string): Name, apiKey (string): Application API Key.
Response Headers:
 
Status Codes:

Get Application

GET /api/applications/(string: applicationId)

Retrieve application details.

Example request:

GET /api/applications/applicationId01 HTTP/1.1
Host: portal.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]
Parameters:
  • applicationId – Application id.
Request Headers:
 
  • Host – portal.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "applicationId01",
  "name": "HR System",
  "description": "HR System",
  "apiKey": [Application API key],
  "faceMinimumQualityScore": 0.6
}
Response JSON Object:
 
  • id (string) – Gallery id.
  • name (string) – Name.
  • description (string) – Description.
  • apiKey (string) – Application API Key.
Request JSON Object:
 
  • faceMinimumQualityScore (float) – Minimum estimated overall quality of face - see Face Attributes.
Response Headers:
 
Status Codes:

Create Application

POST /api/applications

Create an application.

Example request:

POST /api/applications HTTP/1.1
Host: portal.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]

{
  "name": "Building Access System",
  "description": "Building Access System",
  "faceMinimumQualityScore": 0.8,
  "galleryId": "galleryguid-327D-4D31-8E25-35891A034220",
}
Request JSON Object:
 
  • name (string) – Name of the application.
  • description (string) – Description of the application.
  • faceMinimumQualityScore (float) – Minimum estimated overall quality of face - see Face Attributes, must be greater than or equal to 0.45.
  • galleryId (string) – Id of the target gallery.
Request Headers:
 
  • Host – portal.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "applicationId02",
  "name": "Building Access System",
  "description": "Building Access System",
  "apiKey": [Application API key],
  "faceMinimumQualityScore": 0.8
}
Response JSON Object:
 
  • id (string) – Application id.
  • name (string) – Name.
  • description (string) – Description.
  • apiKey (string) – Application API Key.
Request JSON Object:
 
  • faceMinimumQualityScore (float) – Minimum estimated overall quality of face - see Face Attributes.
Response Headers:
 
Status Codes:
  • 200 OK – Application created.

Update Application

PATCH /api/applications/(string: applicationId)

Update an application.

Example request:

PATCH /api/applications HTTP/1.1
Host: portal.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]

{
  "name": "Building Access System",
  "description": "Building Access System",
  "faceMinimumQualityScore": 0.6
}
Parameters:
  • applicationId – Application id.
Request JSON Object:
 
  • name (string) – Name of the application.
  • description (string) – Description of the application.
  • faceMinimumQualityScore (float) – Minimum estimated overall quality of face - see Face Attributes, must be greater than or equal to 0.45.
Request Headers:
 
  • Host – portal.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "applicationId02",
  "name": "Building Access System",
  "description": "Building Access System"
  "apiKey": [Application API key],
  "faceMinimumQualityScore": 0.8
}
Response JSON Object:
 
  • id (string) – Application id.
  • name (string) – Name.
  • description (string) – Description.
  • apiKey (string) – Application API Key.
Request JSON Object:
 
  • faceMinimumQualityScore (float) – Minimum estimated overall quality of face - see Face Attributes.
Response Headers:
 
Status Codes:
  • 200 OK – Application updated.

Delete Application

DELETE /api/applications/(string: applicationId)

Deletes an application.

Example request:

DELETE /api/applications/applicationid02 HTTP/1.1
Host: portal.id.nec.com.au
Accept: application/json
Content-Type: application/json
x-amz-date: [YYYYMMDD'T'HHMMSS'Z' UTC timestamp]
Authorization: [AWS Signature Version 4]
Parameters:
  • applicationId – Application id.
Request Headers:
 
  • Host – portal.id.nec.com.au
  • Accept – application/json
  • Content-Type – application/json
  • x-amz-date – UTC timestamp using ISO 8601 format: YYYYMMDD’T’HHMMSS’Z’.
  • Authorization – AWS Signature Version 4.

Example response:

HTTP/1.1 204 No Content
Content-Type: application/json
Response Headers:
 
Status Codes:

Error Handling

In addition to the valid successful and unsuccessful status codes listed for each endpoint, exceptions will result in a error response (400 or 500 status code) with a JSON Object containing the error details.

For example, a request to register endpoint which does not include the mandatory face property, will return the following:

POST /v1.1/subjects
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "message": "face property must be provided.",
  "errorCode": 1001,
  "errorType": "InvalidRequest"
}
Response JSON Object:
 
  • mesage (string) – Description of the error.
  • errorCode (int) – Numeric code representing the error. See Error Codes and Types.
  • errorType (string) – Named constant representing the error. See Error Codes and Types.
Response Headers:
 
Status Codes:

Error Codes and Types

Type Code Description
InvalidRequest 1001 Request is invalid, possible missing parameters.
Duplicate 1002 Duplicate request, identifier in message.
Timeout 1003 Request timed out.
NoFace 2001 No face was found in the provided image.
PoorQuality 2002 The overall faceQualityScore was too low to process.
MultipleFaces 2003 Multiple faces were found in the image. Only one is permitted for this type of request.