Операции с аппликантами

Аппликант – это объект, который содержит данные о пользователе (имя, фамилию, контактные данные и т.д.), количество произведенных попыток верификации и ее текущий статус, а также другие сопутствующие верификации данные.

В BAF предусмотрено несколько попыток верификации для каждого аппликанта (количество попыток устанавливается заказчиком в настройках BAF Dashboard). Аппликант считается закрытым после успешной верификации или по истечении доступного количества попыток.

Создание аппликанта

Эндпоинт POST /api/v2/private/Applicants

Тело запроса:

{
  "firstName": "string",
  "lastName": "string",
  "phone": "string",
  "email": "string",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "callbackUrl": "string",
  "sendSms": true,
  "status": 0,
  "verificationMethod": 0
}

• firstName - имя аппликанта (необязательное поле)
• lastName - фамилия аппликанта (необязательное поле)
• phone - номер телефона аппликанта. Должен быть указан валидный номер (необязательное поле)
• email - электронная почта аппликанта (необязательное поле)
• metadata - объект с дополнительной информацией об аппликанте. Содержит 3 поля: additionalProp1, additionalProp2 и additionalProp3. (необязательное поле)
• callbackUrl - URL, на который происходит перенаправление при верификации (необязательное поле)
• sendSms - флаг для получения ссылок на верифицацию по SMS. Значение false - выключено, true - включено (необязательное поле)
• status - статус аппликанта. 0 - аппликант не верифицирован, 1 - аппликант успешно верифицирован. 2 - верификация в статусе failed, 3 - верификация отменена (необязательное поле)
• verificationMethod - метод верификации. 0 - верификация через SMS, 1 - ручная верификация. Значение по умолчанию - 1 (необязательное поле)

Возможные ошибки:

Код	Сообщение	Описание
400	Account with id {id} not found	Указанный аккаунт не найден

Пример запроса:

curl -X 'POST' \
  'https://baf.3divi.ai/publicapi/api/v2/private/Applicants' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer sk_3938ab7b-cdbf-4a1a-952b-e3782f061f4b' \
  -H 'Content-Type: application/json' \
  -d '{
  "firstName": "John",
  "lastName": "Dow",
  "phone": "49828585009568",
  "email": "string",
  "referenceId": "string",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "callbackUrl": "string",
  "sendSms": true,
  "case": [
    {
      "name": 1,
      "value": "string"
    }
  ],
  "status": 0,
  "verificationMethod": 0
}'

Пример ответа:

Status Code

200

{
  "applicantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "validationLink": "https://host/embedded?requestId=c3e5599f-4742-4a60-b511-b65e5707c963",
  "shortValidationLink": "https://host/UA6IB5g"
}

Возможные ошибки:

Code	Message	Description	Code
400	Sms sending error. Please check your phone number	Sms sending failed	120027

Получение списка аппликантов

Список аппликантов можно отфильтровать по времени. Если не задать фильтрацию для списка аппликантов, то будут выведены все созданные запросы, начиная с последнего.

Эндпоинт GET /api​/v2​/private​/Applicants

Параметры:

Название поля	Описание	Значение
Page	Номер страницы	От 1 до 2147483647
PageSize	Максимальное количество аппликантов на странице	От 1 до 400

Для поиска и сортировки можно использовать следующие необязательные поля:

Название поля	Описание
CreatedFrom	Нижняя граница даты: дд-мм-гггг
CreatedTo	Верхняя граница даты: дд-мм-гггг
SortField	Поле для сортировки. Можно указать firstName, lastName, phone и т.д.
Order	Порядок сортировки для выбранного поля. Для порядка по убыванию укажите значение: descending. Порядок по возрастанию задан по умолчанию.
TextFilter	Текстовый поиск

Пример запроса:

curl -X 'GET' \
  'https://baf.3divi.ai/publicapi/api/v2/private/Applicants?Page=2&PageSize=2' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer sk_3938ab7b-cdbf-4a1a-952b-e3782f061f4b'

Пример ответа:

Status Code

200

