Introduction

Welcome to the AimBrain API spec.

Current API Version: API v1

Dashboard

The Dashboard for AimBrain On Demand allows you to create api-keys for your applications as well as debug the integrations.

Quick-start Guide

This guide will familiarise you with the concepts used in the AimBrain API and help you get started with the Dashboard

Create Your First Application

The first thing you need to do is create an Application. With AimBrain On Demand applications are an abstraction for a set of keys with specific permissions, each with its own event table.

Create Application

Enter the name of your Application, which you’ll use to find it in the dashboard, as well as keep the “DEBUG” box ticked. This will allow the events (api calls) to be stored in the dashboard. This functionality is meant to help with integarting AimBrain into your solutions.

Name your Application

After your Application is created, select it from the applications list.

Select your Application

Note the API Secret Key

From the top bar select “Application Settings”

Select Application Settings

On this page you can change your Application Name and check the API Secret Key and the Application Permissions (e.g. DEBUG). For now, we only care about the API Secret Key. It consists of the API Key and the API Secret. They are used in the authentication process against the API described here. It is critical to keep the API Secret secret.

Note down your API Secret Key

Setup the AimBrain CLI

The next step is downloading the AimBrain CLI tool.

Example setup for Ubuntu (any recent version) including dependencies:

sudo apt-get -y install python git libsm-dev libxrender-dev
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python get-pip.py
git clone https://github.com/aimbrain/aimbrain-cli.git
cd aimbrain-cli/
pip install . --no-cache-dir

Example setup for Fedora including dependencies:

sudo yum -y install python git libSM-devel libXrender-devel libXext-devel
git clone https://github.com/aimbrain/aimbrain-cli.git
cd aimbrain-cli/
pip install . --no-cache-dir

Download the example images

Get the example images to use with the AimBrain CLI:

wget https://aimbrain.github.io/aimbrain-api/images/The_Hoff_1.jpg
wget https://aimbrain.github.io/aimbrain-api/images/The_Hoff_2.jpg
wget https://aimbrain.github.io/aimbrain-api/images/Pratt.jpg

Use the AimBrain CLI

Now that you have all the tools and examples ready, you can use the AimBrain CLI with your own credentials (which you noted down here).

For this example we will use the AimFace module. You can see the full functionality of the AimBrain CLI tool by running aimbrain-cli --help.

To enroll a face within your application with the AimBrain CLI run:

aimbrain-cli enroll face The_Hoff_1.jpg \
--user-id=the-hoff \
--api-key=<YOUR_API_KEY> \
--secret=<YOUR_API_SECRET>

The command you’ll be using has 6 parameters:

enroll face indicates which functionality you want to use (in this case face enrollment)

The_Hoff_1.jpg indicates which image to use for the enrollment (subject to limits described here)

--user-id=the-hoff indicates the user ID for which the enrollment image will be used.

--api-key=<YOUR_API_KEY> indicates your API Key from the step above

--secret=<YOUR_API_SECRET> indicates your API Secret from the step above

At this point you’ll receive a response and some events will appear in your dashboard. To view them swith back to your dasboard and from the top bar select “Events”

View Events in the Dashboard

