The Verifications API from MetaMap — 7 operation(s) for verifications.
openapi: 3.1.0
info:
title: MetaMap Authentication Verifications API
version: '1.4'
description: MetaMap (formerly Mati) identity verification REST API. Start and manage user verifications, retrieve verification media, run watchlist, email, phone, credit, court-record, and government database checks across Latin America, Africa, and Asia.
contact:
name: MetaMap
url: https://metamap.com
license:
name: MetaMap Terms of Service
url: https://metamap.com/legal/terms-of-service
servers:
- url: https://api.prod.metamap.com
description: Production
security:
- bearerAuth: []
tags:
- name: Verifications
paths:
/verifications/{verificationId}:
delete:
summary: Delete Verification
description: ''
operationId: delete-verification
parameters:
- name: verificationId
in: path
description: Unique string assigned to a user's verification status
schema:
type: string
required: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Success:
value: '{}'
schema:
type: object
properties: {}
'400':
description: '400'
content:
application/json:
examples:
Invalid status movement:
value: '{}'
schema:
type: object
properties: {}
'404':
description: '404'
content:
text/plain:
examples:
Verification not found:
value: '{}'
schema:
type: object
properties: {}
'500':
description: '500'
content:
text/plain:
examples:
Unexpected error:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
x-readme:
code-samples:
- language: curl
code: "curl --request DELETE \\\n --url 'https://api.prod.metamap.com/verifications/{verificationId}' \\\n --header 'Authorization: Bearer <access_token>'\n"
samples-languages:
- curl
tags:
- Verifications
/verification/v1/pdf/download:
post:
summary: Download Verification Results
description: Use this API to download verification results in a PDF file.
operationId: download-verifications
requestBody:
content:
application/json:
schema:
type: object
required:
- request_id
- verification_ids
- timezone
properties:
request_id:
type: string
description: String to be associated with the PDF request. We will pass this string with the callback.
verification_ids:
type: array
description: Verification numbers identifying the verifications to be downloaded.
items:
type: string
timezone:
type: string
description: Your timezone.
default: Australia/Darwin
callback_details:
type: object
properties: {}
metadata:
type: string
description: Additional data you need returned as part of the callback.
format: json
responses:
'200':
description: '200'
content:
application/json:
examples:
All IDs Found:
value: "{\n \"status\": \"SUCCESS\",\n \"acceptedVerificationIds\": [\n \"000aaaaaaa00a0000aa0aa00\"\n ],\n \"rejectedVerificationIds\": []\n}"
One Or More IDs Rejected:
value: "{\n \"status\": \"FAILURE\",\n \"acceptedVerificationIds\": [],\n \"rejectedVerificationIds\": [\n \"000aaaaaaa00a0000aa0aa00\"\n ]\n}"
schema:
oneOf:
- title: All IDs Found
type: object
properties:
status:
type: string
example: SUCCESS
acceptedVerificationIds:
type: array
items:
type: string
example: 000aaaaaaa00a0000aa0aa00
rejectedVerificationIds:
type: array
items:
type: object
properties: {}
- title: One Or More IDs Rejected
type: object
properties:
status:
type: string
example: FAILURE
acceptedVerificationIds:
type: array
items:
type: object
properties: {}
rejectedVerificationIds:
type: array
items:
type: string
example: 000aaaaaaa00a0000aa0aa00
'400':
description: '400'
content:
text/plain:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
x-readme:
code-samples:
- language: curl
code: "curl --location --request POST 'https://api.getmati.com/verification/v1/pdf/download' \\\n--header 'Authorization: Bearer <auth_token>' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"request_id\": \"<request id>\",\n \"verification_ids\": [\"<verification id 1>\",\"<verification id 2>\",\"<verification id 3>\",],\n \"callback_details\": {\n \"url\": \"<callback http url>\",\n \"headers\": {\n \"api_key\": \"<api key>\",\n \"content-type\": \"multipart/form-data\"\n }\n }\n}'"
name: REQUEST
samples-languages:
- curl
tags:
- Verifications
servers:
- url: https://api.getmati.com
/file:
get:
summary: Get Verification Media
description: Use this API to download user documents, photos, and videos.
operationId: get-verification-media
parameters:
- name: media_auth
in: path
description: The `media_auth` is part of the path returned when a Retrieve Webhook Resource call succeeds.
schema:
type: string
required: true
responses:
'400':
description: '400'
content:
application/json:
examples:
Bad URL:
value: "{\n \"code\": 400,\n \"data\": {},\n \"message\": \"Media URL malformed\",\n \"name\": \"MoleculerError\",\n \"type\": \"MEDIA_API_ERROR\"\n}"
schema:
type: object
properties:
code:
type: integer
example: 400
default: 0
data:
type: object
properties: {}
message:
type: string
example: Media URL malformed
name:
type: string
example: MoleculerError
type:
type: string
example: MEDIA_API_ERROR
deprecated: false
x-readme:
code-samples:
- language: curl
code: 'curl --location --request GET ''https://media.getmati.com/file?location={media_auth}'' \
--header ''Authorization: Bearer <access_token>'''
name: Get Media Example
samples-languages:
- curl
tags:
- Verifications
servers:
- url: https://media.prod.metamap.com
/v2/identities/{identity}/send-input:
post:
summary: Send Inputs
description: Use this API to send documents, selfies, videos, or other identifying information
operationId: send-inputs
parameters:
- name: identity
in: path
description: The identity is in the successful response to a Verification Creation request
schema:
type: string
required: true
- name: Content-Type
in: header
required: true
schema:
type: string
default: multipart/form-data
requestBody:
content:
application/json:
schema:
type: object
properties:
inputs:
type: object
required:
- inputType
properties:
inputType:
type: string
description: User input type
group:
type: integer
description: Index of verificationSteps with given inputType in merchant configurations. Each document must have a unique group number, starting from 0. MetaMap-supported documents must precede custom documents.
format: int32
data:
type: object
required:
- filename
properties:
type:
type: string
description: For a MetaMap-supported document, the type of document, (driving-license, national-id, passport, proof-of-residency). For a selfie, selfie-photo. For a liveness video, selfie-video For a custom document, use the webhook label name you defined when you added the Custom Document merit to your metamap
country:
type: string
description: Country code. Used only for MetaMap-supported documents to specify the document's country of issue. Omit this parameter for custom documents. Uses ISO 2 codes.
region:
type: string
description: Used only to verify users in the United States. For non-US users, leave blank (example, ""). Refers to the user's state of residency (for example, "AL" for "Alabama"). Uses the US Postal Service state abbreviations
page:
type: string
description: The document's page side. 1-sided documents require only the front 2-sided documents can be uploaded as two separate files (front and back) 2-sided Custom documents can be uploaded as 2 separate image files (front and back) or as a single *.pdf file (multi) Custom documents with >2 sides must upload a single *.pdf file (multi)
filename:
type: string
description: The name of the file being uploaded.
document:
type: string
description: MetaMap-supported documents only. Location of file to upload.
format: binary
custom-document:
type: string
description: Custom documents only. Location of file to upload.
format: binary
responses:
'201':
description: '201'
content:
application/json:
examples:
Successful Response, Fully Validated:
value: "[\n {\n \"data\": {\n \"inputType\": \"selfie-photo\",\n \"type\": \"selfie-photo\",\n \"filename\": \"selfie.png\"\n },\n \"result\": true\n },\n {\n \"data\": {\n \"inputType\": \"document-photo\",\n \"type\": \"national-id\",\n \"country\": \"MX\",\n \"page\": \"front\",\n \"filename\": \"INE-front.jpg\"\n },\n \"result\": true\n },\n {\n \"data\": {\n \"inputType\": \"document-photo\",\n \"type\": \"national-id\",\n \"country\": \"MX\",\n \"page\": \"back\",\n \"filename\": \"INE-back.jpg\"\n },\n \"result\": true\n }\n]"
Successful Response, Partial Validation:
value: "[\n {\n \"data\": {\n \"inputType\": \"selfie-photo\",\n \"type\": \"selfie-photo\",\n \"filename\": \"selfie.png\"\n },\n \"error\": {\n \"type\": \"ValidationError\",\n \"code\": \"selfiePhoto.noFace\"\n }\n },\n {\n \"data\": {\n \"inputType\": \"document-photo\",\n \"type\": \"national-id\",\n \"country\": \"MX\",\n \"page\": \"front\",\n \"filename\": \"INE-front.jpg\"\n },\n \"result\": true\n },\n {\n \"data\": {\n \"inputType\": \"document-photo\",\n \"type\": \"national-id\",\n \"country\": \"MX\",\n \"page\": \"back\",\n \"filename\": \"INE-back.jpg\"\n },\n \"result\": true\n }\n]"
schema:
oneOf:
- title: Successful Response, Fully Validated
type: array
items:
type: object
properties:
data:
type: object
properties:
inputType:
type: string
example: selfie-photo
type:
type: string
example: selfie-photo
filename:
type: string
example: selfie.png
result:
type: boolean
example: true
default: true
- title: Successful Response, Partial Validation
type: array
items:
type: object
properties:
data:
type: object
properties:
inputType:
type: string
example: selfie-photo
type:
type: string
example: selfie-photo
filename:
type: string
example: selfie.png
error:
type: object
properties:
type:
type: string
example: ValidationError
code:
type: string
example: selfiePhoto.noFace
'400':
description: '400'
content:
application/json:
examples:
Error In The Input Parameters:
value: "{\n \"code\": 400,\n \"message\": \"No input strategy found for document-photo\"\n}"
Bad Input Structure:
value: "{\n \"code\": 400,\n \"message\": \"Invalid structure of request body\",\n \"name\": \"MoleculerError\"\n}"
schema:
oneOf:
- title: Error In The Input Parameters
type: object
properties:
code:
type: integer
example: 400
default: 0
message:
type: string
example: No input strategy found for document-photo
- title: Bad Input Structure
type: object
properties:
code:
type: integer
example: 400
default: 0
message:
type: string
example: Invalid structure of request body
name:
type: string
example: MoleculerError
deprecated: false
x-readme:
code-samples:
- language: curl
code: "curl --location --request POST 'https://api.getmati.com/v2/identities/{{identity}}/send-input' \\\n--header 'Content-Type: multipart/form-data' \\\n--header 'Authorization: Bearer {{access_token}}' \\\n--form 'inputs=[\n {\n \"inputType\": \"document-photo\",\n \"group\": 0,\n \"data\": {\n \"type\": \"driving-license\",\n \"country\": \"MX\",\n \"page\": \"front\",\n \"filename\": \"MX_NI_FRONT.jpg\"\n }\n },\n {\n \"inputType\": \"document-photo\",\n \"group\": 0,\n \"data\": {\n \"type\": \"driving-license\",\n \"country\": \"MX\",\n \"page\": \"back\",\n \"filename\": \"MX_NI_BACK.jpg\"\n }\n },\n {\n \"inputType\": \"document-photo\",\n \"group\": 1,\n \"data\": {\n \"type\": \"passport\",\n \"country\": \"MX\",\n \"page\": \"front\",\n \"filename\": \"MX_PASSPORT.jpg\"\n }\n {\n \"inputType\": \"document-photo\",\n \"group\": 2,\n \"data\": {\n \"type\": \"proof-of-residency\",\n \"country\": \"MX\",\n \"page\": \"front\",\n \"filename\": \"proof-of-residence.png\"\n }\n },\n {\n \"inputType\": \"selfie-photo\",\n \"data\": {\n \"type\": \"selfie-photo\",\n \"filename\": \"selfie-photo.jpg\"\n }\n }\n]' \\\n--form 'document=@/C:/PATH_TO_FILE/MX_NI_FRONT.jpg' \\\n--form 'document=@/C:/PATH_TO_FILE/MX_NI_BACK.jpg' \\\n--form 'document=@/C:/PATH_TO_FILE/MX_PASSPORT.jpg' \\\n--form 'document=@/C:/PATH_TO_FILE/proof-of-residence.png' \\\n--form 'selfie=@/C:/PATH_TO_FILE/selfie-photo.jpg'"
name: Driving License + Passport + Proof of Residency + Selfie
- language: curl
code: "curl --location --request POST 'https://api.getmati.com/v2/identities/{{_id}}/send-input' \\\n--header 'Content-Type: multipart/form-data' \\\n--header 'Authorization: Bearer {{access_token}}' \\\n--form 'inputs=[ \n {\"inputType\":\"document-photo\",\"group\":0, \n \"data\":{\"type\":\"national-id\",\"country\":\"BR\",\"region\":\"\",\"page\":\"front\",\"filename\":\"43_front.jpg\"}}, \n {\"inputType\":\"document-photo\",\"group\":0, \n \"data\":{\"type\":\"national-id\",\"country\":\"BR\",\"region\":\"\",\"page\":\"back\",\"filename\":\"44_back.jpg\"}} \n ]' \n--form 'document=@/C:/PATH_TO_FILE/43_front.jpg' \n--form 'document=@/C:/PATH_TO_FILE/44_back.jpg'"
name: National ID
- language: curl
code: "curl --location --request POST 'https://api.getmati.com/v2/identities/{{_id}}/send-input' \\\n--header 'Content-Type: multipart/form-data' \\\n--header 'Authorization: Bearer {{access_token}}' \\\n--form 'inputs=[\n {\n \"inputType\": \"document-photo\",\n \"group\": 0,\n \"data\": {\n \"type\": \"national-id\",\n \"country\": \"US\",\n \"region\" : \"CA\",\n \"page\": \"front\",\n \"filename\": \"US_CA_DL_FRONT.jpg\"\n }\n },\n {\n \"inputType\": \"document-photo\",\n \"group\": 0,\n \"data\": {\n \"type\": \"national-id\",\n \"country\": \"US\",\n \"region\" : \"CA\",\n \"page\": \"back\",\n \"filename\": \"US_CA_DL_BACK.jpg\"\n }\n },\n {\n \"inputType\": \"selfie-video\",\n \"data\": {\n \"filename\": \"Liveness_video.mp4\"\n }\n }\n]' \\\n--form 'document=@/C:/PATH_TO_FILE/US_CA_DL_FRONT.jpg' \\\n--form 'document=@/C:/PATH_TO_FILE/US_CA_DL_BACK.jpg' \\\n--form 'video=@/C:/PATH_TO_FILE/Liveness_video.mp4'"
name: National ID + Selfie Video
- language: curl
code: "curl --location --request POST 'https://api.getmati.com/v2/identities/{id}/send-input' \\\n--header 'Content-Type: x-www-form-urlencoded' \\\n--header 'Authorization: Bearer {{access_token}}' \\\n--form 'inputs=[\n {\n \"inputType\":\"custom-document-photo\",\n \"group\":0,\n \"data\":{\n \"type\":\"custom-birth-certificate\",\n \"page\":\"front\",\n \"filename\":\"birth_front.jpg\"\n }\n },\n {\n \"inputType\":\"custom-document-photo\",\n \"group\":0,\n \"data\":{\n \"type\":\"custom-birth-certificate\",\n \"page\":\"back\",\n \"filename\":\"birth_back.jpg\"\n }\n }\n]' \\\n--form 'custom-document=@/C:/PATH_TO_FILE/birth_front.jpg' \\\n--form 'custom-document=@/C:/PATH_TO_FILE/birth_back.jpg' \\\n \n "
name: Custom Document - Birth Certificate
- language: curl
code: "curl --location --request POST 'https://api.getmati.com/v2/identities/{id}/send-input' \\\n--header 'Authorization: Bearer {{TOKEN}}' \\\n--form 'document=@\"/<PATH>/co-nid-front.png\"' \\\n--form 'document=@\"/<PATH>/co-nid-back.png\"' \\\n--form 'inputs=[\n {\n \"inputType\":\"document-photo\",\n \"group\":0,\n \"data\":\n {\n \"type\":\"national-id\",\n \"country\":\"CO\",\n \"page\":\"front\",\n \"filename\":\"co-nid-front.png\"\n }\n },\n {\n \"inputType\":\"document-photo\",\n \"group\":0,\n \"data\":\n {\n \"type\":\"national-id\",\n \"country\":\"CO\",\n \"page\":\"back\",\n \"filename\":\"co-nid-back.png\"\n }\n },\n {\n \"inputType\":\"custom-document-photo\",\n \"group\":1,\n \"data\":\n {\n \"type\":\"custom-dummy-doc\",\n \"page\":\"multi\",\"filename\":\"dummy-doc.pdf\"\n }\n }\n]' \\\n--form 'custom-document=@\"/<PATH>/dummy-doc.pdf\"'"
name: National ID + Custom Document
samples-languages:
- curl
tags:
- Verifications
/v2/verifications/{verification_id}/inputs/document-photo/skip:
put:
summary: Skip Verification Upload Wait Time
description: Use this API to skip the wait time when uploading the back of a document
operationId: skip-verification-upload
parameters:
- name: x-mati-app
in: header
description: platform=web_desktop; version=22.2.10
required: true
schema:
type: string
- name: verification_id
in: path
description: The ID returned by the Start Verification endpoint.
schema:
type: string
required: true
deprecated: false
x-readme:
code-samples:
- language: curl
code: 'curl --location --request POST ''https://api.getmati.com/verifications/{verification_id}/inputs/document-photo/skip/'' \
-H ''x-mati-app: platform=web_desktop; version=22.2.10'' \
-H "Authorization: Bearer <access_token>" \
'
name: REQUEST
samples-languages:
- curl
tags:
- Verifications
/v2/verifications:
post:
summary: Start Verification
description: Use this endpoint to create a new user verification or reverify an existing user.
operationId: start-verification
parameters:
- name: x-forwarded-for
in: header
description: 'WARNING: This header is only used for demonstration purposes on this site and is not necessary when using the MetaMap SDKs or tools such as Postman.'
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- flowId
properties:
flowId:
type: string
description: Your flowId can be found in the Metamap dashboard under "Integrations".
metadata:
type: string
description: Use the metadata parameter to add internal references.
default: '{ "user-defined-1" : "abcde", "user-defined-2" : "12345" }'
format: json
responses:
'200':
description: '200'
content:
application/json:
examples:
New User Verified:
value: "{\n \"documents\": [],\n \"expired\": false,\n \"flow\": {\n \"id\": \"<YOUR_METAMAP_VERIFICATION_ID>\",\n \"name\": \"<YOUR_METAMAP_FLOW_NAME>\"\n },\n \"identity\": \"<USER_IDENTITY_ID>\",\n \"inputs\": [\n {\n \"id\": \"connection-data\",\n \"status\": 200,\n \"optional\": false\n },\n {\n \"id\": \"document-photo\",\n \"status\": 0,\n \"group\": 0\n }\n ],"
Existing User Verified:
value: "{\n \"documents\": [],\n \"expired\": false,\n \"flow\": {\n \"id\": \"<YOUR_METAMAP_VERIFICATION_ID>\",\n \"name\": \"API_re_verification\"\n },\n \"identity\": \"<PREVIOUS_USER_IDENTITY_ID>\",\n \"inputs\": [\n {\n \"id\": \"connection-data\",\n \"status\": 200,\n \"optional\": false\n },\n {\n \"id\": \"selfie-photo\",\n \"status\": 0\n }\n ],\n \"metadata\": {\n \"name\": \"re-verification\"\n },\n \"steps\": [\n {\n \"status\": 0,\n \"id\": \"re-facematch\"\n },\n {\n \"status\": 0,\n \"id\": \"selfie\"\n }\n ],\n \"id\": \"<NEW_USER_IDENTITY_ID\",\n \"deviceFingerprint\": {\n \"ua\": \"PostmanRuntime/7.29.0\",\n \"ip\": \"10.0.0.127\",\n \"vpnDetectionEnabled\": false\n },\n \"hasProblem\": false\n}"
schema:
type: object
properties:
documents:
type: array
items:
type: object
properties: {}
expired:
type: boolean
example: false
default: true
flow:
type: object
properties:
id:
type: string
example: <YOUR_METAMAP_VERIFICATION_ID>
name:
type: string
example: API_re_verification
identity:
type: string
example: <PREVIOUS_USER_IDENTITY_ID>
inputs:
type: array
items:
type: object
properties:
id:
type: string
example: connection-data
status:
type: integer
example: 200
default: 0
optional:
type: boolean
example: false
default: true
metadata:
type: object
properties:
name:
type: string
example: re-verification
steps:
type: array
items:
type: object
properties:
status:
type: integer
example: 0
default: 0
id:
type: string
example: re-facematch
id:
type: string
example: <NEW_USER_IDENTITY_ID
deviceFingerprint:
type: object
properties:
ua:
type: string
example: PostmanRuntime/7.29.0
ip:
type: string
example: 10.0.0.127
vpnDetectionEnabled:
type: boolean
example: false
default: true
hasProblem:
type: boolean
example: false
default: true
deprecated: false
x-readme:
code-samples:
- language: curl
code: "curl --location --request POST 'https://api.prod.metamap.com/v2/verifications' \\\n-H 'Content-Type: application/json' \\\n-H \"Authorization: Bearer <YOUR_METAMAP_ACCESS_TOKEN>\" \\\n-d '{\n \"flowId\": \"<YOUR_METAMAP_FLOW_ID>\",\n \"metadata\": {\n \"user\": \"JOHN DOE\",\n \"id\": \"123e4567-e89b-12d3-a456-426614174000\"\n }\n }'"
name: Create Verification
- language: curl
code: "curl --location --request POST 'https://api.prod.metamap.com/v2/verifications' \\\n-H 'Content-Type: application/json' \\\n-H \"Authorization: Bearer <YOUR_METAMAP_ACCESS_TOKEN>\" \\\n-d '{ \n \"flowId\": \"<YOUR_METAMAP_FLOW_ID>\",\n \"identityId\": \"<YOUR_METAMAP_IDENTITY_ID>\",\n \"metadata\": {\n \"name\": \"test-re-verification\"\n }\n}"
name: Reverify User
samples-languages:
- curl
tags:
- Verifications
/v2/verifications/{verificationId}/status:
put:
summary: Update Verification Status
description: ''
operationId: update-verification-status
parameters:
- name: verificationId
in: path
description: Unique string assigned to a user's verification status
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
required:
- status
properties:
status:
type: string
description: '`data-raw` body. Status values can be one of the following: `deleted`, `pending`, `rejected`, `reviewNeeded`, `reviewRunning`, `running`, `postponed`, `verified`'
responses:
'200':
description: '200'
content:
application/json:
examples:
Success:
value: '{}'
schema:
type: object
properties: {}
'400':
description: '400'
content:
application/json:
examples:
Invalid status movement:
value: '{}'
schema:
type: object
properties: {}
'404':
description: '404'
content:
text/plain:
examples:
Verification not found:
value: '{}'
schema:
type: object
properties: {}
'500':
description: '500'
content:
text/plain:
examples:
Unexpected error:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Verifications
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT obtained via POST /oauth using client_id / client_secret as HTTP Basic.
basicAuth:
type: http
scheme: basic
description: Used only on POST /oauth for the initial token exchange.