ID PhotoREST · JSONOpenAPI 3.1

SVOYAGER ID Photo API

Maak van elke foto een foto die voldoet aan de eisen voor een identiteitsbewijs, paspoort of visum.

De SVOYAGER ID Photo API verandert een gewoon portret in een conform documentfoto. ID Photo is één enkel product: paspoort, visum, verblijfsvergunning en nationale identiteitskaart worden weergegeven als documentspecificaties, niet als afzonderlijke producten. U uploadt een foto, genereert een voorbeeld met watermerk op basis van een specificatie en rondt vervolgens het proces af om het resultaat zonder watermerk te verkrijgen.

Voorbeeld → definitieve workflow

1Upload een foto. Maak een uploadbestemming aan en stuur de afbeeldingsbytes daarheen.
2Maak een sessie aan. Maak een voorbeeldweergave met watermerk op basis van een specificatie. Controleer de gerapporteerde problemen.
3Afronden. Zet de beoordeelde sessie om in een bestelling en ontvang het definitieve bestand zonder watermerk.

Snelstart

Elk verzoek wordt geauthenticeerd met een Bearer-geheime sleutel. Begin in de testmodus:

curl

# List specifications to find a spec_id
curl -G "https://partner.svoyager.com/v1/photo-specifications" \
  -H "Authorization: Bearer svoy_sk_test_YOUR_KEY" \
  --data-urlencode "country=US"

Basis-URL en omgevingen

Alle eindpunten worden aangeboden onder één basis-URL:

Base URL

https://partner.svoyager.com/v1

Er is geen omgevingspad of -parameter. Of een verzoek in de test- of live-omgeving wordt uitgevoerd, wordt volledig bepaald door het voorvoegsel van je API-sleutel (svoy_sk_test_… versus svoy_sk_live_…). Reacties geven dit weer als livemode.

Authenticatie

API-sleutels

Verifieer elk verzoek met een Authorization-header die uw geheime sleutel bevat. Sleutels worden aangemaakt en vernieuwd in het Partner Center.

Header

Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx

Het voorvoegsel geeft de omgeving aan: svoy_sk_test_… voor test, svoy_sk_live_… voor live. Een testsleutel kan nooit worden gebruikt voor live gegevens (en vice versa) — bij een verkeerde combinatie wordt de foutcode 401 wrong_environment geretourneerd.

Toepassingsgebieden

Sleutels hebben expliciete ‘least-privilege’-bereiken. Een verzoek waarbij het vereiste bereik ontbreekt, retourneert 403 insufficient_scope.

Toepassingsgebied	Toestemmingen
photo.specs.read	List and retrieve photo specifications.
photo.sessions.read	Retrieve sessions and their previews.
photo.sessions.write	Create uploads and photo sessions (previews).
photo.finalize.write	Finalize a session into a no-watermark order.
photo.orders.read	Retrieve orders and download finals.

Sleutels veilig bewaren

Geheime sleutels zijn uitsluitend bedoeld voor server-naar-server-communicatie. Verwerk een geheime sleutel nooit in browser- of mobiele code, een openbare repository of een client-side bundel. Als een sleutel openbaar wordt gemaakt, vervang deze dan onmiddellijk in het Partner Center.

Core API

Eindpunten

Verplichte velden zijn gemarkeerd met *. In de voorbeelden worden plaatshouders voor inloggegevens gebruikt — nooit echte sleutels.

POST/v1/uploads

Upload a photo

Create a short-lived presigned upload target, then PUT the raw image bytes straight to `upload_url`. This bypasses request-body size limits (product cap 10 MB). No quota is spent.

scope photo.sessions.write

Verzoek

Body (application/json)

Veld	Type	Beschrijving
content_type*	string	MIME type of the image.`image/jpegimage/pngimage/webpimage/heic`

`upload_url` is single-use and expires; upload promptly and do not modify the URL.

Voorbeeldverzoek

curl

