Skip to main content
Version: 1.6.0

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 /publicapi/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.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 Code200
{
"applicantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"validationLink": "https://host/embedded?requestId=c3e5599f-4742-4a60-b511-b65e5707c963",
"shortValidationLink": "https://host/UA6IB5g"
}

Possible errors:

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

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 /publicapi/api​/v2​/private​/Applicants

Parameters:

Field nameDescriptionValue
PagePage numberFrom 1 to 2147483647
PageSizeMaximum number of applicants listed on the pageFrom 1 to 400

The following optional fields can be used for search and sorting:

Field nameDescription
CreatedFromLower date limit: dd-mm-yyyy
CreatedToUpper date limit: dd-mm-yyyy
SortFieldSorting field. You can specify firstName, lastName, phone, etc.
OrderThe sorting order for the selected field. For descending order specify the value: descending. Ascending order is set by default.
TextFilterText search

Request example:

curl -X 'GET' \
'https://baf.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 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": "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:

CodeMessageDescriptionCode
400No sorting by selected propertyWrong sorting field selected120026

Delete an Applicant

Applicant should be deleted if the user needs to repeat verification.

Endpoint: DELETE /publicapi/api​/v2​/private​/Applicants​/{applicantId}

Parameters:

applicantId

Request example:

curl -X 'DELETE' \
'https://baf.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 Code200

Possible errors:

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

Check an applicant status

Endpoint: GET /publicapi/api/v2/public/Applicants/{applicantId}/Completed

Parameters:

applicantId

Request example:

curl -X 'GET' \
'https://baf.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 Code200

Possible errors:

CodeMessageDescriptionCode
404Validation 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 /publicapi/api/v2/public/Applicants/{applicantId}/Complete

Parameters:

applicantId

Request example:

curl -X 'POST' \
'https://baf.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 Code200
{
"callbackUrl": null
}

Search an applicant by ID

Endpoint: GET /publicapi/api​/v2​/private​/Applicants/{applicantId}

Parameters:

applicantId

Request example:

curl -X 'GET' \
'https://baf.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 Code200
{
"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,
"livenessReflectionIsValid": null,
"hasBeenBlackListed": false
},
"validations": {
"liveness": {
"verdict": true,
"details": [
{
"name": "FaceLiveness",
"verdict": true,
"score": 0.99
}
]
},
"quality": {
"verdict": true,
"details": [
{
"name": "FaceQuality",
"verdict": true,
"score": 0.53
}
]
},
"matching": {
"verdict": true,
"details": [
{
"name": "FaceMatching",
"verdict": true,
"score": 0.0
}
]
},
"motionControl": {
"verdict": false,
"motionControlInfo": [
{
"pattern": "up",
"result": true
},
{
"pattern": "left",
"result": false
}
]
}
}
},
"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,
"hasBackgroundRiskEvents": true,
"metadata": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"callbackUrl": null,
"verificationMethod": 0
}

Update applicant

Update applicant data

Endpoint: GET /publicapi/api​/v2​/private​/Applicants/{applicantId}

Parameters:

applicantId

Request body:

{
"firstName": "string",
"lastName": "string",
"phone": "string",
"email": "string",
"referenceId": "string",
"callbackUrl": "string",
"metadata": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "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)
  • referenceId - (optional field)
  • callbackUrl - (optional field)
  • metadata - (optional field)
note

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.ai/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",
"callbackUrl": "string",
"metadata": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}'

Response example:

Status Code200

Possible errors:

CodeMessageDescriptionCode
400Wrong 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 /publicapi/api​/v2​/private​/Applicants/{applicantId}/Attempts

Parameters:

applicantId

Request example:

curl -X 'GET' \
'https://baf.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 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 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.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 Code200
{
"documentFailStatusReasons": [
"string"
],
"faceFailStatusReasons": [
"string"
],
"invalidDataErrors": [
{
"code": "120058",
"message": "No faces found on image",
"description": "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": 0.99
}
]
},
"quality": {
"verdict": true,
"details": [
{
"name": "FaceQuality",
"verdict": true,
"score": 0.53
}
]
},
"matching": {
"verdict": true,
"details": [
{
"name": "FaceMatching",
"verdict": true,
"score": 0.0
}
]
},
"motionControl": {
"verdict": false,
"motionControlInfo": [
{
"pattern": "up",
"result": true
},
{
"pattern": "left",
"result": false
}
]
}
},
"similarApplicants": {
"ids": [
"be9561bb-3c0b-426d-acac-7d2c11825af5"
]
},
"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",
"livenessActiveVideoLink": "string",
"backOrSecondImageBase64": "string",
"faceImageBase64": "string",
"frontImageBase64": "string",
"trackString": "string"
},
"applicantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"attemptId": 0
}

Possible errors:

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

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.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 Code200

Possible errors:

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

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.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 Code200
{
"livenessReflectionVideoLink": "string",
"livenessActiveVideoLink": "string",
"backOrSecondImageBase64": "string",
"faceImageBase64": "string",
"frontImageBase64": "string",
"trackString": "string"
}

Possible errors:

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

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.ai/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 Code200

Video file

Possible errors:

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

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.ai/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 Code200

Video file

Possible errors:

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

Unlock or open the applicant

This request allows you to unlock or open the applicant. If the applicant is in Failed status, the number of attempts spent is reset.

Endpoint: POST /api/v2/private/Applicants/{applicantId}/Open

Parameters:

applicantId

Request example:

curl -X 'POST' \
'http://baf.ai/publicapi/api/v2/private/Applicants/dcf431c7-786a-4097-83e0-ba9b6dc00e76/Open' \
-H 'accept: */*' \
-H 'Authorization: Bearer sk_e291909c-687f-43b7-b234-216681350c6c' \
-d ''

Response example:

Status Code200

Possible errors:

CodeMessageDescriptionCode
400Request already unblockedError occurs when attempting to unlock an unlocked applicant150002

Update the applicant's registration photo

This request allows you to update the applicant's registration photo. All subsequent authorizations will be compared to the new photo.

Endpoint: POST /api/v2/private/Applicants/{applicantId}/UpdateMainPhoto

Parameters:

applicantId

Request example:

curl -X 'POST' \
'http://baf.ai/publicapi/api/v2/private/Applicants/dcf431c7-786a-4097-83e0-ba9b6dc00e76/UpdateMainPhoto' \
-H 'accept: */*' \
-H 'Content-Type: application/json-patch+json' \
-d '{"faceImageBase64": "string"}'

Response example:

Status Code200

Possible errors:

CodeMessageDescriptionCode
400Applicant has not yet registeredAttempting to update a photo from an unregistered applicant150006
400Graphql error: "error message"Platform returned errors in response to a graphql query120029