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 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 each request using the x-api-key header to identify the target application.

Example request:

POST /v1/subjects HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
x-api-key: [Application API key]
x-amz-date: 20180816T032046Z
Authorization: AWS4-HMAC-SHA256
Credential=AKIAIOSFODNN8EXAMPLE/20130524/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 in the x-api-key header 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"
}

REST Endpoints

NEC ID support endpoints for registering, updating and unregistering subjects, as well as performing face extraction, search and verification.

Subjects

Manage subjects for search and verification matching.

Register

POST /v1/subjects

Registers a new subject.

Example request:

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

{
  "face": "[FACE]"
}
Request JSON Object:

  • face (string) – Base64 encoded image.

Request Headers:

  • Host – api.id.nec.com.au

  • Accept – 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",
  "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:
Response Headers:
Status Codes:

Update

PUT /v1/subjects/(string: id)

Update an existing subject.

Example request:

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

{
  "face": "[FACE]"
}
Query Parameters:

  • id – Subject id.

Request JSON Object:

  • face (string) – Base64 encoded image.

Request Headers:

  • Host – api.id.nec.com.au

  • Accept – 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",
  "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:
Response Headers:
Status Codes:

Unregister

DELETE /v1/subjects/(string: id)

Unregister an existing subject.

Example request:

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

  • id – Subject id.

Request Headers:

  • Host – api.id.nec.com.au

  • Accept – 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 OK
Content-Type: application/json
Response Headers:
Status Codes:

Face

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

Extract

POST /v1/face/extract

Extract face attributes.

Example request:

POST /v1/face/extract HTTP/1.1
Host: api.id.nec.com.au
Accept: application/json
x-api-key: [Application API key]
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

  • 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

{
  "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:

Verify

POST /v1/face/verify

Verify a subject against a probe.

Example request:

POST /v1/face/verify HTTP/1.1
Host: api.id.nec.com.au
Accept: 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

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

Response Headers:
Status Codes:

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.

Errors

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

NoFace

2001

No face was found in the provided image.

PoorQuality

2002

The overall faceQualityScore was too low to process.