Skip to content
Developers12 min read

Building Photo Evidence Into Your App: A Developer's Guide

A photo evidence API lets your app open a live capture page, then returns a sealed proof: SHA-256 fingerprints, a qualified timestamp, a C2PA signature and a public verification link. Your server makes one call and receives one webhook.

By Cédric Driaux, Founder of tryVidimus

Drawing of a code window with a photo

What a photo evidence API does, and what you would have to build

Your product already has photos: a vehicle at pickup, a parcel before shipping, a room before a stay. The trouble starts when two parties disagree and each one shows its own files. A photo evidence API turns those photos into proofs that a third party can check without trusting you, your user or the vendor.

Hashing a file is the easy part, and you could write it in an afternoon. What you cannot write is the third party. A date only counts if someone independent certifies it, and a proof only counts if the other side can check it alone.

Building the whole chain yourself means running several things before the first photo holds up:

  • A contract with a qualified trust service for timestamps, plus signing keys, certificate chains and C2PA manifests to buy, run and renew.
  • A camera flow that refuses gallery imports, sends files straight to storage and speaks the language of your users.
  • Originals stored unchanged, a public verification page, and a way to check a proof without trusting your servers.

tryVidimus does this as one API. It works like an e-signature API: create a session, send a link, get a webhook, share a proof anyone can verify.

This guide walks through the architecture, the calls, verification, webhooks, security and the pricing model. For the reasoning behind sealed photos, read our complete guide to photo evidence.

Architecture: the capture never passes through your servers

The design has one rule: the party that might lose a dispute must never hold the file between capture and sealing. That includes you. If your servers relayed the photos, the other side could say you changed them on the way.

  1. Your server calls the API and gets a one-time capture link for a booking or an order.
  2. Your app opens that link. It is a hosted web page with your logo, your color, your texts and the language of the person.
  3. The person takes the photos with the live camera. There is no import from the gallery.
  4. The files go from the phone straight to storage. They never pass through your servers, and they never go through the API either.
  5. The service checks the files, computes a SHA-256 fingerprint per file, signs each photo with C2PA and obtains one qualified electronic timestamp for the proof.
  6. Your server receives a webhook. Anyone with the link can open the public verification page.

The capture page is a web page, not a native component. In a mobile app you open it in a web view and grant the camera to that page only. There is no mobile SDK, and nothing for the person to install.

The timestamp follows RFC 3161. The timestamp authority receives the fingerprint of the proof, never the photos.

In production the authority is Certigna, a French qualified trust service provider, and the timestamp is a qualified one under the eIDAS Regulation. Our guide to photo authenticity standards explains what eIDAS and C2PA each bring.

ComponentWho runs itWhat your code does
Capture sessiontryVidimusOne POST from your server
Capture pagetryVidimus, under your brandOpens a URL in a browser or a web view
File storagetryVidimusNothing: files go there directly from the phone
TimestampAn independent qualified authorityNothing: one token per proof
C2PA signaturetryVidimus, a C2PA conformant generator productNothing: each JPEG photo is signed
VerificationAnyoneShares a link, or runs the open-source verifier

The calls of the journey: one from your server

Integration guides often promise a number of calls. Here is the honest count.

Your server writes one mandatory call. The capture page makes the upload calls itself, and the result comes back by webhook.

CallWho makes itRequired
POST /v1/capture-sessionsYour server, with your API keyYes
Upload links and finalize, on the capture sessionThe hosted capture page, with the session tokenYes, but not by you
GET /v1/proofs/<id>Your server, with your API keyOptional: the webhook carries the essentials
GET /v1/public/proofs/<id>Anyone, without a keyOptional: the public status and timestamp
GET /v1/public/proofs/<id>/bundleAnyone, without a keyOptional: the data for independent verification

Creating a session takes your own reference and the party who captures. The Idempotency-Key header is required, so a retry after a network failure never creates a second session.

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 answer contains capture_url, the link to open, and expires_at. The link works once and expires at the time given in expires_at. The same call in Node.js:

const res = await fetch("https://api.tryvidimus.com/v1/capture-sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRYVIDIMUS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ external_reference: "booking_4471", party: "provider", stage: "pickup" }),
});
const { capture_url } = await res.json();