# 1) Create the upload target
curl -X POST "https://partner.svoyager.com/v1/uploads" \
  -H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"content_type":"image/jpeg"}'

# 2) PUT the bytes to the returned upload_url (exactly as returned)
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

Antwoord · 201

201 · application/json

{
  "object": "upload",
  "upload_url": "https://upload.svoyager.com/v1/EXAMPLE?signature=…",
  "upload_ref": "up_ref_tXk3W2b8Qe7Ra1Nc0",
  "max_bytes": 10485760,
  "expires_at": "2026-07-24T18: 20: 00Z"
}

Fouten

Status	Code	Wanneer
400	missing_content_type	`content_type` was not provided.
415	unsupported_format	The content type is not an accepted image format.
503	temporarily_unavailable	Uploads are temporarily unavailable.
502	upload_init_failed	The upload could not be initialised — retry shortly.

Plus de standaardfouten op het gebied van authenticatie, machtigingen en rate-limits — zie Fouten en herpogingen.

POST/v1/photo-sessions

Create a photo session

Generate a watermarked preview from an upload against a specification. Spends one `preview` unit of your plan. Review `issues` before finalizing.

scope photo.sessions.write Idempotency-Key vereist

Verzoek

Body (application/json)

Veld	Type	Beschrijving
upload_ref*	string	The `upload_ref` from Upload a photo.
spec_id*	string	The `photo_specification` id (`spc_…`) to render against.

Voorbeeldverzoek

curl

curl -X POST "https://partner.svoyager.com/v1/photo-sessions" \
  -H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx" \
  -H "Idempotency-Key: a7f3c9e1-2b4d-4c8a-9f10-3e5d6b7a8c9d" \
  -H "Content-Type: application/json" \
  -d '{"upload_ref":"up_ref_tXk3W2b8Qe7Ra1Nc0","spec_id":"spc_9wTv2c1Kd8Qe"}'

Antwoord · 201

201 · application/json

{
  "object": "photo_session",
  "id": "3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10",
  "livemode": false,
  "status": "preview_ready",
  "spec_id": "spc_9wTv2c1Kd8Qe",
  "preview_url": "https://partner.svoyager.com/v1/photo-sessions/3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10/preview",
  "watermarked": true,
  "issues": [],
  "created_at": "2026-07-24T18: 30: 00Z"
}

Fouten

Status	Code	Wanneer
400	missing_idempotency_key	The `Idempotency-Key` header is missing.
400	missing_upload_ref	`upload_ref` is missing.
400	missing_spec_id	`spec_id` is missing.
400	invalid_upload_ref	The referenced upload could not be read.
413	file_too_large	The uploaded file exceeds 10 MB.
415	unsupported_format	The uploaded file is not an accepted image format.
404	spec_not_found	No active specification matches `spec_id`.
402	no_active_plan	No active plan is assigned for this environment.
402	quota_exceeded	Included preview quota for the period is exhausted.
402	plan_inactive	The plan is not active for this environment.
409	idempotency_key_reuse	The key was reused with a different body.
409	request_in_progress	A request with this key is still processing.
422	unprocessable_image	The image could not be processed.
502	provider_error	The preview could not be generated upstream — retry shortly.
503	provider_busy	The processing service is busy — retry shortly.

Plus de standaardfouten op het gebied van authenticatie, machtigingen en rate-limits — zie Fouten en herpogingen.

GET/v1/photo-sessions/{id}

Retrieve a photo session

Fetch a session by id, including its current status, `preview_url`, and any `issues`.

scope photo.sessions.read

Verzoek

Padparameters

Veld	Type	Beschrijving
id*	string	Session id.

Voorbeeldverzoek

curl

curl "https://partner.svoyager.com/v1/photo-sessions/3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10" \
  -H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx"

Antwoord · 200

200 · application/json

