Biometric Identification Service (BIS Plus)

POST

  https://api.apptenticate.com/api/v3/biometrics/nationals/

Authentication

Use your JWT obtained from the authentication process to make requests to this endpoint.

The response will be 401 unauthorized if the JWT has expired. In such case, you should obtain a new JWT.

---

This endpoint handles all requests directed to the SIB Biometric microservice, which allows biometric verification of Panamanian citizens. These requests must contain at least two parameters: the citizen's ID card and a .jpg image of their face. Ultimately, the Electoral Tribunal service will respond whether this face matches the provided ID card.

NOTE

• The response may be 401 unauthorized if the JWT token needs to be refreshed.

• The image sent in jpg format must not exceed 2MB.

• If you wish to receive the transaction ID in the response, you must specify "return_id": "True" in the request JSON.

• If you want to improve the accuracy of the proof of life (if this service is contracted), you must specify the device type in the request JSON. These can be "DESKTOP", "IOS", or "ANDROID", and the way to specify it would be "device":"IOS", for example.

Request Structure - method: POST

Path: api/biometrics/nationals/

• Base request payload:

Payload: {
    'citizen_id':'Citizen's ID',
    'selfie': image
} // (where the image is a .jpg file)

• If you want to get the transaction ID:

Payload: {
    'return_id':True,
    'citizen_id':'Citizen's ID',
    'selfie': image
} // (where the image is a .jpg file)

• If you want to improve the accuracy of the proof of life:

Payload: {
    'citizen_id':'Citizen's ID',
    'device':'IOS', // Devices: IOS, ANDROID, or DESKTOP
    'selfie': image
} // (where the image is a .jpg file)

Request Examples

Python

# JWT Token
header = { 'Authorization': 'Bearer {}'.format(token) }

# Base request payload
data = { 'citizen_id': 'Citizen's ID'}
files = { 'selfie': image } # Where the image is a .jpg file

# If you want to get the transaction ID:
data = { 'return_id': True,'citizen_id': 'Citizen's ID' }
files = { 'selfie': image } # Where the image is a .jpg file

# If you want to improve the accuracy of the proof of life
data = { 'citizen_id': 'Citizen's ID', 'device':'IOS' }

# Devices: IOS, ANDROID, or DESKTOP
files = { 'selfie': image } # Where the image is a .jpg file

# Sending request
response = requests.post(
    apptenticate_url,
    data=data,
    files=files,
    headers=header
)
response = json.loads(response.content)

Response Structure

Response format: JSON

• Base Response:

Response: {
    "valid": True or False, // Boolean determining if the request resulted in a successful validation or not
    "error": "String with brief description of the error",
    "error_code": error code (int)
    "details": "A string specifying the error, or a key-value pair detailing if any of the parameters are invalid and the error",
    "citizen_id": "Citizen's ID",
    "first_names": "Citizen's first names",
    "last_names": "Citizen's last names",
    "gender": "Citizen's gender",
    "place_of_birth": "Citizen's place of birth" (str),
    "date_of_birth": "Citizen's date of birth" (str),
    "date_of_request": "Date of ID card request" (str),
    "expiration_date": "ID card expiration date" (str),
    "signature": "Image of the citizen's signature as it appears on the ID card" (base64),
}

In addition to the response, the corresponding status code for the operation outcome is sent.

• Response with Transaction ID:

Response format: JSON

Response: {
    "valid": True or False, // Boolean determining if the request resulted in a successful validation or not
    "error": "String with brief description of the error",
    "details": "A string specifying the error, or a key-value pair detailing if any of the parameters are invalid and the error",
    "error_code": error code (int),
    "id": transaction number (int),
    "citizen_id": "Citizen's ID",
    "first_names": "Citizen's first names",
    "last_names": "Citizen's last names",
    "gender": "Citizen's gender",
    "place_of_birth": "Citizen's place of birth" (str),
    "date_of_birth": "Citizen's date of birth" (str),
    "date_of_request": "Date of ID card request" (str),
    "expiration_date": "ID card expiration date" (str),
    "signature": "Image of the citizen's signature as it appears on the ID card" (base64),
}

Rejection Codes

Code	Message
601	Operator does not exist in the database.
602	Citizen is under 12 years of age.
603	Citizen is deceased.
604	Citizen with invalid registration.
605	Unrecognized citizen.
606	ID field comes blank.
607	Citizen not found.
608	No SIB access is available for this client.
610	General facial validation error.
611	No image was sent for comparison.
612	Image has no content.
613	Invalid image format.
614	No face detected in the image.
615	Similarity threshold not reached.