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.

Verify a user's document (skip the document back)

Open Recipe

Request Body Requirements

The body parameters should be in type form.
The JSON inputs must match the flow configuration order on your MetaMap Dashboard for both documents and biometric requirements or you will not be able to send this request.
- The merits that use the Send User Identifiers API use the following order of precedence in every metamap:
- The first document of the first merit must have a group number starting at 0. Additional documents must be assigned separate incremental group numbers in order of appearance in the metamap.

Upload a National ID and a Custom Document

Open Recipe

Upload a Custom Document

Open Recipe

🦉

Upload a Bank Account Statement

Open Recipe

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 Code	Description
`media.notFound`	File name in descriptor does not match with name of file being sent
`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
`documentPhoto.croppedDocument`	Document boundaries are not completely visible in the photo
`documentPhoto.sideMismatch`	Document's claimed side (front or back) does not match with the submitted side
`voiceVideo.conversionFailed`	Video conversion failed
`voiceVideo.multipleFaces`	Multiple simultaneous faces are detected in the video
`voiceVideo.noFace`	No faces detected in the video
`bankDocument.passwordRequired`	The bank statement is password-protected. Please provide the password to open and read the file.
`bankDocument.passwordFailed`	The bank statement is password-protected. Please provide the correct password to read the file.
`bankDocument.badFileName`	Bank-document file name differs from input file name.
`bankDocument.invalidMetadata`	Please upload the original bank statement. Altered files will not be accepted.
`bankDocument.statementNotSupported`	The bank statement template is unsupported. Contact MetaMap support for help.
`CustomDocumentPhoto.multiPageInputError`	The file sent as Custom Document has multiple pages, when in the Flow Settings, multiple pages document is not supported.

Send Inputs

File Requirements

Image Files

Video Files

Document Handling

📘
One-Sided Document Handling

Request Body Requirements

Example Requests

Error Codes

File Requirements

Image Files

Video Files

Document Handling

📘One-Sided Document Handling

Request Body Requirements

Example Requests

Error Codes

📘
One-Sided Document Handling