Authenticate Document Endpoint

Method and URL Details

The URL for this multipart API call is fixed, and there are no path parameters passed through this endpoint.  For AuthenticateDocument to work, submit all Document images as multipart form data with the Keys described in the request parameter table below.

HTTP Method URL
POST
Copy 
https://[URL]/AirApi/2.0/AuthenticateDocument
Note:

Recommendations for AutoCrop:

  • Submit cropped images whenever possible and set AutoCrop to False.

  • For a correct Document crop; crop without any extra background.

  • For uncropped images; set AutoCrop to True.

Header Parameters

Use Authenticate request headers for all Document types by submitting the following header parameters: SecretToken, AccountAccess Key, RequestIdentifier, DeviceType, DocumentType or DocumentID, DeviceDetails, AutoCrop, getImages, senderIPAddress, and Orientation.

AuthenticateDocument response allows you to add custom headers related to the specific customer and submitted Document. The API response returns all additional custom headers.

Note:

Recommendations for Custom Header data:

  • Use getTransactionInfo API as an optional method to retrieve AuthenticateDocument response including custom header data if needed after the fact.

Copy 
"ApiRequestHeaders": {
    "CONTENT-LENGTH": "322164",
    "DOCUMENTTYPE": "License",
    "HOST": "rest-api",
    "RAW-REQUEST-URI": "/AirApi/2.0/AuthenticateDocument/",
    "REMOTE-ADDRESS": "126.0.0.x:xxxxx",
    "TIMEOUT-ACCESS": "<function1>",
    "TLS-SESSION-INFO": "Session(1623894073064|SSL_NULL_WITH_NULL_NULL)",
    "USER-AGENT": "PostmanRuntime/7.28.0",
    "X-B3-PARENTSPANID": "2453975th4tfhb556",
    "X-B3-SAMPLED": "0",
    "X-B3-SPANID": "s3975239d234b9883",
    "X-B3-TRACEID": "0670lauy25gg2cc4rt2644soo3399g8ji",
    "X-ENVOY-ATTEMPT-COUNT": "1",
    "X-ENVOY-EXTERNAL-ADDRESS": "93.55.xxx.xxx",
    "X-FORWARDED-CLIENT-CERT": "By=spiffe://cluster.local/ns/core/sa/rest-api;Hash=93f85eff578c2798dea750f514875d2de163cba24ed1cafcfff6170ab0be7b70;Subject=\"\";URI=spiffe://cluster.local/ns/core/sa/firewall",
    "X-FORWARDED-FOR": "93.55.xxx.xxx",
    "X-FORWARDED-PROTO": "https",
    "X-REQUEST-ID": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},

Request Header Parameters

Parameter Name Type Description

AutoCrop

Recommended

boolean

Submit cropped images whenever possible. AutoCrop is a boolean indicating whether the document will be automatically cropped on IDV servers. Cropping is the removal of borders around the ID Document.

  • When set to False, AutoCrop is disabled.

    • Set AutoCrop to False when capturing with a Native iOS or Android device when cropping the ID is already performed on the device.

  • When set to True, AutoCrop is enabled.

    • Set to True where AutoCrop is not performed on the device.

Default: False

Note: We recommend setting this to False. Ensure and align this setting with the mobile app developers on where image cropping is performed.

DocumentType

Required

string

This indicates the submitted Document type.

  1. Set to License; For all non-Passport Documents. Any card that is the shape of a credit card is considered a License. The Passport Card is a License because of its card form factor.

  2. Set to Passport; For all Passports of Visa Documents.

  3. Set to GreenID; For legacy Greenbook common in South Africa (This is not a standard Document).

Default: Licence

transactionInformation

Recommended

string

Allows custom data to be submitted. Some customers using the technology in a store/branch may want to track the employee submitting the ID.  They will insert the employee ID into a custom field.

Example:

  • {EmployeeId:12345}

  • A comma is used to separate multiple custom headers, I.e. {EmployeeId: 12345, StoreNumber: 9876}

Accept

Optional

boolean

This contains information about accepting consent for the ID capture process.

Default: application/JSON

getlmages

Optional

boolean

Customers only set this to True if they want to take the base64 string and use the photo in a subsequent internal system. This is typically set to False. 

  • When set to True, the headshot base64 string is returned.

  • When set to False, the headshot base64 string is not returned.

