Introduction
Welcome to the Mitek Identity Cloud! Synchronous and asynchronous APIs for authenticating and extracting data from identity documents.
Environments
Mitek maintains production environments in multiple regions to ensure compliance with regional data processing requirements as well as ensuring that we are able to provide a responsive solution. In each region, Mitek provides both a pre-production and production environment to ensure our customers are able to develop against a production-like system without impacting production systems.
Availability
Each environment is entirely isolated sharing no information with any other environment, this is inclusive of credentials. When communicating with Mitek's Identity Cloud platform, only the environment in which a tenant is provisioned will be accessible using the provided credentials.
| Region | Product | Pre-Production | Production |
|---|---|---|---|
| United States | Mobile Verify - Manual | X | X |
| United States | Mobile Verify - Expert | X | X |
| EU | Mobile Verify - Manual | X | X |
| EU | Mobile Verify - Expert | X | X |
Authentication
Mitek uses OAuth v2 with opaque tokens for authorization and OpenID for authentication. This token-based standard leverages temporary tokens that provide access to a resource for a limited duration. In our production environments, these tokens will only be valid for 60 minutes. When you are requesting one of these temporary tokens, you need to provide the resource you are trying to access (in OAuth this is called the scope). It is best practice to ensure only the scope(s) for the operation(s) that are minimally required in order to limit the rights of the access token provided.
Client Credential Flow
The client credential flow is used when one server is communicating with another server (and there is no person at a keyboard that can type in a password). In this flow, a ClientId and a Secret are issued to you. You must protect these credentials because anyone with these credentials will be able to request tokens on your behalf. Each client has a list of scopes they are able to access, you will want to give clients access only to the scopes they need to do their job. You send the ClientId, Secret, and the scopes you are accessing to our API and an Access Token is returned. That access token should be included in the Authorization header of any requests to the API.
Authentication Request
Request Example
POST /oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded;
grant_type=client_credentials&
client_id=some.client.id&
client_secret=SecretPassword&
scope=standard.scope additional.scope
Token retrieval requires a basic POST request to our OAuth 2.0 based authentication server. The token returned is valid for a duration of 60 minutes from the time the token is first issued. Mitek recommends that developers pro-actively refresh tokens to ensure a valid token is always available for submission to the API.
In the authentication request, scopes must be included that the token will provide permissions to access. The token generated will only provide acccess to the specific operations for which the scope was requested. Mitek recommends that the token is requested with only the scopes that are minimally required to perform a specific operation.
URL
/oauth2/token
Required Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
grant_type |
string | OAuth credential type | client_credentials |
client_id |
string | Mitek provided client identifier | None |
client_secret |
string | Mitek provided client secret | None |
scope |
string | Space delimited list of scopes requested | Based on the service being used. Refer to the API Scopes section. |
Authentication Response
Response Example
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"access_token": "UWeMFVy6sz1VRvtKXgCyB7UAk805JtHc3-jy8RS04pc.e2pROys-PDNGm0nJ9BbJxBf_yTvHBn8iFrlTYSwb_Ig",
"expires_in": 3600,
"scope": "standard.scope additional.scope",
"token_type": "Bearer"
}
The authentication response includes the token to be used in subsequent requests along with other detail of the issued token including the token expiration and scopes provided within the token. NOTE: The access_token that is issued is not a JWT token, clients are unable to interrogate the token to retrieve additional details.
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
access_token |
String | Token to be submitted with any subsequent API request | None |
expires_in |
Number | Duration of token validity measured in seconds | None |
scope |
string | Scopes included in the token | Based on the service being used. Refer to the API Scopes section. |
token_type |
String | Type of token returned (Mitek only supports Bearer tokens) | Bearer |
API Scopes
| Scope | Product | Endpoint |
|---|---|---|
| verify.v3.id-document.manual.write | Mobile Verify - Manual | Manual Request |
| verify.v3.id-document.manual.read | Mobile Verify - Manual | Manual Retrieval Request |
| verify.v3.id-document.expert.write | Mobile Verify - Expert | Expert Request |
| verify.v3.id-document.expert.read | Mobile Verify - Expert | Expert Retrieval Request |
| v3.poll.read | Polling | Polling Request |
| facecomparison.v3.auto.write | Face Comparison - Auto | Face Comparison - Auto Request |
| facecomparison.v3.manual.write | Face Comparison - Manual | Face Comparison - Manual Request |
| facecomparison.v3.manual.read | Face Comparison - Manual | Face Comparison Retrieval Request |
| biometric.v3.enroll | MiPass - Enroll | MiPass - Enroll Request |
| biometric.v3.verify | MiPass - Verify | MiPass - Verify Request |
| biometric.v3.delete | MiPass - Delete | MiPass - Delete Request |
| biometric.v3.quality | MiPass - Check Quality | MiPass - Check Quality Request |
Authentication Error Responses
400 Response Example (Bad Request)
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed",
"error_hint": "Make sure that the various parameters are correct, be aware of case sensitivity and trim your parameters. Make sure that the client you are using has exactly whitelisted the redirect_uri you specified.",
"status_code": 400
}
400 Response Example (Bad Scopes)
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_scope",
"error_description": "The requested scope is invalid, unknown, or malformed",
"status_code": 400
}
401 Response Example
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error": "invalid_client",
"error_description": "Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method)",
"status_code": 401
}
500 Response Example
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{
"message": "An internal error has occurred. Please try again."
}
503 Service Unavailable
HTTP/1.1 503 Service Unavailable
Content-Type: text/plain
Service Unavailable
Standard HTTP response codes and messages are used to indicate authentication success or failure.
Mobile Verify - Manual
Mobile Verify Manual provides the capability to have one of Mitek's trained Document Review Team manually inspect documents submitted via the Mitek Identity Cloud API. When reviewing documents submitted, the Manual Review team will complete a number of verification checks to determine the Authenticity, Originality and Validity of the document. This product is delivered as an asynchronous API built around a polling approach for retrieval of final results.
Manual Request
Request Example (without Injection Attack Detection)
POST /identity/verify/v3/id-document/manual HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
{
"transactionRequestId": "093ddee6-1a16-4da2-a09f-f4c16e20defa",
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"images": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
],
"deviceExtractedData": [
{
"dataType": "PDF417_STRING",
"data": "PDF417 STRING"
}
],
"configuration": {
"injectionAttackDetection": false
}
}
Request Example (with Injection Attack Detection)
POST /identity/verify/v3/id-document/manual HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
{
"transactionRequestId": "093ddee6-1a16-4da2-a09f-f4c16e20defa",
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"images": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ==",
"encryptedPayload": "WyJVVWlsWGQ3bWhoWVJXc1lGZFRuUjlh"
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA=",
"encryptedPayload": "AiLCJPRENFbmFibGVkIjp0cnVlLCJSZW"
}
],
"deviceExtractedData": [
{
"dataType": "PDF417_STRING",
"data": "PDF417 STRING"
}
],
"configuration": {
"injectionAttackDetection": true
}
}
Each manual processing request is for the evaluation of a single document that can consist of one to many images depending on the type of document being processed. In the submitted request, the API requires a single image for each page of a given identity document to be submitted. An example being if a drivers license is submitted, successful processing will require submission of images of both the front and back of the document.
URL
/identity/verify/v3/id-document/manual
Required Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
images |
Object (array) | An array of base64-encoded images of the document to be verified. | N/A |
data |
String | A base64-encoded image containing a single page of the document to be processed. | |
encryptedPayload |
String | A base64-encoded string containing an encrypted real-time security payload generated by Mitek’s MiSnap Capture SDKs v.5.4.0 and newer. This field is only required if injectionAttackDetection is enabled in the request configuration. |
Optional Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
transactionRequestId |
String | [OPTIONAL] A valid UUID for a previously submitted Mobile Verify Auto request | UUID |
customerReferenceId |
String | [OPTIONAL] Customer provided identifier that will be returned in an identically named field within the body of any subsequent responses | 500 characters limit |
deviceExtractedData |
Object (array) | [OPTIONAL] An array of data extracted on-device from an identity document from machine-readable document features, e.g., barcode. | N/A |
datatype |
String | The type of data being passed for processing. This is commonly barcode details or other machine-encoded data that has been read on-device as part of the initial capture experience. Currently supported data types include:
|
PDF417_STRING |
configuration |
Object | A dictionary of configuration options. | |
injectionAttackDetection |
Object | Indicates whether injection attack detection should be performed on the provided images. | true or false |
Manual Response
Response Example
HTTP/1.1 201 Created
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"requestId": "4d6a4dc2-a756-4479-99c2-a856b41456c6",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
}
All manual requests are processed asynchronously. The initial response from the manual end-point provides acknowledgement that the submitted document has been received for processing and a reference requestId. Additionally, the optional customerReferenceId will also be echoed back as part of the response if submitted as part of the initial request.
Returned HTTP Headers
| Name | Type | Description | Restrictions |
|---|---|---|---|
Mitek-Server-Processing-Time |
Number | The total duration, in milliseconds, from the time the entire request was received until the response was sent. | None |
Mitek-Request-Id |
String | The UUID assigned to the request. | UUID |
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
requestId |
String | The UUID assigned to the request. | UUID |
customerReferenceId |
String | The value that was submitted with the original request. | None |
Manual Retrieval Request
Request Example
GET /identity/verify/v3/id-document/manual/4c52b0ef-aa28-4675-85d7-207b00486520 HTTP/1.1
Authorization: Bearer $OAUTH_TOKEN
Results retrieval is the final step in manual review processing. To retrieve a final result from the platform, a GET request is submitted to the API with the retrievalId that is returned from the polling API.
URL
/identity/verify/v3/id-document/manual/{retrievalId}
Required Attributes
| Name | Type | Description | Restrictions |
|---|---|---|---|
retrievalId |
String | The identifier used for retrieval of the final result of manual processing which was returned from the Polling API. | UUID |
Manual Retrieval Response
The final step in Mitek's manual review API is the retrieval of the final result from the platform using the retrievalId returned by the polling API (NOTE: This is not the same ID as the initial requestId). The results will be available from the retrieval end-point for one retrieval, once retrieval has completed, the results will be evicted from the retrieval infrastructure preventing any additional retrieval requests from being successful. Additionally, if the result has not been retrieved within 7 days of the result being made available, the result will no longer be accessible from the API.
"APPROVED" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"requestId": "4d6a4dc2-a756-4479-99c2-a856b41456c6",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": " ACCEPTED"
},
"findings": {
"documentApproval": "APPROVED",
"details": {
"authenticity": {
"result": "AUTHENTIC"
},
"originality": {
"result": "ORIGINAL"
},
"validity": {
"result": "VALID"
}
}
},
"extractedData": {
"documentAttributes": {
"countryCodeOfIssuance": "USA",
"dateOfExpiry": "1965-08-28",
"dateOfIssuance": "1965-08-28",
"documentNumber": "90933633",
"documentType": "DRIVERS_LICENSE",
"documentSubType": "",
"issuingAuthority": "CALIFORNIA DMV",
"stateOrProvinceOfIssuance": "CA"
},
"personAttributes": {
"dateOfBirth": "1965-08-28",
"gender": "F",
"nationalityCode": "USA",
"personalGovernmentId": "",
"placeOfBirth": ""
},
"name": {
"firstSurname": "LORCA SANCHEZ",
"fullName": "JUANA LORCA SANCHEZ MENDOZA",
"givenNames": "JUANA",
"secondSurname": "MENDOZA",
"surname": "LORCA SANCHEZ MENDOZA"
},
"address": {
"parsedAddress": {
"addressLine1": "123 MAIN ST",
"addressLine2": "SAN DIEGO CA 92101",
"addressLine3": "",
"addressLine4": "",
"city": "SAN DIEGO",
"postalCode": "92101",
"stateOrProvince": "CA"
},
"unparsedAddress": {
"addressLine1": "123 MAIN ST",
"addressLine2": "SAN DIEGO CA 92101",
"addressLine3": "",
"addressLine4": ""
}
},
"machineReadableZone": {
"parsedMachineReadableZone": {
"compositeCheckDigit": "0",
"compositeCheckDigitVerified": "true",
"dateOfBirth": "1967-07-04",
"dateOfBirthCheckDigit": "6",
"dateOfBirthVerified": "true",
"dateOfExpiry": "2016-08-07",
"dateOfExpiryCheckDigit": "8",
"dateOfExpiryVerified": "true",
"documentNumber": "340007955",
"documentNumberCheckDigit": "3",
"documentNumberVerified": "true",
"documentSubType": "",
"documentType": "P",
"gender": "F",
"givenNames": "HAPPY",
"stateOrProvinceOfIssuance": "USA",
"stateOrProvinceOfIssuanceVerified": "true",
"isValid": "true",
"nationalityCode": "USA",
"nationalityCodeVerified": "true",
"personalGovernmentId": "910000833 1119",
"personalGovernmentIdCheckDigit": "2",
"personalGovernmentIdVerified": "true",
"surname": "TRAVELER"
},
"unparsedMachineReadableZone": {
"mrzLine1": "P<USATRAVELER<<HAPPY<<<<<<<<<<<<<<<<<<<<<<<<",
"mrzLine2": "3400079553USA6707046F1608078910000833<111920",
"mrzLine3": "",
}
}
}
}
"NOT_APPROVED" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"requestId": "4d6a4dc2-a756-4479-99c2-a856b41456c6",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": " ACCEPTED"
},
"findings": {
"documentApproval": "NOT_APPROVED",
"details": {
"authenticity": {
"result": "NOT_AUTHENTIC",
"reasons": [
"EVIDENCE_OF_FORGERY_BIODATA_FONTS",
"EVIDENCE_OF_FORGERY_MRZ_FONTS",
"EVIDENCE_OF_FORGERY_PHOTO_ZONE",
"EVIDENCE_OF_FORGERY_SIGNATURE"
]
},
"originality": {
"result": "NOT_ORIGINAL",
"reasons": [
"EVIDENCE_OF_FORGERY_BLACK_AND_WHITE_COPY",
"EVIDENCE_OF_FORGERY_DOCUMENT_STRUCTURE"
]
},
"validity": {
"result": "NOT_VALID",
"reasons": [
"EVIDENCE_OF_FORGERY_DATA_COMPARISON",
"EVIDENCE_OF_FORGERY_MRZ_CHECKSUMS",
"EXPIRED_OR_INVALIDATED"
]
}
}
},
"extractedData": {
"documentAttributes": {
"countryCodeOfIssuance": "USA",
"dateOfExpiry": "1965-08-28",
"dateOfIssuance": "1965-08-28",
"documentNumber": "90933633",
"documentType": "DRIVERS_LICENSE",
"documentSubType": "",
"issuingAuthority": "CALIFORNIA DMV",
"stateOrProvinceOfIssuance": "CA"
},
"personAttributes": {
"dateOfBirth": "1965-08-28",
"gender": "F",
"nationalityCode": "USA",
"personalGovernmentId": "",
"placeOfBirth": ""
},
"name": {
"firstSurname": "LORCA SANCHEZ",
"fullName": "JUANA LORCA SANCHEZ MENDOZA",
"givenNames": "JUANA",
"secondSurname": "MENDOZA",
"surname": "LORCA SANCHEZ MENDOZA"
},
"address": {
"parsedAddress": {
"addressLine1": "123 MAIN ST",
"addressLine2": "SAN DIEGO CA 92101",
"addressLine3": "",
"addressLine4": "",
"city": "SAN DIEGO",
"postalCode": "92101",
"stateOrProvince": "CA"
},
"unparsedAddress": {
"addressLine1": "123 MAIN ST",
"addressLine2": "SAN DIEGO CA 92101",
"addressLine3": "",
"addressLine4": ""
}
},
"machineReadableZone": {
"parsedMachineReadableZone": {
"compositeCheckDigit": "0",
"compositeCheckDigitVerified": "true",
"dateOfBirth": "1967-07-04",
"dateOfBirthCheckDigit": "6",
"dateOfBirthVerified": "true",
"dateOfExpiry": "2016-08-07",
"dateOfExpiryCheckDigit": "8",
"dateOfExpiryVerified": "true",
"documentNumber": "340007955",
"documentNumberCheckDigit": "3",
"documentNumberVerified": "true",
"documentSubType": "",
"documentType": "P",
"gender": "F",
"givenNames": "HAPPY",
"stateOrProvinceOfIssuance": "USA",
"stateOrProvinceOfIssuanceVerified": "true",
"isValid": "true",
"nationalityCode": "USA",
"nationalityCodeVerified": "true",
"personalGovernmentId": "910000833 1119",
"personalGovernmentIdCheckDigit": "2",
"personalGovernmentIdVerified": "true",
"surname": "TRAVELER"
},
"unparsedMachineReadableZone": {
"mrzLine1": "P<USATRAVELER<<HAPPY<<<<<<<<<<<<<<<<<<<<<<<<",
"mrzLine2": "3400079553USA6707046F1608078910000833<111920",
"mrzLine3": "",
}
}
}
}
"REJECTED" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"requestId": "4d6a4dc2-a756-4479-99c2-a856b41456c6",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": " REJECTED",
"reasons": [
"GLARE",
"INCOMPLETE_DOCUMENT",
"NOT_VISIBLE_FOUR_CORNERS",
"NOT_VISIBLE_SECURITY_FEATURES",
"OUT_OF_FOCUS",
"POOR_CONTRAST",
"POOR_EXPOSURE",
"UNCLASSIFIED_DOCUMENT",
"UNREADABLE_FIELD",
"UNSUPPORTED_LANGUAGE"
]
}
}
Returned HTTP Headers
| Name | Type | Description | Restrictions |
|---|---|---|---|
Mitek-Server-Processing-Time |
Number | The total duration, in milliseconds, from the time the entire request was received until the response was sent. | None |
Mitek-Request-Id |
String | The UUID assigned to the request. | UUID |
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
requestId |
String | The UUID assigned to the request. | UUID |
customerReferenceId |
String | The value that was submitted with the original request. | None |
acceptance |
Object | The determination of whether the images submitted were of sufficient quality for a document to be processed. In the event a document is unable to be processed successfully, a status of REJECTED will be returned and the reasons for failure will be included in the reasons field. |
N/A |
result |
String | The determinition of whether all of the images submitted were deemed acceptable for processing.
|
ACCEPTED or REJECTED |
reasons |
String (array) | The reasons that a result of
|
GLARE, INCOMPLETE_DOCUMENT, NOT_VISIBLE_FOUR_CORNERS, NOT_VISIBLE_SECURITY_FEATURES, OUT_OF_FOCUS, POOR_CONTRAST, POOR_EXPOSURE, UNCLASSIFIED_DOCUMENT, UNREADABLE_FIELD, UNSUPPORTED_LANGUAGE or INJECTION_ATTACK_DETECTED |
findings |
Object | The following fields are related to the overall findings that resulted from the processing of the document. This includes the overall document approval and a detailed summary of the authenticity, originality and the validity findings that contributed to the document approval result. | N/A |
documentApproval |
String | The overall document approval determination.
|
APPROVED or NOT_APPROVED |
details |
Object | The details of the authenticity, originality, and validity checks that were performed. | N/A |
authenticity |
Object | The details of the authenticity checks that were performed. | N/A |
result |
String | The overall authenticity result of the processed document.
|
AUTHENTIC or NOT_AUTHENTIC |
reasons |
String (array) | The reasons that a result of
|
EVIDENCE_OF_FORGERY_BIODATA_FONTS, EVIDENCE_OF_FORGERY_MRZ_FONTS, EVIDENCE_OF_FORGERY_NOT_HUMAN_FACE and EVIDENCE_OF_FORGERY_PHOTO_ZONE |
originality |
Object | The details of the originality checks that were performed. | N/A |
result |
String | The overall originality result of the processed document. ORIGINAL: The processed document was determined to be original.
|
ORIGINAL or NOT_ORIGINAL |
reasons |
String (array) | The reasons that a result of
|
EVIDENCE_OF_FORGERY_BLACK_AND_WHITE_COPY and EVIDENCE_OF_FORGERY_DOCUMENT_STRUCTURE |
validity |
Object | The details of the validity checks that were performed. | N/A |
result |
String | The overall validity result of the processed document.
|
VALID or NOT_VALID |
reasons |
String (array) | The reasons that a result of
|
EVIDENCE_OF_FORGERY_DATA_COMPARISON, EVIDENCE_OF_FORGERY_MRZ_CHECKSUMS and EXPIRED_OR_INVALIDATED |
extractedData |
Object | The data extracted from the submitted document. The data returned within extracted data is dependent on the type of document submitted; not all documents supported contain all possible fields. | N/A |
documentAttributes |
Object | The data extracted from the submitted document, specifically from fields that are related to attributes of the document. | N/A |
countryCodeOfIssuance |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the ISO code of the country that issued the document. | None |
dateOfExpiry |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the date of expiry of the document, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
dateOfIssuance |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the date of issuance of the document, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
documentNumber |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the number or identifier of the document. | None |
documentType |
String | The type of document that was submitted. |
PASSPORT, DRIVERS_LICENSE, IDENTITY_CARD, RESIDENCE_PERMIT, HEALTH_SERVICES_CARD (PASSPORT_CARD, NEXUS_CARD, MILITARY_ID_CARD and TRIBAL_CARD are automatically mapped to IDENTITY_CARD unless the "Extended document types in agent response" setting is enabled) |
documentSubType |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the sub type of the document. | None |
issuingAuthority |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the name of the authority or organization that issued the document. | None |
stateOrProvinceOfIssuance |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the name of the state, province, or region that issued the document. | None |
personAttributes |
Object | The data extracted from the submitted document, specifically from fields that are related to the person to whom the document was issued. | N/A |
dateOfBirth |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the date of birth of the person to which the document was issued, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
gender |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the gender of the person to which the document was issued, normalized into one of the following values: |
M, F, or N/B |
nationalityCode |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the ISO country code of the nationality of the person to which the document was issued. | None |
personalGovernmentId |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to any government identification number of the person to which the document was issued. | None |
placeOfBirth |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the place of birth of the person to which the document was issued. | None |
name |
Object | The data extracted from the submitted document, specifically from fields that are related to the name of whom the document was issued. | N/A |
fullName |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the full name of the person to which the document was issued. | None |
givenNames |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the given names of the person to which the document was issued. | |
firstSurname |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the first surname of the person to which the document was issued. | None |
secondSurname |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the second surname of the person to which the document was issued. | None |
surname |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the surname of the person to which the document was issued. | None |
address |
Object | The data extracted from the submitted document, specifically from fields that are related to the address of the person to whom the document was issued. | N/A |
parsedAddress |
Object | A parsed version of the address of the person to whom the document was issued. | N/A |
addressLine1 |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the first line of the address, as printed, of the person to which the document was issued. | None |
addressLine2 |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the second line of the address, as printed, of the person to which the document was issued. | None |
addressLine3 |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the third line of the address, as printed, of the person to which the document was issued. | None |
addressLine4 |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the fourth line of the address, as printed, of the person to which the document was issued. | None |
city |
String | The parsed out city of the address of the person to whom the document was issued. | None |
postalCode |
String | The parsed out postal code of the address of the person to whom the document was issued. | None |
stateOrProvince |
String | The parsed out state or province of the address of the person to whom the document was issued. | None |
unparsedAddress |
Object | An unparsed version of the address of the person to whom the document was issued. | N/A |
addressLine1 |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the first line of the address, as printed, of the person to which the document was issued. | None |
addressLine2 |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the second line of the address, as printed, of the person to which the document was issued. | None |
addressLine3 |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the third line of the address, as printed, of the person to which the document was issued. | None |
addressLine4 |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the fourth line of the address, as printed, of the person to which the document was issued. | None |
machineReadableZone |
Object | The data extracted from the Machine Readable Zone of the submitted document. | N/A |
parsedMachineReadableZone |
Object | A parsed version of the Machine Readable Zone. | N/A |
compositeCheckDigit |
String | The composite check digit value. | A single digit or < |
compositeCheckDigitVerified |
String | The indication if the composite check digit contains a valid value. | true or false |
dateOfBirth |
String | The data extracted from an MRZ field related to the date of birth of the person to which the document was issued, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
dateOfBirthCheckDigit |
String | The date of birth check digit value. | A single digit or < |
dateOfBirthVerified |
String | The indication if the date of birth check digit contains a valid value. | true or false |
dateOfExpiry |
String | The data extracted from an MRZ field related to the date of expiry of the document, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
dateOfExpiryCheckDigit |
String | The date of expiry check digit value. | A single digit or < |
dateOfExpiryVerified |
String | The indication if the date of expiry check digit contains a valid value. | true or false |
documentNumber |
String | The data extracted from an MRZ field related to the number or identifier of the document. | None |
documentNumberCheckDigit |
String | The document number check digit value. | A single digit or < |
documentNumberVerified |
String | The indication if the document number check digit contains a valid value. | true or false |
documentSubType |
String | The data extracted from an MRZ field related to the sub type of the document. | None |
documentType |
String (array) | The data extracted from an MRZ field related to the type of document that was submitted. |
None |
gender |
String | The data extracted from an MRZ field related to the gender of the person to which the document was issued, normalized into one of the following values: |
M, F, or N/B |
givenNames |
String | The data extracted from an MRZ field related to the given names of the person to which the document was issued. | |
stateOrProvinceOfIssuance |
String | The data extracted from an MRZ field related to the ISO country code of the country that issued the document. | None |
stateOrProvinceOfIssuanceVerified |
String | The indication if the issuing state or organization contains a valid value. | true or false |
isValid |
String | The parsed out state or province of the address of the person to whom the document was issued. | None |
nationalityCode |
String | The data extracted from an MRZ field related to the ISO country code of the nationality of the person to which the document was issued. | None |
nationalityCodeVerified |
String | The indication if the nationality contains a valid value. | true or false |
personalGovernmentId |
String | The data extracted from an MRZ field related to any government identification number of the person to which the document was issued. | None |
personalGovernmentIdCheckDigit |
String | The personal government ID check digit value. | A single digit or < |
personalGovernmentIdVerified |
String | The indication if the personal government ID check digit contains a valid value. | true or false |
surname |
String | The data extracted from an MRZ field related to the surname of the person to which the document was issued. | None |
unparsedMachineReadableZone |
Object | An unparsed version of the Machine Readable Zone. | N/A |
mrzLine1 |
String | The first line of the MRZ. | None |
mrzLine2 |
String | The second line of the MRZ. | None |
mrzLine3 |
String | The third line of the MRZ. | None |
Manual Error Responses
400 Response Example
HTTP/1.1 400 Bad Request
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "Customer reference id should not exceed 500 characters."
}
OR
{
"message": "Missing image data."
}
OR
{
"message": "No images were provided."
}
OR
{
"message": "Please specify a valid dataType for deviceExtractedData."
}
OR
{
"message": "Unknown value "PDF417_STRING_VAL" for enum customerapi.DeviceExtractedData_DataType."
}
OR
{
"message": "Incorrect endpoint for request type."
}
401 Response Example
HTTP/1.1 401 Unauthorized
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "The token is either invalid, malformed, inactive, or missing the required scopes."
}
404 Response Example
HTTP/1.1 404 Not Found
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "The result you attempted to retrieve does not exist or has already been retrieved."
}
OR
{
"message": "Not Found"
}
408 Response Example
HTTP/1.1 408 Request Timeout
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "Request Timeout"
}
413 Response Example
HTTP/1.1 413 Request Entity Too Large
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "Request Entity Too Large"
}
415 Response Example
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
{
"message": "Please ensure you are specifying application/json as the Content-Type."
}
429 Response Example
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "Too Many Requests"
}
500 Response Example
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "An internal error has occurred. Please try again in a few minutes."
}
503 Service Unavailable
HTTP/1.1 503 Service Unavailable
Content-Type: text/plain
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
Service Unavailable
OR
HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "Service Unavailable"
}
Standard HTTP REST-based response codes and messages are used to indicate success or failure for a request.
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
message |
String | A message describing the error. | None |
Mobile Verify - Expert
Mobile Verify Expert provides the capability to have one of Mitek's trained Document Review Team Expert manually inspect documents submitted via the Mitek Identity Cloud API. When reviewing documents submitted, the Manual Review Expert team will complete series of verification checks to determine the Authenticity, Originality and Validity of the document. This product is delivered as an asynchronous API built around a polling approach for retrieval of final results.
Expert Request
Request Example (without Injection Attack Detection)
POST /identity/verify/v3/id-document/expert HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
{
"transactionRequestId": "093ddee6-1a16-4da2-a09f-f4c16e20defa",
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"images": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
],
"deviceExtractedData": [
{
"dataType": "PDF417_STRING",
"data": "PDF417 STRING"
}
],
"configuration": {
"injectionAttackDetection": false
}
}
Request Example (with Injection Attack Detection)
POST /identity/verify/v3/id-document/expert HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
{
"transactionRequestId": "093ddee6-1a16-4da2-a09f-f4c16e20defa",
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"images": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ==",
"encryptedPayload": "WyJVVWlsWGQ3bWhoWVJXc1lGZFRuUjlh"
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA=",
"encryptedPayload": "AiLCJPRENFbmFibGVkIjp0cnVlLCJSZW"
}
],
"deviceExtractedData": [
{
"dataType": "PDF417_STRING",
"data": "PDF417 STRING"
}
],
"configuration": {
"injectionAttackDetection": true
}
}
Each expert processing request is for the evaluation of a single document that can consist of one to many images depending on the type of document being processed. In the submitted request, the API requires a single image for each page of a given identity document to be submitted. An example being if a drivers license is submitted, successful processing will require submission of images of both the front and back of the document.
URL
/identity/verify/v3/id-document/expert
Required Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
images |
Object (array) | An array of base64-encoded images of the document to be verified. | N/A |
data |
String | A base64-encoded image containing a single page of the document to be processed. | |
encryptedPayload |
String | A base64-encoded string containing an encrypted real-time security payload generated by Mitek’s MiSnap Capture SDKs v.5.4.0 and newer. This field is only required if injectionAttackDetection is enabled in the request configuration. |
Optional Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
transactionRequestId |
String | [OPTIONAL] A valid UUID for a previously submitted Mobile Verify Auto request | UUID |
customerReferenceId |
String | [OPTIONAL] Customer provided identifier that will be returned in an identically named field within the body of any subsequent responses | 500 characters limit |
deviceExtractedData |
Object (array) | [OPTIONAL] An array of data extracted on-device from an identity document from machine-readable document features, e.g., barcode. | N/A |
datatype |
String | The type of data being passed for processing. This is commonly barcode details or other machine-encoded data that has been read on-device as part of the initial capture experience. Currently supported data types include:
|
PDF417_STRING |
configuration |
Object | A dictionary of configuration options. | |
injectionAttackDetection |
Object | Indicates whether injection attack detection should be performed on the provided images. | true or false |
Expert Response
Response Example
HTTP/1.1 201 Created
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
}
All expert requests are processed asynchronously. The initial response from the expert end-point provides acknowledgement that the submitted document has been received for processing and also a reference requestId back to that caller that will later be used in order to retrieve the results. Additionally, the optional customerReferenceId will also be echoed back as part of the response if submitted as part of the initial request.
Returned HTTP Headers
| Name | Type | Description | Restrictions |
|---|---|---|---|
Mitek-Server-Processing-Time |
Number | The total duration, in milliseconds, from the time the entire request was received until the response was sent. | None |
Mitek-Request-Id |
String | The UUID assigned to the request. | UUID |
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
requestId |
String | The UUID assigned to the request. | UUID |
customerReferenceId |
String | The value that was submitted with the original request. | None |
Expert Retrieval Request
Request Example
GET /identity/verify/v3/id-document/expert/1a55b710-def3-4bc2-89c8-17cefd8c7c98 HTTP/1.1
Authorization: Bearer $OAUTH_TOKEN
Results retrieval is the final step in expert review processing. To retrieve a final result from the platform, a GET request is submitted to the API with the retrievalId that is returned from the polling API. The results will be available from the retrieval end-point for one retrieval, once retrieval has completed, the results will be evicted from the retrieval infrastructure preventing any additional retrieval requests from being successful. Additionally, if the result has not been retrieved within 7 days of the result being made available, the result will no longer be accessible from the API.
URL
/identity/verify/v3/id-document/expert/{retrievalId}
Required Attributes
| Name | Type | Description | Restrictions |
|---|---|---|---|
retrievalId |
String | The identifier used for retrieval of the final result of expert processing which was returned from the Polling API. | UUID |
Expert Retrieval Response
"APPROVED" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": " ACCEPTED"
},
"findings": {
"documentApproval": "APPROVED",
"details": {
"authenticity": {
"result": "AUTHENTIC"
},
"originality": {
"result": "ORIGINAL"
},
"validity": {
"result": "VALID"
}
}
},
"extractedData": {
"documentAttributes": {
"countryCodeOfIssuance": "USA",
"dateOfExpiry": "1965-08-28",
"dateOfIssuance": "1965-08-28",
"documentNumber": "90933633",
"documentType": "DRIVERS_LICENSE",
"documentSubType": "",
"issuingAuthority": "CALIFORNIA DMV",
"stateOrProvinceOfIssuance": "CA"
},
"personAttributes": {
"dateOfBirth": "1965-08-28",
"gender": "F",
"nationalityCode": "USA",
"personalGovernmentId": "",
"placeOfBirth": ""
},
"name": {
"firstSurname": "LORCA SANCHEZ",
"fullName": "JUANA LORCA SANCHEZ MENDOZA",
"givenNames": "JUANA",
"secondSurname": "MENDOZA",
"surname": "LORCA SANCHEZ MENDOZA"
},
"address": {
"parsedAddress": {
"addressLine1": "123 MAIN ST",
"addressLine2": "SAN DIEGO CA 92101",
"addressLine3": "",
"addressLine4": "",
"city": "SAN DIEGO",
"postalCode": "92101",
"stateOrProvince": "CA"
},
"unparsedAddress": {
"addressLine1": "123 MAIN ST",
"addressLine2": "SAN DIEGO CA 92101",
"addressLine3": "",
"addressLine4": ""
}
},
"machineReadableZone": {
"parsedMachineReadableZone": {
"compositeCheckDigit": "0",
"compositeCheckDigitVerified": "true",
"dateOfBirth": "1967-07-04",
"dateOfBirthCheckDigit": "6",
"dateOfBirthVerified": "true",
"dateOfExpiry": "2016-08-07",
"dateOfExpiryCheckDigit": "8",
"dateOfExpiryVerified": "true",
"documentNumber": "340007955",
"documentNumberCheckDigit": "3",
"documentNumberVerified": "true",
"documentSubType": "",
"documentType": "P",
"gender": "F",
"givenNames": "HAPPY",
"stateOrProvinceOfIssuance": "USA",
"stateOrProvinceOfIssuanceVerified": "true",
"isValid": "true",
"nationalityCode": "USA",
"nationalityCodeVerified": "true",
"personalGovernmentId": "910000833 1119",
"personalGovernmentIdCheckDigit": "2",
"personalGovernmentIdVerified": "true",
"surname": "TRAVELER"
},
"unparsedMachineReadableZone": {
"mrzLine1": "P<USATRAVELER<<HAPPY<<<<<<<<<<<<<<<<<<<<<<<<",
"mrzLine2": "3400079553USA6707046F1608078910000833<111920",
"mrzLine3": "",
}
}
}
}
"NOT_APPROVED" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": " ACCEPTED"
},
"findings": {
"documentApproval": "NOT_APPROVED",
"details": {
"authenticity": {
"result": "NOT_AUTHENTIC",
"reasons": [
"EVIDENCE_OF_FORGERY_BIODATA_FONTS",
"EVIDENCE_OF_FORGERY_MRZ_FONTS",
"EVIDENCE_OF_FORGERY_PHOTO_ZONE",
"EVIDENCE_OF_FORGERY_SECURITY_FEATURES",
"EVIDENCE_OF_FORGERY_SIGNATURE"
]
},
"originality": {
"result": "NOT_ORIGINAL",
"reasons": [
"EVIDENCE_OF_FORGERY_BLACK_AND_WHITE_COPY",
"EVIDENCE_OF_FORGERY_DOCUMENT_STRUCTURE"
]
},
"validity": {
"result": "NOT_VALID",
"reasons": [
"EVIDENCE_OF_FORGERY_DATA_COMPARISON",
"EVIDENCE_OF_FORGERY_MRZ_CHECKSUMS",
"EXPIRED_OR_INVALIDATED"
]
}
}
},
"extractedData": {
"documentAttributes": {
"countryCodeOfIssuance": "USA",
"dateOfExpiry": "1965-08-28",
"dateOfIssuance": "1965-08-28",
"documentNumber": "90933633",
"documentType": "DRIVERS_LICENSE",
"documentSubType": "",
"issuingAuthority": "CALIFORNIA DMV",
"stateOrProvinceOfIssuance": "CA"
},
"personAttributes": {
"dateOfBirth": "1965-08-28",
"gender": "F",
"nationalityCode": "USA",
"personalGovernmentId": "",
"placeOfBirth": ""
},
"name": {
"firstSurname": "LORCA SANCHEZ",
"fullName": "JUANA LORCA SANCHEZ MENDOZA",
"givenNames": "JUANA",
"secondSurname": "MENDOZA",
"surname": "LORCA SANCHEZ MENDOZA"
},
"address": {
"parsedAddress": {
"addressLine1": "123 MAIN ST",
"addressLine2": "SAN DIEGO CA 92101",
"addressLine3": "",
"addressLine4": "",
"city": "SAN DIEGO",
"postalCode": "92101",
"stateOrProvince": "CA"
},
"unparsedAddress": {
"addressLine1": "123 MAIN ST",
"addressLine2": "SAN DIEGO CA 92101",
"addressLine3": "",
"addressLine4": ""
}
},
"machineReadableZone": {
"parsedMachineReadableZone": {
"compositeCheckDigit": "0",
"compositeCheckDigitVerified": "true",
"dateOfBirth": "1967-07-04",
"dateOfBirthCheckDigit": "6",
"dateOfBirthVerified": "true",
"dateOfExpiry": "2016-08-07",
"dateOfExpiryCheckDigit": "8",
"dateOfExpiryVerified": "true",
"documentNumber": "340007955",
"documentNumberCheckDigit": "3",
"documentNumberVerified": "true",
"documentSubType": "",
"documentType": "P",
"gender": "F",
"givenNames": "HAPPY",
"stateOrProvinceOfIssuance": "USA",
"stateOrProvinceOfIssuanceVerified": "true",
"isValid": "true",
"nationalityCode": "USA",
"nationalityCodeVerified": "true",
"personalGovernmentId": "910000833 1119",
"personalGovernmentIdCheckDigit": "2",
"personalGovernmentIdVerified": "true",
"surname": "TRAVELER"
},
"unparsedMachineReadableZone": {
"mrzLine1": "P<USATRAVELER<<HAPPY<<<<<<<<<<<<<<<<<<<<<<<<",
"mrzLine2": "3400079553USA6707046F1608078910000833<111920",
"mrzLine3": "",
}
}
}
}
"REJECTED" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": " REJECTED",
"reasons": [
"GLARE",
"INCOMPLETE_DOCUMENT",
"NOT_VISIBLE_FOUR_CORNERS",
"NOT_VISIBLE_SECURITY_FEATURES",
"OUT_OF_FOCUS",
"POOR_CONTRAST",
"POOR_EXPOSURE",
"UNCLASSIFIED_DOCUMENT",
"UNREADABLE_FIELD",
"UNSUPPORTED_LANGUAGE"
]
}
}
Returned HTTP Headers
| Name | Type | Description | Restrictions |
|---|---|---|---|
Mitek-Server-Processing-Time |
Number | The total duration, in milliseconds, from the time the entire request was received until the response was sent. | None |
Mitek-Request-Id |
String | The UUID assigned to the request. | UUID |
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
requestId |
String | The UUID assigned to the request. | UUID |
customerReferenceId |
String | The value that was submitted with the original request. | None |
acceptance |
Object | The determination of whether the images submitted were of sufficient quality for a document to be processed. In the event a document is unable to be processed successfully, a status of REJECTED will be returned and the reasons for failure will be included in the reasons field. |
N/A |
result |
String | The determinition of whether all of the images submitted were deemed acceptable for processing.
|
ACCEPTED or REJECTED |
reasons |
String (array) | The reasons that a result of
|
GLARE, INCOMPLETE_DOCUMENT, NOT_VISIBLE_FOUR_CORNERS, NOT_VISIBLE_SECURITY_FEATURES, OUT_OF_FOCUS, POOR_CONTRAST, POOR_EXPOSURE, UNCLASSIFIED_DOCUMENT, UNREADABLE_FIELD, UNSUPPORTED_LANGUAGE or INJECTION_ATTACK_DETECTED |
findings |
Object | The following fields are related to the overall findings that resulted from the processing of the document. This includes the overall document approval and a detailed summary of the authenticity, originality and the validity findings that contributed to the document approval result. | N/A |
documentApproval |
String | The overall document approval determination.
|
APPROVED or NOT_APPROVED |
details |
Object | The details of the authenticity, originality, and validity checks that were performed. | N/A |
authenticity |
Object | The details of the authenticity checks that were performed. | N/A |
result |
String | The overall authenticity result of the processed document.
|
AUTHENTIC or NOT_AUTHENTIC |
reasons |
String (array) | The reasons that a result of
|
EVIDENCE_OF_FORGERY_BIODATA_FONTS, EVIDENCE_OF_FORGERY_MRZ_FONTS, EVIDENCE_OF_FORGERY_PHOTO_ZONE, EVIDENCE_OF_FORGERY_SECURITY_FEATURES and EVIDENCE_OF_FORGERY_SIGNATURE |
originality |
Object | The details of the originality checks that were performed. | N/A |
result |
String | The overall originality result of the processed document. ORIGINAL: The processed document was determined to be original.
|
ORIGINAL or NOT_ORIGINAL |
reasons |
String (array) | The reasons that a result of
|
EVIDENCE_OF_FORGERY_DOCUMENT_STRUCTURE and EVIDENCE_OF_FORGERY_BLACK_AND_WHITE_COPY |
validity |
Object | The details of the validity checks that were performed. | N/A |
result |
String | The overall validity result of the processed document.
|
VALID or NOT_VALID |
reasons |
String (array) | The reasons that a result of
|
EVIDENCE_OF_FORGERY_DATA_COMPARISON, EVIDENCE_OF_FORGERY_MRZ_CHECKSUMS and EXPIRED_OR_INVALIDATED |
extractedData |
Object | The data extracted from the submitted document.The data returned within extracted data is dependent on the type of document submitted; not all documents supported contain all possible fields. | N/A |
documentAttributes |
Object | The data extracted from the submitted document, specifically from fields that are related to attributes of the document. | N/A |
countryCodeOfIssuance |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the ISO code of the country that issued the document. | None |
dateOfExpiry |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the date of expiry of the document, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
dateOfIssuance |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the date of issuance of the document, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
documentNumber |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the number or identifier of the document. | None |
documentType |
String | The type of document that was submitted. |
PASSPORT, DRIVERS_LICENSE, IDENTITY_CARD, RESIDENCE_PERMIT, HEALTH_SERVICES_CARD (PASSPORT_CARD, NEXUS_CARD, MILITARY_ID_CARD and TRIBAL_CARD are automatically mapped to IDENTITY_CARD unless the "Extended document types in agent response" setting is enabled) |
documentSubType |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the sub type of the document. | None |
issuingAuthority |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the name of the authority or organization that issued the document. | None |
stateOrProvinceOfIssuance |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the name of the state, province, or region that issued the document. | None |
personAttributes |
Object | The data extracted from the submitted document, specifically from fields that are related to the person to whom the document was issued. | N/A |
dateOfBirth |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the date of birth of the person to which the document was issued, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
gender |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the gender of the person to which the document was issued, normalized into one of the following values: |
M, F, or N/B |
nationalityCode |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the ISO country code of the nationality of the person to which the document was issued. | None |
personalGovernmentId |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to any government identification number of the person to which the document was issued. | None |
placeOfBirth |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the place of birth of the person to which the document was issued. | None |
name |
Object | The data extracted from the submitted document, specifically from fields that are related to the name of whom the document was issued. | N/A |
fullName |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the full name of the person to which the document was issued. | None |
givenNames |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the given names of the person to which the document was issued. | |
firstSurname |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the first surname of the person to which the document was issued. | None |
secondSurname |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the second surname of the person to which the document was issued. | None |
surname |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the surname of the person to which the document was issued. | None |
address |
Object | The data extracted from the submitted document, specifically from fields that are related to the address of the person to whom the document was issued. | N/A |
parsedAddress |
Object | A parsed version of the address of the person to whom the document was issued. | N/A |
addressLine1 |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the first line of the address, as printed, of the person to which the document was issued. | None |
addressLine2 |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the second line of the address, as printed, of the person to which the document was issued. | None |
addressLine3 |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the third line of the address, as printed, of the person to which the document was issued. | None |
addressLine4 |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the fourth line of the address, as printed, of the person to which the document was issued. | None |
city |
String | The parsed out city of the address of the person to whom the document was issued. | None |
postalCode |
String | The parsed out postal code of the address of the person to whom the document was issued. | None |
stateOrProvince |
String | The parsed out state or province of the address of the person to whom the document was issued. | None |
unparsedAddress |
Object | An unparsed version of the address of the person to whom the document was issued. | N/A |
addressLine1 |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the first line of the address, as printed, of the person to which the document was issued. | None |
addressLine2 |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the second line of the address, as printed, of the person to which the document was issued. | None |
addressLine3 |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the third line of the address, as printed, of the person to which the document was issued. | None |
addressLine4 |
String | The data extracted from an MRZ, PDF417 barcode, or biozone field related to the fourth line of the address, as printed, of the person to which the document was issued. | None |
machineReadableZone |
Object | The data extracted from the Machine Readable Zone of the submitted document. | N/A |
parsedMachineReadableZone |
Object | A parsed version of the Machine Readable Zone. | N/A |
compositeCheckDigit |
String | The composite check digit value. | A single digit or < |
compositeCheckDigitVerified |
String | The indication if the composite check digit contains a valid value. | true or false |
dateOfBirth |
String | The data extracted from an MRZ field related to the date of birth of the person to which the document was issued, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
dateOfBirthCheckDigit |
String | The date of birth check digit value. | A single digit or < |
dateOfBirthVerified |
String | The indication if the date of birth check digit contains a valid value. | true or false |
dateOfExpiry |
String | The data extracted from an MRZ field related to the date of expiry of the document, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
dateOfExpiryCheckDigit |
String | The date of expiry check digit value. | A single digit or < |
dateOfExpiryVerified |
String | The indication if the date of expiry check digit contains a valid value. | true or false |
documentNumber |
String | The data extracted from an MRZ field related to the number or identifier of the document. | None |
documentNumberCheckDigit |
String | The document number check digit value. | A single digit or < |
documentNumberVerified |
String | The indication if the document number check digit contains a valid value. | true or false |
documentSubType |
String | The data extracted from an MRZ field related to the sub type of the document. | None |
documentType |
String (array) | The data extracted from an MRZ field related to the type of document that was submitted. |
None |
gender |
String | The data extracted from an MRZ field related to the gender of the person to which the document was issued, normalized into one of the following values: |
M, F, or N/B |
givenNames |
String | The data extracted from an MRZ field related to the given names of the person to which the document was issued. | |
stateOrProvinceOfIssuance |
String | The data extracted from an MRZ field related to the ISO country code of the country that issued the document. | None |
stateOrProvinceOfIssuanceVerified |
String | The indication if the issuing state or organization contains a valid value. | true or false |
isValid |
String | The parsed out state or province of the address of the person to whom the document was issued. | None |
nationalityCode |
String | The data extracted from an MRZ field related to the ISO country code of the nationality of the person to which the document was issued. | None |
nationalityCodeVerified |
String | The indication if the nationality contains a valid value. | true or false |
personalGovernmentId |
String | The data extracted from an MRZ field related to any government identification number of the person to which the document was issued. | None |
personalGovernmentIdCheckDigit |
String | The personal government ID check digit value. | A single digit or < |
personalGovernmentIdVerified |
String | The indication if the personal government ID check digit contains a valid value. | true or false |
surname |
String | The data extracted from an MRZ field related to the surname of the person to which the document was issued. | None |
unparsedMachineReadableZone |
Object | An unparsed version of the Machine Readable Zone. | N/A |
mrzLine1 |
String | The first line of the MRZ. | None |
mrzLine2 |
String | The second line of the MRZ. | None |
mrzLine3 |
String | The third line of the MRZ. | None |
Expert Error Responses
400 Response Example
HTTP/1.1 400 Bad Request
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "Customer reference id should not exceed 500 characters."
}
OR
{
"message": "Missing image data."
}
OR
{
"message": "No images were provided."
}
OR
{
"message": "Please specify a valid dataType for deviceExtractedData."
}
OR
{
"message": "Unknown value "PDF417_STRING_VAL" for enum customerapi.DeviceExtractedData_DataType."
}
OR
{
"message": "Incorrect endpoint for request type."
}
401 Response Example
HTTP/1.1 401 Unauthorized
Content-Type: application/json
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"message": "The token is either invalid, malformed, inactive, or missing the required scopes."
}
404 Response Example
HTTP/1.1 404 Not Found
Content-Type: application/json
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"message": "The result you attempted to retrieve does not exist or has already been retrieved."
}
OR
{
"message": "Not Found"
}
408 Response Example
HTTP/1.1 408 Request Timeout
Content-Type: application/json
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"message": "Request Timeout"
}
413 Response Example
HTTP/1.1 413 Request Entity Too Large
Content-Type: application/json
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"message": "Request Entity Too Large"
}
415 Response Example
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
{
"message": "Please ensure you are specifying application/json as the Content-Type."
}
429 Response Example
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"message": "Too Many Requests"
}
500 Response Example
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"message": "An internal error has occurred. Please try again in a few minutes."
}
503 Service Unavailable
HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"message": "Service Unavailable"
}
Standard HTTP REST-based response codes and messages are used to indicate success or failure for a request.
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
message |
String | A message describing the error. | None |
Face Comparison - Auto
Each auto face comparison request provides the ability to compare the face present on an identity document with selfie(s) provided as part of the request. In addition, liveness detection can be enabled to determine if the selfie is from a live person. The API only supports providing up to two reference images and up to 3 selfies.
Face Comparison - Auto Request
Request Example
POST /identity/facecomparison/v3/auto HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
{
"transactionRequestId": "093ddee6-1a16-4da2-a09f-f4c16e20defa",
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"referenceImages": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
}
],
"selfieImages": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
}
]
}
Request Example with Liveness Detection
POST /identity/facecomparison/v3/auto HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
{
"configuration": {
"faceLiveness": true
},
"transactionRequestId": "093ddee6-1a16-4da2-a09f-f4c16e20defa",
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"referenceImages": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
}
],
"selfieImages": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
}
]
}
Request Example with Injection Attack Detection
POST /identity/facecomparison/v3/auto HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
{
"configuration": {
"injectionAttackDetection": ["selfieImages", "referenceImages"]
},
"transactionRequestId": "093ddee6-1a16-4da2-a09f-f4c16e20defa",
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"referenceImages": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ==",
"encryptedPayload": "QkFTRTY0IEVOQ09ERUQgRU5DUllQVEVEIFBBWUxPQUQ="
}
],
"selfieImages": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ==",
"encryptedPayload": "QkFTRTY0IEVOQ09ERUQgRU5DUllQVEVEIFBBWUxPQUQ="
}
]
}
URL
/identity/facecomparison/v3/auto
Required Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
referenceImages |
Object (array) | An array of images that are used as the reference for face comparison, these should be derived from a document previously submitted via mobile verify | Maximum of 2 reference images can be submitted per request |
data |
String | A base64-encoded image to be used as a reference to be compared against the selfie image(s) provided | |
encryptedPayload |
String | A base64-encoded string containing an encrypted real-time security payload generated by Mitek’s MiSnap Capture SDKs v.5.4.0 and newer. This field is only required if referenceImages is enabled in the Injection Attack Detection object in the request configuration |
|
selfieImages |
Object (array) | An array of base-64 encoded images of selfies to be verified | |
data |
String | A base64-encoded image of a selfie to be compared against the reference image provided | |
encryptedPayload |
String | A base64-encoded string containing an encrypted real-time security payload generated by Mitek’s MiSnap Capture SDKs v.5.4.0 and newer. This field is only required if selfieImages is enabled in the Injection Attack Detection object in the request configuration |
Optional Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
transactionRequestId |
String | A valid UUID for a previously submitted Mobile Verify (Auto, Manual, or Expert) request | UUID |
configuration |
Object | A dictionary of configuration options. | N/A |
faceLiveness |
Boolean | A value, that when set to true will enable face liveness detection to be performed on the given selfie(s). A |
true or false |
injectionAttackDetection |
Object | A list of image types enabled for injection attack detection to be performed on. An |
selfieImages, referenceImages |
customerReferenceId |
String | [OPTIONAL] Customer provided identifier that will be returned in an identically named field within the body of any subsequent responses | 500 characters limit |
Face Comparison - Auto Response
"MATCH" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: fc59ec41-cbdb-4438-9526-a7d6c7990647
{
"requestId": "fc59ec41-cbdb-4438-9526-a7d6c7990647",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"approval": "APPROVED",
"findings": {
"faceComparisonApproval": "MATCH"
}
}
"NOT_MATCH" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 47b9db6f-0099-436a-9200-67e7e55c8938
{
"requestId": "47b9db6f-0099-436a-9200-67e7e55c8938",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"approval": "NOT_APPROVED",
"findings": {
"faceComparisonApproval": "NOT_MATCH"
}
}
Face Liveness "NOT_LIVE" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 47b9db6f-0099-436a-9200-67e7e55c8938
{
"requestId": "47b9db6f-0099-436a-9200-67e7e55c8938",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"approval": "NOT_APPROVED",
"findings": {
"faceComparisonApproval": "MATCH",
"faceLivenessApproval": "NOT_LIVE"
}
}
Injection Attack Detection "NOT_PASS" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 47b9db6f-0099-436a-9200-67e7e55c8938
{
"requestId": "47b9db6f-0099-436a-9200-67e7e55c8938",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"approval": "NOT_APPROVED",
"findings": {
"faceComparisonApproval": "MATCH",
"faceLivenessApproval": "LIVE",
"injectionAttackDetectionApproval": "NOT_PASS"
}
}
"NOT_APPROVED" with "reasons" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 47b9db6f-0099-436a-9200-67e7e55c8938
{
"requestId": "47b9db6f-0099-436a-9200-67e7e55c8938",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"approval": "NOT_APPROVED",
"findings": {
"faceComparisonApproval": "NOT_MATCH",
"faceLivenessApproval": "NOT_LIVE",
"injectionAttackDetectionApproval": "NOT_PASS",
"reasons": [
"FACE_NOT_DETECTED_SELFIE_IMAGE",
"MISSING_ENCRYPTED_PAYLOAD"
]
}
}
Response Example with "referenceImageUsed"
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 47b9db6f-0099-436a-9200-67e7e55c8938
{
"requestId": "47b9db6f-0099-436a-9200-67e7e55c8938",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"approval": "APPROVED",
"findings": {
"faceComparisonApproval": "MATCH"
},
"referenceImageUsed": "fetched"
}
Deepfake Detection "NOT_LIVE" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: db169bbb-148c-489d-baad-828ff51c66af
{
"requestId": "db169bbb-148c-489d-baad-828ff51c66af",
"findings": {
"faceComparisonApproval": "MATCH",
"faceLivenessApproval": "LIVE",
"deepfakeDetectionApproval": "NOT_LIVE"
},
"approval": "NOT_APPROVED"
}
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
requestId |
String | The UUID assigned to the request | UUID |
customerReferenceId |
String | A value that will be returned within the body of subsequent responses. | N/A |
approval |
String | An overall service approval result taking all individual biometric checks into account.APPROVED: The value will be returned when all individual checks return a positive result.NOT_APPROVED: The value will be returned when any given check returns a negative result. |
APPROVED or NOT_APPROVED |
findings |
|||
faceComparisonApproval |
String | Service approval result containing auto face comparison judgement.MATCH: The value will be returned in case selfie photo matches portrait image of document holder.NOT_MATCH: The value will be returned in case selfie photo does not match portrait image of document holder. |
MATCH or NOT_MATCH |
faceLivenessApproval |
String | Service approval result containing face liveness detection judgement.LIVE: The value will be returned in case selfie photo is from a live person.NOT_LIVE: The value will be returned in case selfie is not from a live person -- e.g. if the selfie is a picture of a picture |
LIVE or NOT_LIVE |
injectionAttackDetectionApproval |
String | Service approval result containing injection attack detection judgement.PASS: The value will be returned in case injection is not detected on all of the images of the enabled image types.NOT_PASS: The value will be returned in case injection is detected on any of the images of the enabled image types. |
PASS or NOT_PASS |
deepfakeDetectionApproval |
String | Service approval result containing deepfake detection judgement.LIVE: The value will be returned in case selfie photo does not have evidence of a deepfake image.NOT_LIVE: The value will be returned in case selfie has evidence of a deepfake image or other digital manipulation. |
LIVE or NOT_LIVE |
reasons |
String (array) | The reasons that the service is unable to complete face comparison and/or face liveness detection.FACE_CROPPED_SELFIE_IMAGE: The complete face is not present in the selfie image. FACE_NOT_DETECTED_REFERENCE_IMAGE: The face could not be detected in the reference image.FACE_NOT_DETECTED_SELFIE_IMAGE: The face could not be detected in the selfie image.FACE_TOO_CLOSE_SELFIE_IMAGE: The face in the selfie image is too close to the camera.FACE_TOO_FAR_SELFIE_IMAGE: The face in the selfie image is too far from the camera.FACE_ANGLE_TOO_LARGE_SELFIE_IMAGE: The angle between the face and camera is too large in the selfie image.QUALITY_TOO_LOW_SELFIE_IMAGE: The selfie has failed the image quality check.TOO_MANY_FACES_SELFIE_IMAGE: More than one face was detected in the selfie image.MISSING_ENCRYPTED_PAYLOAD: The required encrypted payload associated with any image of the enabled image types was not submitted in the service request. |
FACE_CROPPED_SELFIE_IMAGE, FACE_NOT_DETECTED_REFERENCE_IMAGE, FACE_NOT_DETECTED_SELFIE_IMAGE, FACE_TOO_CLOSE_SELFIE_IMAGE, FACE_TOO_FAR_SELFIE_IMAGE, FACE_ANGLE_TOO_LARGE_SELFIE_IMAGE, QUALITY_TOO_LOW_SELFIE_IMAGE, TOO_MANY_FACES_SELFIE_IMAGE, or MISSING_ENCRYPTED_PAYLOAD. |
referenceImageUsed |
String | This field is only returned for tenants with the feature enabled to reference a Mobile Verify Auto Derived Cropped Portrait.fetched: Will be returned when a fetched cropped portrait from a previous mobile verify transaction is used for face comparison.submitted: Will be returned when the original submitted document image is used for face comparison, i.e. whenever a derived cropped portrait cannot be obtained or in cases where we fall back to using the submitted image when a face cannot be found in the fetched cropped portrait. |
fetched or submitted |
Face Comparison - Auto Error Responses
400 Response Example
HTTP/1.1 400 Bad Request
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "Customer reference id should not exceed 500 characters."
}
OR
{
"message": "Too many reference images included in request."
}
OR
{
"message": "Too many selfies included in request."
}
OR
{
"message": "No reference images were provided."
}
OR
{
"message": "No selfie images were provided."
}
OR
{
"message": "Missing image data."
}
OR
{
"message": "The selfie image could not be encoded."
}
OR
{
"message": "The reference image base64 string could not be decoded."
}
OR
{
"message": "The selfie image base64 string could not be decoded."
}
OR
{
"message": "Invalid transactionRequestID."
}
OR
{
"message": "Invalid configuration value provided for Injection Attack Detection; allowed values are: [selfieImages, referenceImages]"
}
401 Response Example
HTTP/1.1 401 Unauthorized
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "The token is either invalid, malformed, inactive, or missing the required scopes."
}
403 Response Example
HTTP/1.1 403 Forbidden
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "Face liveness detection is not enabled for your account."
}
OR
{
"message": "Injection Attack Detection is not enabled on your account. Please contact support to resolve."
}
404 Response Example
HTTP/1.1 404 Not Found
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "Not Found"
}
408 Response Example
HTTP/1.1 408 Request Timeout
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "Request Timeout"
}
413 Response Example
HTTP/1.1 413 Request Entity Too Large
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "Request Entity Too Large"
}
415 Response Example
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
{
"message": "Please ensure you are specifying application/json as the Content-Type."
}
429 Response Example
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "Too Many Requests"
}
500 Response Example
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "An internal error has occurred. Please try again in a few minutes."
}
503 Service Unavailable
HTTP/1.1 503 Service Unavailable
Content-Type: text/plain
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
Service Unavailable
OR
HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "Service Unavailable"
}
Standard HTTP REST-based response codes and messages are used to indicate success or failure for a request.
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
message |
String | A message describing the error. | None |
Face Comparison - Manual
Each manual face comparison request provides the ability to compare the face present on an identity document with selfie(s) provided as part of the request. The API only supports providing up to two reference images and up to 3 selfies. NOTE: The API requires a valid Mobile Verify (Auto, Manual or Expert) request ID to be included in the request.
Face Comparison - Manual Request
Request Example (without Injection Attack Detection)
POST /identity/facecomparison/v3/manual HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
{
"transactionRequestId": "093ddee6-1a16-4da2-a09f-f4c16e20defa",
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"referenceImages": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
}
],
"selfieImages": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
]
}
Request Example (Injection Attack Detection requested for both reference and selfie images)
POST /identity/facecomparison/v3/manual HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
{
"transactionRequestId": "093ddee6-1a16-4da2-a09f-f4c16e20defa",
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"referenceImages": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ==",
"encryptedPayload": "WyJVVWlsWGQ3bWhoWVJXc1lGZFRuUjlh"
},
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ==",
"encryptedPayload": "WyJVVWlsWGQ3bWhoWVJXc1lGZFRuUjlh"
}
],
"selfieImages": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ==",
"encryptedPayload": "WyJVVWlsWGQ3bWhoWVJXc1lGZFRuUjlh"
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA=",
"encryptedPayload": "AiLCJPRENFbmFibGVkIjp0cnVlLCJSZW"
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA=",
"encryptedPayload": "AiLCJPRENFbmFibGVkIjp0cnVlLCJSZW"
}
],
"configuration": {
"injectionAttackDetection": ["referenceImages", "selfieImages"]
}
}
URL
/identity/facecomparison/v3/manual
Required Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
referenceImages |
Object (array) | An array of images that are used as the reference for face comparison, these should be derived from a document previously submitted via mobile verify | Maximum of 2 reference images can be submitted per request |
data |
String | A base64-encoded image to be used as a reference to be compared against the selfie image(s) provided | |
encryptedPayload |
String | A base64-encoded string containing an encrypted real-time security payload generated by Mitek’s MiSnap Capture SDKs v.5.4.0 and newer. This field is only required if referenceImages is enabled in the Injection Attack Detection object in the request configuration. |
|
selfieImages |
Object (array) | An array of base-64 encoded images of selfies to be verified | |
data |
String | A base64-encoded image of a selfie to be compared against the reference image provided | |
encryptedPayload |
String | A base64-encoded string containing an encrypted real-time security payload generated by Mitek’s MiSnap Capture SDKs v.5.4.0 and newer. This field is only required if selfieImages is enabled in the Injection Attack Detection object in the request configuration. |
Optional Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
transactionRequestId |
String | A valid UUID for a previously submitted Mobile Verify (Auto, Manual or Expert) request | UUID |
customerReferenceId |
String | [OPTIONAL] Customer provided identifier that will be returned in an identically named field within the body of any subsequent responses | 500 characters limit |
configuration |
Object | A dictionary of configuration options. | |
injectionAttackDetection |
Object | A list of image types enabled for injection attack detection to be performed on. | selfieImages, referenceImages |
Face Comparison - Manual Response
Response Example
HTTP/1.1 201 Created
Content-Type: application/json
{
"transactionRequestId": "093ddee6-1a16-4da2-a09f-f4c16e20defa",
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER"
}
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
transactionRequestId |
String | The UUID for the previously submitted Mobile Verify (Auto, Manual or Expert) request that this transaction will be associated with | UUID |
requestId |
String | The UUID assigned to this request | UUID |
customerReferenceId |
String | [OPTIONAL] The customer reference ID value that was submitted with the original request | N/A |
Face Comparison - Manual Retrieval Request
Request Example
GET /identity/facecomparison/v3/manual/093ddee6-1a16-4da2-a09f-f4c16e20defa HTTP/1.1
Authorization: Bearer $OAUTH_TOKEN
Results retrieval is the final step in retrieving the final results from a manual request. To retrieve the final result from the platform, a GET request is submitted to the API with the retrievalID that is returned from the polling API (NOTE: The retrievalId is not the same as the requestId). The results will be available from the retrieval end-point for one retrieval, once retrieval has completed, the results will be evicted from the retrieval infrastructure preventing any additional retrieval requests from being successful. Additionally, if the result has not been retrieved within 7 days of the result being made available, the result will no longer be accessible from the API.
URL
/identity/facecomparison/v3/manual/{retrievalId}
Required Attributes
| Name | Type | Description | Restrictions |
|---|---|---|---|
retrievalId |
String | Unique identifier used for the retrieval of the final result. For details of the retrieval ID, see this section here. | UUID |
Face Comparison - Manual Response
"MATCH", "LIVE" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: fc59ec41-cbdb-4438-9526-a7d6c7990647
{
"requestId": "fc59ec41-cbdb-4438-9526-a7d6c7990647",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "ACCEPTED"
},
"findings": {
"faceComparisonApproval": "MATCH"
"faceLivenessApproval": "LIVE"
}
}
"NOT_MATCH", "NOT_LIVE" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: fc59ec41-cbdb-4438-9526-a7d6c7990647
{
"requestId": "fc59ec41-cbdb-4438-9526-a7d6c7990647",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "ACCEPTED"
},
"findings": {
"faceComparisonApproval": "NOT_MATCH"
"faceLivenessApproval": "NOT_LIVE"
}
}
"REJECTED" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": " REJECTED",
"reasons": [
"POOR_CONTRAST",
"POOR_EXPOSURE",
"OUT_OF_FOCUS",
"GLARE",
"MISSING_SELFIE",
"MISSING_PORTRAIT",
"NOT_HUMAN_FACE",
"PARTIALLY_VISIBLE_HUMAN_FACE",
"SELFIE_NOT_LIVE",
"PORTRAIT_IS_FAKE"
]
}
}
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
requestId |
String | The UUID assigned to the request | UUID |
customerReferenceId |
String | A value that will be returned within the body of subsequent responses. | N/A |
acceptance |
|||
result |
String | Determination of whether the images provided were of sufficient quality to be processed | ACCEPTED, REJECTED |
reasons |
String (array) | MISSING_SELFIE: One or more images are missing selfie for processing face comparison. Please retake live selfie image before resubmitting them.MISSING_PORTRAIT: One or more document images are missing portrait required for processing face comparison. Please retake document image containing portrait before resubmitting them.NOT_HUMAN_FACE: One or more document images have portrait without human face for processing face comparison. Please retake document image containing human face portrait before resubmitting them.PARTIALLY_VISIBLE_HUMAN_FACE: One or more of the submitted images could not be processed due to a human face that is only partially visible. Please retake the images containing the complete human face portrait before resubmitting them.PORTRAIT_IS_FAKE: One or more document images have a portrait with strong evidence of forgery and is thus not eligible for face comparison Please retake the live document image containing a real portrait before resubmitting them.SELFIE_NOT_LIVE: One or more selfies are deemed not live which is not eligible for face comparison. Please recapture the live selfie image before resubmitting them.OUT_OF_FOCUS: One or more of the submitted images could not be processed due to the image being out of focus. Please retake the images before resubmitting them.POOR_CONTRAST: One or more of the submitted images could not be processed due to the image having poor contrast. Please retake the images before resubmitting them.POOR_EXPOSURE: One or more of the submitted images could not be processed due to the image having poor exposure. Please retake the images before resubmitting them.GLARE: One or more of the submitted images could not be processed due to the image having glare on essential elements. Please retake the images before resubmitting them.INJECTION_ATTACK_DETECTED: An injection attack was detected in one or more of the submitted images. Please do not resubmit. |
MISSING_SELFIE, MISSING_PORTRAIT, NOT_HUMAN_FACE, PARTIALLY_VISIBLE_HUMAN_FACE, PORTRAIT_IS_FAKE, SELFIE_NOT_LIVE, OUT_OF_FOCUS, POOR_CONTRAST, POOR_EXPOSURE, GLARE or INJECTION_ATTACK_DETECTED. |
findings |
|||
faceComparisonApproval |
String | Service approval result containing manual comparison judgement .MATCH: The value will be returned in case selfie photo matches portrait image of document holder.NOT_MATCH: The value will be returned in case selfie photo does not match portrait image of document holder. |
MATCH or NOT_MATCH |
faceLivenessApproval |
String | Service approval result containing automatic liveness judgement .LIVE: The value will be returned in case selfie photo is considered to be a live photo.NOT_LIVE: The value will be returned in case selfie photo is considered to be not a live photo. |
LIVE or NOT_LIVE |
Face Comparison - Manual Error Responses
400 Response Example
HTTP/1.1 400 Bad Request
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "Customer reference id should not exceed 500 characters."
}
OR
{
"message": "Invalid transactionRequestID."
}
OR
{
"message": "Too many reference images included in request."
}
OR
{
"message": "No selfie images were provided."
}
OR
{
"message": "Too many selfies included in request."
}
OR
{
"message": "Maximum document image size exceeded."
}
OR
{
"message": "Missing image data."
}
OR
{
"message": "No reference images were provided."
}
401 Response Example
HTTP/1.1 401 Unauthorized
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "The token is either invalid, malformed, inactive, or missing the required scopes."
}
404 Response Example
HTTP/1.1 404 Not Found
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "The result you attempted to retrieve does not exist or has already been retrieved."
}
OR
{
"message": "Not Found"
}
408 Response Example
HTTP/1.1 408 Request Timeout
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "Request Timeout"
}
413 Response Example
HTTP/1.1 413 Request Entity Too Large
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "Request Entity Too Large"
}
415 Response Example
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
{
"message": "Please ensure you are specifying application/json as the Content-Type."
}
429 Response Example
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "Too Many Requests"
}
500 Response Example
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "An internal error has occurred. Please try again in a few minutes."
}
503 Service Unavailable
HTTP/1.1 503 Service Unavailable
Content-Type: text/plain
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
Service Unavailable
OR
HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"message": "Service Unavailable"
}
Standard HTTP REST-based response codes and messages are used to indicate success or failure for a request.
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
message |
String | A message describing the error. | None |
Polling
Mitek has implemented a polling approach for the retrieval of results via our asynchronous APIs. The polling API provides details of the state of all currently in-process and completed transactions to customers on a per-tenant basis. Completed transactions will be available for a limited amount of time. When leveraging the API, Mitek recommends a polling interval of 5 seconds and will start to return a 429 response if polling exceeds 1 API call per second.
Polling Request
Request Example
GET /identity/v3/poll HTTP/1.1
Authorization: Bearer $OAUTH_TOKEN
Polling is implemented as a simple GET operation on the polling end-point and will return a list of current transactions for the tenant with details of their current status (PROCESSING, COMPLETED, or ERROR).
URL
/identity/v3/poll
Polling Response
Response Example
HTTP/1.1 200 OK
Content-Type: application/json;
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"requests": [
{
"service": "VERIFY_MANUAL"
"requestId": "4d6a4dc2-a756-4479-99c2-a856b41456c6",
"customerReferenceId": "CUSTOMER PROVIDED REFERENCE ID",
"retrievalId": "4c52b0ef-aa28-4675-85d7-207b00486520",
"status": "COMPLETED"
},
{
"service": "VERIFY_EXPERT"
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED REFERENCE ID",
"retrievalId": "1a55b710-def3-4bc2-89c8-17cefd8c7c98",
"status": "COMPLETED"
}
]
}
All of Mitek's asynchronous APIs leverage a polling approach for statusing and retrieval of responses. Each request to the polling API will return the details of all current documents that are in process with their associated status (PROCESSING, COMPLETED, or ERROR). The polling response will only return the details of those documents that have not yet completed or have not yet been retrieved from the platform. Once final results have been retrieved from the retrieval end-point, the polling API will no longer return the transaction status in the response. Furthermore, completed transactions will be deleted after seven days. The transaction has to be resubmitted after that period of time to recreate the results.
Returned HTTP Headers
| Name | Type | Description | Restrictions |
|---|---|---|---|
Mitek-Server-Processing-Time |
Number | The total duration, in milliseconds, from the time the entire request was received until the response was sent. | None |
Mitek-Request-Id |
String | The UUID assigned to the request. | UUID |
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
requests |
|||
requestId |
String | The UUID assigned to the request. | UUID |
customerReferenceId |
String | The optional CustomerReferenceID value that was submitted with the original request. | None |
service |
String | Type of service requested
|
VERIFY, VERIFY_MANUAL, VERIFY_EXPERT, FILL_MANUAL or FACECOMPARE_MANUAL |
retrievalId |
String | Unique identifier used for the retrieval of the final result | UUID |
status |
String | Current status of the transaction
|
PROCESSING, COMPLETED, or ERROR |
Polling Error Responses
401 Response Example
HTTP/1.1 401 Unauthorized
Content-Type: application/json
Mitek-Request-Id: 1068a8af-4ef7-4507-98a2-8334657b2bc4
{
"requestId": "1068a8af-4ef7-4507-98a2-8334657b2bc4",
"message": "The token is either invalid, malformed, inactive, or missing the required scopes"
}
403 Response Example
HTTP/1.1 403 Forbidden
Content-Type: application/json
Mitek-Request-Id: 1068a8af-4ef7-4507-98a2-8334657b2bc4
{
"requestId": "1068a8af-4ef7-4507-98a2-8334657b2bc4",
"message": "Forbidden"
}
408 Response Example
HTTP/1.1 408 Request Timeout
Content-Type: text/plain
Mitek-Request-Id: 1068a8af-4ef7-4507-98a2-8334657b2bc4
Request Timeout
429 Response Example
HTTP/1.1 429 Too Many Requests
Content-Type: text/plain
Mitek-Request-Id: 1068a8af-4ef7-4507-98a2-8334657b2bc4
Too Many Requests
500 Response Example
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Mitek-Request-Id: 1068a8af-4ef7-4507-98a2-8334657b2bc4
{
"message": "An internal error has occurred. Please try again in a few minutes."
}
503 Service Unavailable
HTTP/1.1 503 OK
Content-Type: text/plain
Mitek-Request-Id: 1068a8af-4ef7-4507-98a2-8334657b2bc4
Service Unavailable
Standard HTTP REST-based response codes and messages are used to indicate success or failure for a request.
Canned Responses
The canned response service will return an automated predefined response that is intended for testing and development purposes. This service will only be available in sand-box environments and not in production environments. Each transaction will have an added delay, to simulate real-life traffic conditions.
To receive a canned response, a custom header is required with the name canned-response, with one of following values: APPROVED, NOT_APPROVED, REJECTED. The response will vary based on the canned-response value, and selected product endpoint Also canned-reasons header can be set to determine corresponding reject or fraud reasons if the canned-response value is REJECTED or NOT_APPROVED.
Required header
| Name | Type | Description | Restrictions |
|---|---|---|---|
canned-response |
String | This header will determine the type of response and should be one of the following values: APPROVED, NOT_APPROVED, REJECTED. If the supplied value is REJECTED, the the service will return all corresponding reject reasons. |
N/A |
Optional header
| Name | Type | Description | Restrictions |
|---|---|---|---|
canned-reasons |
[]String | This header will return corresponding reject or fraud reasons if the supplied value is REJECTED or NOT_APPROVED. As a sample it can be like UNSUPPORTED_DOCUMENT_TYPE, SECURITY_FEATURES_NOT_VISIBLE, NOT_A_DOCUMENT for rejected reasons and like EVIDENCE_OF_FORGERY_SIGNATURE, EVIDENCE_OF_FORGERY_BLACK_AND_WHITE_COPY, EXPIRED_OR_INVALIDATED for fraud reasons. |
Is applicable when canned-response has values of REJECTED or NOT_APPROVED |
Canned Mobile Verify
Canned Mobile Verify provides the capability to receive an automated and predefined response based on the Mitek Identity Cloud API. When reviewing documents submitted, the canned response service will return a series of canned verification results (depending on the value of the canned-response and canned-reasons (if provided) headers) and return canned Authenticity, Originality and Validity results.
"APPROVED" Request Example
POST /identity/verify/v3/id-document HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
canned-response: APPROVED
{
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"images": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
],
"deviceExtractedData": [
{
"dataType": "PDF417_STRING",
"data": "PDF417 STRING"
}
]
}
Mobile Verify Request
URL
/identity/verify/v3/id-document
Required Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
images |
Object (array) | An array of base64-encoded images of the document to be verified. | N/A |
data |
String | A base64-encoded image containing a single page of the document to be processed. |
Optional Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
String | [OPTIONAL] Customer provided identifier that will be returned in an identically named field within the body of any subsequent responses | 500 characters limit |
deviceExtractedData |
Object (array) | [OPTIONAL] An array of data extracted on-device from an identity document from machine-readable document features, e.g., barcode. | N/A |
datatype |
String | The type of data being passed for processing. This is commonly barcode details or other machine-encoded data that has been read on-device as part of the initial capture experience. Currently supported data types include:
|
PDF417_STRING |
Mobile Verify Response
"APPROVED" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "ACCEPTED"
},
"findings": {
"documentApproval": "APPROVED",
"details": {
"authenticity": {
"result": "AUTHENTIC"
},
"originality": {
"result": "ORIGINAL"
},
"validity": {
"result": "VALID"
}
}
},
"extractedData": {
"documentAttributes": {
"countryCodeOfIssuance": "USA",
"dateOfExpiry": "2165-08-28",
"dateOfIssuance": "1965-08-28",
"documentNumber": "90933633",
"documentType": "DRIVERS_LICENSE",
"issuingAuthority": "CALIFORNIA DMV",
"stateOrProvinceOfIssuance": "CA"
},
"personAttributes": {
"dateOfBirth": "1965-08-28",
"gender": "F",
"nationalityCode": "GBR",
"personalGovernmentId": "123435534",
"placeOfBirth": "LONDON"
},
"name": {
"firstSurname": "LORCA SANCHEZ",
"fullName": "JUANA LORCA SANCHEZ MENDOZA",
"givenNames": "JUANA",
"secondSurname": "MENDOZA",
"surname": "LORCA SANCHEZ MENDOZA"
},
"address": {
"unparsedAddress": {
"addressLine1": "123 MAIN ST",
"addressLine2": "SAN DIEGO CA 92101",
"addressLine3": "APT 4",
"addressLine4": "BLOCK 1"
}
},
"machineReadableZone": {
"parsedMachineReadableZone": {
"compositeCheckDigit": "0",
"compositeCheckDigitVerified": "true",
"dateOfBirth": "1967-07-04",
"dateOfBirthCheckDigit": "6",
"dateOfBirthVerified": "true",
"dateOfExpiry": "2016-08-07",
"dateOfExpiryCheckDigit": "8",
"dateOfExpiryVerified": "true",
"documentNumber": "340007955",
"documentNumberCheckDigit": "3",
"documentNumberVerified": "true",
"documentSubType": "",
"documentType": "P",
"gender": "F",
"givenNames": "HAPPY",
"stateOrProvinceOfIssuance": "USA",
"stateOrProvinceOfIssuanceVerified": "true",
"isValid": "true",
"nationalityCode": "USA",
"nationalityCodeVerified": "true",
"personalGovernmentId": "910000833 1119",
"personalGovernmentIdCheckDigit": "2",
"personalGovernmentIdVerified": "true",
"surname": "TRAVELER"
},
"unparsedMachineReadableZone": {
"mrzLine1": "P<USATRAVELER<<HAPPY<<<<<<<<<<<<<<<<<<<<<<<<",
"mrzLine2": "3400079553USA6707046F1608078910000833<111920",
"mrzLine3": "",
}
}
}
}
"NOT_APPROVED" Request Example
POST /identity/verify/v3/id-document HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
canned-response: NOT_APPROVED
{
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"images": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
],
"deviceExtractedData": [
{
"dataType": "PDF417_STRING",
"data": "PDF417 STRING"
}
]
}
"NOT_APPROVED" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "ACCEPTED"
},
"findings": {
"documentApproval": "NOT_APPROVED",
"details": {
"authenticity": {
"result": "NOT_AUTHENTIC",
"reasons": [
"EVIDENCE_OF_FORGERY_BIODATA_FONTS",
"EVIDENCE_OF_FORGERY_MRZ_FONTS",
"EVIDENCE_OF_FORGERY_PHOTO_ZONE",
"EVIDENCE_OF_FORGERY_SECURITY_FEATURES",
"EVIDENCE_OF_FORGERY_SIGNATURE",
"EVIDENCE_OF_FORGERY_NOT_HUMAN_FACE"
]
},
"originality": {
"result": "NOT_ORIGINAL",
"reasons": [
"EVIDENCE_OF_FORGERY_BLACK_AND_WHITE_COPY",
"EVIDENCE_OF_FORGERY_DOCUMENT_STRUCTURE"
]
},
"validity": {
"result": "NOT_VALID",
"reasons": [
"EVIDENCE_OF_FORGERY_DATA_COMPARISON",
"EVIDENCE_OF_FORGERY_MRZ_CHECKSUMS",
"EXPIRED_OR_INVALIDATED"
]
}
}
},
"extractedData": {
"documentAttributes": {
"countryCodeOfIssuance": "USA",
"dateOfExpiry": "2165-08-28",
"dateOfIssuance": "1965-08-28",
"documentNumber": "90933633",
"documentType": "DRIVERS_LICENSE",
"issuingAuthority": "CALIFORNIA DMV",
"stateOrProvinceOfIssuance": "CA"
},
"personAttributes": {
"dateOfBirth": "1965-08-28",
"gender": "F",
"nationalityCode": "GBR",
"personalGovernmentId": "123435534",
"placeOfBirth": "LONDON"
},
"name": {
"firstSurname": "LORCA SANCHEZ",
"fullName": "JUANA LORCA SANCHEZ MENDOZA",
"givenNames": "JUANA",
"secondSurname": "MENDOZA",
"surname": "LORCA SANCHEZ MENDOZA"
},
"address": {
"unparsedAddress": {
"addressLine1": "123 MAIN ST",
"addressLine2": "SAN DIEGO CA 92101",
"addressLine3": "APT 4",
"addressLine4": "BLOCK 1"
}
},
"machineReadableZone": {
"parsedMachineReadableZone": {
"compositeCheckDigit": "0",
"compositeCheckDigitVerified": "true",
"dateOfBirth": "1967-07-04",
"dateOfBirthCheckDigit": "6",
"dateOfBirthVerified": "true",
"dateOfExpiry": "2016-08-07",
"dateOfExpiryCheckDigit": "8",
"dateOfExpiryVerified": "true",
"documentNumber": "340007955",
"documentNumberCheckDigit": "3",
"documentNumberVerified": "true",
"documentSubType": "",
"documentType": "P",
"gender": "F",
"givenNames": "HAPPY",
"stateOrProvinceOfIssuance": "USA",
"stateOrProvinceOfIssuanceVerified": "true",
"isValid": "true",
"nationalityCode": "USA",
"nationalityCodeVerified": "true",
"personalGovernmentId": "910000833 1119",
"personalGovernmentIdCheckDigit": "2",
"personalGovernmentIdVerified": "true",
"surname": "TRAVELER"
},
"unparsedMachineReadableZone": {
"mrzLine1": "P<USATRAVELER<<HAPPY<<<<<<<<<<<<<<<<<<<<<<<<",
"mrzLine2": "3400079553USA6707046F1608078910000833<111920",
"mrzLine3": "",
}
}
}
}
"NOT_APPROVED" Request with canned reasons header Example
POST /identity/verify/v3/id-document HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
canned-response: NOT_APPROVED
canned-reasons: EVIDENCE_OF_FORGERY_SIGNATURE, EVIDENCE_OF_FORGERY_BLACK_AND_WHITE_COPY, EXPIRED_OR_INVALIDATED
{
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"images": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
],
"deviceExtractedData": [
{
"dataType": "PDF417_STRING",
"data": "PDF417 STRING"
}
]
}
"NOT_APPROVED" Response with canned reasons header Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "ACCEPTED"
},
"findings": {
"documentApproval": "NOT_APPROVED",
"details": {
"authenticity": {
"result": "NOT_AUTHENTIC",
"reasons": [
"EVIDENCE_OF_FORGERY_SIGNATURE"
]
},
"originality": {
"result": "NOT_ORIGINAL",
"reasons": [
"EVIDENCE_OF_FORGERY_BLACK_AND_WHITE_COPY"
]
},
"validity": {
"result": "NOT_VALID",
"reasons": [
"EXPIRED_OR_INVALIDATED"
]
}
}
},
"extractedData": {
"documentAttributes": {
"countryCodeOfIssuance": "USA",
"dateOfExpiry": "2165-08-28",
"dateOfIssuance": "1965-08-28",
"documentNumber": "90933633",
"documentType": "DRIVERS_LICENSE",
"issuingAuthority": "CALIFORNIA DMV",
"stateOrProvinceOfIssuance": "CA"
},
"personAttributes": {
"dateOfBirth": "1965-08-28",
"gender": "F",
"nationalityCode": "GBR",
"personalGovernmentId": "123435534",
"placeOfBirth": "LONDON"
},
"name": {
"firstSurname": "LORCA SANCHEZ",
"fullName": "JUANA LORCA SANCHEZ MENDOZA",
"givenNames": "JUANA",
"secondSurname": "MENDOZA",
"surname": "LORCA SANCHEZ MENDOZA"
},
"address": {
"unparsedAddress": {
"addressLine1": "123 MAIN ST",
"addressLine2": "SAN DIEGO CA 92101",
"addressLine3": "APT 4",
"addressLine4": "BLOCK 1"
}
},
"machineReadableZone": {
"parsedMachineReadableZone": {
"compositeCheckDigit": "0",
"compositeCheckDigitVerified": "true",
"dateOfBirth": "1967-07-04",
"dateOfBirthCheckDigit": "6",
"dateOfBirthVerified": "true",
"dateOfExpiry": "2016-08-07",
"dateOfExpiryCheckDigit": "8",
"dateOfExpiryVerified": "true",
"documentNumber": "340007955",
"documentNumberCheckDigit": "3",
"documentNumberVerified": "true",
"documentSubType": "",
"documentType": "P",
"gender": "F",
"givenNames": "HAPPY",
"stateOrProvinceOfIssuance": "USA",
"stateOrProvinceOfIssuanceVerified": "true",
"isValid": "true",
"nationalityCode": "USA",
"nationalityCodeVerified": "true",
"personalGovernmentId": "910000833 1119",
"personalGovernmentIdCheckDigit": "2",
"personalGovernmentIdVerified": "true",
"surname": "TRAVELER"
},
"unparsedMachineReadableZone": {
"mrzLine1": "P<USATRAVELER<<HAPPY<<<<<<<<<<<<<<<<<<<<<<<<",
"mrzLine2": "3400079553USA6707046F1608078910000833<111920",
"mrzLine3": "",
}
}
}
}
"REJECTED" Request Example
POST /identity/verify/v3/id-document HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
canned-response: REJECTED
{
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"images": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
],
"deviceExtractedData": [
{
"dataType": "PDF417_STRING",
"data": "PDF417 STRING"
}
]
}
"REJECTED" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "REJECTED",
"reasons": [
"GLARE",
"INCOMPLETE_DOCUMENT",
"NOT_VISIBLE_FOUR_CORNERS",
"NOT_VISIBLE_SECURITY_FEATURES",
"OUT_OF_FOCUS",
"POOR_CONTRAST",
"POOR_EXPOSURE",
"UNCLASSIFIED_DOCUMENT",
"UNREADABLE_FIELD",
"UNSUPPORTED_LANGUAGE"
]
}
}
"REJECTED" Request with canned reasons header Example
POST /identity/verify/v3/id-document HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
canned-response: REJECTED
canned-reasons: UNCLASSIFIED_DOCUMENT, UNREADABLE_FIELD, UNSUPPORTED_LANGUAGE
{
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"images": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
],
"deviceExtractedData": [
{
"dataType": "PDF417_STRING",
"data": "PDF417 STRING"
}
]
}
"REJECTED" Response with canned reasons header Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "REJECTED",
"reasons": [
"UNCLASSIFIED_DOCUMENT",
"UNREADABLE_FIELD",
"UNSUPPORTED_LANGUAGE"
]
}
}
Returned HTTP Headers
| Name | Type | Description | Restrictions |
|---|---|---|---|
Mitek-Server-Processing-Time |
Number | The total duration, in milliseconds, from the time the entire request was received until the response was sent. | None |
Mitek-Request-Id |
String | The UUID assigned to the request. | UUID |
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
requestId |
String | The UUID assigned to the request. | UUID |
customerReferenceId |
String | The value that was submitted with the original request. | None |
acceptance |
Object | Based on the value of the canned-response header, the canned response will return a result of either REJECTED or ACCEPTED. |
N/A |
result |
String | The determinition of whether all of the images submitted were deemed acceptable for processing. Based on the |
N/A |
reasons |
String (array) | When the |
N/A |
findings |
Object | The following fields are related to the canned results from the processing of the document. This includes the canned document approval and a detailed summary of the canned authenticity, originality and the validity findings that contributed to the document approval result. | N/A |
documentApproval |
String | The canned document approval determination. Based on the |
N/A |
details |
Object | The details of the canned authenticity, originality, and validity that were performed. | N/A |
authenticity |
Object | The details of the canned authenticity that were performed. | N/A |
result |
String | The canned authenticity result of the document. Based on the |
N/A |
reasons |
String (array) | The reasons that a result of |
N/A |
originality |
Object | The details of the originality checks that were canned. | N/A |
result |
String | The canned originality result of the document. Either |
ORIGINAL or NOT_ORIGINAL |
reasons |
String (array) | The reasons that a canned result of |
N/A |
validity |
Object | The details of the canned validity checks that were performed. | N/A |
result |
String | The validity result of the processed document. Will be eitherVALID or NOT_VALID Based on the setting privided to the canned-response header. |
N/A |
reasons |
String (array) | If the value of |
N/A |
extractedData |
Object | A canned response of the data extracted from the submitted document. | N/A |
documentAttributes |
Object | The canned response related to attributes of the document. | N/A |
countryCodeOfIssuance |
String | The canned response related to the ISO code of the country that issued the document. | None |
dateOfExpiry |
String | The canned response related to the date of expiry of the document, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
dateOfIssuance |
String | The canned response related to the date of issuance of the document, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
documentNumber |
String | The canned response related to the number or identifier of the document. | None |
documentType |
String (array) | The type of document that was submitted. |
PASSPORT, DRIVERS_LICENSE, IDENTITY_CARD, RESIDENCE_PERMIT, HEALTH_SERVICES_CARD |
issuingAuthority |
String | The canned response related to the name of the authority or organization that issued the document. | None |
stateOrProvinceOfIssuance |
String | The canned response related to the name of the state, province, or region that issued the document. | None |
personAttributes |
Object | The canned response related to the person to whom the document was issued. | N/A |
dateOfBirth |
String | The canned response related to the date of birth of the person to which the document was issued, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
gender |
String | The canned response related to the gender of the person to which the document was issued, normalized into one of the following values: |
M, F, or N/B |
nationalityCode |
String | The canned response related to the ISO country code of the nationality of the person to which the document was issued. | None |
personalGovernmentId |
String | The canned response related to any government identification number of the person to which the document was issued. | None |
placeOfBirth |
String | The canned response related to the place of birth of the person to which the document was issued. | None |
name |
Object | The canned response related to the name of whom the document was issued. | N/A |
fullName |
String | The canned response related to the full name of the person to which the document was issued. | None |
givenNames |
String | The canned response related to the given names of the person to which the document was issued. | |
firstSurname |
String | The canned response related to the first surname of the person to which the document was issued. | None |
secondSurname |
String | The canned response related to the second surname of the person to which the document was issued. | None |
surname |
String | The canned response related to the surname of the person to which the document was issued. | None |
address |
Object | The canned response related to the address of the person to whom the document was issued. | N/A |
unparsedAddress |
Object | An unparsed version of the address of the person to whom the document was issued. | N/A |
addressLine1 |
String | The canned response related to the first line of the address, as printed, of the person to which the document was issued. | None |
addressLine2 |
String | The canned response related to the second line of the address, as printed, of the person to which the document was issued. | None |
addressLine3 |
String | The canned response related to the third line of the address, as printed, of the person to which the document was issued. | None |
addressLine4 |
String | The canned response related to the fourth line of the address, as printed, of the person to which the document was issued. | None |
machineReadableZone |
Object | The data extracted from the Machine Readable Zone of the submitted document. | N/A |
parsedMachineReadableZone |
Object | A parsed version of the Machine Readable Zone. | N/A |
compositeCheckDigit |
String | The composite check digit value. | A single digit or < |
compositeCheckDigitVerified |
String | The indication if the composite check digit contains a valid value. | true or false |
dateOfBirth |
String | The data extracted from an MRZ field related to the date of birth of the person to which the document was issued, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
dateOfBirthCheckDigit |
String | The date of birth check digit value. | A single digit or < |
dateOfBirthVerified |
String | The indication if the date of birth check digit contains a valid value. | true or false |
dateOfExpiry |
String | The data extracted from an MRZ field related to the date of expiry of the document, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
dateOfExpiryCheckDigit |
String | The date of expiry check digit value. | A single digit or < |
dateOfExpiryVerified |
String | The indication if the date of expiry check digit contains a valid value. | true or false |
documentNumber |
String | The data extracted from an MRZ field related to the number or identifier of the document. | None |
documentNumberCheckDigit |
String | The document number check digit value. | A single digit or < |
documentNumberVerified |
String | The indication if the document number check digit contains a valid value. | true or false |
documentSubType |
String | The data extracted from an MRZ field related to the sub type of the document. | None |
documentType |
String (array) | The data extracted from an MRZ field related to the type of document that was submitted. |
None |
gender |
String | The data extracted from an MRZ field related to the gender of the person to which the document was issued, normalized into one of the following values: |
M, F, or N/B |
givenNames |
String | The data extracted from an MRZ field related to the given names of the person to which the document was issued. | |
stateOrProvinceOfIssuance |
String | The data extracted from an MRZ field related to the ISO country code of the country that issued the document. | None |
stateOrProvinceOfIssuanceVerified |
String | The indication if the issuing state or organization contains a valid value. | true or false |
isValid |
String | The parsed out state or province of the address of the person to whom the document was issued. | None |
nationalityCode |
String | The data extracted from an MRZ field related to the ISO country code of the nationality of the person to which the document was issued. | None |
nationalityCodeVerified |
String | The indication if the nationality contains a valid value. | true or false |
personalGovernmentId |
String | The data extracted from an MRZ field related to any government identification number of the person to which the document was issued. | None |
personalGovernmentIdCheckDigit |
String | The personal government ID check digit value. | A single digit or < |
personalGovernmentIdVerified |
String | The indication if the personal government ID check digit contains a valid value. | true or false |
surname |
String | The data extracted from an MRZ field related to the surname of the person to which the document was issued. | None |
unparsedMachineReadableZone |
Object | An unparsed version of the Machine Readable Zone. | N/A |
mrzLine1 |
String | The first line of the MRZ. | None |
mrzLine2 |
String | The second line of the MRZ. | None |
mrzLine3 |
String | The third line of the MRZ. | None |
Canned Mobile Verify - Manual
Canned Mobile Verify Manual provides the capability to have an automated predefined response based on the the Mitek Identity Cloud API. Automated responses will be returned, based on real-life checks (Authenticity, Originality and Validity) of the document.
"APPROVED" Request Example
POST /identity/verify/v3/id-document/manual HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
canned-response: APPROVED
{
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"images": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
],
"deviceExtractedData": [
{
"dataType": "PDF417_STRING",
"data": "PDF417 STRING"
}
]
}
Mobile Verify - Manual Request
URL
/identity/verify/v3/id-document/manual
Required Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
images |
Object (array) | An array of base64-encoded images of the document to be verified. | N/A |
data |
String | A base64-encoded image containing a single page of the document to be processed. |
Optional Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
String | [OPTIONAL] Customer provided identifier that will be returned in an identically named field within the body of any subsequent responses | 500 characters limit |
deviceExtractedData |
Object (array) | [OPTIONAL] An array of data extracted on-device from an identity document from machine-readable document features, e.g., barcode. | N/A |
datatype |
String | The type of data being passed for processing. This is commonly barcode details or other machine-encoded data that has been read on-device as part of the initial capture experience. Currently supported data types include:
|
PDF417_STRING |
Mobile Verify - Manual Response
"APPROVED" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"requestId": "4d6a4dc2-a756-4479-99c2-a856b41456c6",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "ACCEPTED"
},
"findings": {
"documentApproval": "APPROVED",
"details": {
"authenticity": {
"result": "AUTHENTIC"
},
"originality": {
"result": "ORIGINAL"
},
"validity": {
"result": "VALID"
}
}
},
"extractedData": {
"documentAttributes": {
"countryCodeOfIssuance": "USA",
"dateOfExpiry": "2165-08-28",
"dateOfIssuance": "1965-08-28",
"documentNumber": "90933633",
"documentType": "DRIVERS_LICENSE",
"issuingAuthority": "CALIFORNIA DMV",
"stateOrProvinceOfIssuance": "CA"
},
"personAttributes": {
"dateOfBirth": "1965-08-28",
"gender": "F",
"nationalityCode": "GBR",
"personalGovernmentId": "123435534",
"placeOfBirth": "LONDON"
},
"name": {
"firstSurname": "LORCA SANCHEZ",
"fullName": "JUANA LORCA SANCHEZ MENDOZA",
"givenNames": "JUANA",
"secondSurname": "MENDOZA",
"surname": "LORCA SANCHEZ MENDOZA"
},
"address": {
"unparsedAddress": {
"addressLine1": "123 MAIN ST",
"addressLine2": "SAN DIEGO CA 92101",
"addressLine3": "APT 4",
"addressLine4": "BLOCK 1"
}
},
"machineReadableZone": {
"parsedMachineReadableZone": {
"compositeCheckDigit": "0",
"compositeCheckDigitVerified": "true",
"dateOfBirth": "1967-07-04",
"dateOfBirthCheckDigit": "6",
"dateOfBirthVerified": "true",
"dateOfExpiry": "2016-08-07",
"dateOfExpiryCheckDigit": "8",
"dateOfExpiryVerified": "true",
"documentNumber": "340007955",
"documentNumberCheckDigit": "3",
"documentNumberVerified": "true",
"documentSubType": "",
"documentType": "P",
"gender": "F",
"givenNames": "HAPPY",
"stateOrProvinceOfIssuance": "USA",
"stateOrProvinceOfIssuanceVerified": "true",
"isValid": "true",
"nationalityCode": "USA",
"nationalityCodeVerified": "true",
"personalGovernmentId": "910000833 1119",
"personalGovernmentIdCheckDigit": "2",
"personalGovernmentIdVerified": "true",
"surname": "TRAVELER"
},
"unparsedMachineReadableZone": {
"mrzLine1": "P<USATRAVELER<<HAPPY<<<<<<<<<<<<<<<<<<<<<<<<",
"mrzLine2": "3400079553USA6707046F1608078910000833<111920",
"mrzLine3": "",
}
}
}
}
"NOT_APPROVED" Request Example
POST /identity/verify/v3/id-document/manual HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
canned-response: NOT_APPROVED
{
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"images": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
],
"deviceExtractedData": [
{
"dataType": "PDF417_STRING",
"data": "PDF417 STRING"
}
]
}
"NOT_APPROVED" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"requestId": "4d6a4dc2-a756-4479-99c2-a856b41456c6",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "ACCEPTED"
},
"findings": {
"documentApproval": "NOT_APPROVED",
"details": {
"authenticity": {
"result": "NOT_AUTHENTIC",
"reasons": [
"EVIDENCE_OF_FORGERY_BIODATA_FONTS",
"EVIDENCE_OF_FORGERY_MRZ_FONTS",
"EVIDENCE_OF_FORGERY_PHOTO_ZONE",
"EVIDENCE_OF_FORGERY_SIGNATURE",
"EVIDENCE_OF_FORGERY_NOT_HUMAN_FACE"
]
},
"originality": {
"result": "NOT_ORIGINAL",
"reasons": [
"EVIDENCE_OF_FORGERY_BLACK_AND_WHITE_COPY",
"EVIDENCE_OF_FORGERY_DOCUMENT_STRUCTURE"
]
},
"validity": {
"result": "NOT_VALID",
"reasons": [
"EVIDENCE_OF_FORGERY_DATA_COMPARISON"
"EVIDENCE_OF_FORGERY_MRZ_CHECKSUMS",
"EXPIRED_OR_INVALIDATED"
]
}
}
},
"extractedData": {
"documentAttributes": {
"countryCodeOfIssuance": "USA",
"dateOfExpiry": "2165-08-28",
"dateOfIssuance": "1965-08-28",
"documentNumber": "90933633",
"documentType": "DRIVERS_LICENSE",
"issuingAuthority": "CALIFORNIA DMV",
"stateOrProvinceOfIssuance": "CA"
},
"personAttributes": {
"dateOfBirth": "1965-08-28",
"gender": "F",
"nationalityCode": "GBR",
"personalGovernmentId": "123435534",
"placeOfBirth": "LONDON"
},
"name": {
"firstSurname": "LORCA SANCHEZ",
"fullName": "JUANA LORCA SANCHEZ MENDOZA",
"givenNames": "JUANA",
"secondSurname": "MENDOZA",
"surname": "LORCA SANCHEZ MENDOZA"
},
"address": {
"unparsedAddress": {
"addressLine1": "123 MAIN ST",
"addressLine2": "SAN DIEGO CA 92101",
"addressLine3": "APT 4",
"addressLine4": "BLOCK 1"
}
},
"machineReadableZone": {
"parsedMachineReadableZone": {
"compositeCheckDigit": "0",
"compositeCheckDigitVerified": "true",
"dateOfBirth": "1967-07-04",
"dateOfBirthCheckDigit": "6",
"dateOfBirthVerified": "true",
"dateOfExpiry": "2016-08-07",
"dateOfExpiryCheckDigit": "8",
"dateOfExpiryVerified": "true",
"documentNumber": "340007955",
"documentNumberCheckDigit": "3",
"documentNumberVerified": "true",
"documentSubType": "",
"documentType": "P",
"gender": "F",
"givenNames": "HAPPY",
"stateOrProvinceOfIssuance": "USA",
"stateOrProvinceOfIssuanceVerified": "true",
"isValid": "true",
"nationalityCode": "USA",
"nationalityCodeVerified": "true",
"personalGovernmentId": "910000833 1119",
"personalGovernmentIdCheckDigit": "2",
"personalGovernmentIdVerified": "true",
"surname": "TRAVELER"
},
"unparsedMachineReadableZone": {
"mrzLine1": "P<USATRAVELER<<HAPPY<<<<<<<<<<<<<<<<<<<<<<<<",
"mrzLine2": "3400079553USA6707046F1608078910000833<111920",
"mrzLine3": "",
}
}
}
}
"NOT_APPROVED" Request with canned reasons header Example
POST /identity/verify/v3/id-document/manual HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
canned-response: NOT_APPROVED
canned-reasons: EVIDENCE_OF_FORGERY_BIODATA_FONTS, EVIDENCE_OF_FORGERY_MRZ_FONTS, EVIDENCE_OF_FORGERY_BLACK_AND_WHITE_COPY, EXPIRED_OR_INVALIDATED
{
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"images": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
],
"deviceExtractedData": [
{
"dataType": "PDF417_STRING",
"data": "PDF417 STRING"
}
]
}
"NOT_APPROVED" Response with canned reasons header Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"requestId": "4d6a4dc2-a756-4479-99c2-a856b41456c6",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "ACCEPTED"
},
"findings": {
"documentApproval": "NOT_APPROVED",
"details": {
"authenticity": {
"result": "NOT_AUTHENTIC",
"reasons": [
"EVIDENCE_OF_FORGERY_BIODATA_FONTS",
"EVIDENCE_OF_FORGERY_MRZ_FONTS"
]
},
"originality": {
"result": "NOT_ORIGINAL",
"reasons": [
"EVIDENCE_OF_FORGERY_BLACK_AND_WHITE_COPY"
]
},
"validity": {
"result": "NOT_VALID",
"reasons": [
"EXPIRED_OR_INVALIDATED"
]
}
}
},
"extractedData": {
"documentAttributes": {
"countryCodeOfIssuance": "USA",
"dateOfExpiry": "2165-08-28",
"dateOfIssuance": "1965-08-28",
"documentNumber": "90933633",
"documentType": "DRIVERS_LICENSE",
"issuingAuthority": "CALIFORNIA DMV",
"stateOrProvinceOfIssuance": "CA"
},
"personAttributes": {
"dateOfBirth": "1965-08-28",
"gender": "F",
"nationalityCode": "GBR",
"personalGovernmentId": "123435534",
"placeOfBirth": "LONDON"
},
"name": {
"firstSurname": "LORCA SANCHEZ",
"fullName": "JUANA LORCA SANCHEZ MENDOZA",
"givenNames": "JUANA",
"secondSurname": "MENDOZA",
"surname": "LORCA SANCHEZ MENDOZA"
},
"address": {
"unparsedAddress": {
"addressLine1": "123 MAIN ST",
"addressLine2": "SAN DIEGO CA 92101",
"addressLine3": "APT 4",
"addressLine4": "BLOCK 1"
}
},
"machineReadableZone": {
"parsedMachineReadableZone": {
"compositeCheckDigit": "0",
"compositeCheckDigitVerified": "true",
"dateOfBirth": "1967-07-04",
"dateOfBirthCheckDigit": "6",
"dateOfBirthVerified": "true",
"dateOfExpiry": "2016-08-07",
"dateOfExpiryCheckDigit": "8",
"dateOfExpiryVerified": "true",
"documentNumber": "340007955",
"documentNumberCheckDigit": "3",
"documentNumberVerified": "true",
"documentSubType": "",
"documentType": "P",
"gender": "F",
"givenNames": "HAPPY",
"stateOrProvinceOfIssuance": "USA",
"stateOrProvinceOfIssuanceVerified": "true",
"isValid": "true",
"nationalityCode": "USA",
"nationalityCodeVerified": "true",
"personalGovernmentId": "910000833 1119",
"personalGovernmentIdCheckDigit": "2",
"personalGovernmentIdVerified": "true",
"surname": "TRAVELER"
},
"unparsedMachineReadableZone": {
"mrzLine1": "P<USATRAVELER<<HAPPY<<<<<<<<<<<<<<<<<<<<<<<<",
"mrzLine2": "3400079553USA6707046F1608078910000833<111920",
"mrzLine3": "",
}
}
}
}
"REJECTED" Request with canned reasons header Example
POST /identity/verify/v3/id-document/manual HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
canned-response: REJECTED
canned-reasons: GLARE, NOT_VISIBLE_FOUR_CORNERS, NOT_VISIBLE_SECURITY_FEATURES, POOR_CONTRAST
{
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"images": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
],
"deviceExtractedData": [
{
"dataType": "PDF417_STRING",
"data": "PDF417 STRING"
}
]
}
"REJECTED" Response with canned reasons header Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 4d6a4dc2-a756-4479-99c2-a856b41456c6
{
"requestId": "4d6a4dc2-a756-4479-99c2-a856b41456c6",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "REJECTED",
"reasons": [
"GLARE",
"NOT_VISIBLE_FOUR_CORNERS",
"NOT_VISIBLE_SECURITY_FEATURES",
"POOR_CONTRAST"
]
}
}
Returned HTTP Headers
| Name | Type | Description | Restrictions |
|---|---|---|---|
Mitek-Server-Processing-Time |
Number | The total duration, in milliseconds, from the time the entire request was received until the response was sent. | None |
Mitek-Request-Id |
String | The UUID assigned to the request. | UUID |
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
requestId |
String | The UUID assigned to the request. | UUID |
customerReferenceId |
String | The value that was submitted with the original request. | None |
acceptance |
Object | Based on the value of the canned-response header, the canned response will return a result of either REJECTED or ACCEPTED. |
N/A |
result |
String | The determinition of whether all of the images submitted were deemed acceptable for processing. Based on the |
N/A |
reasons |
String (array) | When the |
N/A |
findings |
Object | The following fields are related to the canned results from the processing of the document. This includes the canned document approval and a detailed summary of the canned authenticity, originality and the validity findings that contributed to the document approval result. | N/A |
documentApproval |
String | The canned document approval determination. Based on the |
N/A |
details |
Object | The details of the canned authenticity, originality, and validity that were performed. | N/A |
authenticity |
Object | The details of the canned authenticity that were performed. | N/A |
result |
String | The canned authenticity result of the document. Based on the |
N/A |
reasons |
String (array) | The reasons that a result of |
N/A |
originality |
Object | The details of the originality checks that were canned. | N/A |
result |
String | The canned originality result of the document. Either |
ORIGINAL or NOT_ORIGINAL |
reasons |
String (array) | If canned-reasons header is provided, its values will be returned otherwise, The reasons that a canned result of |
N/A |
validity |
Object | The details of the canned validity checks that were performed. | N/A |
result |
String | The validity result of the processed document. Will be eitherVALID or NOT_VALID Based on the setting privided to the canned-response header. |
N/A |
reasons |
String (array) | If the value of |
N/A |
extractedData |
Object | A canned response of the data extracted from the submitted document. | N/A |
documentAttributes |
Object | The canned response related to attributes of the document. | N/A |
countryCodeOfIssuance |
String | The canned response related to the ISO code of the country that issued the document. | None |
dateOfExpiry |
String | The canned response related to the date of expiry of the document, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
dateOfIssuance |
String | The canned response related to the date of issuance of the document, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
documentNumber |
String | The canned response related to the number or identifier of the document. | None |
documentType |
String (array) | The type of document that was submitted. |
PASSPORT, DRIVERS_LICENSE, IDENTITY_CARD, RESIDENCE_PERMIT, HEALTH_SERVICES_CARD |
issuingAuthority |
String | The canned response related to the name of the authority or organization that issued the document. | None |
stateOrProvinceOfIssuance |
String | The canned response related to the name of the state, province, or region that issued the document. | None |
personAttributes |
Object | The canned response related to the person to whom the document was issued. | N/A |
dateOfBirth |
String | The canned response related to the date of birth of the person to which the document was issued, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
gender |
String | The canned response related to the gender of the person to which the document was issued, normalized into one of the following values: |
M, F, or N/B |
nationalityCode |
String | The canned response related to the ISO country code of the nationality of the person to which the document was issued. | None |
personalGovernmentId |
String | The canned response related to any government identification number of the person to which the document was issued. | None |
placeOfBirth |
String | The canned response related to the place of birth of the person to which the document was issued. | None |
name |
Object | The canned response related to the name of whom the document was issued. | N/A |
fullName |
String | The canned response related to the full name of the person to which the document was issued. | None |
givenNames |
String | The canned response related to the given names of the person to which the document was issued. | |
firstSurname |
String | The canned response related to the first surname of the person to which the document was issued. | None |
secondSurname |
String | The canned response related to the second surname of the person to which the document was issued. | None |
surname |
String | The canned response related to the surname of the person to which the document was issued. | None |
address |
Object | The canned response related to the address of the person to whom the document was issued. | N/A |
unparsedAddress |
Object | An unparsed version of the address of the person to whom the document was issued. | N/A |
addressLine1 |
String | The canned response related to the first line of the address, as printed, of the person to which the document was issued. | None |
addressLine2 |
String | The canned response related to the second line of the address, as printed, of the person to which the document was issued. | None |
addressLine3 |
String | The canned response related to the third line of the address, as printed, of the person to which the document was issued. | None |
addressLine4 |
String | The canned response related to the fourth line of the address, as printed, of the person to which the document was issued. | None |
machineReadableZone |
Object | The data extracted from the Machine Readable Zone of the submitted document. | N/A |
parsedMachineReadableZone |
Object | A parsed version of the Machine Readable Zone. | N/A |
compositeCheckDigit |
String | The composite check digit value. | A single digit or < |
compositeCheckDigitVerified |
String | The indication if the composite check digit contains a valid value. | true or false |
dateOfBirth |
String | The data extracted from an MRZ field related to the date of birth of the person to which the document was issued, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
dateOfBirthCheckDigit |
String | The date of birth check digit value. | A single digit or < |
dateOfBirthVerified |
String | The indication if the date of birth check digit contains a valid value. | true or false |
dateOfExpiry |
String | The data extracted from an MRZ field related to the date of expiry of the document, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
dateOfExpiryCheckDigit |
String | The date of expiry check digit value. | A single digit or < |
dateOfExpiryVerified |
String | The indication if the date of expiry check digit contains a valid value. | true or false |
documentNumber |
String | The data extracted from an MRZ field related to the number or identifier of the document. | None |
documentNumberCheckDigit |
String | The document number check digit value. | A single digit or < |
documentNumberVerified |
String | The indication if the document number check digit contains a valid value. | true or false |
documentSubType |
String | The data extracted from an MRZ field related to the sub type of the document. | None |
documentType |
String (array) | The data extracted from an MRZ field related to the type of document that was submitted. |
None |
gender |
String | The data extracted from an MRZ field related to the gender of the person to which the document was issued, normalized into one of the following values: |
M, F, or N/B |
givenNames |
String | The data extracted from an MRZ field related to the given names of the person to which the document was issued. | |
stateOrProvinceOfIssuance |
String | The data extracted from an MRZ field related to the ISO country code of the country that issued the document. | None |
stateOrProvinceOfIssuanceVerified |
String | The indication if the issuing state or organization contains a valid value. | true or false |
isValid |
String | The parsed out state or province of the address of the person to whom the document was issued. | None |
nationalityCode |
String | The data extracted from an MRZ field related to the ISO country code of the nationality of the person to which the document was issued. | None |
nationalityCodeVerified |
String | The indication if the nationality contains a valid value. | true or false |
personalGovernmentId |
String | The data extracted from an MRZ field related to any government identification number of the person to which the document was issued. | None |
personalGovernmentIdCheckDigit |
String | The personal government ID check digit value. | A single digit or < |
personalGovernmentIdVerified |
String | The indication if the personal government ID check digit contains a valid value. | true or false |
surname |
String | The data extracted from an MRZ field related to the surname of the person to which the document was issued. | None |
unparsedMachineReadableZone |
Object | An unparsed version of the Machine Readable Zone. | N/A |
mrzLine1 |
String | The first line of the MRZ. | None |
mrzLine2 |
String | The second line of the MRZ. | None |
mrzLine3 |
String | The third line of the MRZ. | None |
Canned Mobile Verify - Expert
Canned Mobile Verify Expert provides the capability to have an automated predefined response of the Mitek Identity Cloud API. This product is delivered as an asynchronous API built around a polling approach for retrieval of final results.
"APPROVED" Request Example
POST /identity/verify/v3/id-document/expert HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
canned-response: APPROVED
{
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"images": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
],
"deviceExtractedData": [
{
"dataType": "PDF417_STRING",
"data": "PDF417 STRING"
}
]
}
Mobile Verify - Expert Request
URL
/identity/verify/v3/id-document/expert
Required Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
images |
Object (array) | An array of base64-encoded images of the document to be verified. | N/A |
data |
String | A base64-encoded image containing a single page of the document to be processed. |
Optional Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
String | [OPTIONAL] Customer provided identifier that will be returned in an identically named field within the body of any subsequent responses | 500 characters limit |
deviceExtractedData |
Object (array) | [OPTIONAL] An array of data extracted on-device from an identity document from machine-readable document features, e.g., barcode. | N/A |
datatype |
String | The type of data being passed for processing. This is commonly barcode details or other machine-encoded data that has been read on-device as part of the initial capture experience. Currently supported data types include:
|
PDF417_STRING |
Mobile Verify - Expert Response
"APPROVED" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "ACCEPTED"
},
"findings": {
"documentApproval": "APPROVED",
"details": {
"authenticity": {
"result": "AUTHENTIC"
},
"originality": {
"result": "ORIGINAL"
},
"validity": {
"result": "VALID"
}
}
},
"extractedData": {
"documentAttributes": {
"countryCodeOfIssuance": "USA",
"dateOfExpiry": "2165-08-28",
"dateOfIssuance": "1965-08-28",
"documentNumber": "90933633",
"documentType": "DRIVERS_LICENSE",
"issuingAuthority": "CALIFORNIA DMV",
"stateOrProvinceOfIssuance": "CA"
},
"personAttributes": {
"dateOfBirth": "1965-08-28",
"gender": "F",
"nationalityCode": "GBR",
"personalGovernmentId": "123435534",
"placeOfBirth": "LONDON"
},
"name": {
"firstSurname": "LORCA SANCHEZ",
"fullName": "JUANA LORCA SANCHEZ MENDOZA",
"givenNames": "JUANA",
"secondSurname": "MENDOZA",
"surname": "LORCA SANCHEZ MENDOZA"
},
"address": {
"unparsedAddress": {
"addressLine1": "123 MAIN ST",
"addressLine2": "SAN DIEGO CA 92101",
"addressLine3": "APT 4",
"addressLine4": "BLOCK 1"
}
},
"machineReadableZone": {
"parsedMachineReadableZone": {
"compositeCheckDigit": "0",
"compositeCheckDigitVerified": "true",
"dateOfBirth": "1967-07-04",
"dateOfBirthCheckDigit": "6",
"dateOfBirthVerified": "true",
"dateOfExpiry": "2016-08-07",
"dateOfExpiryCheckDigit": "8",
"dateOfExpiryVerified": "true",
"documentNumber": "340007955",
"documentNumberCheckDigit": "3",
"documentNumberVerified": "true",
"documentSubType": "",
"documentType": "P",
"gender": "F",
"givenNames": "HAPPY",
"stateOrProvinceOfIssuance": "USA",
"stateOrProvinceOfIssuanceVerified": "true",
"isValid": "true",
"nationalityCode": "USA",
"nationalityCodeVerified": "true",
"personalGovernmentId": "910000833 1119",
"personalGovernmentIdCheckDigit": "2",
"personalGovernmentIdVerified": "true",
"surname": "TRAVELER"
},
"unparsedMachineReadableZone": {
"mrzLine1": "P<USATRAVELER<<HAPPY<<<<<<<<<<<<<<<<<<<<<<<<",
"mrzLine2": "3400079553USA6707046F1608078910000833<111920",
"mrzLine3": "",
}
}
}
}
"NOT_APPROVED" Request Example
POST /identity/verify/v3/id-document/expert HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
canned-response: NOT_APPROVED
{
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"images": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
],
"deviceExtractedData": [
{
"dataType": "PDF417_STRING",
"data": "PDF417 STRING"
}
]
}
"NOT_APPROVED" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "ACCEPTED"
},
"findings": {
"documentApproval": "NOT_APPROVED",
"details": {
"authenticity": {
"result": "NOT_AUTHENTIC",
"reasons": [
"EVIDENCE_OF_FORGERY_BIODATA_FONTS",
"EVIDENCE_OF_FORGERY_MRZ_FONTS",
"EVIDENCE_OF_FORGERY_PHOTO_ZONE",
"EVIDENCE_OF_FORGERY_SECURITY_FEATURES",
"EVIDENCE_OF_FORGERY_SIGNATURE",
"EVIDENCE_OF_FORGERY_NOT_HUMAN_FACE"
]
},
"originality": {
"result": "NOT_ORIGINAL",
"reasons": [
"EVIDENCE_OF_FORGERY_BLACK_AND_WHITE_COPY",
"EVIDENCE_OF_FORGERY_DOCUMENT_STRUCTURE"
]
},
"validity": {
"result": "NOT_VALID",
"reasons": [
"EVIDENCE_OF_FORGERY_DATA_COMPARISON",
"EVIDENCE_OF_FORGERY_MRZ_CHECKSUMS",
"EXPIRED_OR_INVALIDATED"
]
}
}
},
"extractedData": {
"documentAttributes": {
"countryCodeOfIssuance": "USA",
"dateOfExpiry": "2165-08-28",
"dateOfIssuance": "1965-08-28",
"documentNumber": "90933633",
"documentType": "DRIVERS_LICENSE",
"issuingAuthority": "CALIFORNIA DMV",
"stateOrProvinceOfIssuance": "CA"
},
"personAttributes": {
"dateOfBirth": "1965-08-28",
"gender": "F",
"nationalityCode": "GBR",
"personalGovernmentId": "123435534",
"placeOfBirth": "LONDON"
},
"name": {
"firstSurname": "LORCA SANCHEZ",
"fullName": "JUANA LORCA SANCHEZ MENDOZA",
"givenNames": "JUANA",
"secondSurname": "MENDOZA",
"surname": "LORCA SANCHEZ MENDOZA"
},
"address": {
"unparsedAddress": {
"addressLine1": "123 MAIN ST",
"addressLine2": "SAN DIEGO CA 92101",
"addressLine3": "APT 4",
"addressLine4": "BLOCK 1"
}
},
"machineReadableZone": {
"parsedMachineReadableZone": {
"compositeCheckDigit": "0",
"compositeCheckDigitVerified": "true",
"dateOfBirth": "1967-07-04",
"dateOfBirthCheckDigit": "6",
"dateOfBirthVerified": "true",
"dateOfExpiry": "2016-08-07",
"dateOfExpiryCheckDigit": "8",
"dateOfExpiryVerified": "true",
"documentNumber": "340007955",
"documentNumberCheckDigit": "3",
"documentNumberVerified": "true",
"documentSubType": "",
"documentType": "P",
"gender": "F",
"givenNames": "HAPPY",
"stateOrProvinceOfIssuance": "USA",
"stateOrProvinceOfIssuanceVerified": "true",
"isValid": "true",
"nationalityCode": "USA",
"nationalityCodeVerified": "true",
"personalGovernmentId": "910000833 1119",
"personalGovernmentIdCheckDigit": "2",
"personalGovernmentIdVerified": "true",
"surname": "TRAVELER"
},
"unparsedMachineReadableZone": {
"mrzLine1": "P<USATRAVELER<<HAPPY<<<<<<<<<<<<<<<<<<<<<<<<",
"mrzLine2": "3400079553USA6707046F1608078910000833<111920",
"mrzLine3": "",
}
}
}
}
"NOT_APPROVED" Request with canned reasons header Example
POST /identity/verify/v3/id-document/expert HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
canned-response: NOT_APPROVED
canned-reasons: EVIDENCE_OF_FORGERY_BIODATA_FONTS, EVIDENCE_OF_FORGERY_BLACK_AND_WHITE_COPY, EVIDENCE_OF_FORGERY_DATA_COMPARISON
{
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"images": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
],
"deviceExtractedData": [
{
"dataType": "PDF417_STRING",
"data": "PDF417 STRING"
}
]
}
"NOT_APPROVED" Response with canned reasons header Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "ACCEPTED"
},
"findings": {
"documentApproval": "NOT_APPROVED",
"details": {
"authenticity": {
"result": "NOT_AUTHENTIC",
"reasons": [
"EVIDENCE_OF_FORGERY_BIODATA_FONTS"
]
},
"originality": {
"result": "NOT_ORIGINAL",
"reasons": [
"EVIDENCE_OF_FORGERY_BLACK_AND_WHITE_COPY"
]
},
"validity": {
"result": "NOT_VALID",
"reasons": [
"EVIDENCE_OF_FORGERY_DATA_COMPARISON"
]
}
}
},
"extractedData": {
"documentAttributes": {
"countryCodeOfIssuance": "USA",
"dateOfExpiry": "2165-08-28",
"dateOfIssuance": "1965-08-28",
"documentNumber": "90933633",
"documentType": "DRIVERS_LICENSE",
"issuingAuthority": "CALIFORNIA DMV",
"stateOrProvinceOfIssuance": "CA"
},
"personAttributes": {
"dateOfBirth": "1965-08-28",
"gender": "F",
"nationalityCode": "GBR",
"personalGovernmentId": "123435534",
"placeOfBirth": "LONDON"
},
"name": {
"firstSurname": "LORCA SANCHEZ",
"fullName": "JUANA LORCA SANCHEZ MENDOZA",
"givenNames": "JUANA",
"secondSurname": "MENDOZA",
"surname": "LORCA SANCHEZ MENDOZA"
},
"address": {
"unparsedAddress": {
"addressLine1": "123 MAIN ST",
"addressLine2": "SAN DIEGO CA 92101",
"addressLine3": "APT 4",
"addressLine4": "BLOCK 1"
}
},
"machineReadableZone": {
"parsedMachineReadableZone": {
"compositeCheckDigit": "0",
"compositeCheckDigitVerified": "true",
"dateOfBirth": "1967-07-04",
"dateOfBirthCheckDigit": "6",
"dateOfBirthVerified": "true",
"dateOfExpiry": "2016-08-07",
"dateOfExpiryCheckDigit": "8",
"dateOfExpiryVerified": "true",
"documentNumber": "340007955",
"documentNumberCheckDigit": "3",
"documentNumberVerified": "true",
"documentSubType": "",
"documentType": "P",
"gender": "F",
"givenNames": "HAPPY",
"stateOrProvinceOfIssuance": "USA",
"stateOrProvinceOfIssuanceVerified": "true",
"isValid": "true",
"nationalityCode": "USA",
"nationalityCodeVerified": "true",
"personalGovernmentId": "910000833 1119",
"personalGovernmentIdCheckDigit": "2",
"personalGovernmentIdVerified": "true",
"surname": "TRAVELER"
},
"unparsedMachineReadableZone": {
"mrzLine1": "P<USATRAVELER<<HAPPY<<<<<<<<<<<<<<<<<<<<<<<<",
"mrzLine2": "3400079553USA6707046F1608078910000833<111920",
"mrzLine3": "",
}
}
}
}
"REJECTED" Request Example
POST /identity/verify/v3/id-document/expert HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
canned-response: REJECTED
{
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"images": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
],
"deviceExtractedData": [
{
"dataType": "PDF417_STRING",
"data": "PDF417 STRING"
}
]
}
"REJECTED" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "REJECTED",
"reasons": [
"GLARE",
"INCOMPLETE_DOCUMENT",
"NOT_VISIBLE_FOUR_CORNERS",
"NOT_VISIBLE_SECURITY_FEATURES",
"OUT_OF_FOCUS",
"POOR_CONTRAST",
"POOR_EXPOSURE",
"UNCLASSIFIED_DOCUMENT",
"UNREADABLE_FIELD",
"UNSUPPORTED_LANGUAGE"
]
}
}
"REJECTED" Request with canned reasons header Example
POST /identity/verify/v3/id-document/expert HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
canned-response: REJECTED
canned-reasons: GLARE, INCOMPLETE_DOCUMENT
{
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"images": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
],
"deviceExtractedData": [
{
"dataType": "PDF417_STRING",
"data": "PDF417 STRING"
}
]
}
"REJECTED" Response with canned reasons header Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "REJECTED",
"reasons": [
"GLARE",
"INCOMPLETE_DOCUMENT"
]
}
}
Returned HTTP Headers
| Name | Type | Description | Restrictions |
|---|---|---|---|
Mitek-Server-Processing-Time |
Number | The total duration, in milliseconds, from the time the entire request was received until the response was sent. | None |
Mitek-Request-Id |
String | The UUID assigned to the request. | UUID |
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
requestId |
String | The UUID assigned to the request. | UUID |
customerReferenceId |
String | The value that was submitted with the original request. | None |
acceptance |
Object | Based on the value of the canned-response header, the canned response will return a result of either REJECTED or ACCEPTED. |
N/A |
result |
String | The determinition of whether all of the images submitted were deemed acceptable for processing. Based on the |
N/A |
reasons |
String (array) | When the |
N/A |
findings |
Object | The following fields are related to the canned results from the processing of the document. This includes the canned document approval and a detailed summary of the canned authenticity, originality and the validity findings that contributed to the document approval result. | N/A |
documentApproval |
String | The canned document approval determination. Based on the |
N/A |
details |
Object | The details of the canned authenticity, originality, and validity that were performed. | N/A |
authenticity |
Object | The details of the canned authenticity that were performed. | N/A |
result |
String | The canned authenticity result of the document. Based on the |
N/A |
reasons |
String (array) | If canned-reasons header is provided, its values will be returned otherwise, the reasons that a result of |
N/A |
originality |
Object | The details of the originality checks that were canned. | N/A |
result |
String | The canned originality result of the document. Either |
ORIGINAL or NOT_ORIGINAL |
reasons |
String (array) | If canned-reasons header is provided, its values will be returned otherwise, the reasons that a canned result of |
N/A |
validity |
Object | The details of the canned validity checks that were performed. | N/A |
result |
String | The validity result of the processed document. Will be eitherVALID or NOT_VALID Based on the setting privided to the canned-response header. |
N/A |
reasons |
String (array) | If the value of |
N/A |
extractedData |
Object | A canned response of the data extracted from the submitted document. | N/A |
documentAttributes |
Object | The canned response related to attributes of the document. | N/A |
countryCodeOfIssuance |
String | The canned response related to the ISO code of the country that issued the document. | None |
dateOfExpiry |
String | The canned response related to the date of expiry of the document, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
dateOfIssuance |
String | The canned response related to the date of issuance of the document, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
documentNumber |
String | The canned response related to the number or identifier of the document. | None |
documentType |
String (array) | The type of document that was submitted. |
PASSPORT, DRIVERS_LICENSE, IDENTITY_CARD, RESIDENCE_PERMIT, HEALTH_SERVICES_CARD |
issuingAuthority |
String | The canned response related to the name of the authority or organization that issued the document. | None |
stateOrProvinceOfIssuance |
String | The canned response related to the name of the state, province, or region that issued the document. | None |
personAttributes |
Object | The canned response related to the person to whom the document was issued. | N/A |
dateOfBirth |
String | The canned response related to the date of birth of the person to which the document was issued, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
gender |
String | The canned response related to the gender of the person to which the document was issued, normalized into one of the following values: |
M, F, or N/B |
nationalityCode |
String | The canned response related to the ISO country code of the nationality of the person to which the document was issued. | None |
personalGovernmentId |
String | The canned response related to any government identification number of the person to which the document was issued. | None |
placeOfBirth |
String | The canned response related to the place of birth of the person to which the document was issued. | None |
name |
Object | The canned response related to the name of whom the document was issued. | N/A |
fullName |
String | The canned response related to the full name of the person to which the document was issued. | None |
givenNames |
String | The canned response related to the given names of the person to which the document was issued. | |
firstSurname |
String | The canned response related to the first surname of the person to which the document was issued. | None |
secondSurname |
String | The canned response related to the second surname of the person to which the document was issued. | None |
surname |
String | The canned response related to the surname of the person to which the document was issued. | None |
address |
Object | The canned response related to the address of the person to whom the document was issued. | N/A |
unparsedAddress |
Object | An unparsed version of the address of the person to whom the document was issued. | N/A |
addressLine1 |
String | The canned response related to the first line of the address, as printed, of the person to which the document was issued. | None |
addressLine2 |
String | The canned response related to the second line of the address, as printed, of the person to which the document was issued. | None |
addressLine3 |
String | The canned response related to the third line of the address, as printed, of the person to which the document was issued. | None |
addressLine4 |
String | The canned response related to the fourth line of the address, as printed, of the person to which the document was issued. | None |
machineReadableZone |
Object | The data extracted from the Machine Readable Zone of the submitted document. | N/A |
parsedMachineReadableZone |
Object | A parsed version of the Machine Readable Zone. | N/A |
compositeCheckDigit |
String | The composite check digit value. | A single digit or < |
compositeCheckDigitVerified |
String | The indication if the composite check digit contains a valid value. | true or false |
dateOfBirth |
String | The data extracted from an MRZ field related to the date of birth of the person to which the document was issued, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
dateOfBirthCheckDigit |
String | The date of birth check digit value. | A single digit or < |
dateOfBirthVerified |
String | The indication if the date of birth check digit contains a valid value. | true or false |
dateOfExpiry |
String | The data extracted from an MRZ field related to the date of expiry of the document, normalized into the following format: YYYY-MM-DD. | Date (YYYY-MM-DD) |
dateOfExpiryCheckDigit |
String | The date of expiry check digit value. | A single digit or < |
dateOfExpiryVerified |
String | The indication if the date of expiry check digit contains a valid value. | true or false |
documentNumber |
String | The data extracted from an MRZ field related to the number or identifier of the document. | None |
documentNumberCheckDigit |
String | The document number check digit value. | A single digit or < |
documentNumberVerified |
String | The indication if the document number check digit contains a valid value. | true or false |
documentSubType |
String | The data extracted from an MRZ field related to the sub type of the document. | None |
documentType |
String (array) | The data extracted from an MRZ field related to the type of document that was submitted. |
None |
gender |
String | The data extracted from an MRZ field related to the gender of the person to which the document was issued, normalized into one of the following values: |
M, F, or N/B |
givenNames |
String | The data extracted from an MRZ field related to the given names of the person to which the document was issued. | |
stateOrProvinceOfIssuance |
String | The data extracted from an MRZ field related to the ISO country code of the country that issued the document. | None |
stateOrProvinceOfIssuanceVerified |
String | The indication if the issuing state or organization contains a valid value. | true or false |
isValid |
String | The parsed out state or province of the address of the person to whom the document was issued. | None |
nationalityCode |
String | The data extracted from an MRZ field related to the ISO country code of the nationality of the person to which the document was issued. | None |
nationalityCodeVerified |
String | The indication if the nationality contains a valid value. | true or false |
personalGovernmentId |
String | The data extracted from an MRZ field related to any government identification number of the person to which the document was issued. | None |
personalGovernmentIdCheckDigit |
String | The personal government ID check digit value. | A single digit or < |
personalGovernmentIdVerified |
String | The indication if the personal government ID check digit contains a valid value. | true or false |
surname |
String | The data extracted from an MRZ field related to the surname of the person to which the document was issued. | None |
unparsedMachineReadableZone |
Object | An unparsed version of the Machine Readable Zone. | N/A |
mrzLine1 |
String | The first line of the MRZ. | None |
mrzLine2 |
String | The second line of the MRZ. | None |
mrzLine3 |
String | The third line of the MRZ. | None |
Canned Face Comparison Manual
Each canned face comparison request provides the ability to compare the face present on an identity document with selfie(s) provided as part of the request. The API only supports providing up to two reference images and up to 3 selfies.
Face Comparison - Manual Request
"APPROVED" Request Example
POST /identity/facecomparison/v3/manual HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
canned-response: APPROVED
{
"transactionRequestId": "093ddee6-1a16-4da2-a09f-f4c16e20defa",
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"referenceImages": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
}
],
"selfieImages": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
]
}
URL
/identity/facecomparison/v3/manual
Required Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
transactionRequestId |
String | A valid UUID for a previously submitted Mobile Verify (Auto, Manual or Expert) request | UUID |
referenceImages |
Object (array) | An array of images that are used as the reference for face comparison, these should be derived from a document previously submitted via mobile verify | Maximum of 2 reference images can be submitted per request |
data |
String | A base64-encoded image to be used as a reference to be compared against the selfie image(s) provided | |
selfieImages |
Object (array) | An array of base-64 encoded images of selfies to be verified | |
data |
String | A base64-encoded image of a selfie to be compared against the reference image provided |
Optional Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
String | [OPTIONAL] Customer provided identifier that will be returned in an identically named field within the body of any subsequent responses | 500 characters limit |
Face Comparison - Manual Response
"APPROVED" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: fc59ec41-cbdb-4438-9526-a7d6c7990647
{
"requestId": "fc59ec41-cbdb-4438-9526-a7d6c7990647",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "ACCEPTED"
},
"findings": {
"faceComparisonApproval": "MATCH",
"faceLivenessApproval": "LIVE"
}
}
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
requestId |
String | The UUID assigned to the request | UUID |
customerReferenceId |
String | A value that will be returned within the body of subsequent responses. | N/A |
acceptance |
|||
result |
String | ACCEPTED or REJECTED will be returned based on the canned-response header. |
N/A |
reasons |
String (array) | If canned-response header is set to REJECTED, if canned-reasons header is provided, its values will be returned otherwise, the following reasons will be returned: MISSING_SELFIE, MISSING_PORTRAIT, NOT_HUMAN_FACE, PARTIALLY_VISIBLE_HUMAN_FACE, PORTRAIT_IS_FAKE, SELFIE_NOT_LIVE, OUT_OF_FOCUS, POOR_CONTRAST, POOR_EXPOSURE, GLARE |
N/A |
findings |
|||
faceComparisonApproval |
String | Based on the value of the canned-response header the canned response will return either MATCH or NOT_MATCH. |
N/A |
faceLivenessApproval |
String | Based on the value of the canned-response header the canned response will return either LIVE or NOT_LIVE |
N/A |
"REJECTED" Request Example
POST /identity/facecomparison/v3/manual HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
canned-response: REJECTED
{
"transactionRequestId": "093ddee6-1a16-4da2-a09f-f4c16e20defa",
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"referenceImages": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
}
],
"selfieImages": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
]
}
"REJECTED" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "REJECTED",
"reasons": [
"POOR_CONTRAST",
"POOR_EXPOSURE",
"OUT_OF_FOCUS",
"GLARE",
"MISSING_SELFIE",
"MISSING_PORTRAIT",
"NOT_HUMAN_FACE",
"PARTIALLY_VISIBLE_HUMAN_FACE",
"SELFIE_NOT_LIVE",
"PORTRAIT_IS_FAKE"
]
}
}
"REJECTED" Request with canned reasons header Example
POST /identity/facecomparison/v3/manual HTTP/1.1
Content-Type: application/json;
Authorization: Bearer $OAUTH_TOKEN
canned-response: REJECTED
canned-reasons: MISSING_PORTRAIT, NOT_HUMAN_FACE, PARTIALLY_VISIBLE_HUMAN_FACE
{
"transactionRequestId": "093ddee6-1a16-4da2-a09f-f4c16e20defa",
"customerReferenceId": "OPTIONAL CUSTOMER PROVIDED IDENTIFIER",
"referenceImages": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
}
],
"selfieImages": [
{
"data": "TWlTbmFwIENhcHR1cmVkIEltYWdlIFBhZ2UgMQ=="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
},
{
"data": "UGFnZSAyIE1pU25hcCBDYXB0dXJlZCBJbWFnZSA="
}
]
}
"REJECTED" Response with canned reasons header Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Server-Processing-Time: 4012
Mitek-Request-Id: 7bd9aada-d538-4f48-807f-3ba97428e770
{
"requestId": "7bd9aada-d538-4f48-807f-3ba97428e770",
"customerReferenceId": "CUSTOMER PROVIDED IDENTIFIER",
"acceptance": {
"result": "REJECTED",
"reasons": [
"MISSING_PORTRAIT",
"NOT_HUMAN_FACE",
"PARTIALLY_VISIBLE_HUMAN_FACE"
]
}
}
MiPass - Enroll
The enroll endpoint leverages the face and/or voice samples of an individual to create a MiPass enrollment with a biometric mathematical template (biometric). It may also be used to update an individual’s biometrics with a more recent sample, or to append an additional biometric sample when only one was previously enrolled. Note: all biometric samples in a request must pass their respective liveness checks to achieve a successful enrollment or update.
A tenant's MiPass configuration will dictate whether the original face and/or voice samples are stored during enrollment. The enrollment data is assigned an expiration date in accordance with the customer’s data retention policy, after which time the data is irrevocably deleted. Updating an enrollment will reset the expiration date for the updated biometric only; for example, an updated face sample will not modify the expiration date of the voice data. A record’s biometrics may be updated at any time, even after data expiration, unless the record is affirmatively deleted.
MiPass - Enroll Request
Request Example - New Enrollment
POST /identity/biometric/v3/enroll HTTP/1.1
Content-Type: application/json
Authorization: Bearer $OAUTH_TOKEN
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"voiceFeatures": [
{
"data": "BASE64 ENCODED VOICE RECORDING"
},
{
"data": "BASE64 ENCODED VOICE RECORDING"
},
{
"data": "BASE64 ENCODED VOICE RECORDING"
}
],
"selfieImages": [
{
"data": "BASE64 ENCODED IMAGE"
}
]
}
Request Example - New Enrollment with Mibi
POST /identity/biometric/v3/enroll HTTP/1.1
Content-Type: application/json
Authorization: Bearer $OAUTH_TOKEN
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"voiceFeatures": [
{
"data": "BASE64 ENCODED VOICE RECORDING",
"mibi": "BASE64 ENCODED MIBI JSON STRING"
},
{
"data": "BASE64 ENCODED VOICE RECORDING",
"mibi": "BASE64 ENCODED MIBI JSON STRING"
},
{
"data": "BASE64 ENCODED VOICE RECORDING",
"mibi": "BASE64 ENCODED MIBI JSON STRING"
}
],
"selfieImages": [
{
"data": "BASE64 ENCODED IMAGE"
}
]
}
Request Example - Update Enrollment
POST /identity/biometric/v3/enroll HTTP/1.1
Content-Type: application/json
Authorization: Bearer $OAUTH_TOKEN
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"enrollmentId": "32609347-d962-4ec9-9984-5597d7b4c842",
"voiceFeatures": [
{
"data": "BASE64 ENCODED VOICE RECORDING"
},
{
"data": "BASE64 ENCODED VOICE RECORDING"
},
{
"data": "BASE64 ENCODED VOICE RECORDING"
}
],
"selfieImages": [
{
"data": "BASE64 ENCODED IMAGE"
}
]
}
Request Example - Update Enrollment with Mibi
POST /identity/biometric/v3/enroll HTTP/1.1
Content-Type: application/json
Authorization: Bearer $OAUTH_TOKEN
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"enrollmentId": "32609347-d962-4ec9-9984-5597d7b4c842",
"voiceFeatures": [
{
"data": "BASE64 ENCODED VOICE RECORDING",
"mibi": "BASE64 ENCODED MIBI JSON STRING"
},
{
"data": "BASE64 ENCODED VOICE RECORDING",
"mibi": "BASE64 ENCODED MIBI JSON STRING"
},
{
"data": "BASE64 ENCODED VOICE RECORDING",
"mibi": "BASE64 ENCODED MIBI JSON STRING"
}
],
"selfieImages": [
{
"data": "BASE64 ENCODED IMAGE"
}
]
}
Request Example - New Enrollment with Duplicate Identity Scan Enabled
POST /identity/biometric/v3/enroll HTTP/1.1
Content-Type: application/json
Authorization: Bearer $OAUTH_TOKEN
{
"selfieImages": [
{
"data": "BASE64 ENCODED IMAGE"
}
],
"configuration": {
"faceBlocklist": {
"enabled": true,
"rejectEnabled": true
},
"faceVelocity": {
"enabled": true,
"rejectEnabled": true,
"minMatches": 1,
"lookBackPeriodDays": 365
}
},
"userOrigin": {
"countryCode": "USA",
"regionCode": "CA"
}
}
Request Example - New Enrollment with Injection Attack Detection Enabled
POST /identity/biometric/v3/enroll HTTP/1.1
Content-Type: application/json
Authorization: Bearer $OAUTH_TOKEN
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"voiceFeatures": [
{
"data": "BASE64 ENCODED VOICE RECORDING",
"encryptedPayload": "BASE64 ENCODED ENCRYPTED PAYLOAD"
},
{
"data": "BASE64 ENCODED VOICE RECORDING",
"encryptedPayload": "BASE64 ENCODED ENCRYPTED PAYLOAD"
},
{
"data": "BASE64 ENCODED VOICE RECORDING",
"encryptedPayload": "BASE64 ENCODED ENCRYPTED PAYLOAD"
}
],
"selfieImages": [
{
"data": "BASE64 ENCODED IMAGE",
"encryptedPayload": "BASE64 ENCODED ENCRYPTED PAYLOAD"
}
],
"configuration": {
"injectionAttackDetection": ["selfieImages", "voiceFeatures"]
}
}
URL
POST /identity/biometric/v3/enroll
Required Fields
An enrollment can be created/updated with a face, a set of voice recordings, or both. At least three voice recordings in the voiceFeatures object or one image in the selfieImages object must be present in the request.
| Name | Type | Description | Restrictions |
|---|---|---|---|
voiceFeatures |
Object (array) | Array of voice recordings to process and enroll. | At least 3 voice recordings are required to ensure template accuracy. |
data |
String | Base64-encoded WAV, WebM, or MP4 file containing voice recording. | N/A |
mibi |
String | [OPTIONAL] Base64-encoded JSON object containing session analytics data for the voice recording. Only applicable to MiSnap WebSDK capture events. | N/A |
encryptedPayload |
String | A base64-encoded string containing an encrypted real-time security payload generated by Mitek’s MiSnap Capture SDKs v.5.5.0 and newer. This field is only required if voiceFeatures is enabled in the Injection Attack Detection object in the request configuration. |
N/A |
selfieImages |
Object (array) | Array of selfie images to process and enroll. | Currently only supports a single image. |
data |
String | Base64-encoded selfie image file. | N/A |
encryptedPayload |
String | A base64-encoded string containing an encrypted real-time security payload generated by Mitek’s MiSnap Capture SDKs v.5.4.0 and newer. This field is only required if selfieImages is enabled in the Injection Attack Detection object in the request configuration. |
N/A |
userOrigin |
Object | User Origin identifies the country and region of the end-user who is attempting to enroll. | N/A |
countryCode |
String | The country code of the end-user. | ISO 3166-1 alpha-3 country code |
regionCode |
String | The region code of the end-user. It is required when the country code is either USA or CAN, otherwise it is optional. | ISO 3166-2 two-letter region code |
Optional Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
String | Customer provided identifier that will be returned within the body of the response. | 500 characters limit |
enrollmentId |
String | Mitek provided unique identifier from a previous enrollment. If provided, will attempt an update operation. | Do not populate when requesting a new enrollment. It is required if updating an existing enrollment. |
configuration |
Object | Configuration options. | N/A |
faceBlocklist |
Object | DIS - Face Blocklist configuration. | N/A |
enabled |
Boolean | Flag indicating if Face Blocklist lookup should be performed. Defaults to false. | true or false |
rejectEnabled |
Boolean | Flag indicating if any Blocklist matches should trigger a rejection of the enrollment. Defaults to false. | true or false |
faceVelocity |
Object | DIS - Face Velocity configuration. | N/A |
enabled |
Boolean | Flag indicating if Face Velocity search-and-enroll should be performed. Defaults to false. | true or false |
rejectEnabled |
Boolean | Flag indicating if qualifying velocity matches should trigger a rejection of the enrollment. Defaults to false. | true or false |
minMatches |
Integer | The minimum number of qualifying DIS matches required to trigger a rejection. A value is required if rejectEnabled is true. | Value must be between 1 and 100. |
lookBackPeriodDays |
Integer | The number of days which confines the qualifying matches detected by Face Velocity. Defaults to the MiPass data retention duration. | 32-bit Integer |
injectionAttackDetection |
Object | A list of biometric types enabled for injection attack detection to be performed on. | selfieImages, voiceFeatures |
MiPass - Enroll Response
"ENROLLED" Response Example
HTTP/1.1 201 Created
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"enrollmentId": "32609347-d962-4ec9-9984-5597d7b4c842",
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24",
"enrollmentStatus": "ENROLLED",
"details": {
"faceProcessing": {
"status": "SUCCESSFUL",
"dataExpiration": "2025-02-13T17:23:44Z"
},
"voiceProcessing": {
"status": "SUCCESSFUL",
"dataExpiration": "2025-02-13T17:23:44Z"
}
}
}
"ENROLLED" Response Example with Face Velocity and Face Blocklist Matches
HTTP/1.1 201 Created
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"enrollmentId": "32609347-d962-4ec9-9984-5597d7b4c842",
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24",
"enrollmentStatus": "ENROLLED",
"details": {
"faceProcessing": {
"status": "SUCCESSFUL",
"dataExpiration": "2025-02-13T17:23:44Z",
"faceBlocklist": {
"status": "SUCCESSFUL",
"matches": [
{
"itemId": "be3e68e9-284e-44da-9e0a-a88797ad5d8e",
"blockEnrollmentId": "10491320-86ff-404b-93c5-68dcb4418762",
"createdAt": "2022-11-28T12:40:31.8733761Z"
}
],
},
"faceVelocity": {
"status": "SUCCESSFUL",
"matches": [
{
"enrollmentId": "2c6faa24-0276-466b-9fb8-eefcec06303f",
"createdAt": "2023-11-02T15:14:14.075928Z",
"expiresAt": "2026-10-18T15:14:14.075928Z"
}
]
}
}
},
"configuration": {
"faceBlocklist": {
"enabled": true,
"rejectEnabled": false
},
"faceVelocity": {
"enabled": true,
"rejectEnabled": false
}
}
}
"UPDATED" Response Example
HTTP/1.1 201 Created
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"enrollmentId": "32609347-d962-4ec9-9984-5597d7b4c842",
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24",
"enrollmentStatus": "UPDATED",
"details": {
"faceProcessing": {
"status": "SUCCESSFUL",
"dataExpiration": "2026-01-27T11:57:03Z"
},
"voiceProcessing": {
"status": "SUCCESSFUL",
"dataExpiration": "2026-01-27T11:57:03Z"
}
}
}
"FAILED" Response Example
HTTP/1.1 201 Created
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24",
"enrollmentStatus": "FAILED",
"details": {
"faceProcessing": {
"status": "FAILED",
"reasons": ["FACE_TOO_CLOSE"]
},
"voiceProcessing": {
"status": "FAILED",
"reasons": ["VOICE_NOT_DETECTED"]
}
}
}
"FAILED" Response Example with Face Velocity and Face Blocklist Matches
HTTP/1.1 201 Created
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24",
"enrollmentStatus": "FAILED",
"details": {
"faceProcessing": {
"status": "FAILED",
"reasons": [
"FACE_BLOCKLIST",
"FACE_VELOCITY"
],
"faceBlocklist": {
"status": "SUCCESSFUL",
"matches": [
{
"itemId": "be3e68e9-284e-44da-9e0a-a88797ad5d8e",
"blockEnrollmentId": "10491320-86ff-404b-93c5-68dcb4418762",
"createdAt": "2022-11-28T12:40:31.8733761Z"
}
]
},
"faceVelocity": {
"status": "SUCCESSFUL",
"matches": [
{
"enrollmentId": "2c6faa24-0276-466b-9fb8-eefcec06303f",
"createdAt": "2023-11-02T15:14:14.075928Z",
"expiresAt": "2026-10-18T15:14:14.075928Z"
}
]
}
}
},
"configuration": {
"faceBlocklist": {
"enabled": true,
"rejectEnabled": true
},
"faceVelocity": {
"enabled": true,
"rejectEnabled": true,
"minMatches": 1,
"lookBackPeriodDays": 365
}
}
}
"FAILED" Response Example with Injection Attack Detection
HTTP/1.1 201 Created
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24",
"enrollmentStatus": "FAILED",
"details": {
"faceProcessing": {
"status": "FAILED",
"reasons": ["INJECTION_ATTACK_DETECTED"]
},
"voiceProcessing": {
"status": "FAILED",
"reasons": ["MISSING_ENCRYPTED_PAYLOAD"]
}
},
"configuration": {
"injectionAttackDetection": ["selfieImages", "voiceFeatures"]
}
}
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
String | A value submitted with the original request that is returned in the response. | N/A |
enrollmentId |
String | Unique identifier for the enrollment. Used in verify, update, or delete operations. | UUID |
requestId |
String | The unique identifier that Mitek Systems has assigned to this transaction. | UUID |
enrollmentStatus |
String | Status of the enrollment operation. | ENROLLED or UPDATED or FAILED |
details |
Object | Details of processing outcomes for the enrollment operation. | N/A |
faceProcessing |
Object | Contains details regarding processing of faces. | N/A |
status |
String | Status of face processing. | SUCCESSFUL or FAILED |
reasons |
String (array) | Reasons for face processing failure. | N/A |
dataExpiration |
String | The expiration timestamp for the enrolled face data. | RFC 3339 Timestamp |
faceBlocklist |
Object | Contains details regarding DIS - Face Blocklist if enabled. | N/A |
status |
String | Status of the DIS - Face Blocklist operation. | SUCCESSFUL or FAILED |
matches |
Object (array) | An array of blocklist matches is returned when the given selfie image is detected on the face blocklist. | N/A |
itemId |
String | The unique identifier associated with this matching blocklist item. | UUID |
blockEnrollmentId |
String | Enrollment ID of an existing MiPass Enrollment used to create this blocklist item. | UUID |
createdAt |
String | The timestamp for when this item was created. | RFC 3339 Timestamp |
faceVelocity |
Object | Contains details regarding DIS - Face Velocity if enabled. | N/A |
status |
String | Status of the DIS - Face Velocity operation. | SUCCESSFUL or FAILED |
matches |
Object (array) | When the same face has been submitted in prior enrollments, those matching enrollments are listed in this array. | N/A |
enrollmentId |
String | Enrollment ID of a previous MiPass Enrollment with a matching face. | UUID |
createdAt |
String | The timestamp for when this enrollment took place. | RFC 3339 Timestamp |
expiresAt |
String | The timestamp for when this enrollment expires. | RFC 3339 Timestamp |
voiceProcessing |
Object | Contains details regarding processing of voices. | N/A |
status |
String | Status of voice processing. | SUCCESSFUL or FAILED |
reasons |
String (array) | Reasons for voice processing failure. | N/A |
dataExpiration |
String | The expiration timestamp for the enrolled voice data. | RFC 3339 Timestamp |
configuration |
Object | Configuration options. | N/A |
faceBlocklist |
Object | DIS - Face Blocklist configuration. | N/A |
enabled |
Boolean | Flag indicating if Face Blocklist lookup was performed. | true or false |
rejectEnabled |
Boolean | Flag indicating if any Blocklist matches should trigger a rejection of the enrollment. | true or false |
faceVelocity |
Object | DIS - Face Velocity configuration. | N/A |
enabled |
Boolean | Flag indicating if Face Velocity search-and-enroll was performed. | true or false |
rejectEnabled |
Boolean | Flag indicating if qualifying velocity matches should trigger a rejection of the enrollment. | true or false |
minMatches |
Integer | The minimum number of qualifying DIS matches required to trigger a rejection. | Value must be between 1 and 100. |
lookBackPeriodDays |
Integer | The number of days which confines the qualifying matches detected by Face Velocity. | 32-bit Integer |
injectionAttackDetection |
Object | A list of biometric types on which injection attack detection was performed as requested. | selfieImages, voiceFeatures |
MiPass - Enroll Error Responses
400 Response Example
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"message": "Customer reference id should not exceed 500 characters."
}
OR
{
"message": "No voice features or selfie images provided in enrollment request."
}
401 Response Example
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"message": "Authorization has been denied for this request."
}
403 Forbidden
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"message": "You do not have the correct permissions to perform MiPass Enrollment."
}
415 Response Example
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
{
"message": "The request entity's media type '...' is not supported for this resource."
}
500 Response Example
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{
"message": "There was a technical problem processing your request. Please try again."
}
Standard HTTP REST-based response codes and messages are used to indicate success or failure for a request.
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
message |
String | A message describing the error. | None |
All "Bad Request" Error Messages
| Message |
|---|
| No voice features or selfie images provided in enrollment request. |
| Image data not provided in selfie image. |
| Voice data not provided in voice feature. |
| Illegal base64 data at input byte 4. |
| The given Enrollment ID does not exist. If this is a new Enrollment, the Enrollment ID should be omitted. |
| Invalid MiPass Enrollment request format - a minimum of 3 voice features are required to enroll voice. |
| No selfie image provided to perform Duplicate Identity Scan (DIS) check. |
| Invalid MiPass Enrollment request format - user origin data not provided or is invalid. |
| Invalid MiPass Enrollment request format - user origin ISO 3166-1 alpha-3 country code is missing. |
| Invalid MiPass Enrollment request format - user origin ISO 3166-1 alpha-3 country code is invalid. |
| Invalid MiPass Enrollment request format - user origin ISO 3166-2 state code is required when country code is USA. |
| Invalid MiPass Enrollment request format - user origin ISO 3166-2 state code is required when country code is CAN. |
| Invalid MiPass Enrollment request format - user origin ISO 3166-2 state code is invalid. |
| Invalid MiPass Enrollment request format - DIS Face Velocity is enabled with rejection but minimum matches configuration is missing. |
| DIS - Face Blocklist is not enabled on your account. Please contact support to resolve. |
| DIS - Face Velocity is not enabled on your account. Please contact support to resolve. |
| There is an error with your MiPass configuration. Please contact support to resolve. |
| Invalid configuration value provided for Injection Attack Detection; allowed values are: [selfieImages, voiceFeatures]. |
| Injection Attack Detection is not enabled on your account. Please contact support to resolve. |
Enroll Processing Reasons
Face Processing Reasons
| Reason | Description | User Action |
|---|---|---|
| FACE_TOO_CLOSE | Face is too close to the camera to accurately detect features. | Move face back from the camera so all edges are completely visible. |
| FACE_NOT_DETECTED | Face was not detected in the image. | Ensure face is clearly visible and unobstructed. |
| FACE_TOO_SMALL | Face is not large enough to accurately detect features. | Move face closer to the camera and ensure all edges are completely visible. |
| FACE_ANGLE_TOO_LARGE | Face is not directly facing the camera. | Ensure face is pointed straight at the camera and not rotated in any direction. |
| FAILED_TO_READ_IMAGE | There was an error reading the image file. | Ensure raw image bytes are saved and not modified in any way. Make sure an accepted image format is used. |
| FAILED_QUALITY_CHECK | Image does not meet our quality standards. | Ensure image is taken in a location with sufficient lighting and meets our minimum requirements. |
| TOO_MANY_FACES | More than one face was detected in the image. | Ensure only one face is present in the image. |
| FACE_CROPPED | A full face cannot be detected. | Ensure the full face is visible and not obstructed in any way. |
| FACE_FAILED_LIVENESS | Face failed liveness check. | Indicates a fraudulent transaction. |
| FACE_DEEPFAKE_DETECTED | Face failed deepfake detection check. | Indicates a fraudulent transaction. |
| FACE_VELOCITY_SEARCH_ERROR | Face velocity search error occurred. | Retry the transaction. |
| FACE_VELOCITY_ENROLL_ERROR | Face velocity enroll error occurred. | Retry the transaction. |
| FACE_BLOCKLIST_SEARCH_ERROR | Face blocklist search error occurred. | Retry the transaction. |
| USER_ORIGIN_NOT_SUPPORTED | The end-user’s country and/or subdivision is not supported by the Face Velocity or Face Blocklist features. | You may disable the Face Velocity and Face Blocklist features and resubmit. If you require either of these checks, then the end-user is not eligible to enroll. |
| FACE_BLOCKLIST | Face Blocklist with reject was enabled and matches triggered rejection. | Indicates a fraudulent transaction. |
| FACE_VELOCITY | Face Velocity with reject was enabled and matches triggered rejection. | Indicates a fraudulent transaction. |
| INJECTION_ATTACK_DETECTED | Selfie image was injected. | Indicates a fraudulent transaction. |
| MISSING_ENCRYPTED_PAYLOAD | The required encrypted payload associated with the image was not submitted in the service request. | Indicates a fraudulent transaction. |
Voice Processing Reasons
| Reason | Description | User Action |
|---|---|---|
| VOICE_NOT_DETECTED | Unable to detect a voice in the recording. | Submit a clear recording with a voice present. |
| VOICE_FILE_INVALID | There was an error reading the voice file. | Ensure raw voice recording bytes are saved and not modified in any way. Make sure an accepted voice recording format is used. |
| VOICE_FAILED_LIVENESS | Voice failed liveness check. | Indicates a fraudulent transaction. |
| VOICE_TOO_NOISY | Audio is too noisy. | Ask user to repeat the recording in quieter conditions. |
| VOICE_TOO_SMALL_SPEECH_TOTAL_LENGTH | Total speech length in the audio is too small. | Ask user to repeat the given phrase more slowly. |
| DIFFERENT_VOICES_DETECTED | There were different voices detected in the voice files. | Ask user to repeat enrollment phrases and ensure no other voices can be heard while speaking. |
| INJECTION_ATTACK_DETECTED | Voice feature was injected. | Indicates a fraudulent transaction. |
| MISSING_ENCRYPTED_PAYLOAD | The required encrypted payload associated with the voice feature was not submitted in the service request. | Indicates a fraudulent transaction. |
MiPass - Verify
The verify endpoint is used for biometric authentication of an individual’s face and/or voice against a previously-enrolled sample. There are two components to the authentication of each biometric: comparison against the enrolled reference data, and liveness checks on the new sample(s). When authenticating a face and voice simultaneously, the top-level verificationStatus will return the lesser of the two individual biometric judgments. For example, status values of ‘Authentic’ and ‘Undetermined’ will result in a top-level verificationStatus of ‘Undetermined’.
Note: references to nonexistent biometric data will result in a status of ‘Undetermined’. Therefore, overall authentication cannot succeed even if a second biometric is successfully matched and judged to be live.
MiPass - Verify Request
Request Example
POST /identity/biometric/v3/verify HTTP/1.1
Content-Type: application/json
Authorization: Bearer $OAUTH_TOKEN
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"enrollmentId": "32609347-d962-4ec9-9984-5597d7b4c842",
"voiceFeature": {
"data": "BASE64 ENCODED VOICE RECORDING"
},
"selfieImage": {
"data": "BASE64 ENCODED IMAGE"
}
}
Request Example with Mibi
POST /identity/biometric/v3/verify HTTP/1.1
Content-Type: application/json
Authorization: Bearer $OAUTH_TOKEN
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"enrollmentId": "32609347-d962-4ec9-9984-5597d7b4c842",
"voiceFeature": {
"data": "BASE64 ENCODED VOICE RECORDING",
"mibi": "BASE64 ENCODED MIBI JSON STRING"
},
"selfieImage": {
"data": "BASE64 ENCODED IMAGE"
}
}
Request Example with Injection Attack Detection
POST /identity/biometric/v3/verify HTTP/1.1
Content-Type: application/json
Authorization: Bearer $OAUTH_TOKEN
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"enrollmentId": "32609347-d962-4ec9-9984-5597d7b4c842",
"voiceFeature": {
"data": "BASE64 ENCODED VOICE RECORDING",
"encryptedPayload": "BASE64 ENCODED ENCRYPTED PAYLOAD"
},
"selfieImage": {
"data": "BASE64 ENCODED IMAGE"
"encryptedPayload": "BASE64 ENCODED ENCRYPTED PAYLOAD"
},
"configuration": {
"injectionAttackDetection": ["selfieImage", "voiceFeature"]
}
}
URL
POST /identity/biometric/v3/verify
Required Fields
An enrollment can be verified with a face, a voice, or both. At least one of voiceFeatures or selfieImages must be present in the request.
| Name | Type | Description | Restrictions |
|---|---|---|---|
enrollmentId |
String | Mitek provided unique identifier from a previous enrollment. | UUID |
voiceFeature |
Object | Voice recording to verify. | N/A |
data |
String | Base64-encoded WAV, WebM, or MP4 file containing voice recording. | N/A |
mibi |
String | [OPTIONAL] Base64-encoded JSON object containing session analytics data for the voice recording. Only applicable to MiSnap WebSDK capture events. | N/A |
encryptedPayload |
String | A base64-encoded string containing an encrypted real-time security payload generated by Mitek’s MiSnap Capture SDKs v.5.5.0 and newer. This field is only required if voiceFeature is enabled in the Injection Attack Detection object in the request configuration. |
N/A |
selfieImage |
Object | Selfie image to verify. | N/A |
data |
String | Base64-encoded selfie image file. | N/A |
encryptedPayload |
String | A base64-encoded string containing an encrypted real-time security payload generated by Mitek’s MiSnap Capture SDKs v.5.4.0 and newer. This field is only required if selfieImage is enabled in the Injection Attack Detection object in the request configuration. |
N/A |
Optional Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
String | Customer provided identifier that will be returned within the body of the response. | 500 characters limit |
configuration |
Object | Configuration Options. | N/A |
injectionAttackDetection |
Object | A list of biometric types enabled for injection attack detection to be performed on. | selfieImage, voiceFeature |
MiPass - Verify Response
"AUTHENTIC" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"enrollmentId": "32609347-d962-4ec9-9984-5597d7b4c842",
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24",
"verificationStatus": "AUTHENTIC",
"details": {
"faceVerify": {
"status": "AUTHENTIC",
"dataExpiration": "2025-02-13T17:23:44Z"
},
"voiceVerify": {
"status": "AUTHENTIC",
"dataExpiration": "2025-02-13T17:23:44Z"
}
}
}
"FRAUDULENT" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"enrollmentId": "32609347-d962-4ec9-9984-5597d7b4c842",
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24",
"verificationStatus": "FRAUDULENT",
"details": {
"faceVerify": {
"status": "FRAUDULENT",
"reasons": ["FACE_FAILED_LIVENESS"]
},
"voiceVerify": {
"status": "FRAUDULENT",
"reasons": ["VOICE_FAILED_COMPARE"]
}
}
}
"UNDETERMINED" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"enrollmentId": "32609347-d962-4ec9-9984-5597d7b4c842",
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24",
"verificationStatus": "UNDETERMINED",
"details": {
"faceVerify": {
"status": "UNDETERMINED",
"reasons": ["FAILED_QUALITY_CHECK", "FACE_NOT_DETECTED"]
},
"voiceVerify": {
"status": "AUTHENTIC"
}
}
}
"FRAUDULENT" Response Example with Injection Attack Detection
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"enrollmentId": "32609347-d962-4ec9-9984-5597d7b4c842",
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24",
"verificationStatus": "FRAUDULENT",
"details": {
"faceVerify": {
"status": "FRAUDULENT",
"reasons": ["MISSING_ENCRYPYED_PAYLOAD"]
},
"voiceVerify": {
"status": "FRAUDULENT",
"reasons": ["INJECTION_ATTACK_DETECTED"]
}
},
"configuration": {
"injectionAttackDetection": ["selfieImage", "voiceFeature"]
}
}
"UNDETERMINED" Response Example with Injection Attack Detection
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"enrollmentId": "32609347-d962-4ec9-9984-5597d7b4c842",
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24",
"verificationStatus": "UNDETERMINED",
"details": {
"faceVerify": {
"status": "UNDETERMINED",
"reasons": ["FACE_NOT_DETECTED"]
},
"voiceVerify": {
"status": "AUTHENTIC"
}
},
"configuration": {
"injectionAttackDetection": ["selfieImage", "voiceFeature"]
}
}
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
String | A value submitted with the original request that is returned in the response. | N/A |
enrollmentId |
String | Unique identifier for the enrollment. Used in verify, update, or delete operations. | UUID |
requestId |
String | The unique identifier that Mitek Systems has assigned to this transaction. | UUID |
verificationStatus |
String | Overall status of the verify operation. | AUTHENTIC or FRAUDULENT or UNDETERMINED |
details |
Object | Details of processing outcomes for the verify operation. | N/A |
faceVerify |
Object | Contains details regarding face verification. | N/A |
status |
String | Status of face verification. | AUTHENTIC or FRAUDULENT or UNDETERMINED |
reasons |
String (array) | Reasons for face verification failure. | N/A |
dataExpiration |
String | The expiration timestamp for the enrolled face data. | RFC 3339 Timestamp |
voiceVerify |
Object | Contains details regarding voice verification. | N/A |
status |
String | Status of voice verification. | AUTHENTIC or FRAUDULENT or UNDETERMINED |
reasons |
String (array) | Reasons for voice verification failure. | N/A |
dataExpiration |
String | The expiration timestamp for the enrolled voice data. | RFC 3339 Timestamp |
configuration |
Object | Configuration options. | N/A |
injectionAttackDetection |
Object | A list of biometric types on which injection attack detection was performed as requested. | selfieImage, voiceFeature |
MiPass - Verify Error Responses
400 Response Example
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"message": "Customer reference id should not exceed 500 characters."
}
OR
{
"message": "No enrollment id provided in the request."
}
401 Response Example
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"message": "Authorization has been denied for this request."
}
403 Forbidden
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"message": "You do not have the correct permissions to perform MiPass Verify."
}
415 Response Example
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
{
"message": "The request entity's media type '...' is not supported for this resource."
}
500 Response Example
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{
"message": "There was a technical problem processing your request. Please try again."
}
Standard HTTP REST-based response codes and messages are used to indicate success or failure for a request.
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
message |
String | A message describing the error. | None |
All "Bad Request" Error Messages
| Message |
|---|
| No enrollment id provided in the request. |
| No voice feature or selfie image provided in MiPass Verify request. |
| Image data not provided in selfie image. |
| Voice data not provided in voice feature. |
| Illegal base64 data at input byte 4. |
| The given Enrollment ID does not exist or is invalid. |
| The Enrolled Face is no longer valid. Enrollment needs to be updated before running Verify operation. |
| The Enrolled Voice is no longer valid. Enrollment needs to be updated before running Verify operation. |
| Invalid configuration value provided for Injection Attack Detection; allowed values are: [selfieImages, voiceFeatures]. |
| Injection Attack Detection is not enabled on your account. Please contact support to resolve. |
Verify Processing Reasons
Face Processing Reasons
| Reason | Description | User Action |
|---|---|---|
| FACE_TOO_CLOSE | Face is too close to the camera to accurately detect features. | Move face back from the camera so all edges are completely visible. |
| FACE_NOT_DETECTED | Face was not detected in the image. | Ensure face is clearly visible and unobstructed. |
| FACE_TOO_SMALL | Face is not large enough to accurately detect features. | Move face closer to the camera and ensure all edges are completely visible. |
| FACE_ANGLE_TOO_LARGE | Face is not directly facing the camera. | Ensure face is pointed straight at the camera and not rotated in any direction. |
| FAILED_TO_READ_IMAGE | There was an error reading the image file. | Ensure raw image bytes are saved and not modified in any way. Make sure an accepted image format is used. |
| FAILED_QUALITY_CHECK | Image does not meet our quality standards. | Ensure image is taken in a location with sufficient lighting and meets our minimum requirements. |
| TOO_MANY_FACES | More than one face was detected in the image. | Ensure only one face is present in the image. |
| FACE_CROPPED | A full face cannot be detected. | Ensure the full face is visible and not obstructed in any way. |
| FACE_NOT_ENROLLED | Face has not been previously enrolled. | Ensure a face has been previously enrolled before attempting this operation. |
| FACE_FAILED_LIVENESS | Face failed liveness check. | Indicates a fraudulent transaction. |
| FACE_DEEPFAKE_DETECTED | Face failed deepfake detection check. | Indicates a fraudulent transaction. |
| FACE_FAILED_COMPARE | Face did not match with enrolled face. | Indicates a fraudulent transaction. |
| FACE_DATA_EXPIRED | The previously enrolled face data has expired. | Update the enrollment before attempting this operation. |
| INJECTION_ATTACK_DETECTED | Selfie image was injected. | Indicates a fraudulent transaction. |
| MISSING_ENCRYPTED_PAYLOAD | The required encrypted payload associated with the image was not submitted in the service request. | Indicates a fraudulent transaction. |
| INCOMPATIBLE_FACE_TEMPLATE_VERSION | The previously enrolled face data has an incompatible face template version. |
Voice Processing Reasons
| Reason | Description | User Action |
|---|---|---|
| VOICE_NOT_DETECTED | Unable to detect a voice in the recording. | Submit a clear recording with a voice present. |
| VOICE_NOT_ENROLLED | Voice has not been previously enrolled. | Ensure a voice has been previously enrolled before attempting this operation. |
| VOICE_FILE_INVALID | There was an error reading the voice file. | Ensure raw voice recording bytes are saved and not modified in any way. Make sure an accepted voice recording format is used. |
| VOICE_FAILED_LIVENESS | Voice failed liveness check. | Indicates a fraudulent transaction. |
| VOICE_FAILED_COMPARE | Voice did not match with enrolled voice. | Indicates a fraudulent transaction. |
| VOICE_DATA_EXPIRED | The previously enrolled voice data has expired. | Update the enrollment before attempting this operation. |
| VOICE_TOO_NOISY | Audio is too noisy. | Ask user to repeat the recording in quieter conditions. |
| VOICE_TOO_SMALL_SPEECH_TOTAL_LENGTH | Total speech length in the audio is too small. | Ask user to repeat the given phrase more slowly. |
| INJECTION_ATTACK_DETECTED | Voice feature was injected. | Indicates a fraudulent transaction. |
| MISSING_ENCRYPTED_PAYLOAD | The required encrypted payload associated with the voice feature was not submitted in the service request. | Indicates a fraudulent transaction. |
| INCOMPATIBLE_VOICE_TEMPLATE_VERSION | The previously enrolled voice data has an incompatible voice template version. |
MiPass - Delete
A DELETE request to the enroll endpoint will flag an enrollment record as permanently deleted and immediately delete the associated biometric data.
MiPass - Delete Request
Request Example
DELETE /identity/biometric/v3/enroll/32609347-d962-4ec9-9984-5597d7b4c842?customerReferenceId=e759256b-46c0-475a-97eb-fe1c0a18a3bc HTTP/1.1
Authorization: Bearer $OAUTH_TOKEN
URL
DELETE /identity/biometric/v3/enroll/{enrollmentId}?customerReferenceId={customerReferenceId}
Required Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
enrollmentId |
String | Mitek provided unique identifier from a previous enrollment. | UUID |
Optional Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
String | Customer provided identifier that will be returned within the body of the response. | 500 characters limit |
Biometric Auth - Delete Response
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"enrollmentId": "32609347-d962-4ec9-9984-5597d7b4c842",
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24"
}
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
String | A value submitted with the original request that is returned in the response. | N/A |
enrollmentId |
String | Unique identifier for the enrollment. Used in verify, update, or delete operations. | UUID |
requestId |
String | The unique identifier that Mitek Systems has assigned to this transaction. | UUID |
MiPass - Delete Error Responses
400 Response Example
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"message": "Customer reference id should not exceed 500 characters."
}
OR
{
"message": "No enrollment id provided in the request."
}
401 Response Example
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"message": "Authorization has been denied for this request."
}
403 Forbidden
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"message": "You do not have the correct permissions to delete a MiPass Enrollment."
}
404 Not Found
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"message": "The given Enrollment ID does not exist or has already been deleted."
}
415 Response Example
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
{
"message": "The request entity's media type '...' is not supported for this resource."
}
500 Response Example
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{
"message": "There was a technical problem processing your request. Please try again."
}
Standard HTTP REST-based response codes and messages are used to indicate success or failure for a request.
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
message |
String | A message describing the error. | None |
MiPass - Check Quality
The Check Quality endpoint is used to evaluate the quality of the voice recording and determine if it meets the reasonable criteria for biometric enrollment or verification.
MiPass - Check Quality Request
Request Example
POST /identity/biometric/v3/check-quality HTTP/1.1
Content-Type: application/json
Authorization: Bearer $OAUTH_TOKEN
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"transactionType": "ENROLL",
"voiceFeature": {
"data": "BASE64 ENCODED VOICE RECORDING"
}
}
Request Example with Mibi
POST /identity/biometric/v3/check-quality HTTP/1.1
Content-Type: application/json
Authorization: Bearer $OAUTH_TOKEN
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"transactionType": "ENROLL",
"voiceFeature": {
"data": "BASE64 ENCODED VOICE RECORDING",
"mibi": "BASE64 ENCODED MIBI JSON STRING"
}
}
URL
POST /identity/biometric/v3/check-quality
Required Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
transactionType |
String | The transaction type for which the voice recording will be used. | ENROLL or VERIFY |
voiceFeature |
Object | Voice recording to check quality. | N/A |
data |
String | Base64-encoded WAV, WebM, or MP4 file containing voice recording. | N/A |
mibi |
String | [OPTIONAL] Base64-encoded JSON object containing session analytics data for the voice recording. Only applicable to MiSnap WebSDK capture events. | N/A |
Optional Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
String | Customer provided identifier that will be returned within the body of the response. | 500 characters limit |
MiPass - Check Quality Response
"PASS" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24",
"transactionType": "ENROLL",
"qualityResult": {
"status": "PASS"
}
}
"FAIL" Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24",
"transactionType": "ENROLL",
"qualityResult": {
"status": "FAIL",
"reasons": [
"VOICE_TOO_NOISY",
"VOICE_TOO_SMALL_SPEECH_TOTAL_LENGTH"
]
}
}
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
String | A value submitted with the original request that is returned in the response. | N/A |
requestId |
String | The unique identifier that Mitek Systems has assigned to this transaction. | UUID |
transactionType |
String | A value submitted with the original request that is returned in the response. | ENROLL or VERIFY |
qualityResult |
Object | Details of processing outcomes for the check quality operation. | N/A |
status |
String | Status of check quality operation. | PASS or FAIL |
reasons |
String (array) | Reasons for check quality failure. | N/A |
MiPass - Check Quality Error Responses
400 Response Example
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"message": "Customer reference id should not exceed 500 characters."
}
OR
{
"message": "Transaction type is required; allowed values are ENROLL or VERIFY."
}
OR
{
"message": "Voice data not provided in voice feature."
}
401 Response Example
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"message": "Authorization has been denied for this request."
}
403 Forbidden
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"message": "You do not have the correct permissions to perform MiPass Check Quality."
}
415 Response Example
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
{
"message": "The request entity's media type '...' is not supported for this resource."
}
500 Response Example
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{
"message": "There was a technical problem processing your request. Please try again."
}
Standard HTTP REST-based response codes and messages are used to indicate success or failure for a request.
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
message |
String | A message describing the error. | None |
Check Quality Processing Reasons
Voice Processing Reasons
| Reason | Description | User Action |
|---|---|---|
| VOICE_FILE_INVALID | There was an error reading the voice file. | Ensure raw voice recording bytes are saved and not modified in any way. Make sure an accepted voice recording format is used. |
| VOICE_TOO_NOISY | Audio is too noisy. | Ask user to repeat the recording in quieter conditions. |
| VOICE_TOO_SMALL_SPEECH_TOTAL_LENGTH | Total speech length in the audio is too small. | Ask user to repeat the given phrase more slowly. |
Face Blocklist (MiPass) - Create Item
The Create Item endpoint enables the addition of new faces to the blocklist. An Enrollment ID of an existing MiPass Enrollment which contains the selfie image to be blocked is required.
Face Blocklist (MiPass) - Create Item Request
Request Example - New Face Blocklist Item Using Enrollment ID
POST /identity/faceblocklist/v3/items HTTP/1.1
Content-Type: application/json
Authorization: Bearer $OAUTH_TOKEN
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"blockEnrollmentId": "de545132-2942-4df0-b89e-d87bd447ac60"
}
URL
POST /identity/faceblocklist/v3/items
Required Fields
A Face Blocklist item can be created with an Enrollment ID of a MiPass Enrollment.
| Name | Type | Description | Restrictions |
|---|---|---|---|
blockEnrollmentId |
string | Enrollment ID of an existing MiPass Enrollment. The selfie image used in the referenced Enrollment will be added to the blocklist. | UUID |
Optional Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
string | Customer provided identifier that will be returned within the body of the response. | 500 characters limit |
Face Blocklist (MiPass) - Create Item Response
"Successful" Response Example
HTTP/1.1 201 Created
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24",
"status": "Successful",
"item": {
"itemId": "c45c8b05-fa95-4331-89fa-91f7732fdd21",
"blockEnrollmentId": "de545132-2942-4df0-b89e-d87bd447ac60",
"createdAt": "2022-02-13T17:23:44Z"
}
}
"Failed" Response Example
HTTP/1.1 201 Created
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24",
"status": "Failed",
"reasons": ["ENROLLMENT_NOT_FOUND"]
}
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
string | A value submitted with the original request that is returned in the response. | N/A |
requestId |
string | The unique identifier that Mitek Systems has assigned to this transaction. | UUID |
status |
string | Status of the create operation. | Successful Failed |
reasons |
string (array) | Reasons for create failure. | N/A |
item |
object | Details of created item. | N/A |
itemId |
string | The unique identifier associated with this item. | UUID |
blockEnrollmentId |
string | Enrollment ID of an existing MiPass Enrollment used to create this item. | UUID |
createdAt |
string | The timestamp for when this item was created. | RFC 3339 Timestamp |
Face Blocklist (MiPass) - Create Item Error Responses
400 Response Example
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"message": "Customer reference id should not exceed 500 characters."
}
OR
{
"message": "Invalid FaceBlocklist Create Request Format - [... details ...]"
}
OR
{
"message": "Tenant has reached the gallery enrollment limit. Please reach out to customer support to increase the limit."
}
401 Response Example
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"message": "Authorization has been denied for this request."
}
403 Forbidden
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"message": "You do not have the correct permissions to create a Face Blocklist item."
}
415 Response Example
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
{
"message": "The request entity's media type '...' is not supported for this resource."
}
500 Response Example
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{
"message": "There was a technical problem processing your request. Please try again."
}
Standard HTTP REST-based response codes and messages are used to indicate success or failure for a request.
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
message |
String | A message describing the error. | None |
Create Item - Processing Reasons
Processing Reasons
| Reason | Description | User Action |
|---|---|---|
| ENROLLMENT_NOT_FOUND | Referenced enrollment was not found. | Ensure enrollment ID of referenced enrollment is valid. |
| ENROLLMENT_NO_SELFIE | Referenced enrollment does not contain a selfie image. | Referenced enrollment must have a selfie image to add to the blocklist. |
| USER_ORIGIN_UNAVAILABLE | Referenced enrollment does not contain a country and/or subdivision. | The enrollment is not eligible to be added to the blocklist. |
| USER_ORIGIN_NOT_SUPPORTED | Referenced enrollment has country and/or subdivision that is not supported by the Face Blocklist feature. | The enrollment is not eligible to be added to the blocklist. |
Face Blocklist (MiPass) - Get Item
The Get Item endpoint receives a single blocklist item ID and responds with all associated metadata for the item.
Face Blocklist (MiPass) - Get Item Request
Request Example
GET /identity/faceblocklist/v3/items/b6db77ab-b5d4-47e9-b978-0c4277a7af03?customerReferenceId=e759256b-46c0-475a-97eb-fe1c0a18a3bc HTTP/1.1
Authorization: Bearer $OAUTH_TOKEN
URL
GET /identity/faceblocklist/v3/items/{itemId}?customerReferenceId={customerReferenceId}
Required Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
itemId |
string | Mitek provided unique identifier for an existing item. | UUID |
Optional Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
string | Customer provided identifier that will be returned within the body of the response. | 500 characters limit |
Face Blocklist (MiPass) - Get Item Response
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24",
"item": {
"itemId": "b6db77ab-b5d4-47e9-b978-0c4277a7af03",
"blockEnrollmentId": "274a9688-98f6-4b04-9ad9-48dca53522eb",
"createdAt": "2022-02-13T17:23:44Z"
}
}
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
string | A value submitted with the original request that is returned in the response. | N/A |
requestId |
string | The unique identifier that Mitek Systems has assigned to this transaction. | UUID |
item |
object | Details of retrieved item. | N/A |
itemId |
string | The unique identifier associated with this item. | UUID |
blockEnrollmentId |
string | Enrollment ID of the MiPass Enrollment used to create this item. | UUID |
createdAt |
string | The timestamp for when this item was created. | RFC 3339 Timestamp |
Face Blocklist (MiPass) - Get Item Error Responses
400 Response Example
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"message": "Customer reference id should not exceed 500 characters."
}
OR
{
"message": "Invalid FaceBlocklist GetItem Request Format - [... details ...]"
}
401 Response Example
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"message": "Authorization has been denied for this request."
}
403 Forbidden
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"message": "You do not have the correct permissions to retrieve a Face Blocklist item."
}
404 Not Found
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"message": "The given Item ID does not exist or is invalid."
}
415 Response Example
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
{
"message": "The request entity's media type '...' is not supported for this resource."
}
500 Response Example
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{
"message": "There was a technical problem processing your request. Please try again."
}
Standard HTTP REST-based response codes and messages are used to indicate success or failure for a request.
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
message |
String | A message describing the error. | None |
Face Blocklist (MiPass) - Get Items
The Get Items endpoint returns a list of existing blocklist metadata associated to the tenant, sorted by item ID. The response is limited to the first N records with subsequent pages called using cursor-based pagination.
Face Blocklist (MiPass) - Get Items Request
Request Example
GET /identity/faceblocklist/v3/items?customerReferenceId=e759256b-46c0-475a-97eb-fe1c0a18a3bc&cursor=b6db77ab-b5d4-47e9-b978-0c4277a7af03&limit=50 HTTP/1.1
Authorization: Bearer $OAUTH_TOKEN
URL
GET /identity/faceblocklist/v3/items?customerReferenceId={customerReferenceId}&cursor={cursor}&limit={limit}
Optional Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
string | Customer provided identifier that will be returned within the body of the response. | 500 characters limit |
cursor |
string | Paging field that specifies where retrieval should start from. This value comes from a Get Items response. | UUID |
limit |
integer | Paging field that specifies the number of items to return in the response. If limit is not specified, the result set is limited to the first 1MB of data. | int32 |
Face Blocklist (MiPass) - Get Items Response
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24",
"items": [
{
"itemId": "b6db77ab-b5d4-47e9-b978-0c4277a7af03",
"blockEnrollmentId": "09a1c618-7114-488f-b7a6-ca0a93a92a21",
"createdAt": "2022-02-13T17:23:44Z"
},
{
"itemId": "c45c8b05-fa95-4331-89fa-91f7732fdd21",
"blockEnrollmentId": "de545132-2942-4df0-b89e-d87bd447ac60",
"createdAt": "2022-03-23T13:23:12Z"
},
{
"itemId": "087ddea4-a2df-4b0c-b8fb-f7865d827cbc",
"blockEnrollmentId": "274a9688-98f6-4b04-9ad9-48dca53522eb",
"createdAt": "2022-04-07T06:23:17Z"
}
],
"paging": {
"cursor": "f168549f-c29b-4f09-bb69-973c09815640",
"limit": 50
}
}
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
string | A value submitted with the original request that is returned in the response. | N/A |
requestId |
string | The unique identifier that Mitek Systems has assigned to this transaction. | UUID |
items |
object (array) | Array of items in blocklist. | N/A |
item |
object | Details of retrieved item. | N/A |
itemId |
string | The unique identifier associated with this item. | UUID |
blockEnrollmentId |
string | Enrollment ID of the MiPass Enrollment used to create this item. | UUID |
createdAt |
string | The timestamp for when this item was created. | RFC 3339 Timestamp |
paging |
object | Paging details to be used in the next retrieval. | N/A |
cursor |
string | Paging field that specifies where the next retrieval should start from. | UUID |
limit |
integer | Paging field that specifies the number of items returned in the response. | int32 |
Face Blocklist (MiPass) - Get Items Error Responses
400 Response Example
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"message": "Customer reference id should not exceed 500 characters."
}
OR
{
"message": "Invalid FaceBlocklist GetItems Request Format - [... details ...]"
}
401 Response Example
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"message": "Authorization has been denied for this request."
}
403 Forbidden
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"message": "You do not have the correct permissions to retrieve Face Blocklist items."
}
415 Response Example
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
{
"message": "The request entity's media type '...' is not supported for this resource."
}
500 Response Example
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{
"message": "There was a technical problem processing your request. Please try again."
}
Standard HTTP REST-based response codes and messages are used to indicate success or failure for a request.
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
message |
String | A message describing the error. | None |
Face Blocklist (MiPass) - Delete Item
The Delete Item endpoint enables the deletion of a single face image from the blocklist. Upon success the face image is immediately and permanently deleted, and no further MiPass enrollment transactions may be compared with that blocklist item.
Face Blocklist (MiPass) - Delete Item Request
Request Example
DELETE /identity/faceblocklist/v3/items/89034a0e-5908-45bd-9627-6d133c8def3d?customerReferenceId=e759256b-46c0-475a-97eb-fe1c0a18a3bc HTTP/1.1
Authorization: Bearer $OAUTH_TOKEN
URL
DELETE /identity/faceblocklist/v3/items/{itemId}?customerReferenceId={customerReferenceId}
Required Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
itemId |
string | Mitek provided unique identifier for an existing item. | UUID |
Optional Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
string | Customer provided identifier that will be returned within the body of the response. | 500 characters limit |
Face Blocklist (MiPass) - Delete Item Response
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Mitek-Request-Id: 5b55449e-bec3-4cff-b2d2-a8e6e4a3af24
Mitek-Server-Processing-Time: 4021
{
"customerReferenceId": "e759256b-46c0-475a-97eb-fe1c0a18a3bc",
"itemId": "89034a0e-5908-45bd-9627-6d133c8def3d",
"requestId": "5b55449e-bec3-4cff-b2d2-a8e6e4a3af24"
}
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
customerReferenceId |
string | A value submitted with the original request that is returned in the response. | N/A |
itemId |
string | Unique identifier for the item that was deleted. | UUID |
requestId |
string | The unique identifier that Mitek Systems has assigned to this transaction. | UUID |
Face Blocklist (MiPass) - Delete Item Error Responses
400 Response Example
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"message": "Customer reference id should not exceed 500 characters."
}
OR
{
"message": "Invalid Biometric Delete Request Format - [... details ...]"
}
401 Response Example
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"message": "Authorization has been denied for this request."
}
403 Forbidden
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"message": "You do not have the correct permissions to delete a Face Blocklist item."
}
404 Not Found
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"message": "The given Item ID does not exist or has already been deleted."
}
415 Response Example
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
{
"message": "The request entity's media type '...' is not supported for this resource."
}
500 Response Example
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{
"message": "There was a technical problem processing your request. Please try again."
}
Standard HTTP REST-based response codes and messages are used to indicate success or failure for a request.
Returned Fields
| Name | Type | Description | Restrictions |
|---|---|---|---|
message |
String | A message describing the error. | None |