Transaction Fields

Transaction Fields returned by Berbix upon the successful completion of a transaction include data captured from the verified document and provided in the handoff process.

Fields are returned in the fields array of the Get transaction verifications response and are associated with Action Maps in the Berbix dashboard.

All Berbix customers have access to retrieve given_name, middle_name, family_name, id_type, id_issuer, email, and phone_number fields via API. Images are not included in our API responses by default.

Additional fields and images may be added upon request if they are necessary for your use case. Please reach out to [email protected] for more information.

Field Descriptions and Example Values

Included below are all possible field values that can be exposed via the API, their descriptions, and an example value.

Field NameDescriptionExample Value
address_cityThe city of the address collected in the flow.

Successful pdf417 barcode scan only
SAN FRANCISCO
address_countryThe country of the address collected in the flow.

Successful pdf417 barcode scan only
US
address_postal_codeThe postal code of the address collected in the flow.

Successful pdf417 barcode scan only
94114
address_streetThe street address collected in the flow.

Successful pdf417 barcode scan only
2338 MARKET ST
address_subdivisionThe subdivision of the address collected in the flow.

Successful pdf417 barcode scan only
CA
address_unitThe unit of the address collected in the flow.

Successful pdf417 barcode scan only
2A
ageThe age of the person completing the flow.30
date_of_birthThe date of birth of the person completing the flow.1989-12-12
email_addressThe email address for the user if provided when creating a handoff.[email protected]
family_nameThe family name (typically last) of the person completing the flow.DOE
given_nameThe given name (typically first) of the person completing the flow.JOHN
id_expiry_dateThe expiry date of the ID collected in the flow.2018-08-08
id_issue_dateThe issue date of the ID collected in the flow.2016-10-05
id_issuerThe issuer country (and subdivision when available) of the ID collected in the flow.

For more information on the ISO 3166-1 alpha-2 codes used here, refer to our ID issuer documentation.
US-CA
id_numberThe ID number of the ID collected in the flow.D999999
id_typeThe type of ID collected.

Possible values are ID, DL, P (passport), V (visa), PRC (permanent resident card), PC (passport card), or UNK (unknown).
DL
middle_nameThe middle name of the person completing the flow.RYAN
nationalityThe nationality of the person completing the flow.

Available when provided via national ID cards or passports.
US
phone_numberThe phone number of the user if provided when creating a handoff.+14155559999
sexThe sex of the person completing the flow.

Possible values are M, F, or X (non-binary).
M

📘

Missing data?

Our ability to return data depends on whether the data is present in the document or transaction.

Example 1: If the document indicates that the user does not have a middle name, we may return an empty string for middle_name.

Example 2: If we are unable to determine whether the user has a middle name due to image quality or ID format, we may omit the field ("middle_name": null).

Source Values

All verification fields include a source value to convey where the data was sourced from. fields.*.sources will be populated with at least one of the following values:

  • manual: sourced from data entered manually by the user when prompted to confirm or enter their basic details. A verification with manual data entry will always include the id_manual_entry flag.
  • mrz: sourced from a machine readable zone typically found on passports or other national ID cards.
  • ocr: sourced from human readable components typically found on the front of identity documents through optical character recognition.
  • pdf417: sourced from a PDF417 barcode typically found on the back of an AAMVA-compliant US or Canadian ID or DL.
  • handoff: denotes a phone_number or email for which a link has successfully been sent and clicked on.

Confidence Values

Although there are additional factors that may impact our confidence levels, they are generally determined by source.

  • high: Data was sourced from a machine readable component or confirmed through some other high-confidence means (e.g. a handoff link being accessed).
  • medium: Data was sourced from a human readable component.
  • low: Data was provided manually by the user.

Images

If you are reviewing transactions in the Berbix dashboard, the Transaction Report will include all images submitted by the user in the verification flow. You may click on an image to view any alternate or un-cropped images from that stage of the transaction and to reveal the image without watermarks. Please note that all instances of watermark removal are logged and subject to daily and monthly limits.

If you are retrieving transaction data via API, images are not included in the payload by default.

If appropriate for your use case, we may enable access to retrieve links to one or more of the following image types:

  • front_full
  • front_cropped
  • front_face
  • back_full
  • back_cropped
  • selfie_full
  • selfie_face
  • liveness_full
  • liveness_face

Although alternate images are available from the dashboard transaction report, images retrieved via API are limited to one linked image per image type. Each link is only valid for 10 minutes, but may be re-generated with a new call to fetch the transaction if needed.

📘

Best Practice

We recommend that integrations requiring front_cropped or back_cropped images for compliance purposes also retrieve the full versions of these images to be used as a fallback.