API-Only 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.

Please note that an API-only 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-level accounts. Existing customers can contact our Solutions Engineering team ([email protected]) for access to these API endpoints.

Creating a Transaction

Creating a transaction via our API-only flow utilizes the same steps described in Create a Transaction, but includes additional api_only_options parameters to provide id_country and id_type if known.

id_country: The 2-letter country code (ISO 3166-1 alpha-2) for the country that has issued the ID. We have listed potential values here for your convenience.
id_type: The type of the ID to be verified.
- P: passport
- DL: drivers licence
- PRC: permanent resident card
- PC: passport card
- ID: catchall for non-driver IDs and other types of ID cards

📘
Template Key
Make sure you're using the Template Key for an API-Only template. If you don't have access to API-Only templates yet, please reach out to [email protected] for next steps.

When api_only_options are provided in a POST /v0/transactions "create transaction" endpoint, a first_step property is included in the response payload. The first_step value can be used to determine the first action that will be taken for the transaction.

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.

🚧
Getting an Error?
API-Only support is still in early access, and may not yet be available for the Berbix API library you are using.
If you don't see specific instructions for API-Only transactions in the README.md documentation, reach out to us via Slack for next steps.

Uploading ID Data

Once a transaction has been created, ID data can be uploaded to Berbix. In most cases, this will be images, but may also include data from a scanned barcode.

Image Upload

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

❗️
U.S. Restrictions
Due to legal restrictions Berbix does not accept images of United States military ID cards or Social Security cards.
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.

Image Requirements for all image uploads:

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

Best Practice: Keep all images under 10MB and use JPEG file types for optimal performance.

The images must be provided sequentially as determined by your selected template, starting with the first_step provided on transaction creation.

For example, a typical transaction requiring front, back, and selfie/liveness would require images in the following order:

Front: document_front
Back: document_back

Barcode Scan

If your workflow implements barcode scanning hardware, enable the Barcode Scan setting in your API-Only template.

Instead of uploading images, you'll use the ID scan upload endpoint to provide the raw data captured by the scanner hardware.

❗️
What about Selfie and Liveness steps?
In order to mitigate risks associated with recent trends in biometrics privacy litigation, we are not currently offering API-based selfie matching functionality.

Upload Responses

The response returned by the API will contain any issues with the upload and the next_step for you to proceed.

Issues

The issues provided in the API response can be used to inform whether the image is high quality or whether we detected immediate issues that will impact a transaction.

If multiple values are present, the first should be treated as most important to address.

The following values can be returned in the issues list:

Issue	Description
`text_unreadable`	The text on the ID could not be read. May indicate that the photo is blurry.
`no_face_on_id_detected`	Berbix expected a photo of a face in the uploaded ID image, but did not find one.
`incomplete_barcode_detected`	Either no barcode could be detected, or the barcode appears incomplete. This may also be returned if a `document_back` image is blurry from motion, lighting, or print quality and cannot be fully parsed.
`unsupported_id_type`	An ID type we cannot accept was detected in the image. The `issue_details` may provide more detailed information.
`bad_upload`	A generic catch-all for errors that don't fit into other issue types.

In some cases, additional information on the issue(s) detected may be present in the issue_details, such as visa_page_of_passport if the visa page of a passport was uploaded, rather than the ID page.

We recommend using the issues above to design frontend feedback for your end-users to guide them through the flow and prompt them to re-try if issues are detected. You can check out our Advanced SDK options for guidance.

📘
Empty array for issues
The Berbix API will return an empty array[] result for issues in two scenarios:

No issues were detected

The user has exhausted their retry attempts for the current step, and will need to move on to the next step in the flow regardless of any issues detected.

If you are unsure how many retry attempts are permitted in your template, please reach out to [email protected].

Next Step

The next_step is intelligently determined by the template, ID type, and detected issues.

For example, if we returned text_unreadable for an image of the ID front, we would present upload_document_front as the next_step to allow the user to retry the current step.

Possible next_step values:

upload_document_front
upload_document_back
done

Proceed through each step of the upload process 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.

Possible next_step edge case scenarios may include:

If we cannot parse data sent by a barcode scanner, the next_step may fall back to requesting a document_front and proceed through a full ID verification. If no photos are available, abandoning the transaction is sufficient.
When the ID type is P for passport, we automatically skip the document back upload step. However if the ID type is unknown when the transaction is created and a passport is uploaded, we may still ask for the document_back. In these situations, submitting the Passport document image as submitted for document_front will allow the transaction to proceed.
After the transaction has been completed, no additional images or scans may be uploaded. If the user needs to be re-verified or if the verification needs to be re-attempted with new images, a new transaction must be created with the same customer_uid.

Example

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

To try this yourself and to review all possible return values, check out our API documentation.

curl -XPOST "https://api.berbix.com/v0/images/upload" \
-H "Authorization: Bearer <client_token>" \
-d '{ "images": [{
   "image_subject":"document_front",
   "format":"image/jpeg",
   "data":<base64_encoded_image>
}]}'

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 should be stored to avoid unnecessary API calls.

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