{
  "object": "photo_session",
  "id": "3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10",
  "livemode": false,
  "status": "preview_ready",
  "spec_id": "spc_9wTv2c1Kd8Qe",
  "preview_url": "https://partner.svoyager.com/v1/photo-sessions/3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10/preview",
  "watermarked": true,
  "issues": [],
  "created_at": "2026-07-24T18: 30: 00Z"
}

Fouten

Status	Code	Wanneer
404	session_not_found	No session matches the id for this account/environment.

Plus de standaardfouten op het gebied van authenticatie, machtigingen en rate-limits — zie Fouten en herpogingen.

GET/v1/photo-sessions/{id}/preview

Download the preview image

Stream the watermarked preview image bytes for a session (SVOYAGER-hosted; the upstream URL is never exposed). This is the resource `preview_url` points to.

scope photo.sessions.readGeeft afbeeldingsbytes terug

Verzoek

Padparameters

Veld	Type	Beschrijving
id*	string	Session id.

Returns raw `image/*` bytes on success (not JSON).

Voorbeeldverzoek

curl

curl "https://partner.svoyager.com/v1/photo-sessions/3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10/preview" \
  -H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx" \
  --output preview.jpg

Antwoord · 200

Bij succes stuurt het eindpunt ruwe afbeeldingsbytes (geen JSON). Sla de responsbody op in een bestand.

Fouten

Status	Code	Wanneer
404	preview_not_found	The session or its preview does not exist.

Plus de standaardfouten op het gebied van authenticatie, machtigingen en rate-limits — zie Fouten en herpogingen.

POST/v1/photo-sessions/{id}/finalize

Finalize a photo

Turn a reviewed session into a deliverable order. In live mode this produces the no-watermark final and spends one `final` unit; in test mode it emulates the final from the preview.

scope photo.finalize.write Idempotency-Key vereist

Verzoek

Padparameters

Veld	Type	Beschrijving
id*	string	Session id to finalize.

Voorbeeldverzoek

curl

curl -X POST "https://partner.svoyager.com/v1/photo-sessions/3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10/finalize" \
  -H "Authorization: Bearer svoy_sk_live_A8m4Qz1YOURKEYHERExxxxxxx" \
  -H "Idempotency-Key: a7f3c9e1-2b4d-4c8a-9f10-3e5d6b7a8c9d"

Antwoord · 201Returns 200 with the existing order if the session was already finalized (never double-charged).

201 · application/json

{
  "object": "photo_order",
  "id": "8a2d5b40-71c6-4f0e-b3a9-1e7c9d05f284",
  "livemode": true,
  "sandbox_emulated": false,
  "status": "final_ready",
  "session_id": "3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10",
  "spec_id": "spc_9wTv2c1Kd8Qe",
  "final_url": "https://partner.svoyager.com/v1/orders/8a2d5b40-71c6-4f0e-b3a9-1e7c9d05f284/final",
  "watermarked": false,
  "created_at": "2026-07-24T18: 31: 00Z"
}

Fouten

Status	Code	Wanneer
400	missing_idempotency_key	The `Idempotency-Key` header is missing.
404	session_not_found	No session matches the id for this account/environment.
422	session_not_finalizable	The session is not in a finalizable state.
402	no_active_plan	No active plan is assigned for this environment.
402	quota_exceeded	Included final quota for the period is exhausted.
402	plan_inactive	The plan is not active for this environment.
409	idempotency_key_reuse	The key was reused with a different request.
409	request_in_progress	A request with this key is still processing.
502	provider_error	The final could not be produced upstream — retry shortly.
503	provider_busy	The processing service is busy — retry shortly.

Plus de standaardfouten op het gebied van authenticatie, machtigingen en rate-limits — zie Fouten en herpogingen.

GET/v1/orders/{id}

Retrieve an order

Fetch a finalized order by id, including its status and `final_url` once ready.

scope photo.orders.read

Verzoek

Padparameters

Veld	Type	Beschrijving
id*	string	Order id.

Voorbeeldverzoek

curl

