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

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 '[email protected]/C:/PATH_TO_FILE/MX_NI_FRONT.jpg' \
--form '[email protected]/C:/PATH_TO_FILE/MX_NI_BACK.jpg' \
--form '[email protected]/C:/PATH_TO_FILE/MX_PASSPORT.jpg' \
--form '[email protected]/C:/PATH_TO_FILE/proof-of-residence.png' \
--form '[email protected]/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 '[email protected]/C:/PATH_TO_FILE/43_front.jpg' 
--form '[email protected]/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 '[email protected]/C:/PATH_TO_FILE/US_CA_DL_FRONT.jpg' \
--form '[email protected]/C:/PATH_TO_FILE/US_CA_DL_BACK.jpg' \
--form '[email protected]/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 '[email protected]/C:/PATH_TO_FILE/birth_front.jpg' \
--form '[email protected]/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 '[email protected]"/<PATH>/co-nid-front.png"' \
--form '[email protected]"/<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 '[email protected]"/<PATH>/dummy-doc.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 Code

Description

documentPhoto.badText

Document field validation failed

documentPhoto.blurryText

Document photo is too blurry

documentPhoto.smallImageSize

Document photo resolution is too low

documentPhoto.unexpectedData

Unexpected error in document reading

documentPhoto.noText

Document photo has no text

documentPhoto.noFace

Document photo has no face (for validation steps that require a face)

documentPhoto.grayscaleImage

Document photo is in grayscale

documentPhoto.screenPhoto

Document photo is a screen shot. User must upload a different photo

documentPhoto.noDocument

Document photo does not match a known document template

documentPhoto.missingFields

Document photo is missing some required fields

documentPhoto.wrongFormat

Some required fields from the document use an invalid format

documentPhoto.noMrz

Document photo has no Machine-Readable Zone (MRZ, for validation steps that require one)

documentPhoto.badMrz

Document photo has corrupted Machine-Readable Zone
(MRZ, for validation steps that require one)

documentPhoto.noPdf417

Document photo has no PDF417 barcode (for validation steps that require one)

documentPhoto.badPdf417

Document photo has corrupted PDF417 barcode (for validation steps that require one)

documentPhoto.typeMismatch

Document type claimed by user and document type detected from photo are different

documentPhoto.countryMismatch

Document country claimed by user and document country detected from document photo are different

voiceVideo.conversionFailed

Video conversion failed

voiceVideo.multipleFaces

Multiple simultaneous faces are detected in the video

voiceVideo.noFace

No faces detected in the video

Language
Authentication
OAuth2