Upload images for use in an API-only transaction. Feedback on the uploaded image, such as whether Berbix was able to extract text from the image, will be provided in the response body in the issues
and issue_details
properties. If multiple values are present in issues
, the first should be treated as most important to address. The possible values that can appear in issues
are "bad_upload"
, "text_unreadable"
, "no_face_on_id_detected"
, "incomplete_barcode_detected"
, "unsupported_id_type"
, and "bad_selfie"
.
This endpoint requires a client_token
bearer token for authentication in the Authorization
header parameter: Authorization: Bearer <token>
. Because the client_token
is safe to pass client-side, this endpoint may be called from a browser or mobile app.
The transaction this image should be used for will be inferred from the client_token
used.
With the exception of selfie photos for templates with "Selfie With Liveness" enabled, the endpoint expects the images
property to contain a single-element array whose element which represents an image of a particular subject, e.g. the front of the ID document. The image_subject
expected by the first call to this endpoint for a particular transaction depends on the verifications you have enabled for a template. Unless you only have the "Barcode scan" verification enabled, the first call to this endpoint for a transaction must include a single element in images
with the image_subject
set to "document_front"
. That element should contain data for an image for the front of an ID document.
Selfie with Liveness mode requires that a "selfie_front"
, "selfie_left"
and "selfie_right"
be uploaded together in order to correctly process and will return an error if the incorrect number of types of images is submitted.
The next_step
returned will indicate what calls, if any, are expected next. The next_step
will be "upload_document_front"
if the image was low quality and the end user should be prompted to take another photo of the front of the ID document and that photo should be uploaded. The next_step
will be "upload_document_back"
if the next image the API expects is a back, meaning another call with an image_subject
of "document_back"
is expected. Subsequently, if another attempt at taking and uploading a photo of the back of the ID is expected, a next_step
of "upload_document_back"
will be returned. A next_step
of "done"
will be returned when no more images are required. A first_step
property is returned in the response from a call to the POST /v0/transactions
"create transaction" endpoint for API-only transactions. That first_step
value can be used to determine the first action to be taken for a transaction.
Note that we do not require a back image for all IDs. In particular Passport uploads do not require a back as only the photo page of the passport is used. In some circumstances if the id_type
is not known at transaction creation time and a passport is uploaded, we may erroneously ask for a document_back
. In these situations, submitting the Passport document image as submitted for document_front
will allow the transaction to proceed.
Special types of verification such as barcode only accept a "document_barcode"
image and will either return a next step of "done"
, or will fallback to requesting a "document_front"
and will do a full Photo ID verification if the barcode scan isn't successful. Following the Photo ID upload guide to upload "document_front"
and then "document_back"
will allow completing the verification. If no Photo IDs are available, abandoning the transaction is sufficient since it is not completable.
The total size of the request body may not exceed 10 MiB, and the total size of any image must not exceed 10MiB or 10,000 pixels in either direction.
Photos of military IDs or Social Security cards should not be uploaded. Callers should make sure to handle cases where "unsupported_id_type"
is in the list of issues
returned, which indicates Berbix detected an ID type that we cannot accept.