Skip to content
Developers7 min read

Add Tamper-Proof Photo Capture to Your App: One API Call, Four Steps

A tamper-proof photo capture API needs one call from your server. You create a capture session, open the link it returns, wait for the proof.sealed webhook, then share the public verification link. The capture page does the rest.

By Cédric Driaux, Founder of tryVidimus

Drawing of a code window with a photo

What you will build

This tutorial adds sealed photo capture to an existing product: a booking app, a claims tool, a delivery back office. It is the hands-on companion to our developer guide to the photo evidence API, which explains the architecture and the choices behind it.

The journey has four steps, but your server writes only one API call. The capture page, hosted by tryVidimus, makes the upload calls itself. The sealed proof then comes to you by webhook.

StepWho actsWhat happens
1. Create a capture sessionYour serverPOST /v1/capture-sessions returns a capture_url.
2. Open the capture pageYour app and the personThe person takes the photos live, in the browser or in a web view.
3. Receive the sealed prooftryVidimus, then your serverYou receive the proof.sealed webhook, or you read the proof with your key.
4. Share the verification linkAnyoneThe public page shows the status of the proof and its timestamp, without an account.

Prerequisites

  • An account. Test mode is free and needs no card.
  • A test key, created in your dashboard under API keys. It starts with sk_test_. Keep it in an environment variable, never in source code.
  • The create_proof scope on that key to create capture sessions, and read_proof to read proofs.
  • A server that can receive an HTTPS call, for the webhook. A script that polls the proof is enough for a first try.
  • A real phone. The capture page uses the live camera, and simulators have none.

No library is required: the API is plain JSON over HTTPS. If you prefer a terminal, the command line runs the same calls. The packages are on npm under the MIT licence.

npm install -g @tryvidimus/cli
tryvidimus login
tryvidimus sessions create --reference booking_4471 --party provider --stage pickup
tryvidimus proofs list --reference booking_4471

Step 1: create a capture session (the API call)

A capture session is a one-time link for one transaction. You give your own identifier in external_reference (a booking, an order, a claim) and say who takes the photos in party: provider or recipient. The stage field is optional and free: pickup, return, delivery.

curl -X POST https://api.tryvidimus.com/v1/capture-sessions \
  -H "Authorization: Bearer $TRYVIDIMUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"external_reference":"booking_4471","party":"provider","stage":"pickup"}'

The Idempotency-Key header is required. If the call fails on the network, send it again with the same key: you get the original answer instead of a second session. The answer carries the link to open.

{
  "id": "cps_01m4akapdbe8e8qq3er9r5qwyj",
  "capture_url": "https://capture.tryvidimus.com/3f9aXq…",
  "expires_at": "2026-10-07T12:00:00.000Z",
  "mode": "test",
  "compare_to": null
}

The link works once and expires at the time given in expires_at. Create it when the person is ready to capture, not the day before. Optional fields choose a capture template (template_id), the language of the page (locale) and the address the person returns to at the end (return_url).

Step 2: open the branded capture page

Send capture_url to the person, or open it from your app. It is a web page with your logo, your color and your texts. There is nothing to install and no native SDK.

  • In a browser: send the link by SMS, e-mail or QR code. The person opens it on their phone.
  • In a mobile app: open the link in a web view and grant the camera to the capture page only. The documentation has a guide for iOS and Android.
  • In both cases the camera is the only source. The page refuses imports from the gallery.

Your server creates the session and hands the app the capture_url alone. The API key never lives in the app. The files go from the phone straight to storage, so they never pass through your servers.

Step 3: receive the sealed proof

When the person finishes, tryVidimus checks the files, signs each photo (C2PA) and obtains a timestamp for the proof. This usually takes a few seconds. Your server is told by the proof.sealed event.

{
  "event": "proof.sealed",
  "proof_id": "prf_01m4akapdbe8e8qq3er9r5qwyj",
  "external_reference": "booking_4471",
  "party": "provider",
  "stage": "pickup",
  "status": "sealed",
  "sealed_at": "2026-10-13T15:48:12.000Z",
  "verify_url": "https://verify.tryvidimus.com/prf_01m4akapdbe8e8qq3er9r5qwyj"
}

