Skip to main content

BlinkID Verify API v1 Reference

Legacy API​

The v1 API is our legacy API. It's being maintained, but is not getting new features (like the UseCase and RecommendedOutcome).

Migration to v2​

Depending on how much of our result you're using, the migration can be more or less straightforward. That said, one of the biggest advantages of the v2 API is that by default you'll need to inspect less of the result, and tweak fewer options to get the behavior you want (without losing any of the detail if you really need it).

Request​

The basic v1 request is very similar to the v2 request, with the following differences:

  • imageUrl is renamed to just url in v2
  • imageBase64 is renamed to just base64 in v2
  • the v2 request uses an options object to group the options/settings instead of having them as top level parameters in v1

Response​

The v1 and v2 responses are quite different.

A large chunk of the changes are additions in v2, but the entire response was reorganized. Let's start with the overall fraud verdict.

Whereas the overallFraudCheck is just a check like all the others in v1 (and you need to know that it's the actual output of the verification), in v2 it's its own verification object. It contains all the same information, with the addition of the RecommendedOutcome field which builds on top of the verification result.

Instead of having all the constituent checks as top level fields, v2 has a single checks field that contains all the checks in an array. This enables easier iteration over the checks (e.g. find all the checks that failed). The structure of a check is also reworked and carries more information in v2.

Notably, the imageQualityCheck isn't present in the checks array, to differentiate it from pure fraud checks, but is moved into v2's processIndicators array.

All of the returned images are moved into the images top level array in v2 for easier access, instead of buried in check and extraction fields.

The extraction part of the result has also been reworked, simplified, and reorganized.

The typical integration uses the overall fraud verdict, some information about image quality and specific checks (which should be fully replaced with the UseCase/RecommendedOutcome system in v2), and some extracted data. The largest change for an integration like that will likely be in the extraction part of the result, depending on how much of it is used.

Interpreting results​

When it comes to verification, the v1 API returns check object, namely:

  • overallFraudCheck - the overall fraud verdict (whether the document is genuine and live or not)
  • dataCheck
  • documentLivenessCheck
  • visualCheck
  • documentValidityCheck
  • imageQualityCheck - not a fraud check, but checks for issues with the quality of the captured images

Not all Pass or Fail verdicts are the same, however.

  • A document can Pass all the underlying checks, but Fail image quality to the point where we're not able to make a fraud verdict. The OverallFraudCheck will end up being NotPerformed in this case.

  • Certain checks are only strong signals of fraud, but not necessarily a smoking gun. For example, it's not impossible for someone to genuinely be named "Jon Doe" or have the document number "1234567890". The overallFraudCheck will Fail in this and similar cases, but you might want to send a document like that to manual review.

  • Some checks are on a gradient (represented by our satisfiedMatchLevels) and you may want to send less confident results to manual review, while trusting the more confident results.

If you're using the v1 API and are maintaining your own logic to interpret the results, you should be able to simply use our UseCase configuration in conjunction with the RecommendedOutcome to achieve the same or better behavior with the v2 API, without writing any code.

Schema Files​

If you're just looking for raw schema files, you can download them here:

Last updated on