Example: Some banks insert the photo into the customer profile systems.

Default: True

Location

Optional

string

This always sends an exact location code. If the wrong location is sent, an error occurs. The location code is also referred to as an Account code. The code is used to differentiate between sub-accounts within a merchant account. Your implementation manager can provide this code.

Note: Exclude parameters unless your stakeholder has elected to use multiple decision models in IDE.

Default: Configured for the Merchant in IDE.

Orientation

Optional

 

   This indicates if the Document orientation is in landscape or portrait. Orientation is for submitted ID3 Documents only (Passport, Visa).

  • Landscape: Indicates the Document was captured horizontally.

  • Portrait: Indicates the Document was captured vertically.

Default: Landscape

PerformOrientationCorrection

Optional

 

 boolean

  • When set to True, this corrects the document's orientation based on the face image present on the document.

  • When set to False, this is disabled.

Default: False

RequestIdentifier

Optional

string A unique ID is controlled and generated by the customer for identifying the transaction.

RequestIdentifierType

Optional

string This is the type of unique ID requested.

senderIPAddress

string

IP Address of the request where it originated.

TransactionHistory

Optional

 

string

TransactionHistory links transactions together in the Decision Engine. For the first transaction submitted, this is either blank or not returned. TransactionHistory is required when a ReCapture is in process.

  • Insert the prior TransactionId into this field before submitting. Notdoing this will result in each Recapture transaction being billable.

  • If the Decision Engine requires a Recapture of the transaction, insert the prior TransactionId into the Recapture transaction and repeat this process.

    Important: A maximum of three recapture attempts are permitted contractually. The API workflow must have a capture counter, and when a maximum of three is met, then set this value to blank or do not include, this forces a new cycle.

UID

Optional

string

This is a user identifier Merchant configurable string. UID helps you correlate transactions to your internal systems.

captureSource

Optional

string

Possible values:

  • Web - Indicated that the source is coming from a web browser.

  • iOS - Indicates that the source is coming from an iOS mobile device.

  • Android - Indicates that the source is coming from an Android mobile device.

Default: Taken based on XMP

Deletion Protocol Parameters

These are headers used when deletion protocols are executed in DQL.

Parameter Name Type Description

TransactingState

 

Optional (Merchant Defined)

string

This is used to indicate the geographic location of where the transaction is being executed. This is determined by the Merchant’s app (We do not use GPS to determine this).

Note:

TransactingState is required if the customer wants to delete data based on the geographic location of the transaction.

We strongly recommend using the 2 letter code or you may see functionality not working as expected expressing the state name. State 2 letter code example: “WA”.

-Insert using transactionInformation header

(Any Transaction)

IssuingState

Optional (Merchant Defined)

 string

This represents the end customer’s identification of the issuer for the Document they are submitting. This is only used if you want two ways of identifying the issuer (End-user and IDV classification). This is only used for Deletion Rules execution and is not a requirement to use the deletion. If this is left blank, then we rely on the IDV classifications or Deletion rules.

Note: We strongly recommend using the 2 letter code or you may see functionality not working as expected expressing the state name. State 2 letter code example: “WA”.

-Insert using transactionInformation header

(Any Transaction)

Custom Header Parameters

Custom headers can be used for specific customers and submitted documents.

Parameter Name Type Description

FrontEndTransactionId 

 

Optional (Merchant Defined)

string

This is a unique Merchant code inserted by the Merchant into the transaction. It generally is used as the Key of mapping the JSON to the customers systems using this unique Id for the transaction. This is not used in decision-making.

-Insert using transactionInformation header
TransactionType

Optional (Merchant Defined)

 string

This is used by customers to typically indicate if the transaction is for a new customer or existing customer or used to describe the nature of the transaction. This is sometimes used in decision-making.

-Insert using transactionInformation header

Default: New Account and Existing Account

LocationNumber

Optional (Merchant Defined)

string

Represents the unique identifier for stores, branches, or the physical locations where the transaction is originating. This is configured for the Merchant in IDE.

-Insert using transactionInformation header

LocationCity

Optional (Merchant Defined)

string

These represent the physical address of the location where the transaction is being submitted. This is generally only used for face-to-face interaction where the end-user is submitting their ID in the presence of a Customer Representative.

-Insert using transactionInformation header