Optional fields shape the capture. template_id names a capture template: the shots to take and the texts the person sees. locale sets the language of the page, and return_url brings the person back to your app after the last photo, to a site you declared beforehand.

Two proofs of the same transaction can be linked. Capture the first as usual, wait until it is sealed, then create the second session with compare_to set to the identifier of the first proof. The "after" then asks for the same shots as the "before".

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":"return","compare_to":"prf_01m4akapdbe8e8qq3er9r5qwyj"}'

The link is a pointer between two proofs, nothing more. The service does not compare the photos and does not judge the condition of the item. The step-by-step version of this section is our tutorial on how to add sealed photo capture to your app in four steps.

Verification: a proof anyone can check

A proof that only you can confirm is your word. So verification is public by design, at three levels.

  • A public verification page per proof, open without an account. Its address comes in the verify_url field of the webhook. It shows the status of the proof, the certified time next to the observed time, and what the proof does and does not show.
  • Two public routes, without an API key. One returns the status and the timestamp. The other returns the verification bundle: the fingerprints and the RFC 3161 timestamp token.
  • An open-source verifier under the MIT licence, published on npm. It recomputes the fingerprints and checks the timestamp on its own, without trusting our servers.

The public routes never return the files, the name of your organization or your external reference. A person who holds a proof identifier learns that a proof exists and when it was timestamped, not what your business is.

Two dates appear on a proof, and they are never mixed up. captured_at, on each file, is the time the service observed the file: it is not qualified. gen_time, on the timestamp, is the time certified by the authority: the proof existed at the latest at that time.

The timestamp can be checked with OpenSSL alone, from the bundle. This is the command given in the API reference:

openssl ts -verify -digest <manifest_sha256> -in proof.tsr -CAfile chain.pem

Each signed photo also embeds a C2PA manifest that Content Credentials tools can read. tryVidimus is a C2PA conformant generator product for JPEG photos, at assurance level 1, under a conformance letter dated 19 October 2026. The full walk-through is in our article on how to verify a sealed photo programmatically.

Webhooks: knowing when a proof is sealed

Sealing happens a few seconds after the capture, on a phone you do not control. Instead of polling, declare an HTTPS endpoint and choose the events you want.

EventMeaning
capture_session.completedThe person has finished and the files are saved. The proof is not sealed yet.
proof.sealedThe proof is signed and timestamped. It can be read and verified by anyone.
proof.failedThe proof could not be sealed. The body says why, and whether the failure can be run again.
capture_session.rejectedAn "after" capture was refused because another one already completed the same "before".

Every delivery is signed. The X-Signature header carries a timestamp and an HMAC-SHA256 of the raw body, keyed with the secret of your endpoint. The X-Event-Id header is identical across retries, so your handler can ignore duplicates.

If your server does not answer with a 2xx status, the delivery is retried several times over the following hours, then abandoned. A delivery log shows what was sent and what your server answered, and a test route sends a signed example event to your endpoint.

One rule saves a lot of support tickets: never rely on the redirection at the end of the capture. The person can close the page before it happens. The webhook is the reliable signal, and our guide to photo evidence webhooks gives the signature code and a working receiver.

Security and data residency (EU)

A proof system is only as credible as its access rules. These are the ones you work with as an integrator.

  • API keys carry scopes. create_proof creates capture sessions, read_proof reads proofs, manage_webhooks manages endpoints, manage_templates manages templates and themes, and manage_settings manages your settings. A call without the right scope fails with 403 insufficient_scope.
  • Test and live never share data. The prefix of the key sets the mode: sk_test_ for the sandbox, sk_live_ for production. A test key never sees a live proof.
  • The key stays on your server. Your app receives the capture_url alone, which works once and expires.
  • A capture link cannot send a person to a site you did not choose. A return_url is refused unless its site is in the list you declared.
  • Webhook secrets are shown once, at creation or rotation. Rotation keeps the old secret valid for a while, so you switch without losing a call.
  • Signed copies are downloaded through temporary links. The public routes never return files.

On data residency, two facts matter for your own privacy documentation. tryVidimus is hosted in the European Union. Live proofs and their files are kept for 24 months.

