Version: 1.9.0 (latest)

Report control

This section of the API allows you to manage reports that reflect the system's performance.

A report is created with a specified time interval for collecting metrics and then put into processing. Once processed, the metrics can be retrieved via the API.

You can view the status of the report in the “status” field. The possible report statuses are:

0: Pending – The report has just been created and processing has not started.
1: Processing – The report is being processed. The time to process may vary depending on the database size and the reporting period.
2: Completed – The report has been successfully processed. If the data for the check period has been updated, a new report must be created to retrieve it.
3: Error – An error occurred while generating the report.
4: Canceled – Report processing has been canceled. Resuming report processing will only affect metrics that were not calculated for the previous processing.
5: Unexpectedly stopped – Report generation was unexpectedly interrupted, such as if the service was restarted during report processing.

Report Data

The report consists of several sections.

Nist Section

The section contains the following metrics:

failRate. The percentage of applicants who have a status of "Fail" or "Failed Attempt" relative to the total number of applicants.
passRate. The percentage of applicants who have a "Success" status relative to the total number of applicants.
completion. The average time taken from the creation of an applicant to their registration.
suspectedFraud. The percentage of attempts with risks relative to the total number of attempts.
abandonmentRate. The percentage of applicants in a "Pending" status relative to the total number of applicants.
fraudProofing. The total number of applicants who have been "Cancelled" combined with the number of registration attempts with risks.
fraudAuthentication. The total number of applicants with a "Cancelled" status combined with the number of authentication attempts with risks.
authenticationFailures. The average proportion of failed attempts relative to the total number of attempts for each applicant.

RegistrationMetrics section

The section contains the following metrics:

applicantsAttemptToRegister. The number of applicants that have attempted to register or have registered, i.e. have at least one attempt.

The section contains the following subsections:

registeredApplicantsSettledInRegAttempts. Applicants who successfully registered within the allowed number of attempts.
registeredApplicantsNotSettledInRegAttempts. Applicants who registered but exceeded the allowed attempts. If unlimited attempts are enabled, this data will be labeled “Not calculated due to system settings”.
notRegisteredApplicantsSettledInRegAttempts. Applicants who failed to register but stayed within the allowed attempt limit.
notRegisteredApplicantsNotSettledInRegAttempts Applicants who failed to register and exceeded the allowed attempts. If unlimited attempts are enabled, this data will be labeled “Not calculated due to system settings”.

All subsections above contain the same metrics. A dot notation indicates nested values (e.g., sample.data means the data key exists inside the sample dictionary). List of metrics:

count. Number of applicants in a category.
failReasons.validationFailuresCount.qualityFailedSum. Number of quality check failures.
failReasons.validationFailuresCount.faceMatchingFailedSum. Number of face matching failures during registration.
failReasons.validationFailuresCount.lrCrossMatchFailedSum. Number of frame matching failures from video Liveness Reflection.
failReasons.validationFailuresCount.mcCrossMatchFailedSum. Number of frame matching failures from Motion Control video.
failReasons.validationFailuresCount.oneFrameLivenessFailedSum. Number of one frame liveness check failures.
failReasons.validationFailuresCount.livenessReflectionFailedSum. Number of Liveness Reflection failures.
failReasons.inactiveRisksCount.massAttackRiskCount. Number of inactive MassAttack risk triggers.
failReasons.inactiveRisksCount.duplicateFaceCount. Number of inactive DuplicateFace risk triggers.
failReasons.inactiveRisksCount.periodicAttackCount. Number of inactive PeriodicAttack risk triggers.
failReasons.inactiveRisksCount.missingMetadataCount. Number of inactive MissingMetadata risk triggers.
failReasons.inactiveRisksCount.untrustedIpCount.Number of inactive UntrustedIp risk triggers.
failReasons.inactiveRisksCount.untrustedDeviceCount. Number of inactive UntrustedDevice risk triggers.
failReasons.inactiveRisksCount.inconsistentMetadataCount. Number of inactive InconsistentMetadata risk triggers.
failReasons.inactiveRisksCount.motionControlFailedCount. Number of inactive MotionControlFailed risk triggers.
failReasons.activeRisksCount.massAttackRiskCount. Number of active MassAttack risk triggers.
failReasons.activeRisksCount.duplicateFaceCount. Number of active DuplicateFace risk triggers.
failReasons.activeRisksCount.periodicAttackCount. Number of active PeriodicAttack risk triggers.
failReasons.activeRisksCount.missingMetadataCount. Number of active MissingMetadata risk triggers.
failReasons.activeRisksCount.untrustedIpCount.Number of active UntrustedIp risk triggers.
failReasons.activeRisksCount.untrustedDeviceCount. Number of active UntrustedDevice risk triggers.
failReasons.activeRisksCount.inconsistentMetadataCount. Number of active InconsistentMetadata risk triggers.
failReasons.activeRisksCount.motionControlFailedCount. Number of active MotionControlFailed risk triggers.