(Face To Face Submissions)

LocationState

Optional (Merchant Defined)

string

These represent the physical address of the location where the transaction is being submitted. This is generally only used for face-to-face interaction where the end-user is submitting their ID in the presence of a Customer Representative.

-Insert using transactionInformation header

(Face To Face Submissions)

LocationPostalCode

Optional (Merchant Defined)

string

These represent the physical address of the location where the transaction is being submitted. This is generally only used for face-to-face interaction where the end-user is submitting their ID in the presence of a Customer Representative.

-Insert using transactionInformation header

(Face To Face Submissions)

LocationFullAddress

Optional (Merchant Defined)

 

These represent the physical address of the location where the transaction is being submitted. This is generally only used for face-to-face interaction where the end-user is submitting their ID in the presence of a Customer Representative.

-Insert using transactionInformation header.

(Face To Face Submissions)

LocationAddressLine1

Optional (Merchant Defined)

string

These represent the physical address of the location where the transaction is being submitted. This is generally only used for face-to-face interaction where the end-user is submitting their ID in the presence of a Customer Representative.

Insert using transactionInformation header.

(Face To Face Submissions)

LocationAddressLine2

Optional (Merchant Defined)

string

These represent the physical address of the location where the transaction is being submitted. This is generally only used for face-to-face interaction where the end-user is submitting their ID in the presence of a Customer Representative.

Insert using transactionInformation header.

(Face To Face Submissions)

OtherCode1

Optional

object

This is usable by the Merchants to set other codes that will be useful to them. For example, some Customers will use dealerCodes.

Insert using transactionInformation header.

(Any Transaction)

OtherCode2

Optional

object

This is usable by the Merchants to set other codes that will be useful to them. For example, some Customers will use regionCodes.

Insert using transactionInformation header.

(Any Transaction)

DealerCode

Optional (Merchant Defined)

object

This represents the ID of the user capturing the transactions. Only include if decision using this is required or if the Merchant collects this for informational purposes.

Insert using transactionInformation header.

(Any Transaction)

EmployeeId

Optional (Merchant Defined)

object

This represents the ID of the user capturing the transactions. Only include if decision using this is required or if the Merchant collects this for informational purposes.

Insert using transactionInformation header.

(Face to Face submissions)

UID

Optional

object

This is a user identifier Merchant configurable string. UID helps you correlate transactions to your internal systems.

Example: Some customers use telephone numbers, billable account numbers or the customer’s user identifier number.

Insert using transactionInformation header.

(Any Transaction)

Body Parameters

Following parameters must be set in the multipart POST request.

Request Body Parameters

Parameter Name Type Description

Front

Required

object

  • If DocumentType = License, then required.

  • If DocumentType = Passport, then required.

  • If DocumentType = GreenId, then required.

Format = JPEG representation of the front side of the Document.

FrontFlash

Optional

boolean

Only submit if an image taken with a flash is captured. Refer to the Application developers on whether the images are generated.

All DocumentTypes = submit if captured.

Format = JPEG representation of the front side of the Document.

Back

Optional

object

  • If DocumentType = License, then not required.

    • Recommended if you want to generate barcode data.

  • If DocumentType = Passport then not required.

  • If DocumentType = GreenId, then not Required.

Format = JPEG representation of the backside of the Document.

BackFlash

Optional

boolean

See front flash. 

Response Body Parameters

The table below explains the response parameters and values of AuthenticateDocument.

Parameter Name Type Description

ApiRequestHeaders

 

object

Displays all the request parameters sent in the request headers with values.

ProcessingTimeInMilliSeconds

 

number

Displays the time taken to process the Authentication in milliseconds.

MerchantID

 

string

Displays the unique ID of a Merchant.

DocumentRiskConditions

object

See the DocumentRiskConditions section below.

DocumentImages

 

object

Displays the base64 representation of the captured Document images.

AccessKey

 

string

Displays the unique Accesskey used to authenticate the Documents.

ApiVersion

 

string

Displays the API version used to authenticate the Documents.

TransactionId

 

string

A system generated a unique Id for this transaction. This TransactionId can be used to retrieve a transaction in the future. For more information, please refer toGet Transaction Info API.

TransactionDate

 

date

This indicates the transaction date when the transaction is complete.

Description

 

string

This displays the error in case of a failed transaction. For successful transactions, the description is empty.

