# 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 endpoints are available using Swagger UI playground (opens new window).


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.

privateKey string(uuid)


  • 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.

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

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.

The image file is empty or not sent.

The image file type is not accepted by API.

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 does not exist on backend.

User token was not found on update.

User token was not found when comparing image with user_token.

  "message": "The source image sent is empty",
  "code": "empty_file",
  "params": [
  "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.