Server Requests

Introduction

A full biometric interaction with the MobbID Gateway is called a GATEWAY PROCESS. Each process consists of several parts:

  • The creation of the proper process.
  • Interaction of the user with the biometric process.
  • Analysis and application of the biometric results.

While the MobbID Gateway Web displays the front and logic that deals with the user interaction, the MobbID API aims to help with the other parts of the process. Among other tasks, this REST API allows you to:

  • Create a new GATEWAY PROCESS.
  • Check the status of a GATEWAY PROCESS.
  • Retrieve information about the biometric OPERATION performed within the GATEWAY PROCESS.
  • Obtain various evidence related to the biometric OPERATION.

Integration Guide

API Setup

To start using the MobbID API, follow these steps:

  1. Register with MobbID: To use the MobbID API, you need to register on the MobbID platform and obtain access credentials (APPLICATION_ID and API_KEY). Contact the Mobbeel support team to obtain these keys.

  2. URL Configuration: After obtaining the access credentials, configure the code in your system by setting up the base URL for the MobbID API, depending on the selected environment to use. Contact the Mobbeel support team to obtain the SERVER_URL depending on your needs.

Diagram

The following diagram shows an example on how to use MobbID Gateway to perform a user login, being that user previously enrolled in MobbID.

Mermaid code

  sequenceDiagram
  autonumber
  User->>+Web: login
  Web->>+Server: login
  Server ->> Server: get userId from user session or input
  Server ->> Server: check biometric verification is needed    
  Server->>+MobbID API Server: obtain authentication<br/>GET /api/v6/authorization (API_KEY + APPLICATION_ID)
  MobbID API Server-->>-Server: AUTH_TOKEN
  Server->>+MobbID API Server: create gateway process<br/>POST /api/v6/application/APPLICATION_ID/gateway/process (Authorization: Bearer AUTH_TOKEN) userId + returnURL + ...
  MobbID API Server-->>-Server: processId + gatewayURL
  Server ->> Server: store AUTH_TOKEN + processId associated to user session
  Server-->>-Web: gatewayURL
  Web->>+MobbID Gateway Web: redirect or iFrame with gatewayURL
  MobbID Gateway Web-->>-User: verification ready
  User->>+MobbID Gateway Web: perform verification
  MobbID Gateway Web->>+MobbID API Server: perform verification via MobbID Gateway JS
  MobbID API Server-->>-MobbID Gateway Web: verification finished
  MobbID Gateway Web -->> Web: redirect to returnURL
  Web->>+Server: check verification (don't trust js)
  Server ->> Server: retrieve AUTH_TOKEN + processId
  Server->>+MobbID API Server: get gateway process info<br/>GET /api/v6/application/APPLICATION_ID/gateway/process/processId (Authorization: Bearer AUTH_TOKEN)
  MobbID API Server-->>-Server: status + operationId
  Server ->> Server: check process (status=COMPLETED)
  Server->>+MobbID API Server: get biometric operation info<br/>GET /api/v6/application/APPLICATION_ID/operation/operationId (Authorization: Bearer AUTH_TOKEN)
  MobbID API Server-->>-Server: biometric operation info
  Server ->> Server: check operation success (status=SUCCESS data.result=true)
  Server-->>-Web: login success/fail
  Web-->>-User: login success/fail

You can adapat the flow to your needs. If you need more help on this or other use cases, please contact Mobbeel's support team.

Steps in a Gateway Process

As we can see in the diagram above, the main interactions with the MobbID API server and MobbID Gateway Web are:

  1. Request Authentication Credentials: In step 5, you must obtain the authentication credentials in form of a JWT token by calling the proper endpoint. See more

  2. Creating a process: In step 7, to begin a GATEWAY PROCESS process, send a request to the MobbID API with the process configuration. The API will generate a unique identifier for the process. See more

  3. Redirecting to the process: In step 11, after the GATEWAY PROCESS is created, redirect the user to the URL generated by the MobbID API to complete the process. This can be done by forwarding to the URL or embedding an iFrame in the integrator's application.

  4. Retrieving process information: In step 19, to get detailed information about the GATEWAY PROCESS, make a request to the MobbID API with the unique identifier of the process. See more

  5. Retrieving biometric operation information: To get detailed information about the biometric OPERATION performed during the GATEWAY PROCESS, make a request to the MobbID API with the unique identifier of the operation. See more

API Reference

Authentication

The MobbID API REST implements JWT (JSON Web Token) authentication for all requests, ensuring secure and stateless communication. Clients must include a valid JWT token (called AUTH_TOKEN) in the Authorization header of each request to access protected resources.

If the access token is not included in the requests, an error code 401 Not authorized will be returned.

By default, the AUTH_TOKEN is preconfigured with a fixed expiration period of 30 minutes, but it can be changed. Please, contact Mobbeel’s support team to modify this duration.

Request

In order to obtain an AUTH_TOKEN, you must call the authentication endpoint, providing the headers for the APPLICATION_ID and API_KEY given by Mobbeel's support team.

Examples
curl --location 'https://<SERVER_URL>/api/v6/authorization' \
--header 'applicationId: <APPLICATION_ID>' \
--header 'apiKey: <API_KEY>'
import requests

headers = { 
  "applicationId": "<APPLICATION_ID>",
  "apiKey": "<API_KEY>",
}

response = requests.get("https://<SERVER_URL>/api/v6/authorization", headers=headers) 
print(response.json())
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
  private static readonly HttpClient client = new HttpClient();

  static async Task Main()
  {
    string url = "https://<SERVER_URL>/api/v6/authorization";

    client.DefaultRequestHeaders.Add("applicationId", "<APPLICATION_ID>");
    client.DefaultRequestHeaders.Add("apiKey", "<API_KEY>");

    HttpResponseMessage response = await client.GetAsync(url);
    string result = await response.Content.ReadAsStringAsync();

    Console.WriteLine(result);
  }
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {

  public static void main(String[] args) throws Exception {
    String url = "https://<SERVER_URL>/api/v6/authorization";

    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("applicationId", "<APPLICATION_ID>")
            .header("apiKey", "<API_KEY>")
            .GET()
            .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  }
  
}
const axios = require('axios');

const url = 'https://<SERVER_URL>/api/v6/authorization';

const headers = {
    'applicationId': `<APPLICATION_ID>`,
    'apiKey': '<API_KEY>'
};

axios.get(url, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));
<?php
$url = "https://<SERVER_URL>/api/v6/authorization";
$authToken = "<AUTH_TOKEN>";

