Passport Photo API

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

API Calling Modes

We offer two modes for generating ID photos, designed for different use cases:

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

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

In this mode, you upload a photo and receive the final ID photo in a single API call. It's straightforward and ideal if you want to process photos directly without any preview step.

How it works:

Upload a photo → Get the final ID photo immediately

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

Best for: App developers who want to show users a preview before delivering the final photo.

This mode uses a two-step process. First, you generate a preview with a watermark that users can review. Only after they confirm (e.g., by making a payment), you retrieve the final photo without the watermark using the same photoUuid.

How it works:

Step 1: Upload a photo → Get a watermarked preview
Step 2: Use the photoUuid from Step 1 → Get the final photo without watermark

Why use this? This mode protects your content by ensuring users only receive the final high-quality photo after they've completed your desired action (like 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)

Health Check

JSON

GET /v2/health

Description: Simple Health Check

Sample Output:

JSON

{
  "status": "GOOD"
}

Query Account Status

JSON

POST /v2/queryAccountStatus

Description: Query account status, subscription details, and API quota information.

Request:

JSON

{
  "apiKey": "string",
  "apiSecret": "string"
}

Response:

JSON

{
  "accountStatus": "string", // Account status values include: FREE_TRIAL or SUBSCRIBED
  "freeTrialEndTime": 1234567890, // [OPTIONAL] Unix timestamp in seconds (only present when accountStatus is FREE_TRIAL)
  "subscription": { // [OPTIONAL] Subscription details and API quota
    // Subscription status values include: 
    // SUBSCRIPTION_PENDING (initial state before subscription)
    // SUBSCRIPTION_COMPLETE (subscription active)
    // SUBSCRIPTION_FAILED (subscription failed)
    // SUBSCRIPTION_DELETED (subscription permanently deleted)
    // SUBSCRIPTION_CANCELED (subscription canceled, may still be within service period)
    "subscriptionStatus": "string",
    "subscriptionResetTime": 1234567890, // Unix timestamp in seconds when the quota resets
    "makeIdPhotoApiQuota": 100, // Total quota for Make ID Photo API
    "makeIdPhotoWatermarkApiQuota": 100, // Total quota for Make ID Photo Watermark API
    "makeIdPhotoApiRemaining": 95, // Remaining quota for Make ID Photo API
    "makeIdPhotoWatermarkApiRemaining": 98 // Remaining quota for Make ID Photo Watermark API
  }
}

Make ID Photo (Directly Call)

JSON

POST /v2/makeIdPhoto

Description: Make an ID photo directly. Good for direct use cases.

Request:

JSON

{
  "apiKey": "string", 
  "apiSecret": "string",
  "imageBase64": "string", // image base64
  "specCode": "string", // photo spec, you could use "uk-passport" for testing. See the last section for more details
  "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": "string", // [OPTIONAL] Passport Photo code for specCode starts with "uk": uk-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 passport photo app developers.

Request:

JSON

{
  "apiKey": "string",
  "apiSecret": "string",
  "imageBase64": "string", // image base64
  "specCode": "string", // photo spec, you could use "schengen-visa" for testing.
  "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 access the 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 outcome photo.
  "idPhotoCode": "string" // [OPTIONAL] Passport Photo code for specCode starts with "uk": uk-passport
}

Get ID Photo without Watermark (For App Developers)

JSON

POST /v2/getIdPhotoNoWatermark

Description: Get the ID photo without watermark based on photoUuid. For passport app developers.

Request:

JSON

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

Response:

JSON

{
  "photoUuid": "string", // Each photo has a unique ID
  "idPhotoUrl": "string", // The S3 based URL for access the 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": false // indicating marks and watermark in the outcome photo.
}

List Photo Specifications (For App Developers)

JSON

POST /v2/listIdPhotoSpecCode

Description: Get all photo specs supported by us (Free to use). For passport app developers.

Request:

JSON

{
  "apiKey": "string",
  "apiSecret": "string"
}

Response:

JSON

{
  "results": [
    {
      "specCode": "string", // photo spec, for example: us-passport
      "specCodeName": "string" // for example: US Passport
    }
  ],
  "total": "number"
}

Get Photo Specification Details (For App Developers)

JSON

POST /v2/getIdPhotoSpec

Description: Get the details of a photo spec (Free to use). For passport app developers.

Request:

JSON

{
  "apiKey": "string",
  "apiSecret": "string",
  "specCode": "string" // photo spec, you could use "schengen-visa" for testing.
}

Response:

JSON

{
  "specCode": "string", // photo spec, for example: us-passport
  "specCodeName": "string", // for example: US Passport
  "photoSizeUnit": "string", // for example: in
  "photoSize": "string", // for example: 2 x 2 in
  "photoPixel": "string", // for example: 600 x 600 px
  "photoDpi": "string", // for example: 300 DPI
  "headHeight": "string", // for example: 1 - 1 3/8
  "eyeToBottom": "string", // for example: 1 1/8 - 1 3/8
  "backgroundColor": "string", // for example: #FFFFFF
  "backgroundColorName": "string", // for example: white
  "recency": "string", // for example: 6 months
  "expression": "string", // for example: NEUTRAL
  "color": "string", // for example: IN_COLOR
  "glasses": "string", // for example: NOT_ALLOWED
  "eyesAndEars": "string" // for example: VISIBLE_NO_HIDE
}

Reference

Spec Code — A complete list of all supported ID photo specifications (e.g., US Passport, UK Passport, Visa photos) that you can use with the API.
Issue Codes in API Responses — Descriptions of all possible issue codes returned in the API response when a photo doesn't meet requirements (e.g., face not found, poor lighting, wrong expression).
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 in your application.

Passport Photo API ​

API Calling Modes ​

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

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

API Endpoint ​

Health Check ​

Query Account Status ​

Make ID Photo (Directly Call) ​

Make ID Photo with Watermark (For App Developers) ​

Get ID Photo without Watermark (For App Developers) ​

List Photo Specifications (For App Developers) ​

Get Photo Specification Details (For App Developers) ​

Reference ​

Passport Photo API

API Calling Modes

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

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

API Endpoint

Health Check

Query Account Status

Make ID Photo (Directly Call)

Make ID Photo with Watermark (For App Developers)

Get ID Photo without Watermark (For App Developers)

List Photo Specifications (For App Developers)

Get Photo Specification Details (For App Developers)

Reference