{
  "page": 1,
  "pageSize": 3,
  "total": 46,
  "totalPages": 16,
  "items": [
    {
      "applicantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "attemptsCount": 0,
      "lastAttemptId": null,
      "successAttemptId": null,
      "successAttempt": null,
      "firstName": "Test",
      "lastName": "aihv",
      "phone": "+7 982 200-00-00",
      "email": "",
      "referenceId": null,
      "openedLinkTimes": 3,
      "created": "2023-02-06T00:32:22.9260859",
      "accountId": "28608d66-a501-44ec-94db-04a00143ff51",
      "validationRequestSettings": null,
      "completed": false,
      "status": 0,
      "statusName": "Pending",
      "attemptsUsed": 0,
      "documentExpired": null,
      "lastValidationResponse": {
        "validationResponseId": 133,
        "created": "2023-11-17T04:40:31.509932",
        "responseStatus": 0,
        "responseStatusName": "Success"
      },
      "hasRiskEvents": false,
      "metadata": {},
      "callbackUrl": "",
      "verificationMethod": 0
    },
    {
      "applicantId": "08598c21-abdd-48f6-db05-08db07b6879a",
      "attemptsCount": 1,
      "lastAttemptId": null,
      "successAttemptId": null,
      "successAttempt": null,
      "firstName": "Testit",
      "lastName": "bvaddv",
      "phone": "+7 982 200-00-00",
      "email": "",
      "referenceId": null,
      "openedLinkTimes": 5,
      "created": "2023-02-06T00:32:39.0455118",
      "accountId": "28g08d66-a571-44ec-94db-04a00143ff51",
      "validationRequestSettings": null,
      "completed": true,
      "status": 5,
      "statusName": "FailedAttempt",
      "attemptsUsed": 1,
      "documentExpired": false,
      "lastValidationResponse": {
        "validationResponseId": 134,
        "created": "2023-11-17T04:40:31.509932",
        "responseStatus": 0,
        "responseStatusName": "Success"
      },
      "hasRiskEvents": false,
      "metadata": {},
      "callbackUrl": "https://host/?fromonline",
      "verificationMethod": 0
    },
    {
      "applicantId": "ac5abd84-092f-4107-60f3-08db0a81101e",
      "attemptsCount": 1,
      "lastAttemptId": null,
      "successAttemptId": null,
      "successAttempt": null,
      "firstName": "testeSelf",
      "lastName": "teste",
      "phone": "+7 952 500 00 00",
      "email": null,
      "referenceId": null,
      "openedLinkTimes": 6,
      "created": "2023-02-09T03:36:04.0500599",
      "accountId": "28608d66-a571-44ec-94db-04a00149ff51",
      "validationRequestSettings": null,
      "completed": true,
      "status": 1,
      "statusName": "Success",
      "attemptsUsed": 1,
      "documentExpired": false,
      "lastValidationResponse": {
        "validationResponseId": 135,
        "created": "2023-11-17T04:40:31.509932",
        "responseStatus": 0,
        "responseStatusName": "Success"
      },
      "hasRiskEvents": false,
      "metadata": {},
      "callbackUrl": null,
      "verificationMethod": 0
    }
  ]
}

Возможные ошибки:

Code	Message	Description	Code
400	No sorting by selected property	Wrong sorting field selected	120026

Удаление аппликанта

Операция удаления аппликанта применяется в том случае, когда пользователю требуется повторно пройти верификацию.

Эндпоинт DELETE ​/api​/v2​/private​/Applicants​/{applicantId}

Параметры:

applicantId — ID аппликанта

Пример запроса:

curl -X 'DELETE' \
  'https://baf.3divi.ai/publicapi/api/v2/private/Applicants/ac5abd84-092f-4107-60f3-08db0a81101e' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer sk_3938ab7b-cdbf-4a1a-952b-e3782f061f4b'

Пример ответа:

Status Code

200

Возможные ошибки:

Code	Message	Description	Code
400	Graphql error: "error message"	Platform returned errors in response to a graphql query	120029

Проверка статуса аппликанта

Эндпоинт GET /api/v2/public/Applicants/{applicantId}/Completed

Параметры:

applicantId — ID аппликанта

Пример запроса:

curl -X 'GET' \
  'https://baf.3divi.ai/publicapi/api/v2/public/Applicants/ac5abd84-092f-4107-60f3-08db0a81101e/Completed' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer sk_3938ab7b-cdbf-4a1a-952b-e3782f061f4b'

Пример ответа:

Status Code

200

Возможные ошибки:

Code	Message	Description	Code
404	Validation request "applicantId" is not completed yet.	The applicant is not in a completed status.	120025

Принудительное закрытие аппликанта

