API Reference

Create Account

API Authentication

The Face.Match.Expert API uses API login and API password to authenticate all requests with the Authorization HTTP header.

You can find these details in the API Set up page in your Panel.

Keep your API credentials secure and don’t expose them publicly.

Header format:

You have to attach the header below to all API calls.

Authorization: API_LOGIN:API_PASSWORD

You must replace API_LOGIN:API_PASSWORD with your personal API credentials.

API Error Codes

Our API returns HTTP responses with error codes in case of invalid requests, missing data, failed authorization and in any other unexpected cases. In all instances, JSON body with an error explanation will be available.

Error Body application/json

Schema

error string

Error name.

Example: "UNAUTHORIZED"

message string

Issue description.

Example: "Incorrect user credentials"

List of error codes

Code	Status
401	UNAUTHORIZED
404	NOT FOUND
422	UNPROCESSABLE ENTITY
500	INTERNAL SYSTEM ERROR
503	SERVICE UNAVAILABLE

API Endpoints

API URL

https://api.expertum.ai/v1

Add images to collection

Endpoint that is responsible for adding images to the chosen collection. In case of adding larger datasets estimated time of photographs being loaded on the servers is up to 15 minutes.

POST https://api.expertum.ai/v1/collection/{collectionId}/add

Query Parameters

Schema

collectionId string required

Id of collection generated while creation in the panel

Example: "EXAMPLEID1"

Request Body (Array) application/json

Array < Object {

id string required

Id of image that is chosen by the user. It will identify images in search and delete requests.

Example: "image_01"

image string required

Image encoded in Base64 format.

Example: "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAg..."

} >

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request POST https://api.expertum.ai/v1/collection/EXAMPLEID1/add \
--header 'Authorization: API_LOGIN:API_PASSWORD' \
--header 'Content-Type: application/json' \
--data '[{"id":"image_01","image":"\/9j\/4AAQSkZJRgABAQAAAQABAAD\/2wBDAAg..."}]'

Response (Empty)

Success evaluation based on the response code – 200 in case of success.

Face detection

Endpoint that is responsible for face detection and image processing. Does not change the content of the collection.

POST https://api.expertum.ai/v1/collection/{collectionId}/detect

Query Parameters

Schema

collectionId string required

Id of collection generated while creation in the panel

Example: "EXAMPLEID1"

Request Body application/json

Schema

image string required

Image encoded in Base64 format.

Example: "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAg…"

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request POST https://api.expertum.ai/v1/collection/EXAMPLEID1/detect \
--header 'Authorization: API_LOGIN:API_PASSWORD' \
--header 'Content-Type: application/json' \
--data '{"image":"\/9j\/4AAQSkZJRgABAQAAAQABAAD\/2wBDAAg\u2026"}'

Response (Array)

Schema

faceData string

Encoded string that can be reused as input data in order to search through collection.

faceImage string

Part of image where face was detected encoded in Base64 format

leftEye array<int>

X,Y position of left eye.

rightEye array<int>

X,Y position of right eye.

leftMouth array<int>

X,Y position of left part of mouth.

rightMouth array<int>

X,Y position of right part of mouth.

nose array<int>

X,Y position of nose.

Example

                                
                                    Example response (Array)
                                    
                                
                                [
    {
        "faceData": "ywqAXtKxTKGqolFSWLrSFqwY9s_HrpdWI3k5QEMFa9...",
        "faceImage": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBg...",
        "leftEye": "[233,59]",
        "rightEye": "[252,56]",
        "leftMouth": "[235,76]",
        "rightMouth": "[255,73]",
        "nose": "[244,70]"
    }
]

Search by face data

Endpoint that is responsible for collection search and finding images containing a given face.

POST https://api.expertum.ai/v1/collection/{collectionId}/search/face-data

Query Parameters

Schema

collectionId string required

Id of collection generated while creation in the panel

Example: "EXAMPLEID1"

Request Body application/json

Schema

faceData string required

Value that was given while using face detection

Example: "ywqAXtKxTKGqolFSWLrSFqwY9s_HrpdWI3k5QEMFa9..."

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request POST https://api.expertum.ai/v1/collection/EXAMPLEID1/search/face-data \
--header 'Authorization: API_LOGIN:API_PASSWORD' \
--header 'Content-Type: application/json' \
--data '{"faceData":"ywqAXtKxTKGqolFSWLrSFqwY9s_HrpdWI3k5QEMFa9..."}'

Response (Array)

Schema

id string

Id of image that was given while adding it to the collection

similarity double

Similarity of face that was found in comparison to face in request body

leftEye array<int>

X,Y position of left eye.

rightEye array<int>

X,Y position of right eye.

leftMouth array<int>

X,Y position of left part of mouth.

rightMouth array<int>

X,Y position of right part of mouth.

nose array<int>

X,Y position of nose.

Example

                                
                                    Example response (Array)
                                    
                                
                                [
    {
        "id": "image_01",
        "similarity": "99.998",
        "leftEye": "[233,59]",
        "rightEye": "[252,56]",
        "leftMouth": "[235,76]",
        "rightMouth": "[255,73]",
        "nose": "[244,70]"
    }
]

Search by image

