botsKYC API Gateway - Production

Identity Verification

Endpoint:https://api.botskyc.com

Create Liveness Session

POST

https://api.botskyc.com

/v1/liveness/session

Create a new AWS Rekognition Face Liveness session for anti-spoofing verification

Create Liveness Session › Request Body optional

Request to create a new liveness verification session

client_session_id

string

Optional client-provided session ID for tracking

Create Liveness Session › Responses

Liveness session created successfully

session_id

string · required

status

string · enum · required

Enum values:

CREATED

IN_PROGRESS

SUCCEEDED

FAILED

EXPIRED

created_at

string · date-time · required

expires_at

string · date-time · required

POST/v1/liveness/session

curl --request POST \
  --url https://api.botskyc.com/v1/liveness/session \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_session_id": "client_session_id"
}
'

shell

Request Body Example

{
  "client_session_id": "client_session_id"
}

json

Get Liveness Session Results

GET

https://api.botskyc.com

/v1/liveness/session/{sessionId}/results

Retrieve the results of a completed liveness session including confidence scores

Get Liveness Session Results › path Parameters

sessionId

string · required

Liveness session ID

Get Liveness Session Results › Responses

Liveness results retrieved

Result of face liveness verification

session_id

string · required

status

string · enum · required

Enum values:

SUCCEEDED

FAILED

PENDING

confidence

number · min: 0 · max: 100 · required

Liveness confidence score (0-100)

is_live

boolean · required

True if person is determined to be live (not a spoof)

reference_image

string

Base64-encoded reference image

message

string

Verify Liveness Session

POST

https://api.botskyc.com

/v1/liveness/verify/{sessionId}

Verify a liveness session is authentic with anti-spoofing checks

Verify Liveness Session › path Parameters

sessionId

string · required

Liveness session ID to verify

Verify Liveness Session › Responses

Liveness verified

Result of face liveness verification

session_id

string · required

status

string · enum · required

Enum values:

SUCCEEDED

FAILED

PENDING

confidence

number · min: 0 · max: 100 · required

Liveness confidence score (0-100)

is_live

boolean · required

True if person is determined to be live (not a spoof)

reference_image

string

Base64-encoded reference image

message

string

Face Match - Compare Faces

POST

https://api.botskyc.com

/v1/liveness/compare-faces

Compare selfie to ID photo for biometric face matching. Returns similarity score (0-100) and match determination.

Face Match - Compare Faces › Request Body

Request to compare two face images

sourceImage

string · required

Base64-encoded source image (e.g., selfie)

targetImage

string · required

Base64-encoded target image (e.g., ID photo)

Face Match - Compare Faces › Responses

Face comparison completed

Result of face comparison

similarity

number · min: 0 · max: 100 · required

is_match

boolean · required

confidence

number · min: 0 · max: 100

threshold

number

message

string

POST/v1/liveness/compare-faces

curl --request POST \
  --url https://api.botskyc.com/v1/liveness/compare-faces \
  --header 'Content-Type: application/json' \
  --data '
{
  "sourceImage": "sourceImage",
  "targetImage": "targetImage"
}
'

shell

Request Body Example

{
  "sourceImage": "sourceImage",
  "targetImage": "targetImage"
}

json

Validate Face Comparison

POST

https://api.botskyc.com

/v1/liveness/compare-faces/validate

Validate face comparison result meets threshold

Validate Face Comparison › Request Body

Request to compare two face images

sourceImage

string · required

Base64-encoded source image (e.g., selfie)

targetImage

string · required

Base64-encoded target image (e.g., ID photo)

Validate Face Comparison › Responses

Validation result

Result of face comparison

similarity

number · min: 0 · max: 100 · required

is_match

boolean · required

confidence

number · min: 0 · max: 100

threshold

number

message

string

POST/v1/liveness/compare-faces/validate

curl --request POST \
  --url https://api.botskyc.com/v1/liveness/compare-faces/validate \
  --header 'Content-Type: application/json' \
  --data '
{
  "sourceImage": "sourceImage",
  "targetImage": "targetImage"
}
'

shell

Request Body Example

{
  "sourceImage": "sourceImage",
  "targetImage": "targetImage"
}

json

Verify Liveness with Document

POST

https://api.botskyc.com

/v1/liveness/verify-with-document/{sessionId}

Verify liveness session and compare with ID document photo

Verify Liveness with Document › path Parameters

sessionId

string · required

Verify Liveness with Document › Responses

Rate Limiting Response

type

string · required

A URI reference that identifies the problem.

title

string · required

A short, human-readable summary of the problem.