Create a report

When creating a report, specify the time period for receiving metrics. The time must be specified in the UTC time zone.

Endpoint: POST /publicapi/api/v2/private/Report

Request body:

{
  "startDate": "2024-11-19T11:09:44.530Z",
  "endDate": "2024-11-19T11:09:44.530Z"
}

Request example:

curl -X 'POST' \
  'http://baf.ai/publicapi/api/v2/private/Report' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json-patch+json' \
  -d '{
  "startDate": "2024-11-19T11:09:44.530Z",
  "endDate": "2024-11-19T11:09:44.530Z"
}'

Response example:

Status Code

200

{
  "id": "d7b79e25-40e1-4aaa-a203-7ea77f5b6ef2",
  "reportInfo": {
    "nist": {
      "failRate": 0.5,
      "passRate": 0.5,
      "completion": 401,
      "fraudProofing": 0,
      "suspectedFraud": 0,
      "abandonmentRate": 0,
      "fraudAuthentication": 0,
      "authenticationFailures": 0.6666667
    },
    "registrationMetrics": {
      "applicantsAttemptToRegister": 2,
      "notRegisteredApplicantsSettledInRegAttempts": {
        "count": 0,
        "failReasons": {
          "inactiveRisksCount": {
            "massAttackRiskCount": 0,
            "untrustedIpRiskCount": 0,
            "duplicateFaceRiskCount": 0,
            "periodicAttackRiskCount": 0,
            "missingMetadataRiskCount": 0,
            "untrustedDeviceRiskCount": 0,
            "inconsistentMetadataRiskCount": 0,
            "motionControlFailedRiskCount": 0
          },
          "activeRisksCount": {
            "massAttackRiskCount": 0,
            "untrustedIpRiskCount": 0,
            "duplicateFaceRiskCount": 0,
            "periodicAttackRiskCount": 0,
            "missingMetadataRiskCount": 0,
            "untrustedDeviceRiskCount": 0,
            "inconsistentMetadataRiskCount": 0,
            "motionControlFailedRiskCount": 0
          },
          "validationFailuresCount": {
            "qualityFailedSum": 0,
            "faceMatchingFailedSum": 0,
            "lrCrossMatchFailedSum": 0,
            "mcCrossMatchFailedSum": 0,
            "oneFrameLivenessFailedSum": 0,
            "livenessReflectionFailedSum": 0
          }
        }
      },
      "notRegisteredApplicantsNotSettledInRegAttempts": {
        "count": 1,
        "failReasons": {
          "inactiveRisksCount": {
            "massAttackRiskCount": 0,
            "untrustedIpRiskCount": 0,
            "duplicateFaceRiskCount": 0,
            "periodicAttackRiskCount": 0,
            "missingMetadataRiskCount": 0,
            "untrustedDeviceRiskCount": 0,
            "inconsistentMetadataRiskCount": 0,
            "motionControlFailedRiskCount": 0
          },
          "activeRisksCount": {
            "massAttackRiskCount": 0,
            "untrustedIpRiskCount": 0,
            "duplicateFaceRiskCount": 0,
            "periodicAttackRiskCount": 0,
            "missingMetadataRiskCount": 0,
            "untrustedDeviceRiskCount": 0,
            "inconsistentMetadataRiskCount": 0,
            "motionControlFailedRiskCount": 0
          },
          "validationFailuresCount": {
            "qualityFailedSum": 0,
            "faceMatchingFailedSum": 0,
            "lrCrossMatchFailedSum": 3,
            "mcCrossMatchFailedSum": 2,
            "oneFrameLivenessFailedSum": 3,
            "livenessReflectionFailedSum": 1
          }
        }
      },
      "registeredApplicantsSettledInRegAttempts": {
        "count": 1,
        "failReasons": {
          "inactiveRisksCount": {
            "massAttackRiskCount": 0,
            "untrustedIpRiskCount": 0,
            "duplicateFaceRiskCount": 0,
            "periodicAttackRiskCount": 0,
            "missingMetadataRiskCount": 0,
            "untrustedDeviceRiskCount": 0,
            "inconsistentMetadataRiskCount": 0,
            "motionControlFailedRiskCount": 0
          },
          "activeRisksCount": {
            "massAttackRiskCount": 0,
            "untrustedIpRiskCount": 0,
            "duplicateFaceRiskCount": 0,
            "periodicAttackRiskCount": 0,
            "missingMetadataRiskCount": 0,
            "untrustedDeviceRiskCount": 0,
            "inconsistentMetadataRiskCount": 0,
            "motionControlFailedRiskCount": 0
          },
          "validationFailuresCount": {
            "qualityFailedSum": 0,
            "faceMatchingFailedSum": 0,
            "lrCrossMatchFailedSum": 0,
            "mcCrossMatchFailedSum": 0,
            "oneFrameLivenessFailedSum": 0,
            "livenessReflectionFailedSum": 0
          }
        }
      },
      "registeredApplicantsNotSettledInRegAttempts": {
        "count": 0,
        "failReasons": {
          "inactiveRisksCount": {
            "massAttackRiskCount": 0,
            "untrustedIpRiskCount": 0,
            "duplicateFaceRiskCount": 0,
            "periodicAttackRiskCount": 0,
            "missingMetadataRiskCount": 0,
            "untrustedDeviceRiskCount": 0,
            "inconsistentMetadataRiskCount": 0,
            "motionControlFailedRiskCount": 0
          },
          "activeRisksCount": {
            "massAttackRiskCount": 0,
            "untrustedIpRiskCount": 0,
            "duplicateFaceRiskCount": 0,
            "periodicAttackRiskCount": 0,
            "missingMetadataRiskCount": 0,
            "untrustedDeviceRiskCount": 0,
            "inconsistentMetadataRiskCount": 0,
            "motionControlFailedRiskCount": 0
          },
          "validationFailuresCount": {
            "qualityFailedSum": 0,
            "faceMatchingFailedSum": 0,
            "lrCrossMatchFailedSum": 0,
            "mcCrossMatchFailedSum": 0,
            "oneFrameLivenessFailedSum": 0,
            "livenessReflectionFailedSum": 0
          }
        }
      }
    }
  },
  "status": 2,
  "accountId": "28608d66-a571-44ec-94db-04a00143ff51",
  "startDate": "2025-01-31T19:00:00Z",
  "endDate": "2025-02-08T18:59:59Z",
  "creationDate": "2025-02-04T08:26:26.774871Z",
  "lastModified": "2025-02-04T08:26:26.922604Z"
}

