Configuration

Each request can have its own custom configuration. You configure each verification by passing a custom configuration alongside your image upload.

Configuring verification has two main components: use cases and settings. Use cases are presets of settings.

Start with use cases for high-level behavior, and use settings for fine-grained tuning when you need it.

Configuration object reference

{
  "verification": {
    "useCase": {
      "verificationPolicy": "Balanced",
      "verificationContext": "Remote",
      "manualReviewStrategy": "RejectedAndAccepted"
    },
    "settings": {
      "screenPresenceSensitivity": "Level5",
      "photocopySensitivity": "Level5",
      "barcodeAuthenticitySensitivity": "Level7",
      "portraitForgerySensitivity": "Level5",
      "dataMatchSensitivity": "Level5",
      "generativeAiSensitivity": "Level5",
      "imageQualityRetryPolicy": "RetryBadQualityForRejections",
      "rejectExpiredDocuments": true,
      "cropAffectsVerdict": true
    }
  },
  "extraction": {
    "redactionSettings": {
      "globalMode": "FullResult"
    },
    "documentCaptureModuleSettings": {
      "faceImageExtractionEnabled": false,
      "documentImageReturnEnabled": false
    },
    "vizModuleSettings": {
      "signatureImageExtractionEnabled": false
    },
    "barcodeModuleSettings": {
      "barcodeImageReturnEnabled": false
    }
  },
  "imageAssessment": {
    "imageQualitySensitivity": "Level5"
  }
}

Send a custom configuration

The whole configuration travels in a single form field named configuration, which you can send either as a JSON text field or as a JSON file part.

If you don't specify a use case or setting, they fall back to their defaults. Only send the use cases and settings that you want to change.

configuration.json

{
  "verification": {
    "settings": {
      "dataMatchSensitivity": "Level1",
      "rejectExpiredDocuments": true
    },
    "useCase": { "manualReviewStrategy": "Never" }
  },
  "extraction": {
    "documentCaptureModuleSettings": { "documentImageReturnEnabled": true }
  }
}

cURL

curl https://us-east.verify.microblink.com/api/v3/verify \
  --request POST \
  --header 'Authorization: Basic <credentials>' \
  --form 'imageFirstSide=@front_id.jpg' \
  --form 'imageSecondSide=@back_id.png' \
  --form 'configuration=@configuration.json;type=application/json'

JavaScript

const formData = new FormData()
formData.append('imageFirstSide', new Blob([]), 'front_id.jpg')
formData.append('imageSecondSide', new Blob([]), 'back_id.png')
formData.append('configuration', new Blob([]), 'configuration.json')

fetch('https://us-east.verify.microblink.com/api/v3/verify', {
  method: 'POST',
  headers: {
    Authorization: 'Basic <credentials>'
  },
  body: formData
})

Python

requests.post(
    "https://us-east.verify.microblink.com/api/v3/verify",
    headers={
      "Authorization": "Basic <credentials>"
    },
    files=[
      ("imageFirstSide", open("front_id.jpg", "rb")),
      ("imageSecondSide", open("back_id.png", "rb")),
      ("configuration", ("configuration.json", open("configuration.json", "rb"), "application/json"))
    ]
)

Go

package main

import (
	"bytes"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"os"
)

