# Introduction

The Perse API provides endpoints for biometric authentication using facial recognition, voice identification and anti-spoofing methods.

The API is organized around the RESTful message design pattern. It generates JSON-encoded responses with predictable content following standard HTTP response codes, authentications and verbs.

Using only a few lines of code, you can:

  • Detect the number of faces on a given image.
  • Evaluate the overall quality of an image.
  • Compare similarity between two faces.
  • Evaluate the likelihood of a replay-attack.
  • Compare similarity between two voices.

Learn more about Perse (opens new window)

# TEST IT

Test endpoints are available using Swagger UI playground (opens new window).

# BUILDING FOR THE WEB?

Please, take a look at the Javascript SDK available here

# Token

Perse API authenticates your requests using a session token.

The authentication endpoint uses your API Key to create a session token. If you don't own an API Key, you can create an account and get your API key here (opens new window).

Pay attention: Session tokens expires in 15 minutes. After expiration, you need to create a new session token calling the authentication endpoint with your API Key.

All requests must include the session token in the Authorization header.

Body
privateKey string(uuid)

Response

  • 200: Authenticated successfully.

    token string
    Session token used to authenticate requests to other Perse endpoints.

  • 400: privateKey is missing on request body.

  • 401: API key is invalid.

POST https://api.getperse.com/v0/login

$ curl \
 -X POST https://api.getperse.com/v0/login \
 -H "Content-Type: application/json" \
 --data-raw '{
    "privateKey": "<Your API Key here>"
 }'

# Errors

The Perse API uses the standard HTTP response codes to indicate success or failure of a request.

The status codes are grouped together under the following types:

  • 2xx: Successful codes.
  • 4xx: Error codes. This group of codes indicate errors related to the information provided on the request.
  • 5xx: Error codes. This group of codes indicate errors related to the server.
Show HTTP status code summary

200 - OK

Everything worked as expected.

400 - Bad request

The request was unacceptable, often due to a missing required parameter.

401 - Unauthorized

No valid API key provided.

415 - Unsupported Media Type

The content type or encoding is not valid.

422 - Unprocessable Entity

The parameters were valid, but the request failed.

500, 502, 503, 504 - Server Errors

Something went wrong on our side.

# Response Attributes

Whenever an error is thrown, the server will return a JSON encoded response with the following structure.

message string
A human-readable message providing more details about the error.

code string
A simple string with the code message for programmatic error handling.

params string
If the error is parameter-specific, the parameter related to the error will be shown inside the array.

status string
The HTTP status of the request.

time_taken number
Inference time taken in seconds.

# Error Codes

Some 400 errors that can be handled programmatically (e.g., no face detected) include an error code that briefly explains the error reported.

content_type_header_missing
The request header is missing the content-type key with a value of multipart/form-data

no_face_detected
The model couldn't find a face in at least one of the images. Please check the property image_metrics for insight on the image quality.

empty_file
The image file is empty or not sent.

invalid_file_type
The image file type is not accepted by API.

form_key_missing
The request is missing: image file(s) or token.

image_underexposed - Enrollment only
The image file received is too underexposed and could not be used for enrollment.

image_overexposed - Enrollment only
The image file received is too overexposed and could not be used for enrollment.

user_token_not_found
User token does not exist on backend.

image_id_invalid
User token was not found on update.

no_face_biometric_data
User token was not found when comparing image with user_token.

{
  "message": "The source image sent is empty",
  "code": "empty_file",
  "params": [
      "image_file1"
  ],
  "status": 400,
  "time_taken": 5000
}

# Image Requirements

File formats: JPG, PNG

File size: no files larger than 1 MB.

Image dimensions: For best performance we recommend images where faces are at least 200x200 pixels.

# Audio Requirements

File formats: WAV, OGG

File size: no files larger than 1 MB.

In order to use the Perse API, it's necessary to ask the end user (the person on the image or on the audio file) for consent and inform it inside client_declaration_enduser_consent key. Informing end user consent is required for every endpoint that uses biometric data. If consent is false or empty, the request will not be processed.