API-Only Integration Guide

API Only Transactions Integration Guide

This integration guide will take you through the process of getting up and running with an API-only Berbix integration. This integration path is ideal for customers who want to customize the user experience beyond what’s available in our frontend SDKs and Themes. If you’re not sure whether this integration path is the right one for you, feel free to reach out and we’d be happy to advise on the various integration options for working with Berbix. Please note that this integration is not compatible with Berbix’s Hosted Links or frontend; the full scope of the API integration is described below.

This feature is currently only available to Enterprise/Managed accounts. Existing customers can contact our Solutions Engineering team ([email protected]) for access to these API endpoints.

Creating a Transaction

Berbix’s verification flow centers around Transactions, which are sets of images designed to verify an individual user. A unique Transaction should be created for each user and for each new verification attempt.

Creating a transaction via our backend-only flow utilizes the same steps described in Create a Transaction, with the inclusion of the values described below.

An additional api_only_options parameter is required for this API call in order to create an API-Only transaction. These options are used to specify input such as id_type and id_country if known. See the API docs Upload an image for more info on the parameters and an example.

The access_token, client_token, and refresh_token provided in the response payload will be used for subsequent API calls and ID photo uploads. You should store and manage these values on a transaction-level within your database.

Uploading Photos

Once you’ve created a Transaction, you can then proceed to upload images for that user. Note that the images should be provided sequentially (first front of ID, then back of ID, then selfie/liveness). For liveness uploads, the API expects three selfie images in a single request for the user facing left, right, and directly at the camera. In all other cases, images should be provided one at a time. We will provide feedback at each step of the process so you can optionally provide better photos if the first is not able to be fully processed (this will be indicated by the next_step value). For example, you may wish to design a frontend image capture flow that submits an image then re-prompts the user for a better image if the first one didn’t pass. You should proceed through each step of the upload process (the scope of which will be determined based on your Template configuration) until the next_step value indicates that the Transaction is complete. Stopping the upload process or attempting to request results prior will result in Transaction results being unavailable.

The /v0/images/upload API will allow you to upload relevant ID images for a Transaction based on the ID type and Template configuration.

Image Requirements for all image uploads:

  • JPEG or PNG (Contact us if your images are in a different format)
  • Must be smaller than 10MB
  • Must be smaller than 10,000 x 10,000 pixels

When using a Template that has Barcode Scan enabled, start by uploading a document_back image. Otherwise, start by uploading a document_front image. The ImageUploadResponse returned by the API will contain a list of issues with the upload (such as text_unreadable) as well as the next_step for you to proceed (either a re-attempt of the step with another image, uploading an image for a subsequent step, or moving on to request results of the completed transaction). In some cases, additional information on the issue(s) detected may be present in the issue_details.

Special considerations are required to enable selfie verifications for an API integration. Please contact us for assistance.

The issues provided in each response can be used to inform whether the image is high quality or whether we detected immediate issues that will impact a transaction. The unsupported_id_type issue will indicate that Berbix believes that the image is of an unsupported ID type and an image of another ID type should be uploaded if possible.

The next_step will contain an enum about which document is required next or whether the transaction is done and results can be fetched.


The following values can appear in the issues list returned:




The text on the ID could not be read. May indicate that the photo is blurry.


Berbix expected to be able to find a photo of a face on the ID document in the uploaded image, but did not find one.


Either no barcode could be detected, or the barcode appears incomplete.


An ID type we cannot accept was detected in the image. The issue_details may provide more detailed information if this issue is present. See the documentation for the image upload endpoint.


Berbix was unable to verify the uploaded selfie image, and another selfie should be uploaded.


A generic catch-all for errors that don't fit into other issue types.


Here is an example using curl and our API clients for the /images/upload API to upload an image.

See the API docs for more detailed examples and info on all the possible return values.

curl -XPOST "https://api.berbix.com/v0/images/upload" \
-H "Authorization: Bearer <client_token>" \
-d '{ "images": [{

Requesting Transaction Results

Once you’ve submitted all images for a Transaction, you can then proceed to request the results via Get Transaction Verifications. Results for completed transactions can be stored to avoid unnecessary API calls. Note that if based on Transaction results you want to re-verify the user or re-attempt a verification with new images, you will need to create a new Transaction (using the same customer_id). You can not upload additional images once a transaction has been completed.


API Only transactions are available on an early access basis and APIs and features may be subject to change.