status

number · required

The HTTP status code.

instance

string

POST/v1/liveness/verify-with-document/{sessionId}

curl --request POST \
  --url https://api.botskyc.com/v1/liveness/verify-with-document/:sessionId

shell

ID Scan - Extract Data from Omang, Passport & Driver's License

POST

https://api.botskyc.com

/v1/identity/scan

Extract data from ID document images using OCR and AI. Supports Botswana Omang, Passports, and Driver's Licenses.

ID Scan - Extract Data from Omang, Passport & Driver's License › Request Body

documents

string[] · required

ID document images (front and back)

ID Scan - Extract Data from Omang, Passport & Driver's License › Responses

Identity data extracted successfully

Document verification response with extracted data

requestId

string

timestamp

string · date-time

status

string · enum

Enum values:

success

partial

failed

object[]

object

POST/v1/identity/scan

curl --request POST \
  --url https://api.botskyc.com/v1/identity/scan \
  --header 'Content-Type: application/json' \
  --data '
{
  "documents": [
    "string"
  ]
}
'

shell

Request Body Example

{
  "documents": [
    "string"
  ]
}

json

ID Validation - Verify Document Authenticity

POST

https://api.botskyc.com

/v1/identity/validate

Validate extracted identity data for format, checksum, and cross-reference consistency

ID Validation - Verify Document Authenticity › Request Body

id_number

string · required

Omang or passport number

document_type

string · enum

Enum values:

omang

passport

drivers_license

date_of_birth

string · date

full_name

string

ID Validation - Verify Document Authenticity › Responses

Validation result

valid

boolean

checks

object

message

string

POST/v1/identity/validate

curl --request POST \
  --url https://api.botskyc.com/v1/identity/validate \
  --header 'Content-Type: application/json' \
  --data '
{
  "id_number": "id_number",
  "document_type": "omang",
  "date_of_birth": "2024-08-25",
  "full_name": "full_name"
}
'

shell

Request Body Example

{
  "id_number": "id_number",
  "document_type": "omang",
  "date_of_birth": "2024-08-25",
  "full_name": "full_name"
}

json

Liveness Check - Anti-Spoofing Selfie Verification

POST

https://api.botskyc.com

/v1/identity/liveness

Create liveness session to detect screens, masks, and deepfakes

Liveness Check - Anti-Spoofing Selfie Verification › Request Body optional

Request to create a new liveness verification session

client_session_id

string

Optional client-provided session ID for tracking

Liveness Check - Anti-Spoofing Selfie Verification › Responses

Liveness session created

Liveness session created successfully

session_id

string · required

status

string · enum · required

Enum values:

CREATED

IN_PROGRESS

SUCCEEDED

FAILED

EXPIRED

created_at

string · date-time · required

expires_at

string · date-time · required

POST/v1/identity/liveness

curl --request POST \
  --url https://api.botskyc.com/v1/identity/liveness \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_session_id": "client_session_id"
}
'

shell

Request Body Example

{
  "client_session_id": "client_session_id"
}

json

Get Liveness Check Results

GET

https://api.botskyc.com

/v1/identity/liveness/{sessionId}/results

Get liveness verification results with confidence score

Get Liveness Check Results › path Parameters

sessionId

string · required

Session ID

Get Liveness Check Results › Responses

Liveness results

Result of face liveness verification

session_id

string · required

status

string · enum · required

Enum values:

SUCCEEDED

FAILED

PENDING

confidence

number · min: 0 · max: 100 · required

Liveness confidence score (0-100)

is_live

boolean · required

True if person is determined to be live (not a spoof)

reference_image

string

Base64-encoded reference image

message

string

Face Match - Compare Selfie to ID Photo

POST

https://api.botskyc.com

/v1/identity/face-match

Biometric comparison of selfie with ID document photo

Face Match - Compare Selfie to ID Photo › Request Body

selfie

string · binary · required

Selfie image

idDocument

string · binary · required

ID document image

Face Match - Compare Selfie to ID Photo › Responses

Face match result

Result of face comparison

similarity

number · min: 0 · max: 100 · required

is_match

boolean · required

confidence

number · min: 0 · max: 100

threshold

number

message

string

POST/v1/identity/face-match

curl --request POST \
  --url https://api.botskyc.com/v1/identity/face-match \
  --header 'Content-Type: application/json' \
  --data '
{
  "selfie": "selfie",
  "idDocument": "idDocument"
}
'

shell

Request Body Example

{
  "selfie": "selfie",
  "idDocument": "idDocument"
}

json

Health Document Processing

