How to build a UK passport photo code workflow into studio and pharmacy software

A pharmacy till and a photo-studio counter already take a payment and hand the customer something they can use. A UK passport photo code is one more line on that sale: a short address the applicant types into the GOV.UK online passport application. HM Passport Office retrieves the JPEG and checks it. Your software creates the code, tells the colleague what to change when the portrait will not do, and prints words the customer can follow.

This integration is for pharmacy systems, studio point-of-sale, and booth products used across branches. The UK passport photo code API returns idPhotoCode for uk-passport and uk-digital-passport. Photos are checked against published GOV.UK photo rules, and the code is usable on the HM Passport Office online application because the applicant enters it there. A code is not an acceptance decision, and this service is not an HM Passport Office product. Phone-app capture is covered in adding passport photo capture to an app. A shop that wants a finished counter product can use the studio workspace for photo shops.

What the customer is buying

The customer is buying a hosted digital photo and a short address for it. GOV.UK’s photo code guidance for suppliers describes the supplier step: host the digital photo on a secure HTTPS address, shorten that address, and give the short address to the customer as a photo code. The applicant enters the code in the online application. GOV.UK says a signed request is sent with the retrieval so the photo can be limited to HMPO. HMPO then checks the photo. Every photo is reviewed.

On this API the field is idPhotoCode, shaped like idfoto.net/P5E9E47P. The string in the Passport Photo Code API reference is a format sample, not a live photo. Codes from this API stay retrievable for 21 days after they are created. That window is our hosting period. It is not an HM Passport Office rule, and submitting the code does not extend it. Separately, GOV.UK requires the photograph to have been taken in the last month. Confirm the current rule on GOV.UK’s photo guidance. The file behind the code is cropped and sized to the specification you send, and the API reports issue codes for face position, lighting, expression, glasses, colour, and framing. An empty issues array means those checks did not report a problem. The issuing authority still reviews the photo.

Copy you can put on the screen and the slip

Colleagues at the counter should not invent a sentence while a customer is standing on the mark. Ship the words with the software, and keep them aligned with the GOV.UK description of a photo code.

After a clean result, the customer screen and the printed slip can use the same block. Put the code in large type. Include the branch name and the date.

UK passport photo code
idfoto.net/P5E9E47P

Enter this code when the GOV.UK online passport application
asks for your photo code. HM Passport Office retrieves the
digital photo and checks it.

This code stays retrievable for 21 days. The photograph
needs to have been taken in the last month.

A photo code is not an acceptance decision.

Replace the sample code with the idPhotoCode from the response. If the till already has permission to email or text that customer, send the same block. Do not add a line that says the photo will be accepted, and do not describe the code or the shop as endorsed by HM Passport Office. If issues is not empty, do not print the slip and do not send the code. Stay on the retake step. A customer who leaves with a code and a list of problems will meet that problem on GOV.UK instead of at your counter.

Keep the secret off the till

The camera or the upload from the customer’s phone can live in the branch. apiKey and apiSecret live on your server. The sample Python code reads them from the environment and sets a 120-second timeout. A till image that contains the secret will leak it the first time a branch is re-imaged.

Call https://api-us.idphotoapp.com or https://api-eu.idphotoapp.com, whichever region the account uses. Other regions exist on request. Every branch should use that same host, and the preview call and the final call for one portrait must use the same host. A photoUuid created on one host cannot be finished on the other.

Do not log the secret or the Base64 portrait. A passport photograph is personal data. The data privacy policy describes encrypted transmission, temporary URL storage from 2 hours to 14 days, and a Base64 option when the image should stay in your own systems. The 21-day window is our hosting period for the code. Your product still needs its own rule for the slip and the till journal.

Take payment before you release the code

Two calling modes are documented. Pick one per SKU and stay with it for that sale.

Direct mode, when the sale is already paid

POST /v2/makeIdPhoto with specCode set to uk-passport returns the sized JPEG and idPhotoCode together. Use it when the booth has already taken payment, or when a staff tool should hand the code over as soon as the checks are clear. outputFormat is optional. S3_URL is the default. IMAGE_BASE64 returns the JPEG in idPhotoImageBase64.

curl -sS -X POST "https://api-eu.idphotoapp.com/v2/makeIdPhoto" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "apiSecret": "YOUR_API_SECRET",
    "imageBase64": "BASE64_IMAGE",
    "specCode": "uk-passport",
    "outputFormat": "IMAGE_BASE64"
  }'

A documented sample response for uk-passport includes widthPx 413, heightPx 531, and photoDpi 300, the 35 × 45 mm size in the specification list. Read the live size with POST /v2/getIdPhotoSpec before you draw a preview frame. GOV.UK’s rules for digital passport photos also describe a colour JPEG, at least 600 pixels wide and 750 pixels tall, between 50KB and 10MB, with no filters and no edits to the person. Confirm the current file rules there, and do not hard-code either set of numbers into the till.

Watermark mode, when the customer pays after seeing the crop

Most pharmacy and studio tills should use the two-step flow, because the customer looks at the crop and then pays:

1. POST /v2/makeIdPhotoWatermark with uk-passport. Optional watermarkText accepts only Preview or Aperçu, case-insensitively. The response has waterMark: true and a photoUuid. It does not include idPhotoCode.
2. Store photoUuid on the basket, with the branch and the till.
3. When the till marks the line paid, POST /v2/getIdPhotoNoWatermark with that photoUuid. The final response has waterMark: false and the idPhotoCode.

If the basket is voided, do not call the second endpoint. If you lose the photoUuid, you cannot fetch the clean file. Take another portrait. Do not show the watermarked preview as a file the customer should upload on their own. The code exists on the second call, which is what you want if a code should only exist once the sale is complete.

Map the SKU to one spec code

