Applicants
Applicant is an object that contains information about the user (first name, last name, contact information, etc.), the number of verification attempts and its current status, as well as other verification data.
BAF provides several registration attempts for each applicant (a customer can set the number of available attempts in BAF Dashboard Settings). The applicant is considered closed after successful verification or after the available attempts run out.
Create an applicant
Endpoint: POST /api/v2/private/Applicants
Request body:
{
"firstName": "string",
"lastName": "string",
"phone": "string",
"email": "string",
"metadata": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"callbackUrl": "string",
"sendSms": true,
"status": 0,
"verificationMethod": 0
}
- firstName - applicant's name (optional field)
- lastName - applicant's last name (optional field)
- phone - applicant’s phone number. Make sure that the number specified is valid (optional field)
- email - applicant’s email (optional field)
- metadata - additional information about applicant. Contains 3 fields: additionalProp1, additionalProp2 and additionalProp3. (optional field)
- callbackUrl - URL for redirection after successful verification (optional field)
- sendSms - flag for receiving sms verification links (optional field): false - disabled, true - enabled.
- status - applicant status. 0 - applicant is not verified, 1 - applicant is successfully verified. 2 - verification has "failed" status, 3 - verification canceled (optional field)
- verificationMethod - verification method. 0 - verification via SMS, 1 - manual verification. Default value is 1 (optional field)
Request example:
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
}'
Response example:
Status Code | 200 |
{
"applicantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"validationLink": "https://host/embedded?requestId=c3e5599f-4742-4a60-b511-b65e5707c963",
"shortValidationLink": "https://host/UA6IB5g"
}
Possible errors:
Code | Message | Description | Code |
400 | Sms sending error. Please check your phone number | Sms sending failed | 120027 |
Get a List of Applicants
The list of applicants can be filtered by time. If you do not set filtering, all created requests will be displayed, starting with the last one.
Endpoint: GET /api/v2/private/Applicants
Parameters:
Field name | Description | Value |
Page | Page number | From 1 to 2147483647 |
PageSize | Maximum number of applicants listed on the page | From 1 to 400 |
The following optional fields can be used for search and sorting:
Field name | Description |
CreatedFrom | Lower date limit: dd-mm-yyyy |
CreatedTo | Upper date limit: dd-mm-yyyy |
SortField | Sorting field. You can specify firstName, lastName, phone, etc. |
Order | The sorting order for the selected field. For descending order specify the value: descending. Ascending order is set by default. |
TextFilter | Text search |
Request example:
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'
Response example:
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": "2860***",
"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": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"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": "28g08***",
"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": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"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": "28608d***",
"validationRequestSettings": null,
"completed": true,
"status": 1,
"statusName": "Success",
"attemptsUsed": 1,
"documentExpired": false,
"hasRiskEvents": false,
"lastValidationResponse": {
"validationResponseId": 135,
"created": "2023-11-17T04:40:31.509932",
"responseStatus": 0,
"responseStatusName": "Success"
},
"metadata": {},
"callbackUrl": null,
"verificationMethod": 0
}
]
}
Possible errors:
Code | Message | Description | Code |
400 | No sorting by selected property | Wrong sorting field selected | 120026 |
Delete an Applicant
Applicant should be deleted if the user needs to repeat verification.
Endpoint: DELETE /api/v2/private/Applicants/{applicantId}
Parameters:
applicantId
Request example:
curl -X 'DELETE' \
'https://baf.3divi.ai/publicapi/api/v2/private/Applicants/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
-H 'accept: */*' \
-H 'Authorization: Bearer sk_3938ab7b-cdbf-4a1a-952b-e3782f061f4b'
Response example:
Status Code | 200 |
Possible errors:
Code | Message | Description | Code |
400 | Graphql error: "error message" | Platform returned errors in response to a graphql query | 120029 |
Check an applicant status
Endpoint: GET /api/v2/public/Applicants/{applicantId}/Completed
Parameters:
applicantId
Request example:
curl -X 'GET' \
'https://baf.3divi.ai/publicapi/api/v2/public/Applicants/3fa85f64-5717-4562-b3fc-2c963f66afa6/Completed' \
-H 'accept: text/plain' \
-H 'Authorization: Bearer sk_3938ab7b-cdbf-4a1a-952b-e3782f061f4b'
Response example:
Status Code | 200 |
Possible errors:
Code | Message | Description | Code |
404 | Validation request "applicantId" is not completed yet. | The applicant is not in a completed status. | 120025 |
Force close an applicant
Request for forced transfer of an applicant's status to 3 (Canceled)
Endpoint: POST /api/v2/public/Applicants/{applicantId}/Complete
Parameters:
applicantId
Request example:
curl -X 'POST' \
'https://baf.3divi.ai/publicapi/api/v2/public/Applicants/3fa85f64-5717-4562-b3fc-2c963f66afa6/Complete' \
-H 'accept: text/plain' \
-H 'Authorization: Bearer sk_3938ab7b-cdbf-4a1a-952b-e3782f061f4b' \
-d ''
Response example:
Status Code | 200 |
{
"callbackUrl": null
}
Search an applicant by ID
Endpoint: GET /api/v2/private/Applicants/{applicantId}
Parameters:
applicantId
Request example:
curl -X 'GET' \
'https://baf.3divi.ai/publicapi/api/v2/private/Applicants/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
-H 'accept: text/plain' \
-H 'Authorization: Bearer sk_3938ab7b-cdbf-4a1a-952b-e3782f061f4b'
Response example:
Status Code | 200 |
{
"applicantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"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,
"hasBackgroundRiskEvents": true,
"metadata": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"callbackUrl": null,
"verificationMethod": 0
}
Update applicant
Update applicant data
Endpoint: GET /api/v2/private/Applicants/{applicantId}
Parameters:
applicantId
Request body:
{
"firstName": "string",
"lastName": "string",
"phone": "string",
"email": "string",
"referenceId": "string"
}
- firstName - applicant's name (optional field)
- lastName - applicant's last name (optional field)
- phone - applicant’s phone number. Make sure that the number specified is valid (optional field)
- email - applicant’s email (optional field)
- referenceId - (optional field)
An empty line is interpreted as a null value. Namely, to delete a firstName, send a query with an empty string ("") in the firstName field.
Request example:
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"
}'
Response example:
Status Code | 200 |
Possible errors:
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 |
Get a List of Applicant Verification Attempts
A request to receive a list of all attempts to verify an applicant by ID.
Endpoint: GET /api/v2/private/Applicants/{applicantId}/Attempts
Parameters:
applicantId
Request example:
curl -X 'GET' \
'https://baf.3divi.ai/publicapi/api/v2/private/Applicants/3fa85f64-5717-4562-b3fc-2c963f66afa6/Attempts' \
-H 'accept: text/plain' \
-H 'Authorization: Bearer sk_3938ab7b-cdbf-4a1a-952b-e3782f061f4b'
Response example:
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 information about an applicant verification attempt
The request returns all information about the verification attempt for a specific applicant.
Endpoint: GET /api/v2/private/Applicants/{applicantId}/Attempts/{attemptId}
Parameters:
applicantId
attemptId
Request example:
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'
Response example:
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",
"livenessActiveVideoLink": "string",
"backOrSecondImageBase64": "string",
"faceImageBase64": "string",
"frontImageBase64": "string",
"trackString": "string"
},
"applicantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"attemptId": 0
}
Possible errors:
Code | Message | Description | Code |
400 | DVS response Error: "ex.Message" | Failed to deserialize json response from DVS | 120030 |
Resend the Link to Verify the Applicant
The request allows you to resend the verification link to the applicant.
Endpoint: POST /api/v2/private/Applicants/{applicantId}/ReNotify
Parameters:
applicantId
Request example:
curl -X 'POST' \
'https://baf.3divi.ai/publicapi/api/v2/private/Applicants/3fa85f64-5717-4562-b3fc-2c963f66afa6/ReNotify' \
-H 'accept: */*' \
-H 'Authorization: Bearer sk_3938ab7b-cdbf-4a1a-952b-e3782f061f4b' \
-d ''
Response example:
Status Code | 200 |
Possible errors:
Code | Message | Description | Code |
400 | SMS sending disabled for applicant | Sending sms is turned off for applicant | 120027 |
Get Images From an Applicant Verification Attempt
The request returns images from a verification attempt for a specific applicant.
Endpoint: GET /api/v2/private/Applicants/{applicantId}/Attempts/{attemptId}/Images
Parameters:
applicantId
attemptId
Request example:
curl -X 'GET' \
'https://baf.3divi.ai/publicapi/api/v2/private/Applicants/3fa85f64-5717-4562-b3fc-2c963f66afa6/Attempts/1/Images' \
-H 'accept: text/plain' \
-H 'Authorization: Bearer sk_3938ab7b-cdbf-4a1a-952b-e3782f061f4b'
Response example:
Status Code | 200 |
{
"livenessReflectionVideoLink": "string",
"livenessActiveVideoLink": "string",
"backOrSecondImageBase64": "string",
"faceImageBase64": "string",
"frontImageBase64": "string",
"trackString": "string"
}
Possible errors:
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 |
Download liveness reflection video from an Applicant Verification Attempt
The request returns liveness reflection video from a verification attempt for a specific applicant.
Endpoint: GET /api/v2/private/Applicants/{applicantId}/Attempts/{attemptId}/Video
Parameters:
applicantId
attemptId
Request example:
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'
Response example:
Status Code | 200 |
Video file
Possible errors:
Code | Message | Description | Code |
400 | Validation response does not contain a video | No video reference found in validationResponse | 120033 |
Download motion control video from an Applicant Verification Attempt
The request returns motion control video from a verification attempt for a specific applicant.
Endpoint: GET /api/v2/private/Applicants/{applicantId}/Attempts/{attemptId}/LivenessActionVideo
Parameters:
applicantId
attemptId
Request example:
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'
Response example:
Status Code | 200 |
Video file
Possible errors:
Code | Message | Description | Code |
400 | Validation response does not contain a video | No video reference found in validationResponse | 120033 |