Processing a document

This section provides details and examples of how to use the AssureID Connect API to process individual document data capture and authentication transactions. For specifics on using the C# wrapper and REST API interfaces, see the .NET Web SDK and REST API sections in this document. See the AssureID Connect Workflows for more information.

POST document instance

The document instance is created by posting the document instance and obtaining a document instance identifier. Rather than posting all document images, only the images that are required to classify the document (for example, identify the type of document) are posted. At a minimum, this is the white light source image of one side of the document, but may also include the white light source image of the reverse side of the document when images of both sides of the document have been captured.

Posting images typically requires the following distinct operations:

• Capture the image
• Compress the image
• Post (upload) the compressed image

These operations are largely independent and are constrained by different resource types, therefore they can be overlapped for significant performance gains. Image capture tends to be constrained by device I/O, image compression is CPU-driven, and the posting of the image is limited by network bandwidth. See Image Requirements and Recommendations for more information.

Note: Non-imaging data (such as magnetic stripe, machine readable zone) is very small compared to imaging data; therefore, it can be beneficial to post this information prior to initiating document classification provided that the data is already available. In some cases, this information can be used to speed up the classification process. If the data is not immediately available, it should be posted after classification has been completed.

Note: User-specific information for analysis and reporting may be included in the API header using the key “X-Customer-Data.” Doing so will return the same in the GetDocument response. Base64 encoding is recommended. It can include up to 4k worth of data. Header name and value obeys https://www.rfc-editor.org/rfc/rfc9110.html#name-fields.

Example Header: X-Customer-Data: bmF8QkY3UXw3MjQwNDUzYjdiMThiMWI2NDY0NzRmZTQwNGViYTI4Yg==

GET document classification

Getting the document classification will initiate the classification process within the service and return the results of the classification process, including document type, issuer, class, and series. It will also return which additional image types (such as nearinfrared and ultraviolet) are supported to allow for optimization of subsequent captures and transmission so that no images are unnecessarily transmitted.

During classification, the presentation of the document may also be determined. That is, if an image was posted as the front side of the document but is actually the back side of the document, the PresentationChanged property will indicate that the document presentation (for example, sides) were reversed during classification. If this occurs, all subsequent image posts must account for this presentation change.

For example, if a white/front image was posted for classification, but it classified as white/back, the remaining white image should be posted as white/front to properly account for the presentation change.

POST document image

All remaining images are then posted to the document instance.

GET image metrics

If requested, image metrics can be calculated on the images. This is recommended for mobile document capture.

The following metrics are available:

Metric	Description
GlareMetric	A value between 0 and 100 (a score of 50 and above is considered a pass). A null value will be returned if the image is below 512 x 512 pixels
HorizontalResolution	Horizontal resolution of the image
IsCropped	Indicates whether the image is cropped by the web service
IsTampered	Indicates whether the image has been tampered with
SharpnessMetric	A value between 0 and 100 (a score of 50 and above is considered a pass)
VerticalResolution	Vertical resolution of the image

PUT document image

An image can be updated using the document instance created in the POST document instance step. For example, if the image posted in the POST document image step fails the sharpness metric with a score of 40, then you should post a new image in the PUT document image step and then evaluate the image metrics on the updated image.

POST document data

Any non-imaging data that is to be included is posted to the document instance.

POST any non-imaging data

After all data is posted, the client checks and waits for the GET document classification operation to complete. After the operation is complete, the results can be retrieved. This operation will perform any remaining processing, including data capture and authentication that had not yet been performed on the server.

GET corrected image

During classification, AssureID Connect identifies the type of a document as well as its presentation and orientation. When posting images to AssureID Connect, one side of the document must be specified as the front, but this may not actually be the front of the document. If the PresentationChanged property has been set, this means that the presentation of the document has been corrected, indicating that the document was presented with the back side specified as the front side and vice versa. Orientation refers to whether the top edge of the document was at the top of the captured image. If the document was rotated to correct the orientation, the OrientationChanged property will be set. If either of these two properties are set, additional action may be required by the application to ensure that displayed images or images stored external to AssureID Connect reflect the corrected orientation and/or presentation.

To obtain images with corrected presentation and orientation, an application can retrieve each image from AssureID Connect, using the image URIs provided in the document result. It is also possible to retrieve images using the Web SDK.

Barcode-only mode

The Barcode enumeration was added to support 2D barcode-only read mode. It decodes and parses the barcode from an image of the back of a North American (U.S./Canada) ID. If a 2D barcode string is specified, any images are ignored. If 2D barcode string is not specified, AssureID will look first for a Front/White image, then a Back/White image. The first image from which it is able to extract a barcode will be the data processed.

Note: The AssureTec.AssureID.Web.SDK.Document returned by AssureID will include all data fields available in the 2D barcode. AssureID will not classify the document; therefore, the returned classification will be Unknown. No authentication tests will be run.

To process a barcode, use AssureTec.AssureID.Web.SDK.DocumentProcessMode.Barcode. To use this mode, callers must post either a parsed 2D barcode data string, or an image that contains a 2D barcode, for example:

POST /Document/Instance, DocumentSettings.ProcessMode.Barcode
POST /Document/{instanceId}/Data, DocumentDataType.Barcode2D, string
GET /Document/{instanceId}
(optional) DELETE /Document/{instanceId}

or

POST /Document/Instance, DocumentSettings.ProcessMode.Barcode
POST /Document/{instanceId}/Image, DocumentSide.Front|Back,
   LightSource.White, image
GET /Document/{instanceId}
(optional) DELETE /Document/{instanceId}