DocumentId

string

This is a unique Id identifying the actual Document images submitted. No DocumentIdis generated if the transaction failed due to invalid /license expiration/session expired, etc.

ActionCodes

 

object

This determines the action code (code) assigned to the segment name. For example, a segment result of Verified is assigned action code 99.

ActionCodes.actionMessage

 

string

This determines the actionMessage, which describes the type of action to be taken. This is an optional method to assign a message string associated with the action code for possible display to the consumer. The actual message text is determined by the customer.

SegmentName

 

string

This is the name of the segment to which the transaction has been assigned. E.g. Verified or ReCapture, Failed, etc.

SegmentUiSettings

 

string

This is the color of the segment to which the transaction has been assigned.

MatchedSegmentAlgorithms

 

array

This JSON object contains the names of algorithms configured, which are responsible for mapping the transaction to the segment assigned.

DQL Mapping Key-Value Pairs

This is a collection of our default Key-Value pairs that return the Final Document results from our Decisions Engine. The DQL_Final result is the final and best result used after processing. When the data is processed, it is cleaned up and then decisioned as the DQL_Final.

The table below gives the Keys name and description. The Key-Values returned are dependent on the Merchant configuration. If a Key-Value return is null, the field is likely missing, not returned, or not required.

Key-Value Type Description

SegmentName

string

This is the decisioned transaction result.

ActionCodes

string

This determines the action code (code) assigned to the segment name. For example, a segment result of Verified is assigned action code 99.

Example: This is a predefined message to cue the user to take a specific action.

code

string

This is the label/name used to differentiate between Action codes.

TransactionDate

string

This indicates the transaction date when the transaction is complete.

TransactionId

string

A system generated a unique Id for this transaction. This TransactionId can be used to retrieve a transaction in the future.

Analysis_Classification_DocumentClassName

string

This is the Class of documents. DL, ID, Passport, etc. The classification determines the type of document and which determines all subsequent thresholds. If there is no value determined, it defaults to the ID card.

Analysis_Classification_DocumentIssuerCode

string

This is always a two-digit code indicating the state or province. This is only returned for state-issued documents (not federal).

Analysis_Classification_DocumentIssuerCountryCode

string

This is who issued the document. This is the country code, typically a five-digit code such as USAUS.

The first three digits represent the country; US, CAN, MEX, etc. The digits in 4 and 5 positions represent the two-digit country code equivalent.

Analysis_Classification_DocumentName

string

This is a more detailed classification of the document than the name summary.

Analysis_Classification_DocumentSeries

string

This is the year the ID template was first used by the issuing authority. This is not the individual issue date for the document.

Analysis_Classification_IssuerName

string

This is the Issuer Code/Name from where the document was issued.

Analysis_Classification_Type

string

This is the classification type of the document.

Analysis_DPI_Range

string

This is the DPI range of the submitted document image.

Analysis_PII_Source

string

This is the description of where the PII was extracted.

Analysis_Result_API_TransactionDate

string

This is the date of document submission.

DQL_ActionCode

string

Link to the action code to get the final PII data. Never link to the Segment Name as part of your decisioning. The segment name is only the English translation.

conclusion = action code.

DQL_IDE_Capture_Quality_Result

string

This is the Capture quality result score determined by the capture quality algorithms. This will result in a capture quality threshold score to determine a pass, fail, inconclusive, or disabled segment result.

DQL_IDE_Capture_Spoof_Result

string

This is the capture spoof result score determined by capture spook algorithms.  This will result in a pass, fail, inconclusive, or disabled segment result.

DQL_IDE_ExpiredID_Result

string

This result returns a value only when a document has expired.

DQL_Final_FullName_Result

string

The final result after the front/back/MRZ  document has been analyzed.

DQL_Final_GivenName_Result

string

The final result after the front/back/MRZ  document has been analyzed.

DQL_Final_FirstName_Result

string

The final result after the front/back/MRZ  document has been analyzed.

DQL_Final_MiddleName_Result

string

The final result after the front/back/MRZ  document has been analyzed.

DQL_Final_Surname_Result

string

The final result after the front/back/MRZ  document has been analyzed.

DQL_Final_Address_Result

string

The final result after the front/back/MRZ document has been analyzed.

DQL_Final_AddressLine1_Result

string

