REST

Start a recognition session

To start a recognition session send a POST request to facematching.io/recognize with Content-Type multipart/form-data (RFC 2388).

The required parameters are:

The optional parameters are:

When all the required computations have completed the server returns the results in the following format (json):

{
    success: RECOGNITION_SUCCESS # Boolean
    distance: AVERAGE_DISTANCE # Float
    idcheck: { # Only if checkid was set to true
        SCORE_NAME: PERCENTAGE
        # ...
        "Final": FINAL_SCORE
    }
    motioncheck: { # Only if checkmotion was set to true
        CHECK_NAME: SUCCESS
        # ...
    }
}

Websocket protocol

Once connected the server and clients communicate through json messages. These messages all have a type field to identify their purpose and additional parameters. In the following sections, names types LIKE_THIS are to be replaced by the appropriate values. Anything after a # sign is a comment, don't include it in the actual request.

Connection

Client websockets can connect to wss://facematching.io/ws?apikey=API_KEY with API_KEY being the client's API key.

We advise using the secure WSS protocol (WebSocket over SSL/TLS).

Client → Server

Send an image

{
    type: "image"
    image: "BASE64_ENCODED_IMAGE"
}

Server → Client

Send the client ID

{
    type: "id"
    id: "CLIENT_ID"
}

Start a recognition session

{
    type: "start"
    idcard: "BASE64_ENCODED_IDCARD_IMAGE"
}

End a recognition session

{
    type: "end"
}

Notify of an error

{
    type: "error"
    message: "ERROR_MESSAGE"
}

Display a splash message on the image

{
    type: "splash"
    message: "MESSAGE"
    duration: DISPLAY_TIME_IN_MS
    motion: CURRENT_MOTION_OR_NULL
}

Results of face detection

{
    type: "box"
    box: { # Can be null if recognition failed
        x: LEFT_COORDINATE
        y: TOP_COORDINATE
        w: WIDTH
        h: HEIGHT
    }
    landmarks: [ # Can be null if detection failed
        {
            x: LEFT_COORDINATE
            y: TOP_COORDINATE
        }
        # ...
    ]
}

Results of face recognition

{
    type: "result"
    success: BOOLEAN
    distance: AVERAGE_DISTANCE # null for intermediate results
}

Results of ID check

{
    type: "idcheck"
    idcheck: {
        SCORE_NAME: PERCENTAGE
        # ...
        "Final": FINAL_SCORE
    }
}

Website URLs

Examples

Start recognition session

In a directory with the file idcard.png, if your API key is test and the client ID displayed on the webcam page is 0 the request with curl would be:

curl facematching.io/recognize
     -F idcard=@idcard.png
     -F apikey=test
     -F clientid=0

With python you can do it this way:

import requests

with open(path, "rb") as f:
    files = {"idcard": f}
    data = {"apikey": "test", "clientid": 0}
    requests.post(url, data=data, files=files)