$headers = [
    "applicationId: <APPLICATION_ID>",
    "apiKey: <API_KEY>"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Response

The response will be a JSON object with the following structure:

{
  "authToken": "<AUTH_TOKEN>"
}

The following are the fields of the response:

FieldTypeDescriptionFormat
authTokenstringAUTH_TOKEN or access token to use in all request to the API.JWT Token

The authentication endpoint can return the following status codes:

CodeDescriptionComment
200OK. The request has been successfully completed.The response will contain the AUTH_TOKEN.
400Bad Request. It usually means that one or more of the required parameters are not present in the request or are incorrect. The field message includes more information about the error.Check that all required parameters are included and formatted correctly in the request.
401Unauthorized. The license of the client used to generate the AUTH_TOKEN is not valid.Please, contact Mobbeel’s support team.
403Forbidden. The API_KEY used to generate the AUTH_TOKEN is not valid.Ensure you are using the correct APPLICATION_ID and API_KEY headers. If the error persist, please contact Mobbeel’s support team.

Create a Gateway Process

To start a GATEWAY PROCESS you need first to create one using this endpoint. The process will be generated with a unique identifier called processId, and a unique URL will be created to redirect the user via iFrame or URL forwarding to the interactive biometric process.

Request

Headers
HeaderDescription
AuthorizationAuthentication token in the format Bearer <AUTH_TOKEN>
Content-Typeapplication/json
Body

This endpoint allows configuring different parameters to customize the GATEWAY PROCESS. Below is an example of the request structure:

{
  "biometricMethod": "string",
  "operation": "string",
  "returnUrl": "string",
  "userId": "string",
  "groupId": "string"
}

The following are the fields of the request:

FieldTypeDescriptionRequiredFormat
biometricMethodstringBIOMETRIC_METHOD to use during the process. Currently FACE is the only available method.YesEnum
operationstringType of biometric OPERATION to perform. Currently VERIFICATION is the only available operation type.YesEnum
returnUrlstringURL to redirect the user to after completing the process.YesURL
userIdstringUnique identifier of the USER that will perform the biometric process. It is a required parameter only if the operation value is ENROLLMENT or VERIFICATION .NoText
groupIdstringUnique identifier of the GROUP that will be used for identification purposes. It is a required parameter only if the operation value is IDENTIFICATION.NoText
Examples
curl --location 'https://<SERVER_URL>/api/v6/application/<APPLICATION_ID>/gateway/process' \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "biometricMethod": "FACE",
  "operation": "VERIFICATION",
  "returnUrl": "https://example.com/redirect",
  "userId": "<userId>"
}'
import requests