Запрос для принудительного перевода статуса аппликанта в 3 (Canceled).

Эндпоинт POST /api/v2/public/Applicants/{applicantId}/Complete

Параметры:

applicantId — ID аппликанта

Пример запроса:

curl -X 'POST' \
  'https://baf.3divi.ai/publicapi/api/v2/public/Applicants/ac5abd84-092f-4107-60f3-08db0a81101e/Complete' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer sk_3938ab7b-cdbf-4a1a-952b-e3782f061f4b' \
  -d ''

Пример ответа:

Status Code

200

{
  "callbackUrl": null
}

Поиск аппликанта по ID

Эндпоинт GET /api​/v2​/private​/Applicants/{applicantId}

Параметры:

applicantId — ID аппликанта

Пример запроса:

curl -X 'GET' \
  'https://baf.3divi.ai/publicapi/api/v2/private/Applicants/9687***' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer sk_3938ab7b-cdbf-4a1a-952b-e3782f061f4b'

Пример ответа:

Status Code

200

{
  "applicantId": "0ec2b***",
  "attemptsCount": 2,
  "lastAttemptId": 133,
  "successAttemptId": 133,
  "successAttempt": {
    "document": null,
    "attemptId": 117,
    "created": "2023-11-17T04:38:04.653858",
    "documentType": null,
    "documentTypeInt": 10,
    "hasRiskEvents": false,
    "status": 0,
    "validationStatus": {
      "expired": null,
      "documentIsValid": null,
      "faceIsValid": true,
      "antiSpoofingIsValid": true,
      "profileAlreadyExists": null,
      "qualityIsValid": true
    }
  },
  "firstName": "John",
  "lastName": "Dow",
  "phone": "1542540505-039",
  "email": "string",
  "referenceId": "string",
  "openedLinkTimes": 0,
  "created": "2023-09-19T10:39:00.0307329",
  "accountId": "28608***",
  "validationRequestSettings": {
    "validationRequestId": "0ec2b5***",
    "faceValidationPercent": 70,
    "documentValidationPercent": 70,
    "antiSpoofingPercent": 70,
    "verifyFace": false,
    "isOCREnabled": true,
    "isAddressCheckEnabled": true,
    "isFaceRequiredOnDocument": true,
    "isCrossMatchRequired": false,
    "isDMVEnabled": false,
    "isDMVPartialEnabled": false,
    "isIdentiFraudEnabled": false,
    "isIdentiFraudFullCaseEnabled": false,
    "isDmvOrIdentiFraudEnabled": false,
    "isDmvAndIdentiFraudEnabled": false,
    "isDmvOrIdentiFraudPartialEnabled": false,
    "isDmvAndIdentiFraudPartialEnabled": false,
    "isGenderCheckEnabled": false,
    "isAgeCheckEnabled": false,
    "ageYearsDifference": 10,
    "showConsentForm": false
  },
  "completed": true,
  "status": 3,
  "statusName": "Canceled",
  "attemptsUsed": 0,
  "documentExpired": null,
  "lastValidationResponse": {
    "validationResponseId": 133,
    "created": "2023-11-17T04:40:31.509932",
    "responseStatus": 0,
    "responseStatusName": "Success"
  },
  "hasRiskEvents": false,
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "callbackUrl": null,
  "verificationMethod": 0
}

Обновление аппликанта

Обновление данных аппликанта

Эндпоинт: GET /api​/v2​/private​/Applicants/{applicantId}

Параметры:

applicantId - ID аппликанта

Тело запроса:

{
  "firstName": "string",
  "lastName": "string",
  "phone": "string",
  "email": "string",
  "referenceId": "string"
}

• firstName - имя аппликанта (необязательное поле)
• lastName - фамилия аппликанта (необязательное поле)
• phone - номер телефона аппликанта. Должен быть указан валидный номер (необязательное поле)
• email - электронная почта аппликанта (необязательное поле)
• referenceId - (необязательное поле)

:::примечание Пустая строка интерпретируется как нулевое значение. А именно, чтобы удалить firstName, отправьте запрос с пустой строкой ("") в поле firstName. :::

Пример запроса:

curl -X 'PUT' \
  'http://baf.3divi.ru/publicapi/api/v2/private/Applicants/a948fb4d-8320-429d-aff1-37925609c22f' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer sk_e291909c-687f-43b7-b234-216681350c6c' \
  -H 'Content-Type: application/json-patch+json' \
  -d '{
  "firstName": "string",
  "lastName": "string",
  "phone": "string",
  "email": "string",
  "referenceId": "string"
}'