func main() {
	requestUrl := "https://us-east.verify.microblink.com/api/v3/verify"

	payload := &bytes.Buffer{}
	writer := multipart.NewWriter(payload)

	part, _ := writer.CreateFormFile("imageFirstSide", "front_id.jpg")

	f, _ := os.Open("front_id.jpg")
	defer f.Close()

	_, _ = io.Copy(part, f)

	part, _ = writer.CreateFormFile("imageSecondSide", "back_id.png")

	f, _ = os.Open("back_id.png")
	defer f.Close()

	_, _ = io.Copy(part, f)

	part, _ = writer.CreateFormFile("configuration", "configuration.json")

	f, _ = os.Open("configuration.json")
	defer f.Close()

	_, _ = io.Copy(part, f)
	writer.Close()

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Set("Content-Type", writer.FormDataContentType())
	req.Header.Add("Authorization", "Basic <credentials>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Use cases

Use cases are the highest-level way to configure Verify.

Rather than exposing every setting individually, a useCase asks high-level questions about your integration—how documents are captured, how you balance fraud prevention against user conversion, whether you can perform manual review—and adjusts Verify's behavior accordingly.

Use case parameters

• verificationContext: whether verification happens remotely or in-person.
• verificationPolicy: whether you prioritize conversions or fraud prevention.
• manualReviewStrategy: whether manual review is enabled, and under what conditions.

Verification context

The verification context tells Verify if the check is a remote one, or in person.

Some document checks only make sense if they are performed remotely. If the end user is being verified in person (for example, physically providing their ID to a bank employee), then some checks are not needed because a human who is also checking the ID will spot irregularities.

For example, a human will immediately see a photocopy of an ID, and so Verify does not need to check if the ID is a photocopy.

Your verification context can be Remote or InPerson.

Depending on how you expect to use Verify (with a human agent in the loop, or without one), set up the context accordingly.

Setting InPerson disables three checks outright, because each of them detects something a person handling the document would notice:

• screenPresenceSensitivity
• photocopySensitivity
• generativeAiSensitivity

configuration.json

{
  "verification": {
    "useCase": { "verificationContext": "InPerson" }
  }
}

Verification policy

The verification policy determines your overall preferences around how strict the checks should be.

You can choose between:

• HighConversion
• Balanced
• HighAssurance

These are presets that determine the threshold of individual underlying checks overall.

The central trade-off is pass rate versus fraud detection.

The more permissive your environment, the more lax the checks can be; if you care most about getting legitimate users through, set the policy to HighConversion.

The more risk-averse the environment, the stricter the checks must be, at the cost of potentially flagging legitimate documents and slowing down the pass rate. If you're optimizing for catching fraud instead, opt for HighAssurance.

Balanced sits between the two (and is the default).

configuration.json

{
  "verification": {
    "useCase": { "verificationPolicy": "Balanced" }
  }
}

A policy works by adjusting the sensitivities you didn't set yourself. Anything you set explicitly wins over the policy.

Balanced makes no adjustments, so every sensitivity keeps its default. The other two policies move a subset:

Sensitivity	HighConversion	Balanced	HighAssurance
screenPresenceSensitivity	Level4	Level5	Level5
photocopySensitivity	Level4	Level5	Level5
portraitForgerySensitivity	Level1	Level5	Level5
dataMatchSensitivity	Level4	Level5	Level5
generativeAiSensitivity	Level4	Level5	Level5
barcodeAuthenticitySensitivity	Level7	Level7	Level8
imageQualitySensitivity	Level6	Level5	Level5
imageQualityRetryPolicy	RetryBadQualityForRejections	RetryBadQualityForRejections	RetryBadQualityAlways

Manual review strategy

BlinkID Verify is commonly used as a filtering system: you first pass all the IDs through the API, and then you route certain ones to manual review, where a human or other agent performs additional checks.

Verify supports such a workflow with the manual review strategy use case.

The outcome of this configuration is in the verdict field.

Your manual review strategy can be:

• Never: you don't have a manual review step, and therefore only use Accept or Reject values
• RejectedAndAccepted: documents which are on the verge of being either rejected or accepted can land in manual review
• RejectedOnly: only documents that are on the verge of being rejected can land in manual review
• AcceptedOnly: only documents that are on the verge of being accepted can land in manual review

configuration.json

{
  "verification": {
    "useCase": { "manualReviewStrategy": "RejectedAndAccepted" }
  }
}

Default use cases

Every request uses the default use cases, unless you override them. The default values are:

• verificationPolicy: Balanced
• verificationContext: Remote
• manualReviewStrategy: RejectedAndAccepted

Settings

Settings give you more granular control than use cases.

Use settings when you have specific requirements: accepting expired documents, allowing cropped documents, or tuning the sensitivity of individual checks.

All available settings are listed in the API reference.

Sensitivities

Most settings are sensitivities:

• screenPresenceSensitivity
• photocopySensitivity
• barcodeAuthenticitySensitivity
• portraitForgerySensitivity
• dataMatchSensitivity
• generativeAiSensitivity

A sensitivity controls how strictly its check is applied. Levels range from Level1 (least strict) to Level10 (most strict). They can also be set to Disabled to skip the check entirely.

Every sensitivity defaults to Level5, except barcodeAuthenticitySensitivity, which defaults to Level7. Your verification policy can move these, and an explicit value always wins over the policy.

For example, if you're particularly concerned about photocopies, set photocopySensitivity to Level10.

configuration.json

{
  "verification": {
    "settings": { "photocopySensitivity": "Level10" }
  }
}

Higher strictness catches more sophisticated fraud, but also increases the chance of rejecting legitimate documents due to minor imperfections.

Image quality

Image quality is graded by a single sensitivity, imageAssessment.imageQualitySensitivity, which applies uniformly to every quality dimension: blur, glare, lighting, sharpness, hand occlusion, resolution, and tilt.

configuration.json

{
  "imageAssessment": { "imageQualitySensitivity": "Level5" }
}

There is no per-dimension control, so you can't reject blurred images while tolerating poor lighting. The outcome is reported in imageAssessment.imageQualityCheck.

Cropped documents

Cropping is a form of digital tampering, so by default a cropped document counts against the verdict.

If you control the cropping yourself, for example because a client-side SDK does it, set cropAffectsVerdict to false to let cropped images be fully processed and pass:

configuration.json

{
  "verification": {
    "settings": { "cropAffectsVerdict": false }
  }
}

Either way, the detection itself is reported per side in imageAssessment.croppedDocumentCheck.

Image quality retry policy

When document images don't fully meet image requirements, checks may fail not because of fraud but because of poor capture quality. imageQualityRetryPolicy controls how Verify handles that ambiguity.

For example, if a document number is obscured, data checks will fail, and Verify cannot tell whether this is intentional or accidental. Similarly, image artifacts may be visually indistinguishable from physical tampering.

Some checks are not affected: if a barcode can be read, barcode data checks run to completion regardless of image quality.

The possible values are:

• NeverRetryBadQuality: reach a verdict regardless of image quality issues.
• RetryBadQualityAlways: ask for a new image whenever image quality issues are detected.
• RetryBadQualityForAcceptances: ask for a new image only when quality issues stand between the document and an Accept.
• RetryBadQualityForRejections: ask for a new image only when quality issues stand between the document and a Reject.

configuration.json

{
  "verification": {
    "settings": { "imageQualityRetryPolicy": "RetryBadQualityForAcceptances" }
  }
}

The default is RetryBadQualityForRejections, so a document that would otherwise be rejected on poor-quality images comes back as Retry instead.

Verdicts are never inverted: a Fail verdict won't become Pass, and vice versa. When Verify can't reach a verdict, the check becomes NotPerformed and the verdict becomes Retry.

Expiration

rejectExpiredDocuments defaults to true, so an expired document fails verification unless you say otherwise.

Set it to false to let expired documents through on their other merits, which is what you want if expiry isn't disqualifying for your use case:

configuration.json

{
  "verification": {
    "settings": { "rejectExpiredDocuments": false }
  }
}

Either way, expiry is reported at verification.checks.documentValidityCheck.expiredCheck, so you can act on it yourself.

Configure extraction

The extraction section controls what data and which images come back. It does not affect the verdict.

Returning images

Images increase the size of the response, so all four are off by default:

• documentCaptureModuleSettings.documentImageReturnEnabled: the cropped document image for each side
• documentCaptureModuleSettings.faceImageExtractionEnabled: the face portrait
• vizModuleSettings.signatureImageExtractionEnabled: the signature
• barcodeModuleSettings.barcodeImageReturnEnabled: the image of the scanned barcode

configuration.json

{
  "extraction": {
    "documentCaptureModuleSettings": { "faceImageExtractionEnabled": true },
    "vizModuleSettings": { "signatureImageExtractionEnabled": true }
  }
}

Enabled images come back in the response's images object, as base64-encoded JPGs.

Redaction

redactionSettings.globalMode controls whether extracted images and result fields are redacted:

• None
• ImageOnly
• ResultFieldsOnly
• FullResult

When omitted, FullResult is used, so documents that legally require redaction are redacted even if you send no configuration at all.

configuration.json

{
  "extraction": {
    "redactionSettings": { "globalMode": "ImageOnly" }
  }
}

The mode applies to the whole request. There is no per-document or per-field redaction.

See also

• Scenario-based configuration: worked examples showing how different constraint profiles map to specific configurations.