url = "https://<SERVER_URL>/api/v6/application/<APPLICATION_ID>/gateway/process"
auth_token = "<AUTH_TOKEN>"

headers = {
    "Authorization": f"Bearer {auth_token}",
    "Content-Type": "application/json"
}

json_data = {
    "biometricMethod": "FACE",
    "operation": "VERIFICATION",
    "returnUrl": "https://example.com/redirect",
    "userId": "<userId>"
}

response = requests.post(url, json=json_data, headers=headers)
print(response.json())
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
  private static readonly HttpClient client = new HttpClient();

  static async Task Main()
  {
    string url = "https://<SERVER_URL>/api/v6/application/<APPLICATION_ID>/gateway/process";
    string authToken = "<AUTH_TOKEN>";

    var jsonData = @"{
        ""biometricMethod"": ""FACE"",
        ""operation"": ""VERIFICATION"",
        ""returnUrl"": ""https://example.com/redirect"",
        ""userId"": ""<userId>""
    }";

    client.DefaultRequestHeaders.Add("Authorization", $"Bearer {authToken}");
    var content = new StringContent(jsonData, Encoding.UTF8, "application/json");

    HttpResponseMessage response = await client.PostAsync(url, content);
    string result = await response.Content.ReadAsStringAsync();
    
    Console.WriteLine(result);
  }
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  
  public static void main(String[] args) throws Exception {
    String url = "https://<SERVER_URL>/api/v6/application/<APPLICATION_ID>/gateway/process";
    String authToken = "<AUTH_TOKEN>";
    String jsonData = "{"
            + "\"biometricMethod\": \"FACE\"," 
            + "\"operation\": \"VERIFICATION\"," 
            + "\"returnUrl\": \"https://example.com/redirect\"," 
            + "\"userId\": \"<userId>\""
            + "}";

    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Authorization", "Bearer " + authToken)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonData))
            .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  }

}
const axios = require('axios');

const url = 'https://<SERVER_URL>/api/v6/application/<APPLICATION_ID>/gateway/process';
const authToken = '<AUTH_TOKEN>';

const headers = {
    'Authorization': `Bearer ${authToken}`,
    'Content-Type': 'application/json'
};

const jsonData = {
    biometricMethod: 'FACE',
    operation: 'VERIFICATION',
    returnUrl: 'https://example.com/redirect',
    userId: '<userId>'
};

axios.post(url, jsonData, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));
<?php
$url = "https://<SERVER_URL>/api/v6/application/<APPLICATION_ID>/gateway/process";
$authToken = "<AUTH_TOKEN>";

$data = [
    "biometricMethod" => "FACE",
    "operation" => "VERIFICATION",
    "returnUrl" => "https://example.com/redirect",
    "userId" => "<userId>"
];