curl "https://partner.svoyager.com/v1/orders/8a2d5b40-71c6-4f0e-b3a9-1e7c9d05f284" \
  -H "Authorization: Bearer svoy_sk_live_A8m4Qz1YOURKEYHERExxxxxxx"

Antwoord · 200

200 · application/json

{
  "object": "photo_order",
  "id": "8a2d5b40-71c6-4f0e-b3a9-1e7c9d05f284",
  "livemode": true,
  "sandbox_emulated": false,
  "status": "final_ready",
  "session_id": "3f9c1e77-2b8a-4a1e-9d2c-6b5a4c3d2e10",
  "spec_id": "spc_9wTv2c1Kd8Qe",
  "final_url": "https://partner.svoyager.com/v1/orders/8a2d5b40-71c6-4f0e-b3a9-1e7c9d05f284/final",
  "watermarked": false,
  "created_at": "2026-07-24T18: 31: 00Z"
}

Fouten

Status	Code	Wanneer
404	order_not_found	No order matches the id for this account/environment.

Plus de standaardfouten op het gebied van authenticatie, machtigingen en rate-limits — zie Fouten en herpogingen.

GET/v1/orders/{id}/final

Download the final image

Stream the final image bytes for an order (SVOYAGER-hosted). In live mode this is the no-watermark deliverable; in test mode it is the sandbox-emulated copy. This is the resource `final_url` points to.

scope photo.orders.readGeeft afbeeldingsbytes terug

Verzoek

Padparameters

Veld	Type	Beschrijving
id*	string	Order id.

Returns raw `image/*` bytes on success (not JSON).

Voorbeeldverzoek

curl

curl "https://partner.svoyager.com/v1/orders/8a2d5b40-71c6-4f0e-b3a9-1e7c9d05f284/final" \
  -H "Authorization: Bearer svoy_sk_live_A8m4Qz1YOURKEYHERExxxxxxx" \
  --output final.jpg

Antwoord · 200

Bij succes stuurt het eindpunt ruwe afbeeldingsbytes (geen JSON). Sla de responsbody op in een bestand.

Fouten

Status	Code	Wanneer
404	final_not_found	The order or its final does not exist.

Plus de standaardfouten op het gebied van authenticatie, machtigingen en rate-limits — zie Fouten en herpogingen.

GET/v1/photo-specifications

List photo specifications

Return a cursor-paginated list of available photo specifications. Filter by country or document type to find the `spec_id` you need.

scope photo.specs.read

Verzoek

Queryparameters

Veld	Type	Beschrijving
limit	integer	Page size, 1–100 (default 20).
starting_after	string	A specification id (`spc_…`) to page after.
country	string	ISO-3166 alpha-2 filter, e.g. `US`.
document_type	string	Filter by document type, e.g. `passport`.

Voorbeeldverzoek

curl

curl -G "https://partner.svoyager.com/v1/photo-specifications" \
  -H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx" \
  --data-urlencode "country=US" \
  --data-urlencode "limit=20"

Antwoord · 200

200 · application/json