Пример ответа:

Status Code

200

Возможные ошибки:

Code	Message	Description	Code
400	Wrong Applicant data: SendSms enabled. Phone number cannot be null.	Attempt to null the phone when the applicant has sms sending enabled.	120028

Получение списка попыток верификации аппликанта

Запрос на получение списка всех попыток верификации аппликанта по ID.

Эндпоинт GET /api​/v2​/private​/Applicants/{applicantId}/Attempts

Параметры:

applicantId — ID аппликанта

Пример запроса:

curl -X 'GET' \
  'https://baf.3divi.ai/publicapi/api/v2/private/Applicants/9687***/Attempts' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer sk_3938ab7b-cdbf-4a1a-952b-e3782f061f4b'

Пример ответа:

Status Code

200

{
  "attempts": [
    {
      "attemptId": 188,
      "created": "2023-09-20T07:51:46.5449834",
      "documentType": "ID",
      "documentTypeInt": 1,
      "hasRiskEvents": false,
      "status": 2,
      "validationStatus": {
        "expired": null,
        "documentIsValid": null,
        "faceIsValid": null,
        "antiSpoofingIsValid": null,
        "profileAlreadyExists": null,
        "qualityIsValid": true
      }
    }
  ]
}

Получение информации о попытке верификации аппликанта

Запрос возвращает всю информацию о попытке верификации для определенного аппликанта.

Эндпоинт GET /api​/v2​/private​/Applicants/{applicantId}/Attempts/{attemptId}

Параметры:

applicantId — ID аппликанта

attemptId — ID попытки

Пример запроса:

curl -X 'GET' \
  'https://baf.3divi.ai/publicapi/api/v2/private/Applicants/3fa85f64-5717-4562-b3fc-2c963f66afa6/Attempts/1' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer sk_3938ab7b-cdbf-4a1a-952b-e3782f061f4b'

Пример ответа:

Status Code

200

{
  "documentFailStatusReasons": [
    "string"
  ],
  "faceFailStatusReasons": [
    "string"
  ],
  "invalidDataErrors": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "dvsResult": {
    "requestId": "3fa85***",
    "documentType": 1,
    "captureMethod": "string",
    "document": {
      "abbr3Country": "string",
      "abbrCountry": "string",
      "address": "string",
      "city": "string",
      "class": "string",
      "country": "string",
      "dob": "string",
      "expires": "string",
      "eyes": "string",
      "familyName": "string",
      "firstName": "string",
      "fullName": "string",
      "gender": "string",
      "hair": "string",
      "height": "string",
      "id": "string",
      "idType": "string",
      "issued": "string",
      "middleName": "string",
      "postalBox": "string",
      "state": "string",
      "issuedBy": "string",
      "template": "string",
      "weight": "string",
      "zip": "string",
      "privateName": "string"
    },
    "parsedData": {
      "isOcrSuccess": true,
      "isPdf417Success": true,
      "isMrzSuccess": true,
      "isShuftiSuccess": true,
      "isAntiSpoofingSuccess": true
    },
    "documentVerificationResult": {
      "status": 0,
      "totalConfidence": 0,
      "validationTests": [
        {
          "rawResponse": "string",
          "name": "string",
          "displayName": "string",
          "reason": "string",
          "effect": 0,
          "values": [
            {
              "score": 0,
              "effect": 0,
              "fieldName": "string",
              "effectString": "string"
            }
          ],
          "effectString": "string",
          "status": 0,
          "statusString": "string"
        }
      ],
      "verificationConfidence": {
        "abbr3Country": 0,
        "abbrCountry": 0,
        "address": 0,
        "city": 0,
        "class": 0,
        "country": 0,
        "dob": 0,
        "expires": 0,
        "eyes": 0,
        "familyName": 0,
        "firstName": 0,
        "fullName": 0,
        "gender": 0,
        "hair": 0,
        "height": 0,
        "id": 0,
        "idType": 0,
        "issued": 0,
        "issuedBy": 0,
        "middleName": 0,
        "postalBox": 0,
        "state": 0,
        "template": 0,
        "weight": 0,
        "zip": 0,
        "ssn": 0,
        "privateName": 0
      }
    },
    "faceVerificationResult": {
      "antiSpoofing": 0,
      "quality": 46,
      "confidence": 0
    }
  },
  "mobilePhoneModel": "string",
  "mobilePhoneOS": "string",
  "captureMethod": "string",
  "requestIpAddress": "string",
  "created": "2023-09-20T08:37:41.799Z",
  "documentType": "string",
  "documentTypeInt": 0,
  "hasRiskEvents": true,
  "status": 0,
  "validationStatus": {
    "expired": true,
    "documentIsValid": true,
    "faceIsValid": true,
    "antiSpoofingIsValid": true,
    "profileAlreadyExists": true,
    "qualityIsValid": true
  },
  "content": {
    "livenessReflectionVideoLink": "string",
    "backOrSecondImageBase64": "string",
    "faceImageBase64": "string",
    "frontImageBase64": "string",
    "trackString": "string"
  },
  "applicantId": "3fa85***",
  "attemptId": 0
}