$headers = [
    "Authorization: Bearer $authToken",
    "Content-Type: application/json"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Response

The response to the request for generating a GATEWAY PROCESS will be a JSON object with the following structure:

{
  "processId": "string",
  "gatewayUrl": "string"
}

The following are the fields of the response:

FieldTypeDescriptionFormat
processIdstringUnique identifier of the GATEWAY PROCESS for further reference.UUID
gatewayUrlstringUnique URL to redirect the user to the GATEWAY PROCESS.URL

This endpoint can return the following status codes:

CodeDescriptionComment
201Created. The request has been successfully completed.The response will contain the process identifier and the unique URL to redirect the user to the process.
400Bad Request. Usually means one or more required parameters are missing or incorrect in the request.Check that all required parameters are included and formatted correctly in the request.
401Unauthorized. The provided AUTH_TOKEN is invalid or expired.Ensure you are using the correct JWT token or reate a new one.
404Not found. The provided APPLICATION_ID does not exist or is inaccessible.Check if the APPLICATION_ID value is correct.
422Unprocessable Content. The process can not be created, due to a GATEWAY_BIOMETRIC_METHOD_NOT_AVAILABLE or GATEWAY_BIOMETRIC_OPERATION_NOT_AVAILABLE error.Ensure you are using the available biometricMethod and operation values.
429Too many requests. For security reasons, this error is triggered if the caller's IP is temporarily or permanently banned.Wait some minutes to perform another request or contact Mobbeel’s support team.

Get a Gateway Process information

This endpoint provides a detailed information on a specific GATEWAY PROCESS, identified by its processId.

The report includes key details such as the GATEWAY PROCESS's current status, the biometric OPERATION associated with the GATEWAY PROCESS and other associated data.

This can be useful for auditing, troubleshooting, and monitoring the progress of a GATEWAY PROCESS within the system.

Request

Headers
HeaderDescription
AuthorizationAuthentication token in the format Bearer <AUTH_TOKEN>
Examples

This endpoint requires the GATEWAY PROCESS unique identifier (processId) to be sent in the URL.

curl --location 'https://<SERVER_URL>/api/v6/application/<APPLICATION_ID>/gateway/process/<processId>' \
--header 'Authorization: Bearer <AUTH_TOKEN>'
import requests

url = "https://<SERVER_URL>/api/v6/application/<APPLICATION_ID>/gateway/process/<processId>"
auth_token = "<AUTH_TOKEN>"

headers = {
    "Authorization": f"Bearer {auth_token}",
}

response = requests.get(url, headers=headers)
print(response.json())
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
  private static readonly HttpClient client = new HttpClient();

  static async Task Main()
  {
    string url = "https://<SERVER_URL>/api/v6/application/<APPLICATION_ID>/gateway/process/<processId>";
    string authToken = "<AUTH_TOKEN>";

    client.DefaultRequestHeaders.Add("Authorization", $"Bearer {authToken}");

    HttpResponseMessage response = await client.GetAsync(url);
    string result = await response.Content.ReadAsStringAsync();
    
    Console.WriteLine(result);
  }
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  
  public static void main(String[] args) throws Exception {
    String url = "https://<SERVER_URL>/api/v6/application/<APPLICATION_ID>/gateway/process/<processId>";
    String authToken = "<AUTH_TOKEN>";

    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Authorization", "Bearer " + authToken)
            .header("Content-Type", "application/json")
            .GET()
            .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  }

}
const axios = require('axios');

const url = 'https://<SERVER_URL>/api/v6/application/<APPLICATION_ID>/gateway/process/<processId>';
const authToken = '<AUTH_TOKEN>';

const headers = {
    'Authorization': `Bearer ${authToken}`
};

axios.get(url, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));
<?php
$url = "https://<SERVER_URL>/api/v6/application/<APPLICATION_ID>/gateway/process/<processId>";
$authToken = "<AUTH_TOKEN>";

