How to automate employee badge photos for HR onboarding

A new hire who starts on Monday is often not in the building where the badge printer sits. They will send a photo from a phone, with a window behind them. Someone else already has a directory portrait cropped for a different card. Security still needs one file: the right pixel size, the background the template expects, and a face a person at the door can recognize. That should not wait for a photo day.

The employee badge photo API is how you run that job. You keep a specification for the card, call the Passport Photo API once per portrait, and write the accepted JPEG back to the person who needs the badge. Workday and SAP SuccessFactors use the same three steps: sync the roster, generate the photo, write it back to the profile. This article is that implementation, for the team that owns onboarding and for the vendor that prints the cards. If you are putting passport or visa capture inside a consumer app, read how to add passport photo capture first. The camera advice overlaps. The document rules do not.

Set the card template before anyone uploads

There is no universal employee badge photo size. Card printers often use CR80 stock, 3.375 × 2.125 inches. The photo window on that card depends on the template: a tall portrait on the left, a small square beside the name, a campus card that also has to work at a turnstile. A “1 × 1 inch headshot” guessed in the client will not match the printer.

Put pixel size, physical size, DPI, and background on a specification, then send that specCode. If the size is not listed, ask support to add a custom photo specification. POST /v2/getIdPhotoSpec returns the size and background when the spec publishes them. POST /v2/listIdPhotoSpecCode confirms the code is on the account. The spec code reference documents 150+ specifications and says to query them. Cache the badge spec in the HR admin tool and refresh it when the card design changes. One specification per card design: a student ID and a staff badge can share CR80 stock and still need different windows.

A code the account does not have can come back as ISSUE_PHOTO_SPEC_NOT_EXIST. That is a configuration bug. Do not tell the new hire their photo was rejected.

Choose who collects the photo

You can collect in two ways. Both end at the same checks.

Build the upload into the HR, access-control, or card-printing product you already run. The page the employee sees is yours. Their browser or phone sends the image to your backend. Your backend calls POST /v2/makeIdPhoto with the portrait and the badge spec. This is the right path when onboarding already has a task list, an identity provider, and a place to store the file.

Use the early-access self-service portal when you do not want to build that page. Each person gets a unique email link, opens it without an account, and uploads from a phone, tablet, or computer. Failed checks tell them what to retake. Accepted photos come back by webhook, API pull, or the storage location on the account. Each link expires after use. The portal is a limited early-access pilot, and you can call the API without it. Request early access if you want the emailed link.

Do not put apiKey or apiSecret in the page the new hire opens. The sample Python code reads both from the environment and sets a 120-second timeout. Hosts are https://api-us.idphotoapp.com and https://api-eu.idphotoapp.com. Stay on the region configured for the account for every call in that person’s flow, including a preview and the final file.

Workday and SAP SuccessFactors are three steps you own

A Workday badge photo and an SAP SuccessFactors employee photo follow the same flow. The photo API does not replace the HR system, and it does not ship a connector you drop into a tenant. Your integration does three things, in order.

1. Sync the roster. The people who need a photo come from Workday or SAP SuccessFactors: new hires, and anyone whose photo you are refreshing. Your record needs the worker ID, the email you will use for the link, and whether a current photo already exists. Keep the HR system as the list of people. Do not create a second employee directory inside the photo service.
2. Generate the badge photo. Each portrait is checked and cropped to the badge specification on the account. Issue codes flag a retake before the file is accepted. Store photoUuid, the spec code, and the issue list against that worker ID.
3. Write the photo back. After your accept rule passes, write the finished JPEG to the employee profile in Workday or SAP SuccessFactors. Do this once, on the accepted file, not on every preview.

Track the case in your database. The API does not. A useful set of states is invited, received, retake, accepted, and written_back. If the write to Workday or SAP SuccessFactors fails, leave the state at accepted and retry the write. Do not call the photo API again because the HR system was down.

Printers and access-control systems outside those two take the file by webhook, API pull, or the storage location on the account. The API response is a temporary image URL or Base64. Copy the bytes into the system that prints the card. If a reviewer must confirm before the clean file exists, use the watermarked pair from the passport capture article: POST /v2/makeIdPhotoWatermark, then POST /v2/getIdPhotoNoWatermark with the saved photoUuid. An internal tool that stores the JPEG immediately should call makeIdPhoto directly. Do not mix the two modes on the same photo.

The request the onboarding worker sends

A minimal body is the key, the secret, the Base64 image, and the badge spec. Replace YOUR_BADGE_SPEC with the code created for the account. outputFormat is optional. S3_URL is the default. IMAGE_BASE64 returns the JPEG in idPhotoImageBase64 so you can keep the portrait in your own systems.

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": "YOUR_BADGE_SPEC",
    "outputFormat": "IMAGE_BASE64"
  }'

Prefer IMAGE_BASE64 for employee photos when your privacy review says the image should not sit in temporary URL storage. The data privacy policy describes encrypted transmission, temporary storage from 2 hours to 14 days, or Base64 so nothing is stored on the service. It also covers GDPR and CCPA. Do not log the secret or the full Base64 payload.

A successful response includes photoUuid, the spec code, pixel dimensions, DPI, and an issues array. An empty array means the checks that ran did not report a problem. It is not a sign-off from security, and it is not acceptance by a passport office. You still decide which codes block a print and which a reviewer may override.

On the capture screen, use the checklist in the capture article and the common mistakes guide: one person, even front light, head upright, both shoulders in frame, an original color photo. A tight crop of a face cannot be resized into a badge that needs shoulders.

Turn issue codes into one retake, not a raw string

Do not put ISSUE_HEAD_YAW_OVER_THRESHOLD in the onboarding email. Map each code to a sentence, and keep the code in your own log. The issue code reference is the contract. The codes that show up when someone photographs themselves at a desk are:

