Send Inputs

Use this API to send documents, selfies, videos, or other identifying information

Use this POST request to send the user's identifiers (for example, images of document - front/back, selfie image, liveness video) for validation.

This API supports uploads for the following merits:

File Requirements
Request Body Requirements
Error Codes

File Requirements

Image Files

Image files (such as document photos and selfies) must have at minimum resolution of 600x600 pixels with a maximum file size of 50MB. The following is a list of supported image file formats:

  • *.jpg
  • *.jpeg
  • *.png
  • *.pdf — exclusive to custom documents & Bank Account Statements

Video Files

Video files (such as liveness tests) can have a maximum file size of 50MB. The following is a list of supported video formats:

  • MP4
  • WebM
  • QuickTime (*.mov)
  • 3GP (*.3gpp)
  • X-Matroska ( _.mkv, _.mk3d, _.mka, _.mks)

Document Handling

📘

One-Sided Document Handling

The API can handle both one- and two-sided documents.

  • If a user only sends the front of a one-sided document, MetaMap will immediately start the verification process
  • If a user only sends the front of a document that may have one or two sides, MetaMap will wait 10 minutes for the image of the document back before starting the verification process with only the front.
  • You can use the Skip Verification Upload Wait Time API for documents that may have one or two sides to skip the 10 minute wait time.

For a list of countries whose documents have one side, two sides, or one or two sides, go here.

Request Body Requirements

Example Requests

The following are example requests to upload documents and images.

curl --location --request POST 'https://api.getmati.com/v2/identities/{identity}/send-input' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer <access_token>' \
--form 'inputs=[
  {
    "inputType": "document-photo",
    "group": 0,
    "data": {
      "type": "driving-license",
      "country": "MX",
      "page": "front",
      "filename": "MX_NI_FRONT.jpg"
    }
  },
  {
    "inputType": "document-photo",
    "group": 0,
    "data": {
      "type": "driving-license",
      "country": "MX",
      "page": "back",
      "filename": "MX_NI_BACK.jpg"
    }
  },
    {
    "inputType": "document-photo",
    "group": 1,
    "data": {
      "type": "passport",
      "country": "MX",
      "page": "front",
      "filename": "MX_PASSPORT.jpg"
    }
   {
    "inputType": "document-photo",
    "group": 2,
    "data": {
      "type": "proof-of-residency",
      "country": "MX",
      "page": "front",
      "filename": "proof-of-residence.png"
    }
  },
  {
    "inputType": "selfie-photo",
    "data": {
      "type": "selfie-photo",
      "filename": "selfie-photo.jpg"
    }
  }
]' \
--form 'document=@/C:/PATH_TO_FILE/MX_NI_FRONT.jpg' \
--form 'document=@/C:/PATH_TO_FILE/MX_NI_BACK.jpg' \
--form 'document=@/C:/PATH_TO_FILE/MX_PASSPORT.jpg' \
--form 'document=@/C:/PATH_TO_FILE/proof-of-residence.png' \
--form 'selfie=@/C:/PATH_TO_FILE/selfie-photo.jpg'
curl --location --request POST 'https://api.getmati.com/v2/identities/{identity}/send-input' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer <access_token>' \
--form 'inputs=[ 
    {"inputType":"document-photo","group":0, 
        "data":{
           "type":"national-id",
           "country":"BR",
           "region":"",
           "page":"front",
           "filename":"43_front.jpg"
           }
        }, 
    {"inputType":"document-photo","group":0, 
        "data":{
           "type":"national-id",
           "country":"BR",
           "region":"",
           "page":"back",
           "filename":"44_back.jpg"
           }
        } 
    ]' 
--form 'document=@/C:/PATH_TO_FILE/43_front.jpg' 
--form 'document=@/C:/PATH_TO_FILE/44_back.jpg'
curl --location --request POST 'https://api.getmati.com/v2/identities/{identity}/send-input' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer <access_token>' \
--form 'inputs=[
  {
    "inputType": "document-photo",
    "group": 0,
    "data": {
      "type": "national-id",
      "country": "US",
      "region" : "CA",
      "page": "front",
      "filename": "US_CA_DL_FRONT.jpg"
    }
  },
  {
    "inputType": "document-photo",
    "group": 0,
    "data": {
      "type": "national-id",
      "country": "US",
      "region" : "CA",
      "page": "back",
      "filename": "US_CA_DL_BACK.jpg"
    }
  },
   {
    "inputType": "selfie-video",
    "data": {
      "filename": "Liveness_video.mp4"
    }
  }
]' \
--form 'document=@/C:/PATH_TO_FILE/US_CA_DL_FRONT.jpg' \
--form 'document=@/C:/PATH_TO_FILE/US_CA_DL_BACK.jpg' \
--form 'video=@/C:/PATH_TO_FILE/Liveness_video.mp4'
curl --location --request POST 'https://api.getmati.com/v2/identities/{identity}/send-input' \
--header 'Content-Type: x-www-form-urlencoded' \
--header 'Authorization: Bearer <access_token>' \
--form 'inputs=[
  {
  "inputType":"custom-document-photo",
  "group":0,
  "data":{
    "type":"custom-birth-certificate",
    "page":"front",
    "filename":"birth_front.jpg"
    }
  },
  {
  "inputType":"custom-document-photo",
  "group":0,
  "data":{
    "type":"custom-birth-certificate",
    "page":"back",
    "filename":"birth_back.jpg"
    }
  }
]' \
--form 'custom-document=@/C:/PATH_TO_FILE/birth_front.jpg' \
--form 'custom-document=@/C:/PATH_TO_FILE/birth_back.jpg' \
  
  
curl --location --request POST 'https://api.getmati.com/v2/identities/{identity}/send-input' \
--header 'Authorization: Bearer <access_token>' \
--form 'document=@"/<PATH>/co-nid-front.png"' \
--form 'document=@"/<PATH>/co-nid-back.png"' \
--form 'inputs=[
    {
    "inputType":"document-photo",
    "group":0,
    "data":
        {
        "type":"national-id",
        "country":"CO",
        "page":"front",
        "filename":"co-nid-front.png"
        }
    },
    {
    "inputType":"document-photo",
    "group":0,
    "data":
        {
        "type":"national-id",
        "country":"CO",
        "page":"back",
        "filename":"co-nid-back.png"
        }
    },
    {
    "inputType":"custom-document-photo",
    "group":1,
    "data":
        {
        "type":"custom-dummy-doc",
        "page":"multi","filename":"dummy-doc.pdf"
        }
    }
]' \
--form 'custom-document=@"/<PATH>/dummy-doc.pdf"'
curl --location --request POST 'https://api.getmati.com/v2/identities/{{identity}}/send-input' 
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer {{access_token}}' \
--form 'inputs="[
{
  "inputType": "custom-fields",
  "data": {
    "fields": [
      {
        "atomicFieldParams": {
         "mapping": {       // mapping is required on only for fields which have system mapping
            "country": "BR",// 2 letter ISO code of the country
            "key": "cpf"    // key of the mapping system field
          },
          "type": "text",   // type of the field: text/date/select/checkbox
          "value": "111111111-111"  // sent value
        },
        "name": "Document_ID",
        "type": "atomic"    // constant
      },
      {
        "atomicFieldParams": {
          "mapping": {      // mapping is required on only for fields which have system mapping
            "country": "AA",
            "key": "fullName"
          },
          "type": "text",   // type of the field
          "value": "John Doe"  // sent value
        },
        "name": "fullname", // Name of the custom input field
        "type": "atomic"    // constant
      }
    ],
    "country": "BR"
  }
}
]"
curl --location --request POST 'https://api.getmati.com/v2/identities/{{identity}}/send-input' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer {{access_token}}' \
--form 'inputs="[
   {
     "inputType":"financial-information-bank-statement-parsing-request",
      "data":{
         "type":"bank-document",
         "country":"MX",
         "institutionId":"{bank_id}",
         "password":"MALC710206TX1",
         "filename":"{bank-statement1}.pdf"
      }
   },
   {
      "inputType":"financial-information-bank-statement-parsing-request",
      "data":{
         "type":"bank-document",
         "country":"MX",
         "institutionId":"{bank_id}",
         "filename":"{bank-statement2}.pdf"
      }
   }
]"' \
--form 'bank-document=@"/{PATH}/{bank-statement1}.pdf"' \
--form 'bank-document=@"/{PATH}/{bank-statement2}.pdf"' \