$headers = [
    "Authorization: Bearer $authToken"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Response

The response to the request for obtaining information about a GATEWAY PROCESS will be a JSON object with the following structure:

{
  "id": "string",
  "status": "string",
  "operationId": "string"
}

The following are the fields of the response:

FieldTypeDescriptionFormat
idstringUnique identifier of the GATEWAY PROCESS or further reference.UUID
statusstringThe current status of the GATEWAY PROCESS.Enum
operationIdstringUnique biometric OPERATION identifier assigned to the GATEWAY PROCESS. You can use it to retrive additional information.UUID

The possible values of the status field are:

ValueDescription
CREATEDThe GATEWAY PROCESS has been created but the user has not yet navigate to it.
STARTEDThe GATEWAY PROCESS has started.
QRThe GATEWAY PROCESS is waiting for the execution in the mobile platform.
IN_PROGRESSThe GATEWAY PROCESS is currently in progress.
PROCESSINGThe GATEWAY PROCESS is currently processing the biometric data.
COMPLETEDThe GATEWAY PROCESS has finished.

This endpoint can return the following status codes:

CodeDescriptionComment
200OK. The request has been successfully completed.The response will contain the process information.
400Bad Request. Usually means one or more required parameters are missing or incorrect in the request.Check that all required parameters are included and formatted correctly in the request.
401Unauthorized. The provided AUTH_TOKEN is invalid or expired.Ensure you are using the correct JWT token or reate a new one.
404Not found. The provided APPLICATION_ID or GATEWAY PROCESS does not exist or is inaccessible.Check for the correct values.
429Too many requests. For security reasons, this error is triggered if the caller's IP is temporarily or permanently banned.Wait some minutes to perform another request or contact Mobbeel’s support team.

Get a Biometric Operation information

This endpoint provides a comprehensive report on the biometric OPERATION associated with the GATEWAY PROCESS and identified by its operationId.

The report includes key details such as the biometric OPERATION's final status, associated data, and relevant RESOURCE s.

Request

Headers
HeaderDescription
AuthorizationAuthentication token in the format Bearer <AUTH_TOKEN>
Examples

This endpoint requires the biometric OPERATION unique identifier (operationId) to be sent in the URL.

curl --location 'https://<SERVER_URL>/api/v6/application/<APPLICATION_ID>/operation/<operationId>' \
--header 'Authorization: Bearer <AUTH_TOKEN>'
import requests

url = "https://<SERVER_URL>/api/v6/application/<APPLICATION_ID>/operation/<operationId>"
auth_token = "<AUTH_TOKEN>"

headers = {
    "Authorization": f"Bearer {auth_token}",
}

response = requests.get(url, headers=headers)
print(response.json())
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
  private static readonly HttpClient client = new HttpClient();

  static async Task Main()
  {
    string url = "https://<SERVER_URL>/api/v6/application/<APPLICATION_ID>/operation/<operationId>";
    string authToken = "<AUTH_TOKEN>";

    client.DefaultRequestHeaders.Add("Authorization", $"Bearer {authToken}");

    HttpResponseMessage response = await client.GetAsync(url);
    string result = await response.Content.ReadAsStringAsync();
    
    Console.WriteLine(result);
  }
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
  
  public static void main(String[] args) throws Exception {
    String url = "https://<SERVER_URL>/api/v6/application/<APPLICATION_ID>/operation/<operationId>";
    String authToken = "<AUTH_TOKEN>";

    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Authorization", "Bearer " + authToken)
            .header("Content-Type", "application/json")
            .GET()
            .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  }

}
const axios = require('axios');

const url = 'https://<SERVER_URL>/api/v6/application/<APPLICATION_ID>/operation/<operationId>';
const authToken = '<AUTH_TOKEN>';

const headers = {
    'Authorization': `Bearer ${authToken}`
};

axios.get(url, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));
<?php
$url = "https://<SERVER_URL>/api/v6/application/<APPLICATION_ID>/operation/<operationId>";
$authToken = "<AUTH_TOKEN>";

