Passport Photo Code API

For details on how we process your personal data, please see our Data Privacy policy.

Overview

The Passport Photo Code API enables developers and photo businesses to generate digital photo codes for UK passport applications (compliant with HMPO - His Majesty's Passport Office).

When applicants apply for or renew a UK passport online on gov.uk, they can simply enter a Photo Code (e.g., idfoto.net/P5E9E47P), and UK GOV will receive the photo.

Key Benefits

HMPO Compliant: Photos are processed and validated against all HMPO biometric standards (face positioning, lighting, neutral expression, plain background).
Digital Photo Code (idPhotoCode): Automatically generated for UK photo specifications (e.g., uk-passport, uk-digital-passport). Format: idfoto.net/XXXXXXXX (e.g., idfoto.net/P5E9E47P).

API Calling Modes

We offer two modes for generating ID photos and UK photo codes, designed for different use cases:

1. Direct Call Mode (`/v2/makeIdPhoto`)

Best for: Direct use cases, backend integrations, photo kiosks, or when you need the final photo and photo code immediately.

In this mode, you upload a photo with a UK specification (e.g., uk-passport) and receive the compliant ID photo along with the generated idPhotoCode in a single API call.

How it works:

Upload a photo with UK spec → Get the final ID photo and idPhotoCode immediately

2. Watermark Based Mode (`/v2/makeIdPhotoWatermark` + `/v2/getIdPhotoNoWatermark`)

Best for: App developers and websites that want to show users a preview before delivering the final photo and photo code.

This mode uses a two-step process:

Step 1: Generate a watermarked preview for user review.
Step 2: After the user confirms (e.g., completes a payment), call /v2/getIdPhotoNoWatermark with the photoUuid to retrieve the watermark-free ID photo and the final idPhotoCode (e.g., idfoto.net/P5E9E47P).

Why use this? This protects your service by ensuring users only receive the official high-resolution photo and valid UK Photo Code after completing your desired conversion step (such as payment).

API Endpoint

API Endpoint:

https://api-us.idphotoapp.com (US region)
https://api-eu.idphotoapp.com (EU region)
(Other regions' deployment are available per request)

Make ID Photo with Photo Code (Directly Call)

JSON

POST /v2/makeIdPhoto

Description: Make an ID photo directly and generate a UK Passport Photo Code (idPhotoCode). Good for direct use cases and backend services.

Request:

JSON

{
  "apiKey": "string", 
  "apiSecret": "string",
  "imageBase64": "string", // image base64
  "specCode": "uk-passport", // Photo spec code. Use "uk-passport" or "uk-digital-passport" for UK Photo Code generation
  "outputFormat": "string", // [OPTIONAL] "S3_URL" or "IMAGE_BASE64". If not provided, S3_URL will be used by default.
  "issueSensitivityOverride": {
      // [OPTIONAL] Sensitivity levels for photo quality checks.
      // Options: VERY_LOW, LOW, MEDIUM, HIGH, VERY_HIGH.
      // Higher levels apply stricter validation. Default for all: MEDIUM.
      "ISSUE_FACE_LIGHT_NOT_BALANCE": "MEDIUM", // Uneven lighting on the face.
      "ISSUE_FACE_BRIGHTNESS_BAD": "MEDIUM", // Face brightness is too dark or too bright.
      "ISSUE_HEAD_YAW_OVER_THRESHOLD": "MEDIUM", // Head is turned too far to the side (yaw).
      "ISSUE_HEAD_PITCH_OVER_THRESHOLD": "MEDIUM", // Head is tilted too far up or down (pitch).
  },
  "photoSheet": {
      // [OPTIONAL] An optional object specifying the desired sheet sizes for printable ID photo layouts.
      // Each value in the "sheetSizes" array should follow the "width*height" format (in pixels).
      // For example, "1800*1200" will generate a sheet that is 1800px wide and 1200px tall, containing repeated ID photo copies.
      // Useful for printing purposes, especially for standard photo paper dimensions.
      "sheetSizes" : ["1800*1200"],
  }
}

Response:

JSON

{
  "photoUuid": "string", // The unique id of the id photo
  "idPhotoUrl": "string", // The url of created ID photo. Available when outputFormat is S3_URL.
  "idphotoImageBase64": "string", // The image base64 of created ID photo. Available when outputFormat is IMAGE_BASE64.
  "originalPhotoUrl": "string", // The url of the original photo
  "issues": ["string"], // Issues found in the photo. See "Issue Code" for more information
  "idPhotoCode": "idfoto.net/P5E9E47P", // UK Passport Photo code for online passport applications (returned for UK specs: "uk-passport", "uk-digital-passport")
  "photoSheet": {
      // [OPTIONAL] An object containing printable photo sheets based on the requested sizes.
      // Each key is a sheet size (e.g., "1800*1200") and the value is a URL to the generated photo sheet image.
      // These sheets are useful for printing multiple copies of the ID photo on a single page.
      "1800*1200" : "URL string",
  }
}

Make ID Photo with Watermark (For App Developers)

JSON

POST /v2/makeIdPhotoWatermark

Description: Make an ID photo with watermark for preview. Designed for passport photo app developers.

Request:

JSON

{
  "apiKey": "string",
  "apiSecret": "string",
  "imageBase64": "string", // image base64
  "specCode": "uk-passport", // Photo spec code. Use "uk-passport" or "uk-digital-passport" for UK Photo Code generation
  "watermarkText": "string", // [OPTIONAL] Watermark text for watermarked ID photos. Whitelisted values are case-insensitive and include only: "Preview", "Aperçu"
  "issueSensitivityOverride": {
      // [OPTIONAL] Sensitivity levels for photo quality checks.
      // Options: VERY_LOW, LOW, MEDIUM, HIGH, VERY_HIGH.
      // Higher levels apply stricter validation. Default for all: MEDIUM.
      "ISSUE_FACE_LIGHT_NOT_BALANCE": "MEDIUM", // Uneven lighting on the face.
      "ISSUE_FACE_BRIGHTNESS_BAD": "MEDIUM", // Face brightness is too dark or too bright.
      "ISSUE_HEAD_YAW_OVER_THRESHOLD": "MEDIUM", // Head is turned too far to the side (yaw).
      "ISSUE_HEAD_PITCH_OVER_THRESHOLD": "MEDIUM", // Head is tilted too far up or down (pitch).
  }
}

Response:

JSON

{
  "photoUuid": "string", // Each photo has a unique ID
  "idPhotoUrl": "string", // The S3 based URL for accessing the watermarked preview ID Photo, in JPG format
  "issues": ["string"], // The issues in the original photo & ID Photo. ISSUE_FACE_LIGHT_NOT_BALANCE, ISSUE_FACE_NOT_FOUND, ISSUE_EXPRESSION_NOT_NEUTRAL
  "waterMark": true // Indicating marks and watermark in the preview photo.
}

Get ID Photo without Watermark & Photo Code (For App Developers)

JSON

POST /v2/getIdPhotoNoWatermark

Description: Get the final ID photo without watermark and retrieve the official idPhotoCode based on photoUuid. Designed for passport app developers after user confirmation or payment.

Request:

JSON

{
  "apiKey": "string",
  "apiSecret": "string",
  "photoUuid": "string" // photoUuid returned from /v2/makeIdPhotoWatermark
}

Response:

JSON

{
  "photoUuid": "string", // Each photo has a unique ID
  "idPhotoUrl": "string", // The S3 based URL for accessing the final ID Photo without watermark, in JPG format
  "issues": ["string"], // The issues in the original photo & ID Photo. ISSUE_FACE_LIGHT_NOT_BALANCE, ISSUE_FACE_NOT_FOUND, ISSUE_EXPRESSION_NOT_NEUTRAL
  "waterMark": false, // Indicating watermark has been removed in the final photo.
  "idPhotoCode": "idfoto.net/P5E9E47P" // UK Passport Photo code for online passport applications (returned for UK specs: "uk-passport", "uk-digital-passport")
}

Supported UK Spec Codes

The idPhotoCode field is generated and returned when using UK-related specifications:

Spec Code	Specification Name	Description	Photo Code Support
`uk-passport`	UK Passport	Standard UK Passport Photo (35 × 45 mm)	Yes
`uk-digital-passport`	UK Passport (Alternative)	UK Passport Photo (Alternative/Under 11 standard)	Yes
`uk-driverlicense`	UK Driver License	UK Driving Licence Photo	Optional

For all supported global photo specs, see Spec Code.

About UK Passport Photo Codes

What is a Photo Code?

A Photo Code (IDPC / Digital Passport Photo Code) is a unique reference code issued for compliant digital UK passport photos. It connects your processed photo directly with His Majesty's Passport Office (HMPO).

Code Format

The code is formatted as a link/code:

idfoto.net/P5E9E47P

Where P5E9E47P is the unique alphanumeric reference code for the photo.

How End-Users Use the Code:

The applicant goes to the official UK passport application portal on gov.uk.
During the digital photo step, the applicant selects "Enter a code" (or enters the Photo Code).
UK GOV receives the digital photo associated with the code.
The applicant completes the application without needing to upload or mail physical prints.

Code Validity

UK Passport Photo Codes are valid for 21 days from the time of creation.
Once submitted with an application, the photo is permanently linked to that passport application.

Reference

Passport Photo API — Complete documentation of the general ID Photo API.
Spec Code — A complete list of all supported ID photo specifications.
Issue Codes in API Responses — Descriptions of all possible issue codes returned in the API response when a photo doesn't meet requirements.
Common Mistakes from End-User — A guide to common mistakes users make when taking photos and tips on how to help them get better results.
Sample Python Code — Ready-to-use Python code examples showing how to call the API endpoints.

Passport Photo Code API ​

Overview ​

Key Benefits ​

API Calling Modes ​

1. Direct Call Mode (/v2/makeIdPhoto) ​

2. Watermark Based Mode (/v2/makeIdPhotoWatermark + /v2/getIdPhotoNoWatermark) ​

API Endpoint ​

Make ID Photo with Photo Code (Directly Call) ​

Make ID Photo with Watermark (For App Developers) ​

Get ID Photo without Watermark & Photo Code (For App Developers) ​

Supported UK Spec Codes ​

About UK Passport Photo Codes ​

What is a Photo Code? ​

Code Format ​

How End-Users Use the Code: ​

Code Validity ​

Reference ​

Passport Photo Code API

Overview

Key Benefits

API Calling Modes

1. Direct Call Mode (`/v2/makeIdPhoto`)

2. Watermark Based Mode (`/v2/makeIdPhotoWatermark` + `/v2/getIdPhotoNoWatermark`)

API Endpoint

Make ID Photo with Photo Code (Directly Call)

Make ID Photo with Watermark (For App Developers)

Get ID Photo without Watermark & Photo Code (For App Developers)

Supported UK Spec Codes

About UK Passport Photo Codes

What is a Photo Code?

Code Format

How End-Users Use the Code:

Code Validity

Reference