Endpoint that is responsible for collection search and finding images containing a given face.

POST https://api.expertum.ai/v1/collection/{collectionId}/search/image

Query Parameters

Schema

collectionId string required

Id of collection generated while creation in the panel

Example: "EXAMPLEID1"

Request Body application/json

Schema

image string required

Image encoded in Base64 format.

Example: "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAg..."

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request POST https://api.expertum.ai/v1/collection/EXAMPLEID1/search/image \
--header 'Authorization: API_LOGIN:API_PASSWORD' \
--header 'Content-Type: application/json' \
--data '{"image":"\/9j\/4AAQSkZJRgABAQAAAQABAAD\/2wBDAAg..."}'

Response (Array)

Schema

id string

Id of image that was given while adding it to the collection

similarity double

Similarity of face that was found in comparison to face in request body

leftEye array<int>

X,Y position of left eye.

rightEye array<int>

X,Y position of right eye.

leftMouth array<int>

X,Y position of left part of mouth.

rightMouth array<int>

X,Y position of right part of mouth.

nose array<int>

X,Y position of nose.

Example

                                
                                    Example response (Array)
                                    
                                
                                [
    {
        "id": "image_01",
        "similarity": "99.998",
        "leftEye": "[233,59]",
        "rightEye": "[252,56]",
        "leftMouth": "[235,76]",
        "rightMouth": "[255,73]",
        "nose": "[244,70]"
    }
]

Compare by face data

Endpoint that is responsible for comparing similarity of two person based on face data.

POST https://api.expertum.ai/v1/collection/{collectionId}/compare/face-data

Query Parameters

Schema

collectionId string required

Id of collection generated while creation in the panel

Example: "EXAMPLEID1"

Request Body application/json

Schema

faceData1 string required

Value that was given while using face detection

Example: "ywqAXtKxTKGqolFSWLrSFqwY9s_HrpdWI3k5QEMFa9..."

faceData2 string required

Value that was given while using face detection

Example: "ywqAXtKxTKGqolFSWLrSFqwY9s_HrpdWI3k5QEMFa9..."

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request POST https://api.expertum.ai/v1/collection/EXAMPLEID1/compare/face-data \
--header 'Authorization: API_LOGIN:API_PASSWORD' \
--header 'Content-Type: application/json' \
--data '{"faceData1":"ywqAXtKxTKGqolFSWLrSFqwY9s_HrpdWI3k5QEMFa9...","faceData2":"ywqAXtKxTKGqolFSWLrSFqwY9s_HrpdWI3k5QEMFa9..."}'

Response (Object)

Schema

similarity double

Similarity of face that was found in comparison to face in request body

Example

                                
                                    Example response (Object)
                                    
                                
                                {
    "similarity": "99.998"
}

Compare by image

Endpoint that is responsible for comparing similarity of two person based on uploaded images.

POST https://api.expertum.ai/v1/collection/{collectionId}/compare/image

Query Parameters

Schema

collectionId string required

Id of collection generated while creation in the panel

Example: "EXAMPLEID1"

Request Body application/json

Schema

image1 string required

Image encoded in Base64 format.

Example: "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAg..."

image2 string required

Image encoded in Base64 format.

Example: "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAg..."

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request POST https://api.expertum.ai/v1/collection/EXAMPLEID1/compare/image \
--header 'Authorization: API_LOGIN:API_PASSWORD' \
--header 'Content-Type: application/json' \
--data '{"image1":"\/9j\/4AAQSkZJRgABAQAAAQABAAD\/2wBDAAg...","image2":"\/9j\/4AAQSkZJRgABAQAAAQABAAD\/2wBDAAg..."}'

Response (Object)

Schema

similarity double

Similarity of face that was found in comparison to face in request body

Example

                                
                                    Example response (Object)
                                    
                                
                                {
    "similarity": "99.998"
}

Delete

Endpoint that is responsible for deleting records from the chosen collection.

DELETE https://api.expertum.ai/v1/collection/{collectionId}/delete

Query Parameters

Schema

collectionId string required

Id of collection generated while creation in the panel

Example: "EXAMPLEID1"

Request Body application/json

Schema

id string required

Id of image that was chosen by the user while adding it to the collection

Example: "image_01"

Example

                            
                                Example request (cURL):
                                
                            
                            curl --request DELETE https://api.expertum.ai/v1/collection/EXAMPLEID1/delete \
--header 'Authorization: API_LOGIN:API_PASSWORD' \
--header 'Content-Type: application/json' \
--data '{"id":"image_01"}'

Response (Empty)

Success evaluation based on the response code – 200 in case of success.

API Authentication

Header format:

API Error Codes

Error Body application/json

List of error codes

API Endpoints

Add images to collection

Query Parameters

Request Body (Array) application/json

Response (Empty)

Face detection

Query Parameters

Request Body application/json

Response (Array)

Search by face data

Query Parameters

Request Body application/json

Response (Array)

Search by image

Query Parameters

Request Body application/json

Response (Array)

Compare by face data

Query Parameters

Request Body application/json

Response (Object)

Compare by image

Query Parameters

Request Body application/json

Response (Object)

Delete

Query Parameters

Request Body application/json

Response (Empty)

THIS WEBSITE USES COOKIES