Integration best practices

This page helps reduce the number of failures during image-based identity verification by providing tips integrated into the verification process.

Most failed image identity verifications are not fraud. They come from how your flow collects the document and the name: a blurry photo, a missing back side, a name typed differently from the ID.

This page lists the changes to make in your flow. Each one shows the failure cause it prevents, an example of a correct integration, and the step to reopen if the verification still fails, based on its status code.

It is written for the product and front-end teams who build the screens your end users see. For the API call itself, see Request an Image Identity Verification.

Why verifications fail

Each recommendation below shows the cause it prevents. Several address the same cause, so their shares do not add up.


Name input

1. Collect the name exactly as printed on the ID

Prevents: name mismatch, 30% of failed attempts.

Ask for the first name and last name in two fields, empty, with the hint "Exactly as written on your ID document". On a French ID card, for example, the last name is the birth name, not the married name. Remove titles such as "Mme" before sending, and keep accents and hyphens.

Name input screen. What not to do: a single pre-filled full name field. What to do instead: ask for the birth name in a field of its own, with separate first and last name fields and a hint that the name must be written exactly as on the ID document.

If it fails: IDDV_1706 (last name), IDDV_1707 (first name) or IDDV_1709 (names inverted) → reopen the name field with the hint. Do not ask for a new photo: the document was read.

If you cannot rely on the name you have: omit first_name and last_name. The verification runs on the document alone, and you compare the extracted identity with your own records.


Document capture

2. Let users choose the document type

Prevents: wrong document type, 3% of failed attempts.

If you set type, a valid document of another type fails: a passport fails when you asked for an ID card. Let users choose the type and send their choice, or omit type.

3. Ask for the front and back in two separate steps

Prevents: side missing, 10% of failed attempts.

Use one step for the front and one for the back, each with its own label and preview, instead of a single drop zone that accepts several files. For a passport, ask only for the photo page.

If both sides end up on a single image or PDF, make sure each side is upright: a back side that is rotated or upside down is not read, and the verification fails with IDDV_1507 (back side not found).

4. Show how to take the photo before the camera opens

Prevents: unreadable photo (40% of failed attempts) and expired document (8%).

Show example photos and short instructions on the upload screen, before the camera or file picker opens. On mobile, open the camera first with a card-shaped overlay, and offer the file picker as a secondary option.

Put these instructions in your own copy:

  • Place the document flat on a dark surface · Turn off the flash · Keep all four corners in the frame · Hold still until the image is sharp. Glare, motion blur and cut corners are three separate status codes, and this one line prevents all three.
  • We need a colour photo of the original document, not a copy. A photocopy or black and white scan loses the document's security features and most of its contrast. Check the image in the browser and reject black and white images before upload.
  • Check that your document has not expired. You cannot fix an expired document, but a check before upload saves your user the upload and the wait.

If it fails: an image issue (IDDV_1200 to IDDV_1208) or IDDV_1508 → reopen the camera step. Show the failed photo next to the instruction that matches the code.

In a nutshell: the document capture flow

Document capture screen. What not to do: a single drop zone that accepts any file, with the document type fixed to ID card. What to do instead: let users choose their document type, capture the front and back in two steps, show example photos of a good and bad capture, list four instructions (colour photo of the original, flat with all four corners visible, no flash and held still, not expired), and open the camera first with the file picker as a secondary option.

Before you send the file

5. Validate the file in the browser

Prevents: file errors.

Check these constraints before calling the API, and show a specific message when the file does not meet them.

ConstraintValue
FormatsPDF, JPG, PNG
Max file size10 MB
Min resolution320 × 256 px
Max resolution20 megapixels

6. Send one document for one person per file

Prevents: ambiguous files.

A PDF with two people's ID cards is ambiguous: we cannot know which holder to verify. Say it on the upload screen, and split the file if you can.
Example message: Upload one document, for one person.

7. Flatten PDFs before sending

Prevents: altered document. PDF annotations alone cause 0.3% of failed attempts.

Annotations and edit layers in a PDF are read as signs of tampering. Flatten the PDF before sending it, or ask for a photo instead.


After a failed verification

8. Show the reason and reopen the right step

A generic "Verification failed, please try again" leads users to send the same photo again. Read the status codes instead. A verification can return several codes, so handle each one.

Results screen. What not to do: a generic 'Verification failed, please try again' message. What to do instead: read the status code, name the real problem, show the photo back, list three concrete actions and offer a fallback.

9. Limit retries and offer a fallback

After two or three failed attempts, stop the retry loop. Offer another route, such as a manual review on your side.


Related pages