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 '\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 ' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"request_id\": \"\",\n \"verification_ids\": [\"\",\"\",\"\",],\n \"callback_details\": {\n \"url\": \"\",\n \"headers\": {\n \"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 ''' 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=@\"//co-nid-front.png\"' \\\n--form 'document=@\"//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=@\"//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 " \ ' 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\": \"\",\n \"name\": \"\"\n },\n \"identity\": \"\",\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\": \"\",\n \"name\": \"API_re_verification\"\n },\n \"identity\": \"\",\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\": \" name: type: string example: API_re_verification identity: type: string example: 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: \" \\\n-d '{\n \"flowId\": \"\",\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 \" \\\n-d '{ \n \"flowId\": \"\",\n \"identityId\": \"\",\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.