The adult passport SKU should send uk-passport. The photo-code reference also returns idPhotoCode for uk-digital-passport, and that page describes it as an alternative UK passport specification, with an under-11 note in the table. uk-passport2 appears on the spec-code list as another UK Passport row. These names are not aliases. Call POST /v2/listIdPhotoSpecCode and POST /v2/getIdPhotoSpec on the account you will ship, and store the code you intend to sell.

Rules for babies and children are published on GOV.UK and are not identical to the adult checklist in every detail. Point colleagues at that guidance, and confirm the spec you send, before you add a separate child button. A driving-licence SKU is uk-driverlicense. Photo-code support for that spec is marked optional in the reference. Do not print the passport-application slip for a licence photo.

If the account does not have the code, the response can include ISSUE_PHOTO_SPEC_NOT_EXIST. Treat that as a configuration bug for the release that owns the SKU map. It is not a reason to ask the customer to stand differently.

A retake script for the counter

The issue code reference is the contract for the issues array. Show one sentence, not the code. When several codes come back, deal with the problem that forces a new photo first. The reference’s own example is blur before a smaller positioning note.

• ISSUE_FACE_NOT_FOUND — one person, face fully visible. Ask them to step in front of the camera again.
• ISSUE_HEAD_YAW_OVER_THRESHOLD and ISSUE_HEAD_PITCH_OVER_THRESHOLD — face the camera and hold the head upright.
• ISSUE_EXPRESSION_NOT_NEUTRAL — mouth closed, plain expression. This check is not an emotion score.
• ISSUE_EYEGLASSES_NOT_ALLOWED, ISSUE_EYEGLASSES_REFLECTION, and ISSUE_SUNGLASSES_NOT_ALLOWED — remove the glasses and take another photo.
• ISSUE_FACE_LIGHT_NOT_BALANCE and ISSUE_FACE_BRIGHTNESS_BAD — the light on the face is uneven or too dark or too bright. Turn them toward a soft light and away from a window behind them.
• ISSUE_PHOTO_SHARPNESS_BAD — the photo is soft. Hold still and take it again.
• ISSUE_BOTTOM_NOT_FULL, ISSUE_LEFT_NOT_FULL, and ISSUE_RIGHT_NOT_FULL — step back so the head, neck, and both shoulders are in the frame.
• ISSUE_HAT_NOT_ALLOWED — unsupported headwear. Ask for another capture. Do not turn that code into an instruction to remove a religious head covering. ISSUE_RELIGION_MASK_FOUND is marked as coming soon. For a religious covering, follow the current GOV.UK guidance for photographers.
• ISSUE_NOT_IN_COLOR — an original colour photo. A photocopy or a screenshot will not do.

Put a short card beside the camera, from the common mistakes guide: one person, even light, no hard shadow, head upright, eyes open, mouth closed, and enough room for both shoulders. A tight crop of the face cannot be rescued by the spec. issueSensitivityOverride runs from VERY_LOW to VERY_HIGH. Higher is stricter. The reference default is MEDIUM. Overrides change detection, not the document specification, so do not lower a check to clear a queue. Treat bad credentials, invalid Base64, an unknown spec, and timeouts as operator errors. A timeout is not proof the photo was skipped, and a blind retry in direct mode can mint a second code.

Print in the branch

Many customers still want paper as well as the code. Add photoSheet.sheetSizes to the makeIdPhoto body when you are in direct mode. Each entry is width*height in pixels, for example 1800*1200, and you can request up to 10 sizes. The response photoSheet object maps each size to a URL. Copy those bytes into the print spool at the branch. URL output uses the temporary storage window in the privacy policy, from 2 hours to 14 days, so a customer who returns next week cannot rely on that URL still resolving.

Read issues before the printer runs. A sheet can come back alongside issue codes. An empty list is the point at which your own rule can allow a print. It is still not an acceptance decision. The online UK application uses the photo code, so it does not need a posted print. Postage is not a field on the request. If the till should offer posted prints, confirm coverage, timing, and price with support first. That boundary is on the print and mailing page.

Leave the person unedited

UK digital photo rules say the picture must be unedited, and GOV.UK guidance for photographers says digital enhancement is not acceptable. Crop, size, the background on the specification, and the checks above are the workflow. If the problem is expression, glasses, pose, or a shadow across the face, take another photo.

Do not send the portrait through face enhancement or the AI Photo Editing API on the way to a UK photo code. The fix passport photo page describes those corrections for workflows whose own policy allows a corrected portrait. AI-edited photos are not acceptable for a UK passport. A staff badge for people who work in the pharmacy is a different specification, the employee badge photo API, including the existing Workday and SAP SuccessFactors paths. That flow, covered in automating employee badge photos, needs its own slip. A separate background removal call is usually unnecessary, because the specification already carries the background and makeIdPhoto returns the finished JPEG. A generated headshot from the AI headshot API is not a document photo. Keep it off this SKU.

Several branches, one call per customer

There is no bulk-upload method. A Saturday queue is your software calling makeIdPhoto, or the watermark pair, once per portrait. One person’s issue codes do not fail the next person. Before a busy session, call POST /v2/queryAccountStatus and read makeIdPhotoApiRemaining, plus makeIdPhotoWatermarkApiRemaining if the till uses a preview. The numbers in the documentation are an example payload, not a rate card. Alert an operator when the remaining count gets low, before the till shows a generic error to someone already on the mark.

Journal each sale: branch, till, operator, spec code, photoUuid, idPhotoCode when you issued one, the issue list, and the time. Open that record when a customer returns, and use it to see which branch repeats the same lighting issue. Copy image bytes into your own storage if you need them after the temporary URL window. A booked school session is the same loop, described on the batch ID photo page. A student-card session should send the card specification, not uk-passport.

FAQ