Docs
Developer Hub

Biometric Verification Webhooks

Suggest Edits

The Biometric Verification Tool uses the following step IDs:


Passive Liveness

Step

"step": {
  "status": 200,
  "id": "selfie",
    "data": {
      "selfiePhotoUrl": "http://media-server/media/selfie/<selfie>.png",
      "ageEstimated": 37, // Only when Age Verification is enabled
      "ageThreshold": 18  // Only when Age Verification is enabled
    },
  "error": null
}

Step Error

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "data" : {
    "selfiePhotoUrl" : "https://media.getmati.com/file?location=XXX"
  }, 
  "error" : {
    "type" : "StepError", 
    "code" : "selfieFraudDetection.fraudAttempt", 
    "message" : "Selfie is considered as fraud attempt"
  }
}

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "data" : {
   "selfiePhotoUrl" : "https://media.getmati.com/file?location=XXX"
  }, 
  "error" : {
    "type" : "StepError", 
    "code" : "selfieFraudDetection.negligence", 
  "message" : "Selfie is considered as negligence"
  }
}

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "data" : {
    "selfiePhotoUrl" : "https://media.getmati.com/file?location=XXX"
  }, 
  "error" : {
    "type" : "StepError", 
    "code" : "selfieFraudDetection.tampered", 
    "message" : "Selfie is considered tampered"
  }
}

Step Error - Digital Spoof

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "data" : {
    "selfiePhotoUrl" : "https://media.getmati.com/file?location=XXX"
  }, 
  "error": {
      "type": "StepError",
      "code": "selfieFraudDetection.digitalSpoofAttackMedium",
      "message": "Selfie is considered as medium severity digital spoof attack"
    }
}

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "data" : {
    "selfiePhotoUrl" : "https://media.getmati.com/file?location=XXX"
  }, 
  "error": {
      "type": "StepError",
      "code": "selfieFraudDetection.digitalSpoofAttackCritical",
      "message": "Selfie is considered as critical severity digital spoof attack"
    }
}

Step Error - Face Evasion

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "data" : {
    "selfiePhotoUrl" : "https://media.getmati.com/file?location=XXX"
  }, 
  "error": {
      "type": "StepError",
      "code": "selfieFraudDetection.faceEvasionAttackMedium",
      "message": "Selfie is considered as medium severity face evasion attack"
    }
}

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "data" : {
    "selfiePhotoUrl" : "https://media.getmati.com/file?location=XXX"
  }, 
  "error": {
      "type": "StepError",
      "code": "selfieFraudDetection.faceEvasionAttackCritical",
      "message": "Selfie is considered as critical severity face evasion attack"
    }
}

Step Error - Age Verification

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "data" : {
    "selfiePhotoUrl" : "https://media.getmati.com/file?location=XXX"
  }, 
  "error": {
      "type": "StepError",
      "code": "selfieFraudDetection.underage",
      "message": "This user is currently underage"
    }
}

System Error

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "data" : {
    "selfiePhotoUrl" : "http://media-server/media/selfie/XXXX.jpeg"
  }, 
  "error" : {
    "type" : "SystemError", 
    "code" : "system.internalError", 
    "message" : "Internal error"
  }
}

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "error" : {
    "type" : "StepError", 
    "code" : "input.failed", 
    "message" : "Cannot meet dependent input"
  }
}

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "error" : {
    "type" : "StepError", 
    "code" : "node.failed", 
    "message" : "Cannot meet dependent node"
  }
}

Liveness (Video Selfie)

Step Completed

"eventName": "step_completed",
"step": {
  "status": 200,
  "id": "liveness",
  "data": {
    "videoUrl": "http://media-server/media/video/<video>.webm",
    "spriteUrl": "http://media-server/media/selfie/<sprite>.jpeg",
    "selfieUrl": {
      "media": "<media>",
      "isUrl": true
    }
  },
  "error": null
}

Step Error

"step" : {
  "status" : 200, 
  "id" : "liveness", 
  "error" : {
    "type" : "StepError", 
    "code" : "input.failed", 
    "message" : "Cannot meet dependent input"
  }
}

"step" : {
  "status" : 200, 
  "id" : "liveness", 
  "error" : {
    "type" : "StepError", 
    "code" : "node.failed", 
    "message" : "Cannot meet dependent node"
  }
}

System Error

"step" : {
  "status" :200, 
  "id" : "liveness", 
  "data" : {
    "videoUrl" : "https://media.getmati.com/file?location=selfie-video-location", 
    "spriteUrl" : "https://media.getmati.com/file?location=selfie-location", 
    "selfieUrl" : {
      "media" : "00000aaa0000a0000a00a0a0", 
      "isUrl" : true
    }
  }, 
  "error" : {
    "type" : "SystemError", 
    "code" : "system.internalError", 
    "message" : "Step timeout"
  }
}

Legacy Error

"step" : {
  "status" : 200, 
  "id" : "liveness", 
  "data" : {
    "videoUrl" : "http://media-server/media/video/some-selfie-video.mkv", 
    "spriteUrl" : "http://media-server/media/selfie/some-selfie.jpeg", 
    "selfieUrl" : {
      "media" : "00000z0aaa0a0a000a00a000", 
      "isUrl" : true
    }
  }, 
  "error" : {
    "type" : "LegacyError", 
    "code" : "legacy.error", 
    "message" : "User did not pass liveness"
  }
}

