Fixing document upload and reading problems
Most document upload and OCR problems come down to image quality, a missing back image, a disallowed subtype, or a copy instead of the original - here's how to fix each one.
Work through them in this order: is the subtype allowed in your workflow, was the back image captured, was the image good enough, and was it an original photo rather than a screenshot or scan. Those four cover almost every case.
If a document fails to upload or key fields aren't extracted correctly, it's almost always one of a few known causes. Here's how to work through them.
#First: is the document even allowed?
Before debugging image quality, confirm your workflow accepts that exact document subtype for that country. A disallowed subtype fails in a way that looks like a reading problem but isn't - and it fails for every user holding that format, not just one. See subtypes are the usual reason a document is rejected.
#Blurry, dark, or overexposed images
Didit checks image quality before processing a document and asks the user to retake the photo if it's too blurry, too dark, or too bright. Ask the user to:
- Use good, even lighting with no direct glare
- Hold the camera steady and let it focus before capturing
- Keep all four corners of the document visible in the frame
- Remove the document from a plastic sleeve - the reflection defeats auto-capture
Users get a limited number of retakes; on their last allowed attempt the image is accepted so they're never permanently blocked, but a low-quality capture can still leave fields unreadable. Check the session's warnings for IMAGE_TOO_BLURRY, IMAGE_TOO_DARK, or IMAGE_TOO_BRIGHT to confirm this was the cause.
If blurry documents are getting through and even being approved, the bar is set too low for your risk appetite. Two settings in the workflow's ID verification step fix it:
- Minimum image quality (the quality slider): every document photo is scored by the quality model the moment it is captured, and captures below your minimum are rejected instantly with a retake request. The default is deliberately permissive; raise it and the blurry back-of-card that scored 33 never reaches the checks.
- Image capture review screen (under Advanced): shows the person the photo they just took and asks them to confirm it or scan again before it is uploaded. It applies to camera scans only, since uploads already preview the file.
The quality score itself is in the session report, so you can look at the sessions that worried you and pick a threshold just above them.
#A field wasn't detected, or was read wrong (name, date of birth, document number)
When OCR can't extract a specific field, that alone usually does not decline the session - by default it's routed to manual review so a human can check it. When it extracted a value that is wrong (a surname with one letter off, the address in the name field), see fixing a name or field that was read wrong: support can't edit it for you, but the user data review step, the update-data API and a resubmission each can.
If this is happening often for one document type or one language, review your workflow's Preferred character format setting: choose whether extracted names should be normalized to Latin characters or kept in the document's original script. A mismatch here is a common cause of scrambled or missing name fields on documents in Cyrillic, Arabic, Greek, or Han script.
#Screenshots, printouts, and photos of screens are rejected
Didit requires an original, real-time photo of the physical document - not a screenshot, a scan, a printed copy, or a photo of the document on another screen. Document liveness checks are designed to catch exactly these cases and will flag or decline the session. Ask the user to photograph the physical document directly.
This is deliberate: accepting a photo-of-a-photo removes most of the value of checking a document at all.
The screen-capture detector can occasionally fire on a genuine document photographed against a busy background - a keyboard, a patterned desk, a monitor behind the card. If you have looked at the images and the document is clearly real, approve the session yourself: the tag routes to review precisely so a person can make that call. Each document-liveness signal (screen capture, printed copy, portrait replacement) has its own review and decline thresholds in the step's forgery settings if one of them is too trigger-happy for your traffic.
#Uploads run fewer fraud checks than live capture
If your workflow allows uploading an existing file instead of photographing the document live, know the trade-off: several fraud-detection models rely on the live capture itself - how the document moves, reflects and focuses on camera - and can't run on a static uploaded image. A fraudulent document that would be caught live can pass as an upload, and low-quality uploads are also the main source of OCR misreads (a blurry file can extract a wrong name and a blurry portrait in one go).
If either of those is biting you, disable the upload option: in the workflow, under ID verification → Advanced, turn off document upload so every user captures the document live.
#Missing back image
ID cards and driver's licenses are dual-sided - Didit needs both the front and back image to complete extraction. If only a front image was submitted for one of these document types, the session will not have the data it needs.
If users consistently stall on the back-side step, check whether the document you're asking about actually carries readable data on the back in that country. Requiring a back image that holds nothing means users fail a step for no benefit.
#The camera never opens
This looks like a document problem but is an environment problem:
- In-app browsers. A link opened inside another app's built-in browser (a chat app, for example) often can't get camera access. Opening the same link in the phone's normal browser fixes it.
- Permission previously denied. Once a person denies camera access for a site, the browser remembers. They have to re-grant it in site settings; the flow can't ask again.
- Camera already in use. Another tab or app holding the camera blocks it. On some devices, granting microphone access can also tie up the camera.
#Text on the flow looks garbled
If the person reports scrambled or nonsense words in the interface (not on the document), the usual cause is a browser page-translation extension rewriting the screen. Ask them to turn translation off for the page - the flow already offers its own languages. See setting the verification language.
#How many languages does OCR support?
Didit's OCR reads documents in over 130 languages as part of its document and country coverage. This is separate from the verification screen's own language, which the user's browser sets automatically unless you set it explicitly.
#Still stuck?
Contact support with the session ID for the affected verification - it's the fastest way for the team to look into a specific case, because it lets them see exactly the images and warnings you're describing.