How UK passport photo codes work
A photo code is not a government login and it is not an official endorsement. GOV.UK’s photo code guidance for suppliers describes the process this way: the supplier hosts the digital photo on a secure HTTPS address, shortens that address, and gives the short address to the customer as a photo code.
The applicant enters the code in the online passport application. His Majesty’s Passport Office retrieves the JPEG. GOV.UK says a signed request, a JSON Web Signature, is sent with that retrieval so the photo can be limited to HMPO. HMPO then checks the photo. Every photo is reviewed. A code only points at the file you are hosting.
Codes from this API use that pattern. The response field idPhotoCode looks like idfoto.net/P5E9E47P. The example code is a format sample from the API reference, not a live photo.
Generate a UK passport photo and photo code in one API call
The photo-code workflow uses the same authentication and regional hosts as the Passport Photo API: https://api-us.idphotoapp.com or https://api-eu.idphotoapp.com. Keep the API key and secret on your server. Read the Passport Photo Code API documentation for every field.
Direct mode
POST /v2/makeIdPhoto with specCode set to uk-passport returns the sized JPEG and idPhotoCode in one response. Use it for kiosks, booths, and backend jobs that should hand the code to the applicant immediately.
curl -sS -X POST "https://api-us.idphotoapp.com/v2/makeIdPhoto" \
-H "Content-Type: application/json" \
-d '{
"apiKey": "YOUR_API_KEY",
"apiSecret": "YOUR_API_SECRET",
"imageBase64": "BASE64_IMAGE",
"specCode": "uk-passport"
}'{
"photoUuid": "…",
"idPhotoUrl": "https://…",
"issues": [],
"idPhotoCode": "idfoto.net/P5E9E47P"
}outputFormat may be S3_URL (the default) or IMAGE_BASE64. An empty issues array means the checks that ran did not report a problem. It does not mean HMPO has approved the photo.
Watermark mode for consumer apps
Show a preview before you release the final file and code:
POST /v2/makeIdPhotoWatermarkwithuk-passportreturns a watermarked preview and aphotoUuid.- After the applicant confirms,
POST /v2/getIdPhotoNoWatermarkwith thatphotoUuidreturns the JPEG without the watermark and theidPhotoCode.
Optional watermark text is limited to the whitelisted values in the documentation, including “Preview”.
UK passport photo requirements the API checks
The standard uk-passport specification is a 35 × 45 mm portrait. Digital photos also have to meet the rules for digital passport photos and the GOV.UK photo guidance:
- Colour JPEG, at least 600 × 750 pixels, between 50KB and 10MB.
- Plain light background, even light, and no shadows on the face or behind the person.
- Facing the camera, eyes open, mouth closed, plain expression. Taken in the last month.
- Unedited. GOV.UK says you can’t “correct” a passport photo, and filters are not allowed.
This API crops, sizes, and checks the background and the detectable quality rules. It returns photo issue codes such as uneven light, a non-neutral expression, glasses, or a head turned too far. It does not change the person’s face, expression, or clothing to force a pass. If an issue cannot be fixed by crop and size alone, ask the applicant to take another photo. See also detect common photo problems before issuing a code.
Checked against published GOV.UK photo rules. This service is not an HM Passport Office product, and a successful API response is not an acceptance decision.
Supported UK spec codes
The photo-code reference returns idPhotoCode for the UK passport specifications below. The UK photo spec codes list also includes uk-passport2, which is a separate row from uk-digital-passport. Confirm the live code with POST /v2/listIdPhotoSpecCode and POST /v2/getIdPhotoSpec before you integrate. These names are not merged here.
| Spec code | What the docs call it | Photo code |
|---|---|---|
uk-passport | UK passport, 35 × 45 mm | Returned |
uk-digital-passport | Alternative UK passport specification in the photo-code reference | Returned |
uk-driverlicense | UK driving licence photo | Optional in the photo-code reference |
uk-passport2 | Listed on the spec-code page as UK Passport | Confirm with the spec endpoints |
Built for apps, kiosks, and photo booths
Passport photo apps
Use watermark mode so the applicant reviews a preview, then release the JPEG and the code after they confirm. Map photo issue codes to short retake instructions. Do not tell the user the photo is approved.
Photo booth and kiosk software
Direct mode fits a booth that prints the portrait and shows the code on screen or on the print. You host the capture, call the API, and give the applicant the idPhotoCode to type into the online application.
Travel and visa platforms
Offer the UK photo-code step next to other document specifications on the same Passport Photo API. For groups of portraits, use bulk UK passport photo processing by calling the API per image.
Running a photo shop? Use our studio workspace
This page is the developer API. Photo shops, camera shops, and pharmacies that want counter software — name and email in, photo uploaded, code sent to the customer — should use UK photo code software for photo shops. That site covers studio workflow and pricing. Build against this API when the code has to come from your own app, booth, or kiosk.
Data handling and code retention
Send requests to the US or EU regional endpoint configured for the account. Transmission is encrypted. URL output uses temporary storage; Base64 output can avoid storing the image on our service. Details are in the data privacy policy.
Photo codes from this API remain retrievable for 21 days after creation. That is our hosting period. It is not an HMPO validity rule, and submitting the code with an application does not extend it. Separately, GOV.UK requires the photograph to have been taken in the last month.
Why developers issue UK photo codes with this API
The code is a field on the same Passport Photo API you use for other documents. idPhotoCode comes back for uk-passport and uk-digital-passport, in direct mode immediately and in watermark mode only after the applicant confirms. Issue codes arrive in that same response, so a turned head or uneven light can force a new capture before you hand anyone a hosted file. The photo meets the published GOV.UK digital photo rules the API can check: crop, size, background, and the detectable quality rules. It works with the HM Passport Office online application because the applicant enters the code there and HMPO retrieves the JPEG. Hosting lasts 21 days on our side. The service is not an HM Passport Office product. HMPO still reviews every photo, and a successful response is not an acceptance decision.
FAQ
What is a UK passport photo code?
A UK passport photo code is a short HTTPS address for a digital passport photo hosted by the photo supplier. An applicant enters the code during the GOV.UK online passport application. His Majesty’s Passport Office retrieves the JPEG and checks it against the photo rules.
How long does a photo code stay valid?
Photo codes from this API remain retrievable for 21 days after they are created. That window is our hosting period, not an HM Passport Office rule. GOV.UK requires the photograph itself to have been taken in the last month.
Does a photo code guarantee HMPO acceptance?
No. A photo code does not guarantee acceptance. HM Passport Office checks every photo. This API crops and sizes the image, checks it against published rules, and returns issue codes before a code is issued. It does not change the person’s appearance, and it cannot promise that an application will be approved.
Can I generate codes from my own booth or app?
Yes. Apps, kiosks, and photo-booth software can call the Passport Photo Code API. Use direct mode when you need the photo and code immediately, or watermark mode when a consumer app should preview the photo before the final code is delivered. Photo shops that want counter software, rather than an API, can use the studio workspace at passportphotocode.com.
What image formats and sizes are returned?
The API returns a JPEG. GOV.UK’s digital photo rules ask for a colour JPEG between 50KB and 10MB, at least 600 pixels wide and 750 pixels tall, with no filters or edits to the person. The standard UK passport print size in our specification list is 35 × 45 mm. Confirm the current file rules on GOV.UK before you submit a photo.