Fix: face position and crop
Align the face to the head size, eye line, and output size in the selected spec code.
Document-photo compliance · API
ID Photo API
SaaS Service
The job is document-photo compliance, not a white-background cutout. Apply the rules for a passport, visa, or ID spec, check the portrait, diagnose what failed, and return a file closer to submission-ready.
Read the API DocsSpec codes such as us-passport, uk-passport, and china-visa are the rules the API checks against.
Rules → check → diagnose → fix
Sample check
Original
Input portrait972 × 778 px
Rules: us-passport
2 × 2 in600 × 600 px
✓ Rules: us-passport
✓ Issues diagnosed
✓ Closer to submission-ready
POST /v2/makeIdPhoto
Example output
RulesSpec codes such as us-passport
CheckCompliance check on the portrait
DiagnoseRejection reasons in the response
FixA file closer to submission-ready
01 / Compliance path
Rules, check, diagnose, fix.
A white background is one rule inside a spec. The API checks the portrait, reports what failed, and applies the fixes that move the file closer to submission-ready.
Fix: the background the spec requires
Replace the backdrop with the color that spec calls for, including white where the rules require it. Edges around hair and clothing stay intact.
Diagnose: what failed
Return rejection reasons when the compliance check finds a turned head, uneven light, poor sharpness, eyeglasses, or a non-neutral expression.
A file closer to submission-ready
Receive the checked image in the API response, from a temporary URL, or as a print layout. The reviewing authority still decides acceptance.
Need a rule set that is not listed? We can add a custom spec code for your compliance check.
Talk to us about a custom specification02 / Sample checks
One portrait. Three sets of rules.
These samples show a compliance check against a US passport photo, a UK passport photo, and a China visa photo. Switch the spec to see the crop those rules target.
Original photoInput
Checked sampleOutput
Rules for this spec
- Photo format
- US Passport Photo
- Rules (specCode)
us-passport- Physical size
- 2 × 2 in
- Pixel size
- 600 × 600 px
- DPI
- 300
- Background
- White
✓ Background checked
✓ Size checked
✓ Expression checked
✓ Lighting checked
✓ Sharpness checked
✓ Eyeglasses checked
Build this compliance check into your product.Call it with a spec code. Primary step is an API key.
Checking one photo yourself? Try one photo.
Built for a fast integration
One compliance check.
Rules, issues, and a file.
Send a portrait and a spec code. The response returns a file closer to submission-ready, plus any rejection reasons the check found.
Authentication, parameters, issue codes, and response schemas are in the API documentation. A clear issues list reduces rejection risk. It is not a decision by a reviewing authority.
Sample RequestJSON
POST /v2/makeIdPhoto
{
"apiKey": "••••••",
"apiSecret": "••••••",
"imageBase64": "...",
"specCode": "us-passport",
"outputFormat": "IMAGE_BASE64"
}● 200 OK
"issues": ["ISSUE_EXPRESSION_NOT_NEUTRAL"]03 / Rules
Spec codes are the rules.
us-passport, uk-passport, and china-visa are rule sets for the compliance check: size, crop, background, and head position. Pass one as specCode on POST /v2/makeIdPhoto.
The same field covers a US passport photo, a UK passport photo, a China visa photo, and a Schengen visa photo, plus passport and visa photos for Canada, Australia, Japan, India, Singapore, New Zealand, Brazil, and South Korea — more than 150 specs in all.
Query specification data through the API so your product can show the rules for each document type.
View all photo specificationsRules the check runs against
- US passport photo
us-passport- UK passport photo
uk-passport- China visa photo
china-visa
These specCode values are the rules for the three sample formats. The same field accepts the other passport, visa, and ID specifications.
04 / For developers
Passport photo compliance API.
Pre-check a portrait before someone submits it. The same call covers a passport photo compliance check, the rejection reasons when something fails, and a KYC or onboarding pre-check.
Check
Passport photo compliance API
Call POST /v2/makeIdPhoto with a spec code. us-passport, uk-passport, and china-visa are the rules that check runs against — size, crop, background, and head position.
Diagnose
Rejection reasons
When something fails, the response issues list is what failed: head pose, lighting, sharpness, eyeglasses, expression, and related checks. Show those reasons so the person can correct the photo and reduce rejection risk.
Pre-check
KYC and onboarding pre-check
Run the same compliance check before an identity, visa, or employee-photo step. Surface what failed while the person is still in the flow, before an application is submitted.
05 / Use cases
Where a pre-check belongs.
Use one compliance check across photo products, travel flows, studios, and identity onboarding. Adapt what you show. The rules, the issues, and the file stay the same.
01
Passport and visa photo apps
Ship a compliance check with direct processing or a watermarked preview. Return the file and the rejection reasons together.
02
Travel and visa platforms
Pre-check the portrait and show what failed before the customer reaches submission.
03
Photo studios and retailers
Apply the spec rules at the counter: crop, background, a printable sheet, and the issues still worth a retake.
04
KYC and onboarding
Pre-check an identity or employee photo during onboarding, before it is attached to an application or badge.
Privacy-conscious by design
Choose how images are delivered and stored.
Identity photos are sensitive. IDPhoto.ai supports workflows designed to reduce unnecessary image retention and give businesses greater control over delivery.
Read our Data Privacy policyBase64 delivery
Receive the generated image as Base64 data without storing the photo on our service.
Temporary URL delivery
Use temporary AWS S3 delivery, with documented retention ranging from 2 hours to 14 days.
Regional endpoints
Use US or EU API endpoints, with other regional deployment options available on request.
Data protection
Data is encrypted during transmission. Our documented practices address GDPR and CCPA requirements.
More from IDPhoto.ai
Extend the compliance check.
Use focused APIs and services alongside the document-photo compliance check.
Batch ID Photo Generation
Process large groups of portraits for organizations, events, schools, or employee directories.
Explore batch generation →UK Passport Photo Code API
Generate UK passport photos and supported digital photo-code workflows through an API.
Explore UK photo codes →Background Removal API
Use background removal independently when you do not need the complete ID photo workflow.
Explore background removal →Photo Enhancement API
Improve image clarity and visual quality before using photos in professional workflows.
Explore photo enhancement →AI Avatar API
Generate unique, customized AI or styled portraits for team pages, events, and profile photos.
Explore AI avatars →Badge Photo API
Streamline employee and corporate photo badges with consistent, compliant portraits via API or software.
Explore badge photos →Live Biometric Verification API
Confirm a real person is present with live biometric checks for secure identity verification.
Explore biometric verification →Face Analysis API
Detect faces and analyze pose, expression, and attributes to check portrait quality automatically.
Explore face analysis →Passport Photo Print & Mailing API
Print compliant passport photos and mail them directly to your customers through one API.
Explore print & mailing →ID Photo Match Verification API
Verify whether a photo matches the person on an ID document with precision and accuracy.
Explore photo match →Frequently asked questions
What you need to know before integrating.
Still have a question or a custom requirement?
Contact support@idphoto.aiWhat photo formats does the API support?
IDPhoto.ai checks portraits against more than 150 spec codes, including passport, visa, ID, driver's license, and application-photo rules from countries around the world. us-passport, uk-passport, and china-visa are three of those rule sets. You can query the available specification codes through the API.
What does the API return when a check fails?
The response includes the processed file when one can be produced, plus an issues list of rejection reasons — what failed, such as head pose, lighting, sharpness, eyeglasses, or expression. Use those codes to tell the person what to correct. The list is a pre-check. The reviewing authority still decides acceptance.
Can you add a custom photo specification?
Yes. If the format you need is not currently available, contact us with the required dimensions, crop, background, and validation rules. We can review the specification for your use case.
How do I get an API key?
Create or access your account in the IDPhoto.ai Dashboard. Your API credentials and account usage are managed separately from this website.
Is a free trial available?
Yes. Create an account in the Dashboard to check the currently available trial access and account quota.
Are uploaded photos stored?
You can request Base64 output for a workflow that stores no images on our service. URL-based output uses temporary AWS S3 storage, with documented retention ranging from 2 hours to 14 days.
What should the input photo look like?
For the best result, provide a clear, front-facing portrait with the face and upper body visible. Avoid strong shadows, blur, extreme head angles, or obstructions around the face.
Does the API guarantee that a photo will be accepted?
No. The compliance check applies the selected spec and reports detectable issues so you can reduce rejection risk. Final acceptance is determined by the relevant government agency, application platform, or reviewing authority.
Which API regions are available?
US and EU API endpoints are currently documented. Other regional deployment options may be available for enterprise requirements.
How is pricing determined?
Pricing depends on usage volume and workflow requirements. Start with a trial account in the Dashboard or contact us for volume pricing and custom deployment needs.
Start building
Run a compliance check.
Start with an API key.
Create your API credentials in the Dashboard, then call the compliance check with a spec code such as us-passport.