diff --git a/docs/hosted/id-bolt/callbacks.md b/docs/hosted/id-bolt/callbacks.md index a3162b1e..e0beb18a 100644 --- a/docs/hosted/id-bolt/callbacks.md +++ b/docs/hosted/id-bolt/callbacks.md @@ -143,6 +143,232 @@ In version 1.x, `images` has a different structure: | `cropped` | `string[]` | Cropped images of the ID in the order they were captured (only available when VIZ is scanned) | 1.0 | | `fullFrame` | `string[]` | Full frame images in the order they were captured | 1.0 | +## Raw Result Data + +The `mrzResult`, `vizResult`, and `barcodeResult` properties on `CapturedId` expose the raw data extracted from the Machine Readable Zone (MRZ), the Visual Inspection Zone (VIZ), and the barcode respectively. Each is `null` when the corresponding zone was not scanned or contained no data. Which of these results is populated depends on the document type and which sides were captured. + +All three result objects share a set of common fields, described below, and then add fields specific to their source. + +### Common Result Fields + +The following fields are common to `MrzResult`, `VizResult`, and `BarcodeResult`: + +| Property | Type | Description | Since | +| ---------------- | ------------------- | ------------------------------------------------- | ----- | +| `firstName` | `string \| null` | First name of the document holder | 1.6 | +| `lastName` | `string \| null` | Last name of the document holder | 1.6 | +| `fullName` | `string \| null` | Full name of the document holder | 1.6 | +| `sex` | `string \| null` | Sex/gender of the document holder | 1.6 | +| `nationality` | `string \| null` | Nationality of the document holder | 1.6 | +| `address` | `string \| null` | Address of the document holder | 1.6 | +| `documentNumber` | `string \| null` | Unique identifier assigned to the document | 1.6 | +| `dateOfBirth` | `DateResult \| null`| Date of birth of the document holder | 1.6 | +| `dateOfExpiry` | `DateResult \| null`| Expiration date of the document | 1.6 | +| `dateOfIssue` | `DateResult \| null`| Date when the document was issued | 1.6 | + +### MrzResult Object + +Raw data extracted from the Machine Readable Zone (MRZ). In addition to the [common fields](#common-result-fields), it contains: + +| Property | Type | Description | Since | +| -------------------------------- | -------------------- | ------------------------------------------------------------------- | ----- | +| `capturedMrz` | `string \| null` | The raw MRZ text as read from the document | 1.6 | +| `documentCode` | `string \| null` | Document code from the MRZ | 1.6 | +| `fullNameSimplifiedChinese` | `string \| null` | Full name in simplified Chinese, when present | 1.6 | +| `issuingAuthorityCode` | `string \| null` | Code of the authority that issued the document | 1.6 | +| `namesAreTruncated` | `boolean \| null` | Whether the names in the MRZ were truncated | 1.6 | +| `omittedCharacterCountInGbkName` | `number \| null` | Number of characters omitted from the GBK-encoded name | 1.6 | +| `omittedNameCount` | `number \| null` | Number of names omitted | 1.6 | +| `optionalDataInLine1` | `string \| null` | Optional data contained in the first MRZ line | 1.6 | +| `optionalDataInLine2` | `string \| null` | Optional data contained in the second MRZ line | 1.6 | +| `passportDateOfExpiry` | `DateResult \| null` | Expiration date of the passport (for documents attached to one) | 1.6 | +| `passportIssuerIso` | `string \| null` | ISO code of the passport issuer | 1.6 | +| `passportNumber` | `string \| null` | Passport number | 1.6 | +| `personalIdNumber` | `string \| null` | Personal identification number of the document holder | 1.6 | +| `renewalTimes` | `number \| null` | Number of times the document has been renewed | 1.6 | + +### VizResult Object + +Raw data extracted from the Visual Inspection Zone (VIZ). In addition to the [common fields](#common-result-fields), it contains: + +| Property | Type | Description | Since | +| ------------------------------ | ------------------------------- | -------------------------------------------------------------- | ----- | +| `additionalAddressInformation` | `string \| null` | Additional address information | 1.11 | +| `additionalNameInformation` | `string \| null` | Additional name information | 1.11 | +| `bloodType` | `string \| null` | Blood type of the document holder | 1.11 | +| `capturedSides` | `string \| null` | Which sides of the document were captured | 1.11 | +| `documentAdditionalNumber` | `string \| null` | Secondary identification number if present | 1.11 | +| `drivingLicenseDetails` | `DrivingLicenseDetails \| null` | Driving license details, when applicable | 1.11 | +| `employer` | `string \| null` | Employer of the document holder | 1.11 | +| `fathersName` | `string \| null` | Father's name of the document holder | 1.11 | +| `isBackSideCaptureSupported` | `boolean \| null` | Whether the back side of the document supports capture | 1.11 | +| `issuingAuthority` | `string \| null` | Authority that issued the document | 1.11 | +| `issuingJurisdiction` | `string \| null` | Jurisdiction that issued the document | 1.11 | +| `issuingJurisdictionIso` | `string \| null` | ISO code of the issuing jurisdiction | 1.11 | +| `maritalStatus` | `string \| null` | Marital status of the document holder | 1.11 | +| `mothersName` | `string \| null` | Mother's name of the document holder | 1.11 | +| `passportNumber` | `string \| null` | Passport number | 1.11 | +| `personalIdNumber` | `string \| null` | Personal identification number of the document holder | 1.11 | +| `placeOfBirth` | `string \| null` | Place of birth of the document holder | 1.11 | +| `profession` | `string \| null` | Profession of the document holder | 1.11 | +| `race` | `string \| null` | Race of the document holder | 1.11 | +| `religion` | `string \| null` | Religion of the document holder | 1.11 | +| `residentialStatus` | `string \| null` | Residential status of the document holder | 1.11 | +| `sponsor` | `string \| null` | Sponsor of the document holder | 1.11 | +| `usRealIdStatus` | `string \| null` | US Real ID compliance status | 1.11 | +| `vehicleOwner` | `string \| null` | Vehicle owner information | 1.11 | +| `visaNumber` | `string \| null` | Visa number | 1.11 | +| `visaDetails` | `VisaDetails \| null` | Visa details, when applicable | 1.11 | + +#### DrivingLicenseDetails Object + +| Property | Type | Description | Since | +| -------------------------- | --------------------------- | ----------------------------------------------- | ----- | +| `drivingLicenseCategories` | `DrivingLicenseCategory[]` | List of driving license categories | 1.11 | +| `restrictions` | `string \| null` | Driving restrictions | 1.11 | +| `endorsements` | `string \| null` | Driving endorsements | 1.11 | + +#### DrivingLicenseCategory Object + +| Property | Type | Description | Since | +| -------------- | -------------------- | ---------------------------------------- | ----- | +| `code` | `string` | Category code | 1.11 | +| `dateOfIssue` | `DateResult \| null` | Date the category was issued | 1.11 | +| `dateOfExpiry` | `DateResult \| null` | Date the category expires | 1.11 | + +#### VisaDetails Object + +| Property | Type | Description | Since | +| -------------------- | -------------------- | -------------------------------------------- | ----- | +| `fullName` | `string \| null` | Full name on the visa | 1.11 | +| `applicationStatus` | `string \| null` | Application status of the visa | 1.11 | +| `dateOfIssue` | `DateResult \| null` | Date the visa was issued | 1.11 | +| `durationInDays` | `number \| null` | Validity duration in days | 1.11 | +| `geographicValidity` | `string \| null` | Geographic validity of the visa | 1.11 | +| `issuingCountryIso` | `string \| null` | ISO code of the issuing country | 1.11 | +| `issuingAuthority` | `string \| null` | Authority that issued the visa | 1.11 | +| `multipleEntries` | `boolean` | Whether the visa allows multiple entries | 1.11 | +| `numberOfEntries` | `number \| null` | Number of allowed entries | 1.11 | +| `passportNumber` | `string \| null` | Passport number associated with the visa | 1.11 | +| `visaNumber` | `string \| null` | Visa number | 1.11 | +| `validFrom` | `DateResult \| null` | Date from which the visa is valid | 1.11 | +| `validUntil` | `DateResult \| null` | Date until which the visa is valid | 1.11 | +| `visaType` | `string \| null` | Type of visa | 1.11 | + +### BarcodeResult Object + +Raw data extracted from the barcode (for example, the PDF417 barcode on the back of US driver licenses). In addition to the [common fields](#common-result-fields), it contains: + +| Property | Type | Description | Since | +| ----------------------------------- | -------------------------------- | -------------------------------------------------------------- | ----- | +| `aamvaVersion` | `number \| null` | AAMVA specification version of the barcode | 2.1 | +| `aliasFamilyName` | `string \| null` | Alias family name | 2.1 | +| `aliasGivenName` | `string \| null` | Alias given name | 2.1 | +| `aliasSuffixName` | `string \| null` | Alias suffix name | 2.1 | +| `barcodeDataElements` | `Record` | Raw barcode data elements keyed by element identifier | 2.1 | +| `barcodeMetadata` | `BarcodeMetadata \| null` | Metadata about the barcode itself | 2.1 | +| `bloodType` | `string \| null` | Blood type of the document holder | 2.1 | +| `branchOfService` | `string \| null` | Branch of service (military documents) | 2.1 | +| `cardInstanceIdentifier` | `string \| null` | Card instance identifier | 2.1 | +| `cardRevisionDate` | `DateResult \| null` | Card revision date | 2.1 | +| `categories` | `string[]` | Document categories | 2.1 | +| `champusEffectiveDate` | `DateResult \| null` | CHAMPUS effective date | 2.1 | +| `champusExpiryDate` | `DateResult \| null` | CHAMPUS expiry date | 2.1 | +| `citizenshipStatus` | `string \| null` | Citizenship status | 2.1 | +| `civilianHealthCareFlagCode` | `string \| null` | Civilian health care flag code | 2.1 | +| `civilianHealthCareFlagDescription` | `string \| null` | Civilian health care flag description | 2.1 | +| `commissaryFlagCode` | `string \| null` | Commissary flag code | 2.1 | +| `commissaryFlagDescription` | `string \| null` | Commissary flag description | 2.1 | +| `countryOfBirth` | `string \| null` | Country of birth | 2.1 | +| `countryOfBirthIso` | `string \| null` | ISO code of the country of birth | 2.1 | +| `deersDependentSuffixCode` | `number \| null` | DEERS dependent suffix code | 2.1 | +| `deersDependentSuffixDescription` | `string \| null` | DEERS dependent suffix description | 2.1 | +| `directCareFlagCode` | `string \| null` | Direct care flag code | 2.1 | +| `directCareFlagDescription` | `string \| null` | Direct care flag description | 2.1 | +| `documentCopy` | `string \| null` | Document copy indicator | 2.1 | +| `documentDiscriminatorNumber` | `string \| null` | Document discriminator number | 2.1 | +| `driverNamePrefix` | `string \| null` | Driver name prefix | 2.1 | +| `driverNameSuffix` | `string \| null` | Driver name suffix | 2.1 | +| `driverRestrictionCodes` | `number[]` | Driver restriction codes | 2.1 | +| `ediPersonIdentifier` | `string \| null` | EDI person identifier | 2.1 | +| `endorsementsCode` | `string \| null` | Endorsements code | 2.1 | +| `exchangeFlagCode` | `string \| null` | Exchange flag code | 2.1 | +| `exchangeFlagDescription` | `string \| null` | Exchange flag description | 2.1 | +| `eyeColor` | `string \| null` | Eye color of the document holder | 2.1 | +| `familySequenceNumber` | `number \| null` | Family sequence number | 2.1 | +| `firstNameTruncation` | `string \| null` | First name truncation indicator | 2.1 | +| `firstNameWithoutMiddleName` | `string \| null` | First name without the middle name | 2.1 | +| `formNumber` | `string \| null` | Form number | 2.1 | +| `genevaConventionCategory` | `string \| null` | Geneva Convention category | 2.1 | +| `hairColor` | `string \| null` | Hair color of the document holder | 2.1 | +| `heightCm` | `number \| null` | Height in centimeters | 2.1 | +| `heightInch` | `number \| null` | Height in inches | 2.1 | +| `iin` | `string \| null` | Issuer identification number | 2.1 | +| `identificationType` | `string \| null` | Identification type | 2.1 | +| `isRealId` | `boolean \| null` | Whether the document is a US Real ID | 2.1 | +| `issuingJurisdiction` | `string \| null` | Jurisdiction that issued the document | 2.1 | +| `issuingJurisdictionIso` | `string \| null` | ISO code of the issuing jurisdiction | 2.1 | +| `jpegData` | `string \| null` | JPEG image data embedded in the barcode | 2.1 | +| `jurisdictionVersion` | `number \| null` | Jurisdiction version | 2.1 | +| `lastNameTruncation` | `string \| null` | Last name truncation indicator | 2.1 | +| `licenseCountryOfIssue` | `string \| null` | Country of issue of the license | 2.1 | +| `middleName` | `string \| null` | Middle name of the document holder | 2.1 | +| `middleNameTruncation` | `string \| null` | Middle name truncation indicator | 2.1 | +| `mwrFlagCode` | `string \| null` | MWR flag code | 2.1 | +| `mwrFlagDescription` | `string \| null` | MWR flag description | 2.1 | +| `payGrade` | `string \| null` | Pay grade | 2.1 | +| `payPlanCode` | `string \| null` | Pay plan code | 2.1 | +| `payPlanGradeCode` | `string \| null` | Pay plan grade code | 2.1 | +| `personDesignatorDocument` | `number \| null` | Person designator document | 2.1 | +| `personDesignatorTypeCode` | `string \| null` | Person designator type code | 2.1 | +| `personMiddleInitial` | `string \| null` | Person middle initial | 2.1 | +| `personalIdNumber` | `string \| null` | Personal identification number of the document holder | 2.1 | +| `personalIdNumberType` | `string \| null` | Type of personal identification number | 2.1 | +| `personnelCategoryCode` | `string \| null` | Personnel category code | 2.1 | +| `personnelEntitlementConditionType` | `string \| null` | Personnel entitlement condition type | 2.1 | +| `placeOfBirth` | `string \| null` | Place of birth of the document holder | 2.1 | +| `professionalDrivingPermit` | `ProfessionalDrivingPermit \| null` | Professional driving permit details | 2.1 | +| `race` | `string \| null` | Race of the document holder | 2.1 | +| `rank` | `string \| null` | Rank (military documents) | 2.1 | +| `relationshipCode` | `string \| null` | Relationship code | 2.1 | +| `relationshipDescription` | `string \| null` | Relationship description | 2.1 | +| `restrictionsCode` | `string \| null` | Restrictions code | 2.1 | +| `securityCode` | `string \| null` | Security code | 2.1 | +| `serviceCode` | `string \| null` | Service code | 2.1 | +| `sponsorFlag` | `string \| null` | Sponsor flag | 2.1 | +| `sponsorName` | `string \| null` | Sponsor name | 2.1 | +| `sponsorPersonDesignatorIdentifier` | `number \| null` | Sponsor person designator identifier | 2.1 | +| `statusCode` | `string \| null` | Status code | 2.1 | +| `statusCodeDescription` | `string \| null` | Status code description | 2.1 | +| `vehicleClass` | `string \| null` | Vehicle class | 2.1 | +| `vehicleRestrictions` | `VehicleRestriction[]` | Vehicle restrictions | 2.1 | +| `version` | `string \| null` | Barcode version | 2.1 | +| `weightKg` | `number \| null` | Weight in kilograms | 2.1 | +| `weightLbs` | `number \| null` | Weight in pounds | 2.1 | + +#### BarcodeMetadata Object + +| Property | Type | Description | Since | +| ----------------- | ---------------- | ------------------------------------ | ----- | +| `errorCorrection` | `number \| null` | Barcode error correction level | 2.1 | +| `moduleCountX` | `number \| null` | Number of barcode modules on the X axis | 2.1 | +| `moduleCountY` | `number \| null` | Number of barcode modules on the Y axis | 2.1 | + +#### ProfessionalDrivingPermit Object + +| Property | Type | Description | Since | +| -------------- | -------------------- | ------------------------------------ | ----- | +| `codes` | `string[]` | Professional driving permit codes | 2.1 | +| `dateOfExpiry` | `DateResult \| null` | Expiry date of the permit | 2.1 | + +#### VehicleRestriction Object + +| Property | Type | Description | Since | +| -------------------- | -------------------- | ------------------------------------ | ----- | +| `vehicleCode` | `string` | Vehicle code | 2.1 | +| `vehicleRestriction` | `string` | Vehicle restriction | 2.1 | +| `dateOfIssue` | `DateResult \| null` | Date the restriction was issued | 2.1 | + ## Example: Complete Callback Usage ```ts