botsKYC API Gateway - Production

Identity Verification

Endpoint:https://api.botskyc.com

Create Liveness Session

POST

https://api.botskyc.com

/v1/liveness/session

Create a new AWS Rekognition Face Liveness session for anti-spoofing verification

Create Liveness Session › Request Body optional

Request to create a new liveness verification session

client_session_id

string

Optional client-provided session ID for tracking

Create Liveness Session › Responses

Liveness session created successfully

session_id

string · required

status

string · enum · required

Enum values:

CREATED

IN_PROGRESS

SUCCEEDED

FAILED

EXPIRED

created_at

string · date-time · required

expires_at

string · date-time · required

POST/v1/liveness/session

curl --request POST \
  --url https://api.botskyc.com/v1/liveness/session \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_session_id": "client_session_id"
}
'

shell

Request Body Example

{
  "client_session_id": "client_session_id"
}

json

Get Liveness Session Results

GET

https://api.botskyc.com

/v1/liveness/session/{sessionId}/results

Retrieve the results of a completed liveness session including confidence scores

Get Liveness Session Results › path Parameters

sessionId

string · required

Liveness session ID

Get Liveness Session Results › Responses

Liveness results retrieved

Result of face liveness verification

session_id

string · required

status

string · enum · required

Enum values:

SUCCEEDED

FAILED

PENDING

confidence

number · min: 0 · max: 100 · required

Liveness confidence score (0-100)

is_live

boolean · required

True if person is determined to be live (not a spoof)

reference_image

string

Base64-encoded reference image

message

string

Verify Liveness Session

POST

https://api.botskyc.com

/v1/liveness/verify/{sessionId}

Verify a liveness session is authentic with anti-spoofing checks

Verify Liveness Session › path Parameters

sessionId

string · required

Liveness session ID to verify

Verify Liveness Session › Responses

Liveness verified

Result of face liveness verification

session_id

string · required

status

string · enum · required

Enum values:

SUCCEEDED

FAILED

PENDING

confidence

number · min: 0 · max: 100 · required

Liveness confidence score (0-100)

is_live

boolean · required

True if person is determined to be live (not a spoof)

reference_image

string

Base64-encoded reference image

message

string

Face Match - Compare Faces

POST

https://api.botskyc.com

/v1/liveness/compare-faces

Compare selfie to ID photo for biometric face matching. Returns similarity score (0-100) and match determination.

Face Match - Compare Faces › Request Body

Request to compare two face images

sourceImage

string · required

Base64-encoded source image (e.g., selfie)

targetImage

string · required

Base64-encoded target image (e.g., ID photo)

Face Match - Compare Faces › Responses

Face comparison completed

Result of face comparison

similarity

number · min: 0 · max: 100 · required

is_match

boolean · required

confidence

number · min: 0 · max: 100

threshold

number

message

string

POST/v1/liveness/compare-faces

curl --request POST \
  --url https://api.botskyc.com/v1/liveness/compare-faces \
  --header 'Content-Type: application/json' \
  --data '
{
  "sourceImage": "sourceImage",
  "targetImage": "targetImage"
}
'

shell

Request Body Example

{
  "sourceImage": "sourceImage",
  "targetImage": "targetImage"
}

json

Validate Face Comparison

POST

https://api.botskyc.com

/v1/liveness/compare-faces/validate

Validate face comparison result meets threshold

Validate Face Comparison › Request Body

Request to compare two face images

sourceImage

string · required

Base64-encoded source image (e.g., selfie)

targetImage

string · required

Base64-encoded target image (e.g., ID photo)

Validate Face Comparison › Responses

Validation result

Result of face comparison

similarity

number · min: 0 · max: 100 · required

is_match

boolean · required

confidence

number · min: 0 · max: 100

threshold

number

message

string

POST/v1/liveness/compare-faces/validate

curl --request POST \
  --url https://api.botskyc.com/v1/liveness/compare-faces/validate \
  --header 'Content-Type: application/json' \
  --data '
{
  "sourceImage": "sourceImage",
  "targetImage": "targetImage"
}
'

shell

Request Body Example

{
  "sourceImage": "sourceImage",
  "targetImage": "targetImage"
}

json

Verify Liveness with Document

POST

https://api.botskyc.com

/v1/liveness/verify-with-document/{sessionId}

Verify liveness session and compare with ID document photo

Verify Liveness with Document › path Parameters

sessionId

string · required

Verify Liveness with Document › Responses

Rate Limiting Response

type

string · required

A URI reference that identifies the problem.

title

string · required

A short, human-readable summary of the problem.

