NAV Navbar
python shell

Introduction

Welcome to the EYN Developer API! You can use our API to access EYN's API endpoints, which can get information on enrolments in our database.

We have language bindings in Python! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Quickstart

TL;DR? EYN API provides demo files which show how to query the API endpoints. This way you can directly see what EYN API has to offer. Click here to go directly to the demos.

Got more time? Continue exploring the API documentation below. In the following, we'll explain every API endpoint, the query and response parameters and give code examples how to query our endpoints and sample responses. As mentioned above, we provide demos which you can run to see how to query the endpoints in more detail. Any more questions --- let us know at developers@eyn.vision.

Authentication

To authorize, use this code:

from warrant_lite import WarrantLite
wl = WarrantLite(username=<username>, password=<password>, 
                 pool_id=<cognito_pool_id>, client_id=<cognito_client_id>, 
                 client_secret=None, pool_region="eu-west-2")
tokens = wl.authenticate_user()
headers = {'Accept': '*/*',
           'Content-Type': 'application/json; charset=UTF-8',
           'Authorization': tokens['AuthenticationResult']['IdToken']}

Make sure to replace username and password with your AWS Cognito credentials. Replace <cognito_pool_id> with eu-west-2_8ZNdnSazL and <cognito_client_id> with 4sn0g6boc405tspau0lfl0aiba.

EYN uses AWS Cognito to authenticate users. Request your credentials from here.

ENY also expects a API key to be included in all API requests to the server. EYN API expects a header to all API requests that looks like the following:

'Accept': '*/*'
'Content-Type': 'application/json; charset=UTF-8'
'Authorization': <Cognito Id Token>

Enrolments

Get Enrolments

import requests
parameters = {'start_time': 0,
              'end_time': 1554389124,
              'eyn_api_key': <your eyn api key>}
headers = {'Accept': '*/*',
           'Content-Type': 'application/json; charset=UTF-8',
           'Authorization': <Cognito Id Token>}

response = requests.get('https://api.eyn.ninja/api/v1/dev/enrolments',
                        params=parameters, headers=headers)
curl "https://api.eyn.ninja/api/v1/dev/enrolments?
    eyn_api_key=<your eyn api key>&
    start_time=<start time>&
    end_time=<end time>" 
    -H "Authorization: <Cognito Id Token>"

The above command returns JSON structured like this:

{"enrolment_ids": [{"enrolment_id": <enrolment_id_1>},
                   {"enrolment_id": <enrolment_id_2>},
                   ...
                   {"enrolment_id": <enrolment_id_n>}]}

This endpoint returns a list of enrolment ids.

HTTP Request

GET https://api.eyn.ninja/api/v1/dev/enrolments

Query Parameters

Parameter Default Required Description
eyn_api_key - Required The api_key of EYN to access the endpoints.
start_time 0 Optional If start_time is set, then the response contains all enrolments from this point in time. start_time should be supplied as a string in UTC format in milliseconds.
end_time request time Optional If end_time is set, then the response contains all enrolments up to this point in time. end_time should be supplied as a string in UTC format in milliseconds.

Response Parameters

Parameter Type Description
enrolment_id uuid An enrolment_id uniquely identifies an enrolment.

Get Information about a Specific Enrolment

import requests
parameters = {'eyn_api_key': <your eyn api key>}
headers = {'Accept': '*/*',
           'Content-Type': 'application/json; charset=UTF-8',
           'Authorization': <Cognito Id Token>}

response = requests.get('https://api.eyn.ninja/api/v1/dev/enrolments/<enrolment_id>',
                        params=parameters, headers=headers)
curl "https://api.eyn.ninja/api/v1/dev/enrolments/<enrolment_id>?
    eyn_api_key=<your eyn api key>" 
    -H "Authorization: <Cognito Id Token>"

The above command returns JSON structured like this:

{"other_names" : "John",
 "family_name" : "Doe",
 "date_of_birth": "19700101",
 "images" : {
    "link_identity_document_chip_face": <link>, 
    "link_identity_document_image_front": <link>,
    "link_identity_document_image_mrz": <link>,
    "link_user_selfie": <link>},
  "right_to_work_status": "warn",
  "document_checks": {
    "mrz_check": true, 
    "chip_check": true}}

This endpoint returns information about a specific enrolment.

HTTP Request

GET https://api.eyn.ninja/api/v1/dev/enrolments/{enrolment_id}

Query Parameters

Parameter Default Required Description
eyn_api_key - Required The api_key of EYN to access the endpoints.
enrolment_id - Required The enrolment_id for that specific information is requested. An 'enrolment_id' can be retrieved via /enrolment.

Response Parameters

Parameter Type Description
other_names string The other_names parameter contains the given names of an enrolee (including middle names).
family_name string The family_name parameter contains the family name of an enrolee.
date_of_birth string The date_of_birth parameter contains the date of birth of an enrolee. The returned value has a format of yyyymmdd.
images dict The images parameter contains a list of public links to (a) the face of an enrolee extracted from the identity document's chip, (b) the front view of the identity document, (c) the MRZ of the identity document and (d) the selfie of an enrolee. Not all values must be present.
right_to_work_status string The right_to_work_status parameter contains the status if an enrolee is allowed to work in the UK. Possible values are {passed, warn, failed}.
document_checks dict The document_checks parameter contains a list of boolean document checks where (a) mrz_check parameter asserts if the scanned MRZ code is correct and (b) chip_check parameter asserts if the chip of the identity document has been read successfully.

Errors

The EYN API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid. Investigate the parameters of your API call. The error message contains pointers what has gone wrong.
401 Unauthorized -- Your Cognito Id Token is wrong. Every query must contain a header with a valid Cognito Id Token (see Authentication for details.)
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Demos

The EYN API includes the following demos:

Demo Get Enrolments
Demo Get Information about a Specific Enrolment

Download and follow the quickstart sections to immediately run the demos. For more details, read the demo guides.

Demo Get Enrolments

Quickstart

(1)
git clone https://github.com/Ayn-AI/eyn-api-demo
cd eyn-api-demo
virtualenv venv -p python3
source venv/bin/activate
pip install -r requirements.txt

You can download the demo file demo_get_enrolments.py. This demo will show you how to query the Get Enrolments endpoint.

(1) Run the following commands to deploy the demo (see tabs on the right-hand side).

(2) To execute, run the following command.

(2)
 python demo_get_enrolments.py

(3) You shall see a demo response like this.

(3)
enrolment_id :a987259c-bbbb-4b26-926e-b3e6ab64620d
enrolment_id :64897f67-c798-40c6-8ba6-fbf888892b3a
enrolment_id :764a4755-79e5-4678-9b11-268b0136fcb6
enrolment_id :a62749cd-5a5b-4723-a8b4-e18a674489c3

(4) Ask EYN for your production credentials and change the following lines in demo_get_enrolments.py.

(4)
64:    # TODO: Demo parameters - replace with your eyn credentials
65:    username = "demo@api.eyn.ninja"   # replace with your username
66:    password = "Def4ultP4ssw0rd!"     # replace with your password
67:    cognito_pool_id = ""              # replace with your cognito pool id
68:    cognito_client_id = ""            # replace with your cognito client id

This will give you access to your production data. Want to know more? The following demo guide will explain the demo step-by-step.

Demo Guide

(1)
if __name__ == '__main__':
    print('[eyn-api-demo] Demo Get Enrolments')

    # TODO: Demo parameters - replace with your eyn credentials
    username = "demo@api.eyn.ninja"   # replace with your username
    password = "Def4ultP4ssw0rd!"     # replace with your password
    cognito_pool_id = ""              # replace with your cognito pool id
    cognito_client_id = ""            # replace with your cognito client id

    # First, we have to authenticate to AWS Cognito
    tokens = do_authentication(username, password, cognito_pool_id, cognito_client_id)