Error Codes

API errors can be one of three types:

  • IntegrationError: There's an error in integrating of API, such as the input does not match the Dashboard configuration
  • ValidationError: Provided data does not pass validation. User should upload another photo or video file.
  • SystemError: Errors related to the server infrastructure.

The 201 responses occur after all uploads have completed and one or more data points has failed validation.

The following table lists the error codes

Error CodeDescription
documentPhoto.badTextDocument field validation failed
documentPhoto.blurryTextDocument photo is too blurry
documentPhoto.smallImageSizeDocument photo resolution is too low
documentPhoto.unexpectedDataUnexpected error in document reading
documentPhoto.noTextDocument photo has no text
documentPhoto.noFaceDocument photo has no face (for validation steps that require a face)
documentPhoto.grayscaleImageDocument photo is in grayscale
documentPhoto.screenPhotoDocument photo is a screen shot. User must upload a different photo
documentPhoto.noDocumentDocument photo does not match a known document template
documentPhoto.missingFieldsDocument photo is missing some required fields
documentPhoto.wrongFormatSome required fields from the document use an invalid format
documentPhoto.noMrzDocument photo has no Machine-Readable Zone (MRZ, for validation steps that require one)
documentPhoto.badMrzDocument photo has corrupted Machine-Readable Zone
(MRZ, for validation steps that require one)
documentPhoto.noPdf417Document photo has no PDF417 barcode (for validation steps that require one)
documentPhoto.badPdf417Document photo has corrupted PDF417 barcode (for validation steps that require one)
documentPhoto.typeMismatchDocument type claimed by user and document type detected from photo are different
documentPhoto.countryMismatchDocument country claimed by user and document country detected from document photo are different
documentPhoto.croppedDocumentDocument boundaries are not completely visible in the photo
documentPhoto.sideMismatchDocument's claimed side (front or back) does not match with the submitted side
voiceVideo.conversionFailedVideo conversion failed
voiceVideo.multipleFacesMultiple simultaneous faces are detected in the video
voiceVideo.noFaceNo faces detected in the video
bankDocument.passwordRequiredThe bank statement is password-protected. Please provide the password to open and read the file.
bankDocument.passwordFailedThe bank statement is password-protected. Please provide the correct password to read the file.
bankDocument.badFileNameBank-document file name differs from input file name.
bankDocument.invalidMetadataPlease upload the original bank statement. Altered files will not be accepted.
bankDocument.statementNotSupportedThe bank statement template is unsupported. Contact MetaMap support for help.
CustomDocumentPhoto.multiPageInputErrorThe file sent as Custom Document has multiple pages, when in the Flow Settings, multiple pages document is not supported.
Language
Authorization
OAuth2