Match external_reference to your booking and store proof_id and verify_url next to it. Declaring the endpoint and checking the signature are covered in our guide to photo evidence webhooks. Without a webhook, read the proof with your key until its status is sealed.

curl https://api.tryvidimus.com/v1/proofs/prf_01m4akapdbe8e8qq3er9r5qwyj \
  -H "Authorization: Bearer $TRYVIDIMUS_API_KEY"

A proof goes through pending and processing, and ends as sealed or failed. Each file carries its SHA-256 fingerprints and a captured_at time. That time is the one our service observed: it is not qualified, and only the timestamp of the proof certifies a date.

Testing in the sandbox

A test key gives the full API. Nothing is billed, and test data never mixes with live data: a test key that asks for a live proof gets a 404.

  • Run the whole journey on a real phone, on iOS and on Android if you ship both.
  • Let a link expire and check what your app shows.
  • Send the creation call twice with the same Idempotency-Key and check that you get one session.
  • Close the capture page before the end and check that your app waits for the webhook, not for the redirection.

Going live

Going live is a change of key. A live key starts with sk_live_, and each proof it seals receives a qualified electronic timestamp under eIDAS, issued by Certigna, a French qualified trust service provider. Your code stays the same.

  • Declare a live webhook endpoint: an endpoint belongs to the mode of the key that created it.
  • Recreate your capture templates with the live key. Test and live templates are separate.
  • Handle the 402 insufficient_balance answer: with a live key, a session is refused when your balance cannot cover one more proof.
  • Keep the live key on your server only, with the scopes it needs and no more.

Each sealed proof is debited from a prepaid balance. The price is on the pricing page. The documentation lists every route, field and error.

Frequently asked questions

How many API calls does the integration really need?

One from your server: POST /v1/capture-sessions, which returns the capture link. The capture page makes the upload calls itself, and the sealed proof reaches you through the proof.sealed webhook. Reading the proof and reading its public status are optional calls. Declaring the webhook endpoint is done once, by API or from your account.

Do the photos pass through my servers?

No. The files go from the phone straight to storage. Your server only creates the capture session and reads the proof. This also helps the proof: since you never hold the files between capture and sealing, nobody can say you changed them on the way. You download signed copies later, through temporary links.

Can users upload a photo from their gallery?

No. The capture page accepts the live camera only, and this is a deliberate limit. Once a photo can come from the camera roll, it can come from another day, another object or an editing app. A timestamp on such a file would only show that the file existed when it was stamped.

Does this work inside an iOS or Android app?

Yes. The capture page is a web page: your app opens it in a web view and gives it the camera. There is no native SDK to install. The documentation has a guide for iOS and Android, with the permission settings and the way to bring the person back to your app after the last photo.

What happens if the person closes the page before the end?

Nothing is sealed until the capture is finished. Rely on the capture_session.completed event to know that a capture is over, and on proof.sealed before using the proof. Do not rely on the redirection alone, since the person can close the page before it happens. A link that was never used simply expires.

Try it in the sandbox

A tamper-proof photo capture API comes down to one call from your server, a hosted capture page and a webhook. The proof that comes back can be checked by anyone, with or without us. You can build and test the whole journey for free in the sandbox, without a card.

Create an account

Official sources

Cédric Driaux · Founder of tryVidimus

Cédric Driaux is the founder of tryVidimus, published by Fyher. He has been a software developer for 23 years. He also builds ScanStay, a photo proof tool for short-term rental hosts.

Related articles

Developers

How to Verify a Sealed Photo Programmatically

To verify photo authenticity programmatically, fetch the public bundle of the proof, recompute the SHA-256 fingerprint of the file you hold, and check the RFC 3161 timestamp token. The open-source verifier does it without trusting our servers.

7 min read