Expanded Document Fields

When data is extracted from an ID document through OCR, data is returned within a document fields object as detailed here.

In addition to document fields, an expanded set of fields can be returned, providing a full list of each extracted field, the source of the extraction, and any corresponding transliterated values.

The following transliterations are currently supported:

Cyrillic and Arabic families of languages
Chinese
Japanese
Korean
Vietnamese
Turkish languages

Configure Expanded Document Fields

Expanded fields are not returned by default. This must be added to the ID Document Text Extraction task.

For non-Latin documents, you must enable them separately; see here for guidance

new RequestedTextExtractionTaskBuilder()

.withCreateExpandedDocumentFields(true) // default is false

.build()

import com.yoti.api.client.ClassPathKeySource;

import com.yoti.api.client.docs.DocScanClient;

import com.yoti.api.client.docs.DocScanException;

import com.yoti.api.client.docs.session.create.CreateSessionResult;

import com.yoti.api.client.docs.session.create.SessionSpec;

import com.yoti.api.client.docs.session.create.task.RequestedIdDocTextExtractionTask;

...

DocScanClient docScanClient = DocScanClient.builder()

.withClientSdkId("YOTI_CLIENT_SDK_ID")

.withKeyPairSource(ClassPathKeySource.fromClasspath("/path/to/pem"))

.build();

RequestedIdDocTextExtractionTask idDocTextExtractionTask = RequestedIdDocTextExtractionTask.builder()

.withManualCheckFallback()

.withCreateExpandedDocumentFields(true)

.build();

SessionSpec sessionSpec = SessionSpec.builder()

POST /sessions