The timestamp authority is not a place where your photos go. It receives a fingerprint, which reveals nothing about the image. The same holds for the public bundle: it carries hashes and a timestamp token, and a cryptographic commitment in place of your external reference.

Two operational details complete the picture. Each key has a rate limit, and a call past the limit gets a 429 answer with a Retry-After header. Errors follow RFC 9457: branch on the code field, which is stable, never on the title.

Tools and packages

You do not need a library. The API is plain JSON over HTTPS, every route lives under /v1, and the contract is a published OpenAPI 3.1 schema. Any generator that supports that version can produce a client for your language.

For those who want them, five packages are published on npm under the MIT licence. They need Node.js 22 or later.

npm install -g @tryvidimus/cli             # the command line
npx -y @tryvidimus/mcp                     # the MCP server
npm install @tryvidimus/api-client         # the typed TypeScript client
npm install @tryvidimus/verifier           # verify a proof without our servers
npm install @tryvidimus/proof-primitives   # the building blocks of the verifier
  • The command line opens a capture, follows proofs, verifies one and manages webhooks, from a terminal or in CI.
  • The MCP server gives an assistant tools to open a capture and read proofs. Our page on using the API with Claude shows the setup.
  • The typed client and the verification libraries are for TypeScript projects. None of them is a mobile SDK.

The developer page gathers these tools, and the documentation has the guides: capture templates and languages, before and after, return to your app, mobile apps.

Pricing model

The model is simple enough to explain to a finance team. You pay per sealed proof, from a prepaid balance. There is no subscription and no monthly minimum.

  • Test mode is free. It gives the full API with simulated timestamps, and nothing is billed.
  • In production, a proof is debited when it is sealed. A proof that fails is not.
  • A proof holds all the photos of one capture, and receives one timestamp.
  • With a live key, a new session is refused with 402 insufficient_balance when the balance cannot cover one more proof. A capture already started always finishes.
  • Balance and usage can be read through the API, so you can alert before the balance runs low.

The price is on the pricing page. If you are comparing vendors, our 10-point checklist for choosing a photo evidence API lists the questions to ask each one, including us.

Where this fits in a business is another question. Rental, delivery, claims and inspections are covered in our overview of photo evidence use cases.

Frequently asked questions

Do I need an SDK to use a photo evidence API?

No. The API is plain JSON over HTTPS and its OpenAPI schema is public, so you can call it directly or generate a client in your language. A typed TypeScript client, a command line, an MCP server and verification libraries are published on npm as packages. There is no native mobile SDK: the capture page is a web page.

Does it work in a mobile app?

Yes. Your app opens the capture page in a web view and gives it the camera. Your server creates the capture session and hands the app the capture link alone, so the API key never lives in the app. The documentation has a guide for iOS and Android, including how to bring the person back to your app.

Do the photos go through my servers?

No. They go straight from the phone to storage. Your server only creates the capture session and reads the proof. This is a design choice, not a shortcut: a platform that never holds the files between capture and sealing cannot be accused of having changed them. You download signed copies afterwards, through temporary links.

What is the difference between test and live?

The key decides. A test key, which starts with sk_test_, gives the full API with simulated timestamps: free, and with no legal value. A live key, which starts with sk_live_, seals proofs with a qualified eIDAS timestamp, debited from your balance. The two modes never share data, and your code is the same in both.

How can someone check a proof without trusting the vendor?

With the public bundle and open tools. The bundle of a sealed proof is served without an API key and contains the fingerprints and the RFC 3161 timestamp token. The open-source verifier recomputes the fingerprints and checks the timestamp on its own, and OpenSSL can verify the token against the certificate chain of the authority.

Where is the data hosted, and for how long?

tryVidimus is hosted in the European Union, and live proofs and their files are kept for 24 months. The timestamp authority receives the fingerprint of the proof, never the photos. The public verification routes never return the files, the name of your organization or your external reference. The documentation remains the reference for details.

Try it in the sandbox

A photo evidence API replaces a chain you would otherwise build and run yourself: live capture, an independent timestamp, a signature and public verification. On your side it is one call, one webhook and a link to share. 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