Возможные ошибки:

Code	Message	Description	Code
400	DVS response Error: "ex.Message"	Failed to deserialize json response from DVS	120030

Повторная отправка ссылки для верификации аппликанта

Запрос позволяет повторно отправить аппликанту ссылку на верификацию.

Эндпоинт POST /api​/v2​/private​/Applicants/{applicantId}/ReNotify

Параметры:

applicantId — ID аппликанта

Пример запроса:

curl -X 'POST' \
  'https://baf.3divi.ai/publicapi/api/v2/private/Applicants/9687***/ReNotify' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer sk_3938ab7b-cdbf-4a1a-952b-e3782f061f4b' \
  -d ''

Пример ответа:

Status Code

200

Возможные ошибки:

Code	Message	Description	Code
400	SMS sending disabled for applicant	Sending sms is turned off for applicant	120027

Получение изображений из попытки верификации аппликанта

Запрос возвращает изображения из попытки верификации для определенного аппликанта.

Эндпоинт GET /api​/v2​/private​/Applicants/{applicantId}/Attempts/{attemptId}/Images

Параметры:

applicantId — ID аппликанта

attemptId — ID попытки

Пример запроса:

curl -X 'GET' \
  'https://baf.3divi.ai/publicapi/api/v2/private/Applicants/9687***/Attempts/1/Images' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer sk_3938ab7b-cdbf-4a1a-952b-e3782f061f4b'

Пример ответа:

Status Code

200

{
  "livenessReflectionVideoLink": "string",
  "backOrSecondImageBase64": "string",
  "faceImageBase64": "string",
  "frontImageBase64": "string",
  "trackString": "string"
}

Возможные ошибки:

Code	Message	Description	Code
413	You do not have a permission to review images.	Photo is not available for viewing.	120032
413	Allowed time to review these images is expired.	Photo availability time limit is exceeded.	120032

Скачивание Liveness Reflection видео попытки верификации аппликанта

Запрос возвращает Liveness Reflection видео попытки верификации для определенного аппликанта.

Эндпоинт: GET /api​/v2​/private​/Applicants/{applicantId}/Attempts/{attemptId}/Video

Параметры:

applicantId

attemptId

Пример запроса:

curl -X 'GET' \
  'http://baf.3divi.ru/publicapi/api/v2/private/Applicants/a948fb4d-8320-429d-aff1-37925609c22f/Attempts/6562/Video' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer sk_e291909c-687f-43b7-b234-216681350c6c'

Пример ответа:

Status Code

200

Видео файл

Возможные ошибки:

Code	Message	Description	Code
400	Validation response does not contain a video	No video reference found in validationResponse	120033

Скачивание видео контроля движений для попытки верификации аппликанта

Запрос возвращает видео контроля движений для попытки верификации для определенного аппликанта.

Эндпоинт: GET /api​/v2​/private​/Applicants/{applicantId}/Attempts/{attemptId}/LivenessActionVideo

Параметры:

applicantId

attemptId

Пример запроса:

curl -X 'GET' \
  'http://baf.3divi.ru/publicapi/api/v2/private/Applicants/a948fb4d-8320-429d-aff1-37925609c22f/Attempts/6562/LivenessActionVideo' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer sk_e291909c-687f-43b7-b234-216681350c6c'

Пример ответа:

Status Code

200

Видео файл

Возможные ошибки:

Code	Message	Description	Code
400	Validation response does not contain a video	No video reference found in validationResponse	120033