{

"client_session_token_ttl": 9000,

"requested_tasks": [

{

"type": "ID_DOCUMENT_TEXT_DATA_EXTRACTION",

"config": {

"manual_check": "NEVER",

"create_expanded_document_fields": true

}

"sdk_config": {

"allowed_capture_methods": "CAMERA_AND_UPLOAD",

"success_url": "https://www.yoti.com/",

"error_url": "https://www.yoti.com/error",

"allow_handoff": true

}

var textExtractionTask = new RequestedTextExtractionTaskBuilder()

.WithCreateExpandedDocumentFields

<?php

$textExtractionTask = (new RequestedTextExtractionTaskBuilder())

->withManualCheckFallback()

->withCreateExpandedDocumentFields(true)

->build();

Retrieving Expanded Document Fields

The expanded document fields object will not always be present. Expanded fields will only be available within the session when a document has been captured and the OCR (Optical character recognition) has been successful.

Data which is keyed in manually will not be returned in the expanded fields section, this will continue to be returned only within the standard document fields payload.

//Retrieve Expanded Document Fields Media ID,

idvClient.getSession(sessionId)

.then((session) => {

// Returns all resources in the session

const resources = session.getResources();

// Returns a collection of ID Documents

const idDocuments = resources.getIdDocuments();

idDocuments.map((idDocument) => {

const expandedFields = document.getExpandedDocumentFields()

const expandedFieldsMediaId = expandedFields.getMedia().getId();

});

// Retrieve data

idvClient.getMediaContent(sessionId, expandedFieldsMediaId).then(media => {

const buffer = media.getContent();

const jsonData = JSON.parse(buffer);

// handle jsonData here

GetSessionResult sessionResult = docScanClient.getSession(sessionId);

// Returns all resources in the session

ResourceContainer resources = sessionResult.getResources();

// Returns a collection of ID Documents

List<? extends IdDocumentResourceResponse> idDocuments = resources.getIdDocuments();

for (IdDocumentResourceResponse idDocument: idDocuments) {

// Gets the UUID of the document resource

String id = idDocument.getId();

// Returns document fields object

ExpandedDocumentFieldsResponse expandedDocumentFields = idDocument.getExpandedDocumentFields();

// Get document fields media id

String expandedDocumentFieldsMediaId = null;

if (documentFields != null) {

expandedDocumentFieldsMediaId = expandedDocumentFields.getMedia().getId();

GET /sessions/<session_id>

GetSessionResult sessionResult = docScanClient.GetSession(sessionId);

// Returns all resources in the session

ResourceContainer resources = sessionResult.Resources;

// Returns a collection of ID Documents

List<IdDocumentResourceResponse> idDocuments = resources.IdDocuments;

foreach (IdDocumentResourceResponse idDocument in idDocuments)

{

// Returns expanded document fields object

ExpandedDocumentFieldsResponse expandedDocumentFields = idDocument.ExpandedDocumentFields;

//Get expanded document fields media id

string expandedDocumentFieldsMediaId = null;

if (expandedDocumentFields != null)

{

expandedDocumentFieldsMediaId = expandedDocumentFields.Media.Id;

}

MediaValue media = docScanClient.GetMediaContent(sessionId, expandedDocumentFieldsMediaId);

<?php

$sessionResult = $docScanClient->getSession($sessionId);

// Returns all resources in the session

$resources = $sessionResult->getResources();

// Returns a collection of ID Documents

$idDocuments = $resources->getIdDocuments();

foreach ($idDocuments as $idDocument) {

// Returns expanded document fields object

$expandedDocumentFields = $idDocument->getExpandedDocumentFields();

// Get dexpanded document fields media id

$expandedDocumentFieldsMediaId;

if ($expandedDocumentFields) {

$expandedDocumentFieldsMediaId = $expandedDocumentFields->getMedia()->getId();

}

$media = $docScanClient->getMediaContent($sessionId, $expandedDocumentFieldsMediaId);

$data = json_decode($media->getContent());

Example Response

A JSON object will be returned when retrieving the expanded document fields media. Some documents will have multiple sources, eg a VIZ and a barcode. Fields that are in both sources will be returned separately with the source available in the response.

{

"fields": [

{

"name": "date_of_birth", //the name of the field

"value": "1970-01-01", //the contents of the field

"locale": "la", //the language/script the field is in on the document

"source": "VIZ" //where this field has been extracted from // VIZ || BARCODE || MRZ

"is_non_latin": true // if the field includes non-latin characters

"is_transliteration": true // if field is transliterated into latin script

{

"name": "full_name",

"value": "MELISSA PETERSON",

"locale": "la",

"source": "MRZ"

...

]

}

Values

Field	Description	Always present
name	The name of the field. A full list is available here	✅
value	The data from the document field	✅
locale	The locale of the field - for any latin script fields this will be "la", for non-latin script this will return the detailed locale eg "ja-JP" for Japan	✅
source	Where on the document this field has been returned, this can be VIZ, MRZ or BARCODE	✅
is_non_latin	This will be present and true if the field is in a non-latin script	❌
is_transliteration	We can transliterate some non-latin fields. This will return the values of the field into latin script	❌

Examples Document Extractions

See the code blocks below for examples of the Expanded Document Fields. The Document Fields JSON is also available at the bottom to compare.

You may use the following keyboard shortcuts to expand or collapse:

Expand: Ctrl + I

Collapse: Ctrl + Y

expandedDocumentFields

{…}

expandedDocumentFields:

{…}

expandedDocumentFields:

{

"fields": [

{

"name": "expiration_date",

"value": "2013-04-10",

"locale": "la",

"source": "VIZ"

{

"name": "date_of_issue",

"value": "2010-03-10",

"locale": "la",

"source": "VIZ"

{

"name": "issuing_country",

"value": "JPN",

"locale": "la",

"source": "VIZ"

{

"name": "date_of_birth",

"value": "1965-03-10",

"locale": "la",

"source": "VIZ"

{

"name": "document_number",

expandedDocumentFields

{

"fields": [

{

"name": "document_number",

"value": "320524197809086414",

"locale": "la",

"source": "VIZ"

{

"name": "date_of_issue",

"value": "2004-06-17",

"locale": "la",

"source": "VIZ"

{

"name": "issuing_country",

"value": "CHN",

"locale": "la",

"source": "VIZ"

{

"name": "gender",

"value": "MALE",

"locale": "la",

"source": "VIZ"

{

"name": "date_of_birth",

Last updated on

Was this page helpful?