$headers = [
    "Authorization: Bearer $authToken"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Response

The response to the request for obtaining information about a biometric OPERATION will be a JSON object with the following structure:

{
  "id": "string",
  "transactionId": "string",
  "biometricMethod": "string",
  "type": "string",
  "status": "string",
  "createdAt": "string",
  "finishedAt": "string",
  "userAgent": "string",
  "clientVersion": "string",
  "data": {
    "result": boolean,
    "userId": "string",
    "liveness": "string",
    "scores": [
      {
        "score": number,
        "scoreType": "string",
      }
    ],
    "ranking": [
      {
        "userId": "string",
        "scores": [
          {
            "score": number,
            "scoreType": "string",
          }
        ]
      }
    ],
    "groupId": "string",
    "error": "string"
  },
  "resources": [
    {
      "id": "string",
      "type": "string",
      "url": "string",
      "format": "string"
    }
  ]
}

The following are the fields of the response:

FieldTypeDescriptionRequiredFormat
idstringUnique identifier of the biometric OPERATION.YesUUID
transactionIdstringThe optional unique transaction identifier associated to the biometric OPERATION.NoUUID
biometricMethodstringBIOMETRIC_METHOD of the OPERATION. Currently FACE is the only available method.YesEnum
typestringType of biometric OPERATION. Currently VERIFICATION is the only available operation type.YesEnum
statusstringThe current status of the OPERATION.YesEnum
createdAtstringStart date of the biometric OPERATION.Yestimestamp
finishedAtstringEnd date of the biometric OPERATION.Notimestamp
userAgentstringThe User-Agent header of the HTTP request for the biometric OPERATION, if available.NoText
clientVersionstringThe clientVersion header of the HTTP request for the biometric OPERATION, if available.NoText
dataobjectThe specific biometric information of the biometric OPERATION.YesObject
resourcesarrayList of RESOURCE associated with the biometric OPERATION.NoText

The possible values of the status field are:

ValueDescription
SUCCESSThe biometric OPERATION was successfully finished.
PENDINGThe biometric OPERATION was started but is waiting to be called with the proper biometric SAMPLES.
PROCESSINGThe biometric OPERATION is currently in progress.
ERRORAn error occurred during the execution of the biometric OPERATION, causing it to terminate.

The fields of one object in the resources array are:

FieldTypeDescriptionRequiredFormat
idstringUnique identifier of the RESOURCEYesText
typestringType of RESOURCE.YesEnum
urlstringFull URL of the RESOURCE.YesURL
formatstringFile format of the RESOURCE.YesText

The possible values of the type field are:

ValueDescription
SAMPLE_SOURCEFor any biometric OPERATION, the SAMPLE sent in the request.
SELFIEFor biometric OPERATION s with the FACE BIOMETRIC METHOD, it is the best user's facial image extracted from the SAMPLE video input.

The fields of the object in the data field are:

FieldTypeDescriptionRequiredFormat
resultbooleanResult of the specific biometric OPERATION if available (e.g. the USER has been verified or not).YesBoolean
userIdstringThe unique USER identifier, if one is directly related to the biometric OPERATION (only in ENROLLMENT and VERIFICATION operation types).NoText
livenessstringThe LIVENESS technique applied to the biometric OPERATION.YesEnum
scoresarrayList of scores obtained for the biometric OPERATION, if available.NoArray
rankingarrayList with the USER s that have been identified as possible candidates. Only for IDENTIFICATION operation type.NoArray
groupIdstringUnique identifier of the biometric GROUP used on the operation (only for IDENTIFICATION operation type).NoText
errorstringA detailed explanation of the error, if encountered.NoText

The possible values of the liveness field are:

Value
NONE
FACE_PASSIVE_VIDEO
FACE_PASSIVE_IMAGE

The fields of one object in the scores array are:

FieldTypeDescriptionRequiredFormat
scorebooleanA number between 0.0 and 1.0 with the value of the score.YesFloat
scoreTypestringType of score.YesEnum

The possible values of the scoreType field are:

ValueDescription
MATCHINGMatching between input SAMPLE s.
LIVENESSConfidence in the LIVENESS detection process after evaluating collaborative measures as well as non-cooperative ones.
IDENTITY_VERIFICATIONOverall identity verification process confidence.

The fields of one object in the ranking array are:

FieldTypeDescriptionRequiredFormat
userIdbooleanThe unique USER identifier of the candidate.YesText
scoresarraySee previous table.YesArray

This endpoint can return the following status codes:

CodeDescriptionComment
200OK. The request has been successfully completed.The response will contain the operation information.
400Bad Request. Usually means one or more required parameters are missing or incorrect in the request.Check that all required parameters are included and formatted correctly in the request.
401Unauthorized. The provided AUTH_TOKEN is invalid or expired.Ensure you are using the correct JWT token or reate a new one.
404Not found. The provided APPLICATION_ID or OPERATION does not exist or is inaccessible.Check for the correct values.
429Too many requests. For security reasons, this error is triggered if the caller's IP is temporarily or permanently banned.Wait some minutes to perform another request or contact Mobbeel’s support team.

Glossary

  • API_KEY: Authentication key that allows to request access to the MobbID API.
  • APPLICATION_ID: Unique identifier of the application in the MobbID API system.
  • AUTH_TOKEN: Authentication JWT token that allows users to access the MobbID API. It is obtained through the APPLICATION_ID and API_KEY credentials.
  • GATEWAY PROCESS: The overall biometric interaction of a user on the platform or service.
  • OPERATION: Biometric process performed with the user biometric features. Each GATEWAY PROCESS consists of one OPERATION.
  • operationId: Unique identifier of a biometric OPERATION.
  • processId: Unique identifier of a GATEWAY PROCESS.
  • RESOURCE: SAMPLE or biometric evidence used during the biometric interaction with MobbID API.
  • SAMPLE: Image, video or audio file with the biometric features of the user.
← Getting StartedThrough An Iframe →