US passport photos, UK passport photos, and DV lottery photos are check, then retake. Do not auto-fix them, and do not replace the background. The US Department of State says not to upload a photo created or edited with artificial intelligence or other digital tools. UK digital photo rules say the photo must be unedited. A manipulated DV lottery photo can make the entry ineligible. The pricing page already says not to use the Fix Passport Photo API on US or UK passport photographs.
Catch the rejection before the customer leaves
A studio, a kiosk, or an app usually finds out a photo is wrong after the print, the payment, or the government form. The check runs on the portrait you already have. POST /v2/checkPhoto does not return a new image. It returns JSON: an overall pass, a score from 0 to 100, and a checks array. Each rule has an id, a name, a status of pass, warn, or fail, the measured value, the expected value, and a sentence you can show.
The score summarizes those rules. It is not a probability that a government will accept the file. A pass means no rule failed. The passport office, visa center, employer, or school still decides. This service is not a certified test against ICAO 9303, ISO/IEC 19794-5, or ISO/IEC 29794-5, and it does not claim NIST, BSI, FedRAMP, or SOC 2 certification.
What the check covers
| Rule | What it looks at |
|---|---|
| Size and dimensions | Pixel size, physical size, and crop for the selected specification. |
| Head size and position | Head height and placement, including a head that is turned or tilted. |
| Background | Color and whether the background is uniform, without objects, texture, or a shadow behind the head. |
| Lighting and shadows | Even light on the face, and shadows that hide features. |
| Glasses and glare | Glasses where the specification refuses them, sunglasses, and reflections on the lenses. |
| Expression | A neutral face and a closed mouth, when the specification asks for that. |
| Eyes | Eyes open and looking at the camera. |
| Focus and blur | Whether the face is sharp enough to use. |
| Compression and resolution | File size, pixel dimensions, and heavy compression. |
| Head coverings | Coverings that hide the face. A religious or medical covering that leaves the face visible is a warning for a person to review, not an instruction to remove it. |
| Digital alteration | Hints of a morph, a generated face, or a retouch that changes the person. A crop or a plain background is not treated as a failure on a specification that allows that processing. |
If no usable face is found, that rule fails and the other rules are not measured. The API reference lists the stable id for each rule. Hints of digital alteration on this call are not the early-access AI photo detection screen. Neither one is a government decision.
Check, then fix or retake
The same response tells the integration what to do next. Read spec.alterationAllowed and fixable. Do not infer either value from the country name.
- Check. Send the portrait and a
specCodetoPOST /v2/checkPhoto. Hosts arehttps://api-us.idphotoapp.comandhttps://api-eu.idphotoapp.com. - Retake when
fixableis false. ShowretakeTips. This is the path forus-passport,uk-passport,uk-digital-passport,uk-passport2, andus-dvlottery. It is also the path when the eyes are closed, the face is missing, a covering hides the face, or the image looks digitally altered. - Fix, then check again only when
fixableis true.fixSuggestion.stepsnames the next call. Pose, expression, glasses, lighting, and recoverable blur go to the Fix Passport Photo API (POST /v2/aiEdit). Size and background, where that processing is allowed, go to the Passport Photo API (POST /v2/makeIdPhoto). Run the check on the file that comes back.
A closed loop for a badge or another specification that allows a correction is: check, fix the rules the response names, check again. A closed loop for a US or UK passport or a DV lottery photo is: check, then tell the person how to take another photo. The fix endpoint keeps the person recognizable and does not select a document size. It still must not be used on those three cases.
Who it is for
| Team | Where the check sits |
|---|---|
| Photo studios and retail counters | Before the print button. The colleague gets one retake sentence instead of a rejected print. See retail counters. |
| Kiosk and photo-booth makers | On the server behind the booth, so a failed rule can ask for another capture before payment. |
| Passport and ID photo apps | On the upload, next to generation. The capture guide is the camera flow. This check is the verdict. |
| Visa agencies and DV lottery services | Before a file is attached to a case. DV lottery photos are retake only. See travel agencies and immigration firms. |
| Universities, HR, and onboarding | On the badge or student-ID upload. A correction is available only when that specification allows it. See universities and HR badge photos. |
| Government agencies, through integrators | A longer-term audience. The integrator owns the deployment. This API is not a government system. |
Specifications
Send the same specCode values the rest of the API uses. Common codes include us-passport, uk-passport, us-dvlottery, germany-passport, and schengen-visa. The catalog covers 300+ specifications across 200+ countries. Look them up in the spec code reference, or from POST /v2/listIdPhotoSpecCode and POST /v2/getIdPhotoSpec. A page address such as us-passport-photo is not the request value. An unknown code returns INVALID_SPEC_CODE.
The rules are the ones that specification publishes: size, background, head position, glasses, expression, and the rest of the fields on the spec. ICAO 9303, ISO/IEC 19794-5, and ISO/IEC 29794-5 are the public references those document photos are written against. Passing this check does not mean a laboratory certified the file.
FAQ
Does a pass mean the passport office will accept the photo?
No. A pass means the rules in that response did not fail. The issuing authority still reviews the photograph. Say that the file was checked against the specification. Do not say it was approved or guaranteed.
Can the check auto-fix a US passport, UK passport, or DV lottery photo?
No. Those specifications come back with alterationAllowed false and fixable false. Show the retake tips. Do not call POST /v2/aiEdit, and do not replace the background.
What if only the background is wrong?
On a specification that forbids alteration, ask for a new photo in front of a plain wall. On a specification that allows processing, fixSuggestion can point at POST /v2/makeIdPhoto. Check the file that call returns.
How do I send the image?
JSON with imageBase64, JSON with an HTTPS imageUrl, or multipart form data with a file field. Send one of those, plus specCode. language is optional and defaults to English. Details, error codes, and curl, JavaScript, and Python samples are in the API reference.
How much does it cost?
Pricing for POST /v2/checkPhoto is available on request. Email support@idphoto.ai or read the pricing page. The $0.20 starting price is for preparing a photo, not for this check. If the endpoint is not enabled on your key, ask support to turn it on.