You should see two events there, one for the /v1/sessions(#v1-sessions) endpoint and one for /v1/face/enroll. There are a few things you can do here:

You can download the media you submitted to the endpoint by clicking “Download Media File”. This can be helpful when debugging applications to see if, for example, the media sent is not corrupted.

Download Media from the Dashboard

The other thing you can do is look at what responses were sent from the AimBrain API. You can do this by clicking the “Response” buttons.

View Enrollment Events the Dashboard

Understanding the Responses

Example enrollment response using the AimBrain CLI:

[/v1/sessions][200][0.22s] {u'behaviour': 0, u'voice': 0, u'session': u'<LONG_RANDOM_STRING>', u'face': 0}
[/v1/face/enroll][200][0.90s] {u'imagesCount': 1}

As mentioned above, two calls are made to the AimBrain API when using the AimBrain CLI to enroll a face. One to /v1/sessions and one to /v1/face/enroll.

Every interaction with the AimBrain API begins with establishing a session. The responses let you know which Modules the user is enrolled for (for details on the response states please check the /v1/sessions) and proceed to either offer to enroll or authenticate. In our case, the response has 'face': 0 which means the user is not enrolled for face yet.

The session call also returns a long session id string to be used in all further calls in this session. Each session can have multiple calls to other endpoints.

The next step the AimBrain CLI did was send the media for enrollment to the face enrollment endpoint. The response 'imagesCount': 1 indicated that the image was of acceptable quality and was enrolled. This also returns a 200 HTTP code. In any other case, for example if image quality is poor (e.g. too dark) or no face is detected the AimBrain API returns 4xx errors (for details on the response states please check the /v1/face/enroll)

View Enrollment Events the Dashboard

Other Examples

Now that we’ve successfully enrolled a user we can try authenticating them. We can use the AimBrain CLI for that as well.

To authenticate a face belonging to the same person using the AimBrain CLI run:

aimbrain-cli auth face The_Hoff_2.jpg \
--user-id=the-hoff \
--api-key=<YOUR_API_KEY> \
--secret=<YOUR_API_SECRET>

The command you’ll be using has 6 parameters:

auth face indicates which functionality you want to use (in this case face authentication)

The_Hoff_2.jpg indicates which image to use for the enrollment (subject to limits described here)

--user-id=the-hoff indicates the user ID for which the enrollment image will be used. We are using the same user-id as above, as it is already enrolled.

--api-key=<YOUR_API_KEY> indicates your API Key from the step above

--secret=<YOUR_API_SECRET> indicates your API Secret from the step above

Example authentication response using the AimBrain CLI:

[/v1/sessions][200][0.15s] {u'behaviour': 0, u'voice': 0, u'session': u'<LONG_RANDOM_STRING>', u'face': 1}
[/v1/face/auth][200][0.64s] {u'liveliness': 0, u'score': 0.7880177}

As with the example above two calls are made. This time however the call to /v1/sessions returns 'face': 1. This means this user can use /v1/face/auth (otherwise there would be an error).

The response from the authentication endpoint has two fields:

'score': 0.7880177 which indicates the matching score. We recommend setting the authentication theshold to 0.5, meaning interpeting any score above 0.5 as a match. In this case, we can see there is a match.

'liveliness': 0 which indicates that the media did not contain a video of the person performing a valid response. In this case it is 0 because we were using a photo. Currently the liveliness system is set up to check if the person is blinking or not.

View Enrollment Events the Dashboard

Finally let’s try authenticating an impostor.

To authenticate a face belonging to a different person using the AimBrain CLI run:

aimbrain-cli auth face Pratt.jpg \
--user-id=the-hoff \
--api-key=<YOUR_API_KEY> \
--secret=<YOUR_API_SECRET>

The only thing that changes from the example above is the image used, this time actually belonging to a different person.

Example authentication response using the AimBrain CLI:

[/v1/sessions][200][0.20s] {u'behaviour': 0, u'voice': 0, u'session': u'<LONG_RANDOM_STRING>', u'face': 1}

[/v1/face/auth][200][0.76s] {u'liveliness': 0, u'score': 0}

As we can see from the response, we have 'score': 0 which indicates that the media definitelly does not match the enrolled user.

View Enrollment Events the Dashboard

Modules

AimBrain supports multiple biometric modalities (modules) as part of its authentication platform. These modules can be used together (e.g. to step-up the authentication on high risk actions) or separately, depending on the specific use-case. Because AimBrain offers a public API, any module can be used in a cross-channel context (e.g. same Voice Module with mobile banking application and customer call center).

At the core AimBrain uses advanced Deep Learning algorithms based on state of the art, PhD level, scientific research. The technology has multiple patents granted and pending in UK and US.

AimAnomaly

With the AimAnomaly module AimBrain flags abnormalities than could signal fraud, from the large scale right down to the manual onboarding stage. Even if you haven’t pinpointed the data patterns yet, we help you isolate and immobilise fraud, before it gets let in the door.

The technology works in mobile applications and websites.

AimBehaviour

With the behavioural modality AimBrain uses machine learning to track not what the user enters, but how they enter it. AimBrain monitors features such as touch pressure, typing speed, as well as movement.

The technology works in mobile applications and websites.

AimFace

The technology works in mobile applications and websites.

Liveliness detection done via random-challenge request.

AimVoice

The technology is language agnostic and supports free speech as well as set-phrase authentication.

Liveliness detection done via spoken challenge-response token.

Works in mobile apps, websites and call centres.

Security

AimBrain takes security very seriously. We adhere to the highest security industry standards and have daily penetration tests performed on the infrastructure and APIs.

API v1

All API requests use POST verb to prevent caching issues and request length limitations. Requests are passed in JSON format in the HTTP request body and MUST include the following header (alongside valid authentication headers):

Content-Type: application/json

Base URL: https://api.aimbrain.com/

Architecture

Production architecture

AimBrain Production Architecture

Integration

This section provides an overview of how to integrate AimBrain into production systems as described in the architecture above. For specific SDK integration please view the relevant READMEs. The integration overview is provided as sequence diagrams below.

In these sequence diagrams interactions between the following components are shown:

App - the app using the AimBrain SDK - developed and maintained by the client
SDK - the AimBrain SDK - developed and maintained by AimBrain
Server - the backend server the App communicates to - controlled by the client
API - the AimBrain API - developed and maintained by AimBrain

Session

AimBrain Production Architecture

iOS, Android
iOS, Android

AimBehaviour

AimBrain Production Architecture

iOS, Android
iOS, Android

AimFace

AimBrain Production Architecture

iOS, Android
iOS auth, iOS enroll, Android auth, Android enroll
/face/auth or /face/enroll endpoint

AimFace/LipSync

AimBrain Production Architecture

iOS, Android
iOS, Android
iOS auth, iOS enroll, Android auth, Android enroll
/face/auth or /face/enroll endpoint

AimVoice

AimBrain Production Architecture

iOS, Android
iOS, Android
iOS auth, iOS enroll, Android auth, Android enroll
/voice/auth or /voice/enroll endpoint

Authentication

To generate and run curl request using curl_hmac.py tool:

python2 curl_hmac.py test secret POST /v1/sessions\
    '{"userId": "user", "device":"device", "system":"system"}'

and to read request body from file:

python2 curl_hmac.py test secret POST /v1/sessions \
    -f "request_example_body.json"

Example output:

curl https://api.aimbrain.com:443/v1/sessions\
    -H 'Content-Type: application/json'\
    -H 'X-aimbrain-apikey: test'\
    -H 'X-aimbrain-signature: uPVe74VR9ncmxltwNX69pe6amFTMbJGM0Y8dIGk8vSI='\
    -d '{"userId": "user", "device":"device", "system":"system"}'

AimBrain uses API key pairs (API key and API secret) to allow access to the API. You can register a new API key by emailing us.

AimBrain expects for the API key and HMAC Signature to be included in all API requests to the server in the HTTP headers that look like the following:

X-aimbrain-apikey: api-key
X-aimbrain-signature: base64-hmac-signature

To make development, testing and debugging easier we provide a python tool for generating correctly signed and formed curl requests, as shown in the example.

Remember - in the examples you must replace test with your personal API Key and secret with your personal API Secret.

Generating X-aimbrain-signature

Use base64 encoded HMAC SHA256 digest as the request signature:

X-aimbrain-signature = base64(HMAC_SHA256(secret, message)), where

secret is your API Secret, and

message = uppercase_http_method + '\n' + lovercase_endpoint + '\n' + request_body.

/v1/behavioural/submit

This endpoint sends behavioural data to the AimBrain backend to be used for the AimAnomaly score with the /v1/score call.

HTTP Request

POST /v1/behavioural/submit

Body

The data collection for AimAnomaly is facilitated by the SDKs and is application dependent. Data such as touch/type events, swipe/mouse movement events and accelerometer readings is gathered and sent.

HTTP Response

Status code: 200 OK

Errors

Please see #errors for description of errors and formatting.

/v1/score

Example response:

{
    "session":"test-session",
    "metadata":[],
    "scores":[
        {
            "version":"1.0.0",
            "type":"test-model",
            "value":1.0
        }
    ]
}

This endpoint returns the AimAnomaly score for the session.

HTTP Request

POST /v1/score

Body

Parameter	Description
`session` required	string Current Session ID.

HTTP Response

Status code: 200 OK

Parameter	Description
`session`	string Current Session ID.
`metadata`	array of objects Metadata associated with the session.
`scores`	array of objects Scores associated with the session.

`metadata` object:

Parameter	Description
`name`	string Name of the metadata object (application specific).
`value`	string Value of the metadata object (application specific).

`scores` object:

Parameter	Description
`version`	string Version of the scoring process used for this score object.
`type`	string Type of the scoring process used for this score object.
`value`	float Score returned by the scoring process in the range [0..1].

Errors

Please see #errors for description of errors and formatting.

/v1/sessions

Download session_request_example_body.json and use:

python2 curl_hmac.py test secret POST /v1/sessions \
    -f 'session_request_example_body.json' -r

Alternatively:

curl https://api.aimbrain.com:443/v1/sessions \
    -H 'Content-Type: application/json' \
    -H 'X-aimbrain-apikey: test' \
    -H 'X-aimbrain-signature: E7vPXCNHsJQhadkTruAbCE+q9fCmRK9Gf+wtl2/3yrA=' \
    --data @session_request_example_body.json

Example response:

{
    "behaviour":0,
    "face":0,
    "voice":0,
    "session":"test-user-test-user-1234567890-1459141412877914289"
}

This endpoint creates a server-side session and returns unique session id to be used with further API requests.

HTTP Request

POST /v1/sessions

Body

Parameter	Description
`userId` required	string Random anonymous static ID used to identify app users.
`device` required	string User’s device name used in the AimBehaviour Module and to calculate the precise accuracy by only testing between users with the same device.
`system` required	string Operating system’s name and version used for tracking SDK’s usage statistics.
`screenHeight` required	integer User’s device screen height (px).
`screenWidth` required	integer User’s device screen width (px).

HTTP Response

Status code: 200 OK

Parameter	Description
`session`	string Generated session id for use with other API requests to maintain session semantics.
`face`	integer Status of the AimFace Module for given user (see below).
`voice`	integer Status of the AimVoice Module for given user (see below).
`behaviour`	integer Status of the AimBehaviour Module for given user and device pair (see below).

`face` parameter values:

Value	Description
`0`	User not enrolled - facial authentication not available, enrollment required.
`1`	User enrolled - facial authentication available.
`2`	Building template - enrollment done, AimBrain is building user template and no further action is required.

`voice` parameter values:

Value	Description
`0`	User not enrolled - voice authentication not available, enrollment required.
`1`	User enrolled - voice authentication available.
`2`	Building template - enrollment done, AimBrain is building user template and no further action is required.

`behaviour` parameter values:

Value	Description
`0`	User not enrolled - behavioural authentication not available, enrollment required.
`1`	User enrolled - behavioural authentication available.

Errors

Please see #errors for description of errors and formatting.

/v1/behavioural

Example response:

{
    "status":0,
    "score":0
}

This endpoint enrolls and authenticates users based on the AimBehaviour Module.

HTTP Request

POST /v1/behavioural

Body

The data collection for AimBehaviour is facilitated by the SDKs and is application dependent. Data such as touch/type events, swipe/mouse movement events and accelerometer readings is gathered and sent.

HTTP Response

Status code: 200 OK

Parameter	Description
`score`	float Probability, expressed as float between (0..1), that the current user is the original / enrolled user (only if the current user is already enrolled).
`status`	integer Status of the Behavioural Module for given user (see below).

`status` parameter values:

Value	Description
`0`	User not enrolled - behavioural authentication not available, enrollment required.
`1`	User enrolled - behavioural authentication available.

Errors

Please see #errors for description of errors and formatting.

/v1/face/token

Download face_token_request_example_body.json and use:

python2 curl_hmac.py test secret POST /v1/face/token \
    -f 'face_token_request_example_body.json' -r

Alternatively:

curl https://api.aimbrain.com:443/v1/face/token \
    -H 'Content-Type: application/json' \
    -H 'X-aimbrain-apikey: test' \
    -H 'X-aimbrain-signature: 9Dh+ODTM0YQ7ACEW+n+0B0I2NFBOmyRc21UyZ94J3+Q=' \
    --data @face_token_request_example_body.json

Example response:

{
    "token":"6-6-7"
}

This endpoint a token to be displayed during face/lipsync recording.

HTTP Request

POST /v1/face/token

Body

Parameter	Description
`session` required	string Current Session ID as returned by /v1/sessions request.
`tokentype` required	string The type of token to be returned.

HTTP Response

Status code: 200 OK

Parameter	Description
`token`	string The token to be displayed during face/lipsync recording.

`tokentype` parameter values:

Value	Description
`enroll-1`	Token type to be used during the first enrollment step.
`enroll-2`	Token type to be used during the second enrollment step.
`enroll-3`	Token type to be used during the third enrollment step.
`enroll-4`	Token type to be used during the fourth enrollment step.
`enroll-5`	Token type to be used during the fifth enrollment step.
`auth`	Token type to be used during authentication.

Errors

Please see #errors for description of errors and formatting.

/v1/face/enroll

Download face_enroll_request_example_body.json and use:

python2 curl_hmac.py test secret POST /v1/face/enroll \
    -f 'face_enroll_request_example_body.json' -r

Alternatively:

curl https://api.aimbrain.com:443/v1/face/enroll \
    -H 'Content-Type: application/json' \
    -H 'X-aimbrain-apikey: test' \
    -H 'X-aimbrain-signature: VXNfJLbOntEVUlOp6UUwo8D4YyKjNtzspeBCOqZYM9A=' \
    --data @face_enroll_request_example_body.json

Example response:

{
    "imagesCount":2
}

This endpoint enrolls users based on the AimFace Module.

HTTP Request

POST /v1/face/enroll

Body

Parameter	Description
`session` required	string Current Session ID as returned by /v1/sessions request.
`faces` required	array of strings List of base64 encoded images or videos containing user face. H.264 encoded videos and JPEG formats supported. 640x480 maximum resolution, 500kB maximum size. In case of video, no longer than 3 seconds.

HTTP Response

Status code: 200 OK

Parameter	Description
`imagesCount`	integer Number of images accepted for enrollment.

Errors

Please see #errors for description of errors and formatting.

/v1/face/auth

Download face_auth_request_example_body.json and use:

python2 curl_hmac.py test secret POST /v1/face/auth \
    -f 'face_auth_request_example_body.json' -r

Alternatively:

curl https://api.aimbrain.com:443/v1/face/auth \
    -H 'Content-Type: application/json' \
    -H 'X-aimbrain-apikey: test' \
    -H 'X-aimbrain-signature: dBxk9M++dNhI7pk+tXvAVaUwlWuOPl8S4wlmrhKhSqs=' \
    --data @face_auth_request_example_body.json

Example response:

{
    "score":0.95256084,
    "liveliness":0.05330102
}

This endpoint authenticates users based on the AimFace Module.

HTTP Request

POST /v1/face/auth

Body

Parameter	Description
`session` required	string Current Session ID as returned by /v1/sessions request.
`faces` required	array of strings List of base64 encoded images or videos containing user face. H.264 encoded videos and JPEG formats supported. 640x480 maximum resolution, 500kB maximum size. In case of video, no longer than 3 seconds.

HTTP Response

Status code: 200 OK

Parameter	Description
`score`	float Probability, expressed as float between (0..1), that the current user is the original / enrolled user.
`liveliness`	float Probability, expressed as float between (0..1), that the received video in `faces` array represent a live person as opposed being still image. In case of images are sent in `faces`, 0.0 is returned.

Errors

Please see #errors for description of errors and formatting.

/v1/face/compare

Download face_compare_request_example_body.json and use:

python2 curl_hmac.py test secret POST /v1/face/compare \
    -f 'face_compare_request_example_body.json' -r

Alternatively:

curl https://api.aimbrain.com:443/v1/face/compare \
    -H 'Content-Type: application/json' \
    -H 'X-aimbrain-apikey: test' \
    -H 'X-aimbrain-signature: NwMmSbjqwsq7Y4x4Src7qHnIFerMhUTWcFxqLuAbbwg=' \
    --data @face_compare_request_example_body.json

Example response:

{
    "score":0.95256084,
    "liveliness1":0.05330102,
    "liveliness2":0.81412222
}

This endpoint compares two faces based on the AimFace Module.

HTTP Request

POST /v1/face/compare

Body

Parameter	Description
`faces1` required	array of strings List of base64 encoded images or videos containing user face. H.264 encoded videos and JPEG formats supported. 640x480 maximum resolution, 500kB maximum size. In case of video, no longer than 3 seconds.
`faces2` required	array of strings List of base64 encoded images or videos containing user face. H.264 encoded videos and JPEG formats supported. 640x480 maximum resolution, 500kB maximum size. In case of video, no longer than 3 seconds.

HTTP Response

Status code: 200 OK

Parameter	Description
`score`	float Probability, expressed as float between (0..1), that the current user is the original / enrolled user.
`liveliness1`	float Probability, expressed as float between (0..1), that the received video in `faces1` array represent a live person as opposed being still image. In case of images are sent in `faces1`, 0.0 is returned.
`liveliness2`	float Probability, expressed as float between (0..1), that the received video in `faces2` array represent a live person as opposed being still image. In case of images are sent in `faces2`, 0.0 is returned.

Errors

Please see #errors for description of errors and formatting.

/v1/voice/token

Download voice_token_request_example_body.json and use:

python2 curl_hmac.py test secret POST /v1/voice/token \
    -f 'voice_token_request_example_body.json' -r

Alternatively:

curl https://api.aimbrain.com:443/v1/voice/token \
    -H 'Content-Type: application/json' \
    -H 'X-aimbrain-apikey: test' \
    -H 'X-aimbrain-signature: isMJ65cfk0B4nJEx3YKroxrkTIkxlE0r/FJhyUVmgEQ=' \
    --data @voice_token_request_example_body.json

Example response:

{
    "token":"Hello, my password is 6-6-7, verify me"
}

This endpoint a token to be displayed during voice recording.

HTTP Request

POST /v1/voice/token

Body

Parameter	Description
`session` required	string Current Session ID as returned by /v1/sessions request.
`tokentype` required	string The type of token to be returned.

HTTP Response

Status code: 200 OK

Parameter	Description
`token`	string The token to be displayed during voice recording.

`tokentype` parameter values:

Value	Description
`enroll-1`	Token type to be used during the first enrollment step.
`enroll-2`	Token type to be used during the second enrollment step.
`enroll-3`	Token type to be used during the third enrollment step.
`enroll-4`	Token type to be used during the fourth enrollment step.
`enroll-5`	Token type to be used during the fifth enrollment step.
`auth`	Token type to be used during authentication.

Errors

Please see #errors for description of errors and formatting.

/v1/voice/enroll

Download voice_enroll_request_example_body.json and use:

python2 curl_hmac.py test secret POST /v1/voice/enroll \
    -f 'voice_enroll_request_example_body.json' -r

Alternatively:

curl https://api.aimbrain.com:443/v1/voice/enroll \
    -H 'Content-Type: application/json' \
    -H 'X-aimbrain-apikey: test' \
    -H 'X-aimbrain-signature: mUBC8eDZ45ObdC8IFll8gADoAsh70zGQcqPnYjVIsZI=' \
    --data @voice_enroll_request_example_body.json

Example response:

{
    "voiceSamples":1
}

This endpoint enrolls users based on the AimVoice Module.

HTTP Request

POST /v1/voice/enroll

Body

Parameter	Description
`session` required	string Current Session ID as returned by /v1/sessions request.
`voices` required	array of strings List of base64 encoded voice samples of the user. 16k Hz sampling rate, 500kB maximum size. No longer than 5 seconds.

HTTP Response

Status code: 200 OK

Parameter	Description
`voiceSamples`	integer Number of voice samples accepted for enrollment.

Errors

Please see #errors for description of errors and formatting.

/v1/voice/auth

Download voice_auth_request_example_body.json and use:

python2 curl_hmac.py test secret POST /v1/voice/auth \
    -f 'voice_auth_request_example_body.json' -r

Alternatively:

curl https://api.aimbrain.com:443/v1/voice/auth \
    -H 'Content-Type: application/json' \
    -H 'X-aimbrain-apikey: test' \
    -H 'X-aimbrain-signature: wVeNTVyYGGfy119x5kOLoisuRTBttyxxht/sJpLy7g8=' \
    --data @voice_auth_request_example_body.json

Example response:

{
    "score":0.95256084,
    "liveliness":1.0
}

This endpoint authenticates users based on the AimVoice Module.

HTTP Request

POST /v1/voice/auth

Body

Parameter	Description
`session` required	string Current Session ID as returned by /v1/sessions request.
`voices` required	array of strings List of base64 encoded voice samples of the user. 16k Hz sampling rate, 500kB maximum size. No longer than 5 seconds.

HTTP Response

Status code: 200 OK

Parameter	Description
`score`	float Probability, expressed as float between (0..1), that the current user is the original / enrolled user.
`liveliness`	float Probability, expressed as float between (0..1), that the received voice samples in `voices` array represent a live person as opposed being a recording. In case voice token is not used, 0.0 is returned.

Errors

Please see #errors for description of errors and formatting.

Errors

Example error:

{
    "error":"User not found",
    "errors":[
        {
            "description": "User not found",
            "code": 107
        }
    ]
}

All errors are indicated by returning HTTP code which is NOT 200. Human readable description as well as specific code is returned via body in JSON format.

Parameter	Description
`error`	string Human readable error description of the main error.
`errors`	array of objects Array of all errors.

`errors` object

Parameter	Description
`description`	string Human readable error description of the error.
`code`	integer Code of the error (list of possible error codes below).

HTTP error codes

The AimBrain API uses the following HTTP error codes in case of main errors:

Code	Meaning	Action
400	Bad Request – malformed request received (e.g. missing API key, API signature, required parameters or malformed json)	Inspect the error message and fix any errors
401	Unauthorized – your API key or API signature is invalid	Check implementation and try generating a new key pair via dashboard
403	Forbidden – specified session with the id could not be found	Generate and include a valid session id and try again
422	Well formed request received, but images were not accepted (reason specified in `error` field)	Capture a NEW set of images and try again
424	Well formed request received, but we could not find an enrolled user with the supplied id	Confirm if enrollnment was done for the specific user
460	Token for the authentication request was not found	Confirm if a token endpoint was called before authenticating
500	Internal Server Error – well formed request received, but we had a problem with our server	Try again later

AimBrain error codes

Further to the HTTP error codes AimBrain also uses custom codes to facilitate the actionable feedback errors:

Code	Meaning	Action
1	Unable to detect a face in the photo/video	Retake the photo/video
2	No image data in the face field	Make sure the photo/video data is not corrupted
3	No facial points in photo/video	Retake the photo/video
5	Image is blurred due to motion	Retake the photo/video without shaking the camera
6	Face has wrong orientation	Retake the photo/video upright
7	Detected face is far away	Retake the photo/video while close to the camera
8	Image has poor sharpness	Retake the photo/video in higher focus
9	Image has poor contrast	Retake the photo/video in better lighting conditions
10	Image has poor brightness	Retake the photo/video in better lighting conditions
11	Image is blurry	Retake the photo/video in higher focus
12	Timeout processing liveliness	Make sure the video adheres to required specifications
13	Image is malformed	Make sure the photo is not corrupted
14	File received is too big	Make sure the size of the request is less than 2 MB
15	Cannot read voice data	Make sure the voice recording is not corrupted
16	Video and audio clips are of different durations	Make sure the video is not corrupted
17	No media found	Make sure the video is not corrupted
18	No video found	Make sure the video is not corrupted
19	Cannot retrieve audio	Make sure the video is not corrupted
20	Unsupported image type	Make sure the photo is in a supported format
103	No user encodings	Retry the request later
104	User cannot be enrolled	Retry the request later
105	Cannot decode data	Make sure the request is not malformed
106	Cannot decode request body	Make sure the request is not malformed
107	User not found	Make sure the user is enrolled
108	Unsupported MIME type	Make sure the data is not corrupted
120	API error	Retry the request later
150	No faces present in request	Make sure the face data is present in the request
151	No voices present in request	Make sure the voice data is present in the request
152	No token found	Make sure the token endpoint was called prior to this request
153	No models found for the API key	Please contact AimBrain
170	Operation timeout	Retry the request later
180	Unsupported file type	Make sure the data is not corrupted
181	Multiple file types detected	Make sure the data is not corrupted
182	Cannot decode request body	Make sure the data is not corrupted
999	Unknown error	Retry the request later

Introduction

Dashboard

Quick-start Guide

Create Your First Application

Note the API Secret Key

Setup the AimBrain CLI

Download the example images

Use the AimBrain CLI

Understanding the Responses

Other Examples

Modules

AimAnomaly

AimBehaviour

AimFace

AimVoice

Security

API v1

Architecture

Production architecture

Integration

Session

AimBehaviour

AimFace

AimFace/LipSync

AimVoice

Authentication

Generating X-aimbrain-signature

/v1/behavioural/submit

HTTP Request

Body

HTTP Response

Errors

/v1/score

HTTP Request

Body

HTTP Response

metadata object:

scores object:

Errors

/v1/sessions

HTTP Request

Body

HTTP Response

face parameter values:

voice parameter values:

behaviour parameter values:

Errors

/v1/behavioural

HTTP Request

Body

HTTP Response

status parameter values:

Errors

/v1/face/token

HTTP Request

Body

HTTP Response

tokentype parameter values:

Errors

/v1/face/enroll

HTTP Request

Body

HTTP Response

Errors

/v1/face/auth

HTTP Request

Body

HTTP Response

Errors

/v1/face/compare

HTTP Request

Body

HTTP Response

Errors

/v1/voice/token

HTTP Request

Body

HTTP Response

tokentype parameter values:

Errors

`metadata` object:

`scores` object:

`face` parameter values:

`voice` parameter values:

`behaviour` parameter values:

`status` parameter values:

`tokentype` parameter values:

`tokentype` parameter values:

`errors` object