status

number · required

The HTTP status code.

instance

string

POST/v1/liveness/verify-with-document/{sessionId}

curl --request POST \
  --url https://api.botskyc.com/v1/liveness/verify-with-document/:sessionId

shell

ID Scan - Extract Data from Omang, Passport & Driver's License

POST

https://api.botskyc.com

/v1/identity/scan

Extract data from ID document images using OCR and AI. Supports Botswana Omang, Passports, and Driver's Licenses.

ID Scan - Extract Data from Omang, Passport & Driver's License › Request Body

documents

string[] · required

ID document images (front and back)

ID Scan - Extract Data from Omang, Passport & Driver's License › Responses

Identity data extracted successfully

Document verification response with extracted data

requestId

string

timestamp

string · date-time

status

string · enum

Enum values:

success

partial

failed

object[]

object

POST/v1/identity/scan

curl --request POST \
  --url https://api.botskyc.com/v1/identity/scan \
  --header 'Content-Type: application/json' \
  --data '
{
  "documents": [
    "string"
  ]
}
'

shell

Request Body Example

{
  "documents": [
    "string"
  ]
}

json

ID Validation - Verify Document Authenticity

POST

https://api.botskyc.com

/v1/identity/validate

Validate extracted identity data for format, checksum, and cross-reference consistency

ID Validation - Verify Document Authenticity › Request Body

id_number

string · required

Omang or passport number

document_type

string · enum

Enum values:

omang

passport

drivers_license

date_of_birth

string · date

full_name

string

ID Validation - Verify Document Authenticity › Responses

Validation result

valid

boolean

checks

object

message

string

POST/v1/identity/validate

curl --request POST \
  --url https://api.botskyc.com/v1/identity/validate \
  --header 'Content-Type: application/json' \
  --data '
{
  "id_number": "id_number",
  "document_type": "omang",
  "date_of_birth": "2024-08-25",
  "full_name": "full_name"
}
'

shell

Request Body Example

{
  "id_number": "id_number",
  "document_type": "omang",
  "date_of_birth": "2024-08-25",
  "full_name": "full_name"
}

json

Liveness Check - Anti-Spoofing Selfie Verification

POST

https://api.botskyc.com

/v1/identity/liveness

Create liveness session to detect screens, masks, and deepfakes

Liveness Check - Anti-Spoofing Selfie Verification › Request Body optional

Request to create a new liveness verification session

client_session_id

string

Optional client-provided session ID for tracking

Liveness Check - Anti-Spoofing Selfie Verification › Responses

Liveness session created

Liveness session created successfully

session_id

string · required

status

string · enum · required

Enum values:

CREATED

IN_PROGRESS

SUCCEEDED

FAILED

EXPIRED

created_at

string · date-time · required

expires_at

string · date-time · required

POST/v1/identity/liveness

curl --request POST \
  --url https://api.botskyc.com/v1/identity/liveness \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_session_id": "client_session_id"
}
'

shell

Request Body Example

{
  "client_session_id": "client_session_id"
}

json

Get Liveness Check Results

GET

https://api.botskyc.com

/v1/identity/liveness/{sessionId}/results

Get liveness verification results with confidence score

Get Liveness Check Results › path Parameters

sessionId

string · required

Session ID

Get Liveness Check Results › Responses

Liveness results

Result of face liveness verification

session_id

string · required

status

string · enum · required

Enum values:

SUCCEEDED

FAILED

PENDING

confidence

number · min: 0 · max: 100 · required

Liveness confidence score (0-100)

is_live

boolean · required

True if person is determined to be live (not a spoof)

reference_image

string

Base64-encoded reference image

message

string

Face Match - Compare Selfie to ID Photo

POST

https://api.botskyc.com

/v1/identity/face-match

Biometric comparison of selfie with ID document photo

Face Match - Compare Selfie to ID Photo › Request Body

selfie

string · binary · required

Selfie image

idDocument

string · binary · required

ID document image

Face Match - Compare Selfie to ID Photo › Responses

Face match result

Result of face comparison

similarity

number · min: 0 · max: 100 · required

is_match

boolean · required

confidence

number · min: 0 · max: 100

threshold

number

message

string

POST/v1/identity/face-match

curl --request POST \
  --url https://api.botskyc.com/v1/identity/face-match \
  --header 'Content-Type: application/json' \
  --data '
{
  "selfie": "selfie",
  "idDocument": "idDocument"
}
'

shell

Request Body Example

{
  "selfie": "selfie",
  "idDocument": "idDocument"
}

json

Health Document Processing