Receiving reports

To receive reports page by page, you need to specify the page number and page size.

Endpoint: GET /publicapi/api/v2/private/Report

Parameters:

Field name	Description	Value
Page	Page number	From 1 to 2147483647
PageSize	Maximum number of reports listed on the page	From 1 to 400

Request example:

curl -X 'GET' \
  'http://baf.ai/publicapi/api/v2/private/Report?Page=1&PageSize=10' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer sk_1d2ca11d-125a-416c-8fdc-e9661ebecb9a'

Response example:

Status Code

200

{
  "totalCount": 2,
  "reports": [
    {
      "id": "a86b6b35-cf6b-462d-9f64-d706cd2490ce",
      "reportInfo": null,
      "status": 0,
      "accountId": "28608d66-a571-44ec-94db-04a00143ff51",
      "startDate": "2024-11-15T06:27:42.706Z",
      "endDate": "2024-11-15T06:27:42.706Z",
      "creationDate": "2024-11-15T06:27:42.231705Z",
      "lastModified": "2024-11-15T06:27:42.231705Z"
    },
    {
      "id": "d7b79e25-40e1-4aaa-a203-7ea77f5b6ef2",
      "reportInfo": {
        "nist": {
          "failRate": 0.5,
          "passRate": 0.5,
          "completion": 401,
          "fraudProofing": 0,
          "suspectedFraud": 0,
          "abandonmentRate": 0,
          "fraudAuthentication": 0,
          "authenticationFailures": 0.6666667
        },
        "registrationMetrics": {
          "applicantsAttemptToRegister": 2,
          "notRegisteredApplicantsSettledInRegAttempts": {
            "count": 0,
            "failReasons": {
              "inactiveRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "activeRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "validationFailuresCount": {
                "qualityFailedSum": 0,
                "faceMatchingFailedSum": 0,
                "lrCrossMatchFailedSum": 0,
                "mcCrossMatchFailedSum": 0,
                "oneFrameLivenessFailedSum": 0,
                "livenessReflectionFailedSum": 0
              }
            }
          },
          "notRegisteredApplicantsNotSettledInRegAttempts": {
            "count": 1,
            "failReasons": {
              "inactiveRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "activeRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "validationFailuresCount": {
                "qualityFailedSum": 0,
                "faceMatchingFailedSum": 0,
                "lrCrossMatchFailedSum": 3,
                "mcCrossMatchFailedSum": 2,
                "oneFrameLivenessFailedSum": 3,
                "livenessReflectionFailedSum": 1
              }
            }
          },
          "registeredApplicantsSettledInRegAttempts": {
            "count": 1,
            "failReasons": {
              "inactiveRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "activeRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "validationFailuresCount": {
                "qualityFailedSum": 0,
                "faceMatchingFailedSum": 0,
                "lrCrossMatchFailedSum": 0,
                "mcCrossMatchFailedSum": 0,
                "oneFrameLivenessFailedSum": 0,
                "livenessReflectionFailedSum": 0
              }
            }
          },
          "registeredApplicantsNotSettledInRegAttempts": {
            "count": 0,
            "failReasons": {
              "inactiveRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "activeRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "validationFailuresCount": {
                "qualityFailedSum": 0,
                "faceMatchingFailedSum": 0,
                "lrCrossMatchFailedSum": 0,
                "mcCrossMatchFailedSum": 0,
                "oneFrameLivenessFailedSum": 0,
                "livenessReflectionFailedSum": 0
              }
            }
          }
        }
      },
      "status": 2,
      "accountId": "28608d66-a571-44ec-94db-04a00143ff51",
      "startDate": "2025-01-31T19:00:00Z",
      "endDate": "2025-02-08T18:59:59Z",
      "creationDate": "2025-02-04T08:26:26.774871Z",
      "lastModified": "2025-02-04T08:26:26.922604Z"
    }
  ]
}