Selfie (Photo Selfie)

Step Completed

"step": {
  "status": 200,
  "id": "selfie",
    "data": {
      "selfiePhotoUrl": "http://media-server/media/selfie/<selfie>.png"
    },
  "error": null
}

Step Error

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "error" : {
    "type" : "StepError", 
    "code" : "input.failed", 
    "message" : "Cannot meet dependent input"
  }
}

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "error" : {
    "type" : "StepError", 
    "code" : "node.failed", 
    "message" : "Cannot meet dependent node"
  }
}

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "data" : {
    "selfiePhotoUrl" : "https://media.getmati.com/file?location=XXX"
  }, 
  "error" : {
    "type" : "StepError", 
    "code" : "selfieFraudDetection.fraudAttempt", 
    "message" : "Selfie is considered as fraud attempt"
  }
}

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "data" : {
   "selfiePhotoUrl" : "https://media.getmati.com/file?location=XXX"
  }, 
  "error" : {
    "type" : "StepError", 
    "code" : "selfieFraudDetection.negligence", 
  "message" : "Selfie is considered as negligence"
  }
}

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "data" : {
    "selfiePhotoUrl" : "https://media.getmati.com/file?location=XXX"
  }, 
  "error" : {
    "type" : "StepError", 
    "code" : "selfieFraudDetection.tampered", 
    "message" : "Selfie is considered tampered"
  }
}

System Error

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "data" : {
    "selfiePhotoUrl" : "http://media-server/media/selfie/XXXX.jpeg"
  }, 
  "error" : {
    "type" : "SystemError", 
    "code" : "system.internalError", 
    "message" : "Internal error"
  }
}


"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "data" : {
    "selfiePhotoUrl" : "http://media-server/media/selfie/XXXX.jpeg"
  }, 
  "error" : {
    "type" : "SystemError", 
    "code" : "system.internalError", 
    "message" : "Internal error"
  }
}

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "error" : {
    "type" : "StepError", 
    "code" : "input.failed", 
    "message" : "Cannot meet dependent input"
  }
}

"step" : {
  "status" : 200, 
  "id" : "selfie", 
  "error" : {
    "type" : "StepError", 
    "code" : "node.failed", 
    "message" : "Cannot meet dependent node"
  }
}

Facematch

Step Completed

"step" : {
        "status" : 200, 
        "id" : "facematch", 
        "data" : {
            "score" : 99.19310481799324
        }, 
        "error" : null
    }, 
    "eventName" : "step_completed", 
    "flowId" : "<METAMAP (FLOW) ID>", 
    "timestamp" : "2021-08-15T00:00:36.439Z"
},

"step" : {
        "status" : 200, 
        "id" : "facematch", 
        "data" : {
            "score" : 100
        }, 
        "error" : null
    }, 
    "eventName" : "step_completed", 
    "flowId" : "<METAMAP (FLOW) ID>", 
    "timestamp" : "2021-08-15T00:00:02.546Z"
},

Step Error

"step" : {
    "status" : 200, 
    "id" : "facematch", 
    "data" : {
        "score" : 20.43746515455734
    }, 
    "error" : {
        "type" : "LegacyError", 
        "code" : "legacy.error", 
        "message" : "The face did not match the document"
    }
}, 
"eventName" : "step_completed", 
"flowId" : "<METAMAP (FLOW) ID>", 
"timestamp" : "2021-08-15T00:02:31.625Z"

"step" : {
        "status" : 200, 
        "id" : "facematch", 
        "error" : {
            "type" : "LegacyError", 
            "code" : "legacy.error", 
            "message" : "selfie_id download error"
        }
    }, 
    "eventName" : "step_completed", 
    "flowId" : "<METAMAP (FLOW) ID>", 
    "timestamp" : "2021-08-15T00:00:43.424Z"

"step" : {
          "status" : 200, 
          "id" : "facematch", 
          "error" : {
              "type" : "LegacyError", 
              "code" : "legacy.error", 
              "message" : "doc_photo_id download error"
          }
      }, 
      "eventName" : "step_completed", 
      "flowId" : "<METAMAP (FLOW) ID>", 
      "timestamp" : "2021-08-15T00:01:25.640Z"

"step" : {
    "status" : 200, 
    "id" : "facematch", 
    "data" : {
        "score" : 29.98143200143104
    }, 
    "error" : {
        "type" : "LegacyError", 
        "code" : "legacy.error", 
        "message" : "This person cannot be confirmed as owner of document provided, a selfie with the document will be requested"
    }
"eventName" : "step_completed", 
"flowId" : "<METAMAP (FLOW) ID>", 
"timestamp" : "2021-08-15T00:47:20.663Z"

"step" : {
  "status" : 200, 
  "id" : "facematch", 
  "error" : {
    "type" : "StepError", 
    "code" : "input.failed", 
    "message" : "Cannot meet dependent input"
  }
}

System Error

"step" : {
  "status" : 200, 
  "id" : "facematch", 
  "error" : {
    "type" : "SystemError", 
    "code" : "system.internalError", 
    "message" : "Step timeout"
  }
}

Updated about 1 month ago