(1) The entry point of the demo is if __name__ == '__main__':

(2)
def do_authentication(username, password, cognito_pool_id, cognito_client_id):
    wl = WarrantLite(username=username, password=password,
                     pool_id=cognito_pool_id, client_id=cognito_client_id,
                     client_secret=None, pool_region="eu-west-2")
    tokens = wl.authenticate_user()
    return tokens

For every call to EYN's API you have to authenticate to AWS Cognito. In the demo this is done via do_authentication(username, password, cognito_pool_id, cognito_client_id)

(2) Authentication can be done via warrant-lite. (To install run pip install warrant-lite.) After successful authentication, warrent-lite returns the authentication tokens.

(3)
req_auth_headers = {'Accept': '*/*',
                    'Content-Type': 'application/json; charset=UTF-8',
                    'Authorization': tokens['AuthenticationResult']['IdToken']}
# Now, we can query EYN API to get a list of enrolments
enrolment_ids = get_enrolments(req_auth_headers)

(3) You can create the autorisation headers using the authentication tokens. Then, we can query EYN's API endpoint /enrolments via get_enrolments(req_auth_headers).

(4)
def get_enrolments(req_auth_headers):
    parameters = {'start_time': 0,
                  'end_time': str(int(datetime.datetime.now().strftime('%s'))*1000),
                  'eyn_api_key': '4f37a768-887f-427c-a784-95a818e60319'}
    response = requests.get('https://api.eyn.ninja/api/v1/dev/enrolments',
                            params=parameters, headers=req_auth_headers)
    body = json.loads(response.content)
    enrolment_ids = body["enrolment_ids"]
    return enrolment_ids

(4) You can use requests to query EYN's API. (To install run pip install requests.) The following code sends a GET request with start_time = 0 and end_time = <current_time_stamp> to retrieve a list of all enrolments.

(5)
# Let's print the list of enrolments that we retrieved
    print('[eyn-api-demo] Results of querying /enrolments')
    for enrolment_id in enrolment_ids:
        print('enrolment_id :' + enrolment_id["enrolment_id"])

(5) Finally, you can use the returned enrolment_ids in your application. (The demo solely prints the retrieved list of enrolment ids.)

Demo Get Information about a Specific Enrolment

Quickstart

(1)
git clone https://github.com/Ayn-AI/eyn-api-demo
cd eyn-api-demo
virtualenv venv -p python3
source venv/bin/activate
pip install -r requirements.txt

You can download the demo file demo_get_specific_enrolment_info.py. This demo will show you how to query the Get Information about a Specific Enrolment endpoint.

(1) Run the following commands to deploy the demo:

(2) To execute, run the following command:

(2)
python demo_get_specific_enrolment_info.py

(3) You shall see a demo response like this:

(3)
{"other_names": "MOHAMED",
"family_name": "BEN ARBIA",
"date_of_birth": "19910205",
"images" : {"link_identity_document_chip_face": "<link>",
"link_identity_document_image_front": "<link>",
"link_identity_document_image_mrz": "<link>",
"link_user_selfie": "<link>",
"right_to_work_status": "warn", 
  "document_checks": {
    "mrz_check": true, 
    "chip_check": true}}

(4) Ask EYN for your production credentials and change the following lines in demo_get_specific_enrolment_info.py:

(4)
64:    # TODO: Demo parameters - replace with your eyn credentials
65:    username = "demo@api.eyn.ninja"   # replace with your username
66:    password = "Def4ultP4ssw0rd!"     # replace with your password
67:    cognito_pool_id = ""              # replace with your cognito pool id
68:    cognito_client_id = ""            # replace with your cognito client id

This will give you access to your production data. Want to know more? The following demo guide will explain the demo step-by-step.

Demo Guide

(1)
if __name__ == '__main__':
    print('[eyn-api-demo] Demo Get Enrolments')

    # TODO: Demo parameters - replace with your eyn credentials
    username = "demo@api.eyn.ninja"   # replace with your username
    password = "Def4ultP4ssw0rd!"     # replace with your password
    cognito_pool_id = ""              # replace with your cognito pool id
    cognito_client_id = ""            # replace with your cognito client id

    # First, we have to authenticate to AWS Cognito
    tokens = do_authentication(username, password, cognito_pool_id, cognito_client_id)

(1) The entry point of the demo is if __name__ == '__main__':

(2)
def do_authentication(username, password, cognito_pool_id, cognito_client_id):
    wl = WarrantLite(username=username, password=password,
                     pool_id=cognito_pool_id, client_id=cognito_client_id,
                     client_secret=None, pool_region="eu-west-2")
    tokens = wl.authenticate_user()
    return tokens

For every call to EYN's API you have to authenticate to AWS Cognito. In the demo this is done via do_authentication(username, password, cognito_pool_id, cognito_client_id)

(2) Authentication can be done via warrant-lite. (To install run pip install warrant-lite.) After successful authentication, warrent-lite returns the authentication tokens.

(3)
req_auth_headers = {'Accept': '*/*',
                    'Content-Type': 'application/json; charset=UTF-8',
                    'Authorization': tokens['AuthenticationResult']['IdToken']}
# Now, we can query EYN API to get specific information about an enrolment
enrolment_info = get_specific_enrolment_info(req_auth_headers, 'd7bd8751-ea88-4e82-94d8-4940cc07eea8')

(3) You can create the autorisation headers using the authentication tokens. Then, we can query EYN's API endpoint /enrolments/{id} via get_specific_enrolment_info(req_auth_headers, 'd7bd8751-ea88-4e82-94d8-4940cc07eea8').

(4)
def get_specific_enrolment_info(req_auth_headers, enrolment_id):
    parameters = {'eyn_api_key': '4f37a768-887f-427c-a784-95a818e60319'}
    response = requests.get('https://api.eyn.ninja/api/v1/dev/enrolments' + enrolment_id,
                            params=parameters, headers=req_auth_headers)
    enrolment_info = json.loads(response.content)
    return enrolment_info

(4) You can use requests to query EYN's API. (To install run pip install requests.) The following code sends a GET request with enrolment_id = <a valid enrolment id> to retrieve specific information about that enrolment.

(5)
# Let's print the information that we retrieved
print('[eyn-api-demo] Results of querying /enrolments/d7bd8751-ea88-4e82-94d8-4940cc07eea8:')
print('other_names: ' + enrolment_info["other_names"])
print('family_name: ' + enrolment_info["family_name"])
print('date_of_birth: ' + enrolment_info["date_of_birth"])
if "link_identity_document_chip_face" in enrolment_info["images"]:
    print('link_identity_document_chip_face: ' + enrolment_info["images"]["link_identity_document_chip_face"])
if "link_identity_document_image_front" in enrolment_info["images"]:
    print('link_identity_document_image_front: ' + enrolment_info["images"]["link_identity_document_image_front"])
if "link_identity_document_image_mrz" in enrolment_info["images"]:
    print('link_identity_document_image_mrz: ' + enrolment_info["images"]["link_identity_document_image_mrz"])
if "link_user_selfie" in enrolment_info["images"]:
    print('link_user_selfie: ' + enrolment_info["images"]["link_user_selfie"])
print('right_to_work_status: ' + enrolment_info["right_to_work_status"])
print('mrz_check: ' + str(enrolment_info["document_checks"]["mrz_check"]))
print('chip_check: ' + str(enrolment_info["document_checks"]["chip_check"]))

(5) Finally, you can use the returned enrolment information in your application. (The demo solely prints all retrieved information.)