The final result after the front/back/MRZ document has been analyzed.

DQL_Final_AddressCity_Result

string

The final result after the front/back/MRZ of the document has been analyzed.

DQL_Final_AddressState_Result

string

The final result after the front/back/MRZ  document has been analyzed.

DQL_Final_AddressPostalCode_Result

string

The final result after the front/back/MRZ document has been analyzed.

DQL_Final_Sex_Result

string

The final result after the front/back/MRZ  document has been analyzed.

DQL_Final_BirthDate_Result

string

The final result after the front/back/MRZ  document has been analyzed.

DQL_Final_DocumentNumber_Result

string

The final result after the front/back/MRZ  document has been analyzed.

DQL_Final_ExpirationDate_Result

string

The final result after the front/back/MRZ  document has been analyzed.

DQL_Final_IssueDate_Result

string

The final result after the front/back/MRZ  document has been analyzed.

DQL Key-Value Pair Sample Response

Copy 
"SegmentName": "Verified",
    "ActionCodes": {
        "code": 98,
    "TransactionDate": "xx/xxx/xxxx xxxxxxxx",
    "TransactionId": "xxxxxxxxxxxxxxxx",
"DocumentRiskConditions": {
        "DQL_Default_Results": {
            "Analysis_Classification_DocumentClassName": "Identification Card",
            "Analysis_Classification_DocumentIssuerCode": "xx",
            "Analysis_Classification_DocumentIssuerCountryCode": "USA",
            "Analysis_Classification_DocumentName": "Identification Card",
            "Analysis_Classification_DocumentSeries": "xxxx",
            "Analysis_Classification_IssuerName": "Georgia",
            "Analysis_Classification_Type": "ID1",
            "Analysis_DPI_Range": "Normal",
            "Analysis_PII_Source": "2D",
            "Analysis_Result_API_TransactionDate": "xx/xxx/xxxx",
            "DQL_ActionCode": "99",
            "DQL_IDE_Capture_Quality_Result": "Passed",
            "DQL_IDE_Capture_Spoof_Result": "Disabled",
            "DQL_IDE_ExpiredID_Result": "Passed",
            "DQL_Final_Address_Result": "xxx x xxxxxx xx xxxxxxx, xx xxxxx",
            "DQL_Final_AddressCity_Result": "xxxxxx",
            "DQL_Final_AddressLine1_Result": "xxx x xxxxxx xx",
            "DQL_Final_AddressPostalCode_Result": "xxxxx",
            "DQL_Final_AddressState_Result": "GA",
            "DQL_Final_BirthDate_Result": "xx/xxx/xxxx",
            "DQL_Final_DocumentNumber_Result": "xxxxxxxxx",
            "DQL_Final_ExpirationDate_Result": "xx/xxx/xxxx",
            "DQL_Final_FirstName_Result": "xxxxxxx",
            "DQL_Final_FullName_Result": "xxxxxxx xxxx xxxxxxx",
            "DQL_Final_GivenName_Result": "xxxxxxx xxxx",
            "DQL_Final_IssueDate_Result": "xx/xxx/xxxx",
            "DQL_Final_MiddleName_Result": "xxxx",
            "DQL_Final_Sex_Result": "M",
            "DQL_Final_Surname_Result": "xxxxxxx",
            "DQL_IDE_SegmentName": "Verified",
            "DQL_IDE_SubmissionError_Result": "Passed",
            "DQL_IDE_Text_Result": "Passed",
            "DQL_IDE_UnsupportedID_Result": "Passed",
            "DQL_IDE_Visual_Result": "Passed",
   
   
        ApiRequestHeaders : {
   
 "DQL_Final_Address_Result": "xxx x xxxxx xx xxxxxxx, xx xxxxx",
            "DQL_Final_AddressCity_Result": "xxxxxxx",
            "DQL_Final_AddressLine1_Result": "xxx x xxxxxx xx",
            "DQL_Final_AddressPostalCode_Result": "xxxxx",
            "DQL_Final_AddressState_Result": "xx",
            "DQL_Final_BirthDate_Result": "xx/xxx/xxxx",
            "DQL_Final_DocumentNumber_Result": "xxxxxxxxx",
            "DQL_Final_ExpirationDate_Result": "xx/xxx/xxxx",
            "DQL_Final_FirstName_Result": "xxxxxxx",
            "DQL_Final_FullName_Result": "xxxxxxx xxxx xxxxxxx",
            "DQL_Final_GivenName_Result": "xxxxxxx xxxx",
            "DQL_Final_IssueDate_Result": "xx/xxx/20xx",
           "DQL_Final_MiddleName_Result": "xxxx",
            "DQL_Final_Sex_Result": "x",
            "DQL_Final_Surname_Result": "xxxxxxx",

Success response

HTTP Code Result
200 The successful authentication response/result is returned.

Sample Response

The following example is a sample of the Response Structure and values of AuthenticateDocument API when the user processes the Authentication request.

Copy

Sample Response

"systemId": "sandbox-core1-cluster1",
 
    },
 
    "ApiVersion": 2.0,
    "AccessKey": "xxxxxxxxxxxxxxxxxxxxxxx",
    "MerchantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
    "LocationCode": "9999",
    "DocumentImageAnalysis": {
        "Front": {
            "ColorSpace": "24-bit Color",
            "DPI": 922
        },
        "Back": {
            "ColorSpace": "24-bit Color",
            "DPI": 266
        },
        "Result": "Passed"
    },
    "DocumentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "DocumentCharacteristics": {
        "Classification": {
            "state": "xxxxxxxx",
            "type": "Identification_Card",
            "year": "2012",
            "country": "United_States",
            "IssuerCode": "xx",
            "IssuerCountry": "USAUS",
            "IssuerContinent": "Americas",
            "IssuerRegion": "Northern America",
            "DocumentClassName": "Identification Card"
        },
        "Authentication": {
            "imagery": 99.76
        },
        "Pass1": {
            "result_inlier": {
                "angle": 0.13787841796875,
                "country": "United_States",
                "inliers": "555.0",
                "state": "xxxxxxx",
                "type": "Identification_Card",
                "year": "2012"
            },
            "rotation": 0
        }
    },
    "DocumentEncoding": {
        "Sex": "M",
        "GivenName": "xxxxxxx xxxx",
        "AddressPostalCode": "xxxxx",
        "AddressCounty": "xxxxxx",
        "EyeColor": "GRN",
        "AddressCity": "xxxxxxx",
        "AddressLongitude": "-xx.xxxxx",
        "Label_21": "OOVERNOR",
        "Label_22": "USA",
        "Height": "x'xx",
        "Label_20": "DONOR",
        "Label_25": "ID",
        "Label_26": "Y",
        "Label_23": "DD",
        "Label_24": "lb",
        "Label_18": "CARD",
        "Label_19": "xxxxxx",
        "Label_16": "xxxxxxx",
        "Label_17": "xxx\"",
        "Address2": "xxxxxxx, xx xxxxxxxxx",
        "Address3": "xxxxxx",
        "IssueDate": "xx/xxx/xxxx",
        "Address1": "xxx x xxxxxx xx",
        "DocumentNumber": "xxxxxxxxx",
        "AddressStateName": "xxxxxxx",
        "Weight": "xxx",
        "Label_1": "NO",
        "Label_2": "CLASS",
        "ExpirationDate": "xx/xxx/xxxx",
        "Label_10": "Hgt",
        "Label_11": "Eyes",
        "Label_8": "Iss",
        "Label_9": "Sex",
        "Label_14": "IDENTIFICATION",
        "Label_3": "ID",
        "Surname": "xxxxxxx",
        "Label_15": "xxxxxxxxxxxxxxxxxx",
        "Label_4": "DOB",
        "Label_12": "Wgt",
        "Label_5": "EXP",
        "BirthDate": "xx/xxx/xxxx",
        "AddressLatitude": "33.77129",
        "Label_13": "",
        "AddressState": "xx",
        "FullName": "xxxxxxx xxxx xxxxxxx"
    },
    "DocumentMaterialAnalysis": {},
    "DocumentImageIntegrityAnalysis": {
        "Glare": {
            "Front": {
                "Tampered": 0.0
            }
        },
        "Focus": {
            "Front": {
                "Tampered": 0.0
            }
        },
        "ScreenPhotoDetector": {
            "Front": {
                "Tampered": 0.06
            },
            "Back": {
                "Tampered": 0.0
            }
        },
        "PaperDetector": {
            "Front": {
                "Tampered": 12.64
            }
        }
    },
    "DocumentImages": {},
    "DocumentFields": {
        "Fused": {
            "VizNative": {},
            "2DBarcode": {},
            "Custom2DBarcode": {
                "Address": "xxx x xxxxxx xx",
                "CardRevisionDate": "xx/xxx/xxxx",
                "Name": "xxxxxxx xxxxx xxxxxxx",
                "EyeColor": "Green",
                "IssuedDate": "xx/xxx/xxxx",
                "ComplianceType": "X",
                "DOB": "13/Mar/1978",
                "LastNameTruncation": "N",
                "authenticateResponse": {
                    "transactionId": "xxxxxxxxxxxxxxxx",
                    "response": {
                        "dataLevel3": "True",
                        "dataLevel2": "True",
                        "dataLevel4": "True",
                        "keyLevel2": "True",
                        "keyLevel1": "True",
                        "csv": "success,4u6DuQCgi3HmVZeK,True,True,False,True,True,True",
                        "dataLevel1": "False",
                        "matchPct": "1.0",
                        "trans": "xxxxxxxxxxxxxxxx"
                    }
                },
                "City": "xxxxxxx",
                "transactionId": "xxxxxxxxxxxxxxxxx",
                "Weight": "209",
                "State": "xx",
                "DocumentDiscriminator": "xxxxxxxxxxxxxxxx",
                "MiddleNameTruncation": "N",
                "issuerIdentificationNumber": xxxxxx.0,
                "Country": "USA",
                "LastName": "xxxxxxx",
                "Sex": "M",
                "AddressPostalCode": "xxxxx-xxxx",
                "OrganDonor": "1",
                "Height": "5'11\"",
                "InventoryControlNumber": "371237926540xxxx",
                "FirstNameTruncation": "N",
                "FirstName": "xxxxxxx",
                "DocumentNumber": "xxxxxxxxx",
                "MiddleName": "xxxx",
                "ExpirationDate": "xx/xxx/xxxx"
            }
        }
    },
    "DocumentRiskVectorData": {
        "Front": {
            "Exif": {
                "Width": 3108,
                "Height": 1964,
                "Orientation": 1
            },
            "MobileSDK": {}
        },
        "Back": {
            "Exif": {
                "Width": 898,
                "Height": 566,
                "Orientation": 1
            },
            "MobileSDK": {}
        }
    },
 
        }
    },
 
    "MatchedSegmentAlgorithms": [
        "BarcodeUsable",
        "RequiredRearIDReceived",
        "BiographicTamperConclusion",
        "SpecialityDocumentAnalysis",
        "CompromisedDocumentAnalysis"
    ],
    "ErrorCodes": {
        "1117": "Error occurred for Tiny Occlusion"
    },
 
        "cat": "Environment"
    },
    "DocumentRiskVectorAnalysis": {
        "CaptureTime": {
            "Front": {
                "Result": "Disabled",
                "Display": ""
            },
            "Back": {
                "Result": "Disabled",
                "Display": ""
            },
            "FrontAndBack": {
                "Result": "Disabled",
                "Display": ""
            }
        },
        "LocationAnalysis": {
            "Front": {
                "Result": "Disabled",
                "Display": ""
            },
            "Back": {
                "Result": "Disabled",
                "Display": ""
            },
            "FrontAndBack": {
                "Result": "Disabled",
                "Display": ""
            }
        },
        "CameraUsed": {
            "Front": {
                "Result": "Disabled",
                "Display": ""
            },
            "Back": {
                "Result": "Disabled",
                "Display": ""
            }
        },
        "DeviceOrientation": {
            "Front": {
                "Result": "Disabled",
                "Display": ""
            },
            "Back": {
                "Result": "Disabled",
                "Display": ""
            }
        },
        "CaptureMethod": {
            "Front": {

Error Responses

This section lists how the error/status code is received.

 

Error Property Name Type Description

ErrorCode

number

The error code is indicating what went wrong.

ErrorMessage

string

A brief description of what went wrong.

Result

string

This field is deprecated and will always be “Failed.”

TransactionId

string

This property is only returned if a transaction has been started, but an error is encountered for some reason.

Status & Error Codes

This section lists the status & error codes that are returned. A response with error codes may include a HTTP status code and a secondary error code.

The HTTP status codes are common (200, 400, 500, etc.) to the HTTP layer. The secondary error code in the response provides the necessary information to troubleshoot the issue. The error response includes  the error message, error code, and the TransactionId (if available).

Therefore, it is recommended that any implementation must capture both the HTTP status code and error codes and error message to help troubleshoot and trace the error.

HTTP Status Code Error Code Description

401

2001

This error is triggered when the customer's account License contract has expired.

“CatfishAIR License Expired.”

400

1001

This error is triggered when Multipart data is empty or incomplete.

"No images found in this request"

400

1002

This error is triggered when request parameters have been left empty.

“No Request Parameters.”

400

1003

This error is triggered when the Access Key is missing.

“Access Key Not found.”

400

1004

This error is triggered when the Secret Token does not match the submitted Access Key.

“The Secret Token does not correspond to the Access Key submitted.”

400

1008

This error is triggered when the submitted document is missing either flash, non-flash, or both.

“Missing Image Data. Fusion requires both Flash and No Flash data to be passed in.”

(TransactionId of request)

500

1007

This error is triggered when the submitted document is unable to crop correctly. This can happen when the image is too crooked, has a low dpi, or is not recognizable in the capture.

“Error Rectifying Image Data.”

(TransactionId of request)

500

1009

This error is triggered when metadata from the front of the submitted document is not readable.

“Error Reading Metadata.”

(TransactionId of request)

500

1010

This error is triggered when the transactionId does not have enough data for a minimal check.

“Error doing the minimal check.”

(TransactionId of request)

400

1011

This error was triggered because the document type was not recognized. The document type refers to a Driver's License & ID Card, Passport, or Visa Passport.

“Invalid Document Type Specified.”

400

1012

This error is triggered when a document is submitted without a front image; the error message is triggered.

“No Front Image Passed In.”

(TransactionId of request)

500

1013

This error is triggered when the document type is not identified. If the type is not determined, the document will go into recapture. You must specify the type for the risk vector analysis to work.

“Error Doing Risk Vector Analysis.”

(TransactionId of request)

500

1016

This error is triggered when there is an error with Connect integration.

“Error Processing with Connect.”

(TransactionId of request)

500

1017

This error is triggered when there is an integration issue with Acufill.

“Error Processing with Acufill.”

(TransactionId of request)

500

1018

This error is triggered when the transactionId is not processed. It is likely the transaction number or the transactionId has been deleted if deletion rules are enabled.

“Error Processing Request.”

(TransactionId of request)

500

1025

This error is triggered when the business card Id is not identified or configured correctly.

“Error doing Business Card Authentication.”

(TransactionId of request)

400

1027

This error is triggered when the transaction does not belong to the Merchant.

“Invalid credentials or TransactionId does not belong to the Merchant.”

(TransactionId of request)

400

1028

This error is triggered when the location code is not found. Check to see if the Location Code is enabled or disabled.

“Location Code Inactive/Not Found/Default Location Not found.”

(TransactionId of request)

400

1034

This error is triggered when a Merchant account is no longer active.

“Inactive Merchant.”

(TransactionId of request)

400

1039

This error was triggered because the JSON key was invalid or malformed. This triggers the error code.

“Malformed/Invalid JSON Key detected.”

400

1042

This error is triggered when the submitted image is invalid. Make sure the image is sent in png format.

“Invalid Image Format.”

(TransactionId of request)

400

1043

This error is triggered when the user submits more than the maximum images allowed.

“More than the required number of images sent.”

(TransactionId of request)

400

2019

This error is triggered because the Access Key/Secret Token was incorrect; check for any errors.

“Invalid Access Key/Secret Token Specified.”

(TransactionId of request)

Sample Error Response

The API request header sends an error message when it receives invalid Keys or Keys with malformed characters. The JSON returns an HTTP status code 400 (Bad Request).

Copy

Error details

{ 
"ErrorCode": 1039, 
"ErrorMessage": "Malformed/Invalid JSON Key detected", 
"Result": "Failed" 
}

Below is a sample error response which is received when an image is sent in an invalid format.

The valid format is jpeg/jpg. The JSON returns an HTTP status code 400 (Bad Request).

Copy

Sample Error Response

{ 
"ErrorCode": 1042, 
"ErrorMessage": "Invalid image format", 
"TransactionId": "TransactionId of the request", 
"Result": "Failed" 
}