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
: passportDL
: drivers licencePRC
: permanent resident cardPC
: passport cardID
: 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 forissues
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 adocument_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 thedocument_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.
Updated 3 months ago