Deleting a report

Endpoint: DELETE /publicapi/api/v2/private/Report

Request example:

curl -X 'DELETE' \
  'http://baf.ai/publicapi/api/v2/private/Report/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer sk_1d2ca11d-125a-416c-8fdc-e9661ebecb9a'

Response example:

Status Code

200

Possible errors:

HTTP Code	Message	Description	Error code
404	Report not found	Report not found for deletion.	120024

Receiving report information

Endpoint: GET /publicapi/api/v2/private/Report/{report_id}

Request example:

curl -X 'GET' \
  'http://baf.ai/publicapi/api/v2/private/Report/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer sk_1d2ca11d-125a-416c-8fdc-e9661ebecb9a'curl -X 'GET'

Response example:

Status Code

200

Possible errors:

HTTP Code	Message	Description	Error code
404	Report not found	Report not found.	120024

Starting building a report

Endpoint: GET /publicapi/api/v2/private/Report/process/{report_id}

Request example:

curl -X 'POST' \
  'http://baf.ai/publicapi/api/v2/private/Report/Process/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer sk_1d2ca11d-125a-416c-8fdc-e9661ebecb9a' \
  -d ''

Response example:

Status Code

200

Possible errors:

HTTP Code	Message	Description	Error code
404	Report not found	Report not found.	120024
400	Report already processing	Report already processing	120024
400	Too many simultaneously processed reports	The number of simultaneously processed reports has reached the limit.	120024

Canceling report generation

Endpoint: DELETE /publicapi/api/v2/private/Report/process/{report_id}

Request example:

curl -X 'DELETE' \
  'http://baf.ai/publicapi/api/v2/private/Report/Process/3fa85f64-5717-4562-b3fc-2c963f66afa7' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer sk_1d2ca11d-125a-416c-8fdc-e9661ebecb9a'

Response example:

Status Code

200

Possible errors:

HTTP Code	Message	Description	Error code
400	This report not processing at this moment	The report is not in the processing state	120024

Report Data​

Nist Section​

RegistrationMetrics section​

Create a report​

Receiving reports​

Deleting a report​

Receiving report information​

Starting building a report​

Canceling report generation​

Report Data

Nist Section

RegistrationMetrics section

Create a report

Receiving reports

Deleting a report

Receiving report information

Starting building a report

Canceling report generation