{
  "object": "list",
  "data": [
    {
      "object": "photo_specification",
      "id": "spc_9wTv2c1Kd8Qe",
      "name": "United States Passport"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Fouten

Dit eindpunt retourneert uitsluitend de onderstaande standaardfouten.

Plus de standaardfouten op het gebied van authenticatie, machtigingen en rate-limits — zie Fouten en herpogingen.

GET/v1/photo-specifications/{id}

Retrieve a photo specification

Fetch a single specification by its stable `spec_id`, including its full requirements.

scope photo.specs.read

Verzoek

Padparameters

Veld	Type	Beschrijving
id*	string	Specification id (`spc_…`).

Voorbeeldverzoek

curl

curl "https://partner.svoyager.com/v1/photo-specifications/spc_9wTv2c1Kd8Qe" \
  -H "Authorization: Bearer svoy_sk_test_R2p9Kx7YOURKEYHERExxxxxxx"

Antwoord · 200

200 · application/json

{
  "object": "photo_specification",
  "id": "spc_9wTv2c1Kd8Qe",
  "name": "United States Passport",
  "country_code": "US",
  "document_type": "passport",
  "physical_size": {
    "width": 51,
    "height": 51,
    "unit": "mm"
  },
  "pixel_size": {
    "width": 600,
    "height": 600
  },
  "dpi": 300,
  "background": {
    "color": "#FFFFFF",
    "name": "white"
  },
  "requirements": {
    "head_height": "25–35 mm (1–1⅜ in)",
    "eye_to_bottom": "28–35 mm (1⅛–1⅜ in)",
    "recency_months": 6,
    "expression": "neutral",
    "color": true,
    "glasses": "not allowed",
    "eyes_and_ears": "both eyes open"
  },
  "updated_at": "2026-07-01T12: 00: 00Z"
}

Fouten

Status	Code	Wanneer
404	spec_not_found	No active specification matches the id.

Plus de standaardfouten op het gebied van authenticatie, machtigingen en rate-limits — zie Fouten en herpogingen.

Idempotentie en veilige herhalingspogingen

Verzend een Idempotency-Key-header (een unieke waarde, bijvoorbeeld een UUID) zodat een herhaald verzoek nooit dubbel in rekening wordt gebracht of dubbel wordt verwerkt. Dit is vereist bij:

POST /v1/photo-sessions
POST /v1/photo-sessions/{id}/finalize

• Dezelfde sleutel + dezelfde body → het oorspronkelijke resultaat wordt opnieuw weergegeven (geen tweede verwerking, geen tweede weergave).
• Dezelfde sleutel + een andere body → 409 idempotency_key_reuse.
• Bij een herhaalbare fout kun je het opnieuw proberen met dezelfde sleutel, body en upload_ref.
• Gelijktijdige afrondingsverzoeken voor één sessie kunnen nooit twee orders aanmaken of in rekening brengen.

Levenscyclus van sessies en bestellingen

Een sessie doorloopt verschillende preview-statussen; een bestelling doorloopt verschillende afrondingsstatussen.

Sessiestatus

preview_ready — Voorbeeld gegenereerd, geen problemen.
preview_has_issues — Voorbeeld gegenereerd met issues.
preview_failed — Het voorbeeld kon niet worden gegenereerd.
finalized — de sessie is beëindigd.

Bestelstatus

final_ready — De definitieve versie is beschikbaar.
processing — De definitieve versie wordt momenteel voorbereid.
failed — Finalisatie is mislukt.

Test- versus live-omgeving

De omgeving wordt bepaald door het voorvoegsel van je sleutel — clients kunnen dit nooit doorgeven. In de testmodus wordt het echte voorbeeld met watermerk weergegeven, zodat je de daadwerkelijke workflow kunt oefenen, maar de uiteindelijke weergave wordt gesimuleerd, zodat er geen live quota of productierendering wordt gebruikt.

Aspect	Test	Live
livemode	false	true
Voorbeeld	Echt, met watermerk	Echt, met watermerk
Eindversie	Sandbox-emulatie vanuit de preview	Echt, zonder watermerk
sandbox_emulated	true	false
watermarked	true	false
Verbruikt quotum	Alleen testquota	Alleen voor live quota

Quota’s en gebruik

Je abonnement omvat een aantal previews en finals per periode, die apart worden geteld. Het aanmaken van een sessie kost één preview; het afronden kost één final. De quota wordt vóór de verwerking in één keer gereserveerd.

Wanneer het inbegrepen voorbeeld of de definitieve quota is opgebruikt, retourneert het verzoek 402 quota_exceeded.
402 is een harde stop — herhalen zal pas slagen in de volgende periode of na een wijziging van het abonnement.
Test- en live-quota’s staan volledig los van elkaar.

Fouten en herpogingen

Elke fout maakt gebruik van één envelope. De request_id komt ook voor in de X-Request-Id-responsheader — vermeld deze in supportverzoeken.

Error envelope

{
  "error": {
    "type": "invalid_request_error",
    "code": "quota_exceeded",
    "message": "Your included final quota for this period is exhausted.",
    "request_id": "req_9wTv2c1Kd8QeR7"
  }
}

Standaardfouten (alle eindpunten)

Status	Code	Wanneer
401	invalid_api_key	Missing, malformed, or unknown API key.
401	revoked_api_key	The key was revoked.
401	expired_api_key	The key passed its rotation grace period.
401	wrong_environment	A test key was used on live traffic (or vice versa).
403	client_disabled	The API client is disabled.
403	api_access_revoked	API access for the account is not active.
403	insufficient_scope	The key lacks the required scope for this endpoint.
429	rate_limited	Per-key rate limit exceeded. Honour `Retry-After`.

422 wordt alleen geretourneerd bij een bevestigd beeldprobleem. 402 betekent dat de quota is opgebruikt. 409 duidt op een idempotentie- of resource-conflict.

429 betekent dat je de limiet per sleutel hebt bereikt — houd je aan de Retry-After-header. Bij 502/503 en andere 5xx-codes: probeer het opnieuw met backoff en dezelfde Idempotency-Key.

Fotoprobleemcodes

Een preview kan nul of meer problemen opleveren, elk bestaande uit een stable-code + bericht. Geef deze weer aan de eindgebruiker, zodat deze de foto opnieuw kan maken. Een niet-herkend upstream-signaal wordt gedegradeerd naar ‘other’.

Code	Bericht
face_not_found	No face was detected in the photo.
uneven_lighting	Lighting on the face is uneven.
poor_brightness	Face brightness is too dark, too bright, or the photo is low quality.
low_sharpness	The photo is blurry or not sharp enough.
eyeglasses_not_allowed	Eyeglasses are not allowed.
sunglasses_not_allowed	Sunglasses are not allowed.
headwear_not_allowed	Hats or head coverings are not allowed.
face_mask_not_allowed	A face mask is not allowed.
face_covering_found	A face covering was detected.
expression_not_neutral	The expression is not neutral.
crop_bottom	Not enough space is visible below the shoulders.
crop_left	Not enough of the left shoulder is visible.
crop_right	Not enough of the right shoulder is visible.
head_turned	The head is turned too far to the side.
head_tilted	The head is tilted too far up or down.
not_in_color	The photo must be in color.
other	The photo did not meet a requirement.

Bestanden, bewaartermijnen en privacy

• Voorbeelden en definitieve versies worden uitsluitend aangeboden via door SVOYAGER gehoste, geauthenticeerde URL’s. Voor toegang zijn je API-sleutel en de juiste scope vereist — de onderliggende opslag wordt nooit openbaar gemaakt.
• Geüploade afbeeldingen zijn privé en beperkt tot uw account en omgeving; uploaddoelen zijn van korte duur en voor eenmalig gebruik.
• Foto’s uit documenten worden verwerkt om uw resultaat te genereren en worden niet gedeeld tussen accounts.

Zie de voorwaarden van SVOYAGER inzake gegevensverwerking, bewaring en verwijdering:Privacybeleid ·Partnerovereenkomst en voorwaarden

SVOYAGER ID Photo API

Overzicht

Wat het doet

Voorbeeld → definitieve workflow

Snelstart

Basis-URL en omgevingen

Authenticatie

API-sleutels

Toepassingsgebieden

Sleutels veilig bewaren

Eindpunten

Upload a photo

Create a photo session

Retrieve a photo session

Download the preview image

Finalize a photo

Retrieve an order

Download the final image

List photo specifications

Retrieve a photo specification

Idempotentie en veilige herhalingspogingen

Levenscyclus van sessies en bestellingen

Test- versus live-omgeving

Quota’s en gebruik

Fouten en herpogingen

Fotoprobleemcodes

Bestanden, bewaartermijnen en privacy