• ISSUE_FACE_NOT_FOUND — no usable face. Ask for one person, face fully visible.
• ISSUE_HEAD_YAW_OVER_THRESHOLD and ISSUE_HEAD_PITCH_OVER_THRESHOLD — head turned or tilted. Ask them to face the camera and hold the head upright.
• ISSUE_EXPRESSION_NOT_NEUTRAL — mouth open or a broad smile. Ask for a closed mouth and a relaxed face. This is not an emotion score.
• ISSUE_FACE_LIGHT_NOT_BALANCE and ISSUE_FACE_BRIGHTNESS_BAD — uneven light, or a face that is too dark or too bright.
• ISSUE_PHOTO_SHARPNESS_BAD — blur. Ask for a sharper photo before you talk about a small framing issue.
• ISSUE_BOTTOM_NOT_FULL, ISSUE_LEFT_NOT_FULL, and ISSUE_RIGHT_NOT_FULL — not enough shoulder. Ask them to step back.
• ISSUE_EYEGLASSES_NOT_ALLOWED and ISSUE_EYEGLASSES_REFLECTION — glasses where your spec refuses them, or glare on the lenses.
• ISSUE_NOT_IN_COLOR — the file is not a color photo.

Agree the accept rule before the worker goes live. No face, blur, a missing shoulder, or a missing spec should block the print. When several codes return, show the one that forces a new photo first. issueSensitivityOverride runs from VERY_LOW to VERY_HIGH. Higher is stricter. It changes detection, not the card template.

A timeout is not proof the photo was skipped. Look up that worker’s last photoUuid before you send the image again.

Background color, and when a correction is allowed

The specification can carry the background, including white or another color you set. For many badges that is the whole step: makeIdPhoto applies the color with the crop.

Call background removal when you need a transparent PNG first, for example to inspect a kitchen behind the person before the crop. POST /v2/removeBackground favors edge quality. POST /v2/removeBackgroundFast is the lower-latency preview. The request needs a data-URI prefix, outputFormat of PNG or JPEG, and outputType IMAGE_BASE64. JPEG cannot keep transparency. The cutout is not a badge photo until you run the spec code. Hair, motion blur, and a background close to clothing can leave a halo, so keep the original until the sized file is accepted. See the Background Remove API docs.

Soft light can go through photo enhancement (POST /v2/photoEnhance) or shadow removal (POST /v2/removeShadow). enableFaceEnhance defaults to false because it can change small details. Neither call decides that a photo meets your badge rule.

Where policy allows a corrected staff portrait, POST /v2/aiEdit can correct pose, expression, glasses, lighting, recoverable blur, and a cut-off shoulder while trying to keep the person recognizable. It does not pick the badge size, and access may need to be enabled. Run it, then pass the result to makeIdPhoto. The AI Photo Editing API page and the AI edit reference describe the boundary. Do not use it on a US or UK passport photo: US rules reject photos created or edited with artificial intelligence or other digital tools, and UK digital photos must be unedited. A UK passport photo code is a separate product, a short address for a JPEG that meets GOV.UK photo rules and is usable for HM Passport Office online applications. It is not a badge file.

Two images of the same person can go to POST /v2/faceMatch, which returns isMatch and similarity. The score is not a legal identity decision, and the reference does not include liveness or document OCR. Face-match access is separate from the passport-photo key. Run issue codes first. See the Face Match API.

A directory you already have is a queue

There is no bulk-upload method. Reprocessing a directory is the same makeIdPhoto call, once per portrait, with the same badge spec. One failure belongs to that person. Record it and continue. Read makeIdPhotoApiRemaining from POST /v2/queryAccountStatus before you start. The numbers in the documentation are an example payload, not your plan size. Progress is how many calls your worker has finished.

Store an idempotency key yourself, by worker ID and source-image hash. The API does not provide one. On timeout, confirm whether a photoUuid exists for that key before you send the image again. The batch ID photo page describes the same loop for schools and agencies. Do not send a badge portrait through us-passport or uk-passport to save a branch. A badge specification returns the sized badge file. Do not expect idPhotoCode on a non-UK spec.

Privacy for a portrait that lives in an HR profile

Each portal link is unique and expires after use. Data is encrypted in transit. Take Base64 when the service should not store the image, or copy a temporary URL into your own storage within the 2-hour to 14-day window. Do not reuse that upload as a passport file unless the person is actually applying, on a separate flow.

A sequence you can ship

1. Record pixel size, physical size, DPI, and background with the printer.
2. Confirm the spec code with getIdPhotoSpec. Store it beside the card design, not in a mobile app.
3. Keep the API secret on the server. Note the US or EU host.
4. Write which issue codes block a print, and whether AI correction is allowed. Keep passport photos on another branch.
5. Sync new hires and refreshes from Workday, SAP SuccessFactors, or the HR export you trust.
6. Collect one color photo per person, by unique link or your own upload step.
7. Call makeIdPhoto, or the watermarked pair if a reviewer confirms first. Stay on one regional host.
8. On issues, send one retake and keep the raw code in your logs.
9. On accept, store the JPEG, write it to the profile, and send the same bytes to the printer.
10. For an existing directory, watch makeIdPhotoApiRemaining and give HR a retake report.

What to tell the new hire

Say three things in the email and on the upload page. The photo will be cropped for their badge. If something is wrong, you will say what to change: light, distance, or expression. The link is only for them, and it expires after use. Do not offer an “auto-fix my face” button on a flow that might also produce a government document. For a US or UK passport, the next step is another photo.

Start from the employee badge photo API page. It covers the Workday and SAP SuccessFactors steps, the early-access portal, and the request. Call the API from the onboarding system you already have, or ask for a portal pilot if you want the emailed link.

FAQ