Перейти к основному содержимому
Версия: 1.4.0

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

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

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

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

Эндпоинт POST /publicapi/publicapi/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 (необязательное поле)

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

КодСообщениеОписание
400Account 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 Code200
{
"applicantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"validationLink": "https://host/embedded?requestId=c3e5599f-4742-4a60-b511-b65e5707c963",
"shortValidationLink": "https://host/UA6IB5g"
}

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

CodeMessageDescriptionCode
400Sms sending error. Please check your phone numberSms sending failed120027

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

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

Эндпоинт GET /publicapi/publicapi/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 Code200
{
"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
}
]
}

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

CodeMessageDescriptionCode
400No sorting by selected propertyWrong sorting field selected120026

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

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

Эндпоинт DELETE /publicapi/publicapi/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 Code200

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

CodeMessageDescriptionCode
400Graphql error: "error message"Platform returned errors in response to a graphql query120029

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

Эндпоинт GET /publicapi/publicapi/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 Code200

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

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

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

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

Эндпоинт POST /publicapi/publicapi/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 Code200
{
"callbackUrl": null
}

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

Эндпоинт GET /publicapi/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 Code200
{
"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,
"livenessReflectionIsValid": null,
"hasBeenBlackListed": false
},
"validations": {
"liveness": {
"verdict": true,
"details": [
{
"name": "FaceLiveness",
"verdict": true,
"score": 99
}
]
},
"quality": {
"verdict": true,
"details": [
{
"name": "FaceQuality",
"verdict": true,
"score": 53
}
]
},
"matching": {
"verdict": true,
"details": [
{
"name": "FaceMatching",
"verdict": true,
"score": 0
}
]
},
"motionControl": null
}
},
"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,
"qualityScore": 30,
"livenessReflectionScore": 30,
"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 /publicapi/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 Code200

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

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

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

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

Эндпоинт GET /publicapi/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 Code200
{
"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,
"livenessReflectionIsValid": true,
"hasBeenBlackListed": false
}
}
]
}

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

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

Эндпоинт GET /publicapi/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 Code200
{
"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,
"livenessReflectionConfidence": 90
}
},
"validations": {
"liveness": {
"verdict": true,
"details": [
{
"name": "FaceLiveness",
"verdict": true,
"score": 99
}
]
},
"quality": {
"verdict": true,
"details": [
{
"name": "FaceQuality",
"verdict": true,
"score": 53
}
]
},
"matching": {
"verdict": true,
"details": [
{
"name": "FaceMatching",
"verdict": true,
"score": 0
}
]
},
"motionControl": null
},
"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,
"livenessReflectionIsValid": true,
"hasBeenBlackListed": false
},
"content": {
"livenessReflectionVideoLink": "string",
"backOrSecondImageBase64": "string",
"faceImageBase64": "string",
"frontImageBase64": "string",
"trackString": "string"
},
"applicantId": "3fa85***",
"attemptId": 0
}

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

CodeMessageDescriptionCode
400DVS response Error: "ex.Message"Failed to deserialize json response from DVS120030

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

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

Эндпоинт POST /publicapi/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 Code200

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

CodeMessageDescriptionCode
400SMS sending disabled for applicantSending sms is turned off for applicant120027

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

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

Эндпоинт GET /publicapi/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 Code200
{
"livenessReflectionVideoLink": "string",
"backOrSecondImageBase64": "string",
"faceImageBase64": "string",
"frontImageBase64": "string",
"trackString": "string"
}

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

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

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

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

Эндпоинт: GET /publicapi/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 Code200

Видео файл

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

CodeMessageDescriptionCode
400Validation response does not contain a videoNo video reference found in validationResponse120033

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

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

Эндпоинт: GET /publicapi/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 Code200

Видео файл

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

CodeMessageDescriptionCode
400Validation response does not contain a videoNo video reference found in validationResponse120033