PCIFIC PixelTrace

Which photos PixelTrace compares against

Live PixelTrace groups only take photos from the seller's phone camera, in iPhone Safari or Android Chrome, so arrange a person with a phone first. Opening the link on a computer does not use it up. Test keys can upload and confirm with test-photos and test-confirm.

PixelTrace compares submitted photos against photos taken with the PixelTrace camera and published. Photos uploaded from a phone gallery or an existing catalogue cannot be published to a live group, so they never become one of your published photos. Photos a test key uploads stay in test groups and only match other test groups. That is by design: if businesses could register their own photos, anyone could claim stock photos as theirs. Sending such a photo to the check address can still show that it is a copy of a published camera photo.

Browser-only capture is submitted evidence. Its trust level is at most normal, never strong. Public badges say PixelTrace submitted evidence; demo badges say PixelTrace demo evidence. The signature covers the ordered photos, file fingerprints and trust levels, not proof of camera hardware.

PixelTrace lets a seller take a listing's photos on their own phone through a PCIFIC camera page, checks each photo for signs it was taken live, and finds photos that were used in this business before.

What a result means, and what it does not

• PixelTrace cannot prove where a photo came from. No web page can. Someone with a modified browser can fake every sign the camera page records, and a real phone pointed at a screen or a printed photo can pass every check. A trust level is evidence, not proof that a camera produced the pixels.
• The signed record proves something narrower: the photos, their order and their trust levels have not changed since the seller confirmed them.
• A match means a similar photo was registered before. It can indicate image reuse; it is not, by itself, proof of who owns the photo, of fraud or of wrongdoing. Treat it as a cue for a person to review.
• Matching compares submitted photos against photos taken with the PixelTrace camera and published inside this shop. Its photos are never shared with, or matched for, any other shop. PixelTrace will not detect photos copied from elsewhere. A result of no_match does not prove a photo is original.
• For captures, send ?marketplaceId=<id> on POST /api/v1/pixel-trace/captures and every API-key call for the group. Camera links keep its shop. Hosted embeds are not available yet.
• A test key and a live key never see each other's groups or matches.

How you can use it

Before you start

• An API key (a secret password your server sends with each request) with the "Take and check photos with PixelTrace" permission (pixel-trace). Test keys take the permissions you tick, so tick that one. Read API keys and permissions first.
• Use a test key while you build. Its groups are separate from live ones and spend no credits. A live key spends credits when you start a group or check a photo, and requires a live key activated by you on the API keys page.
• PixelTrace must be on for your account (it is on by default). While it is off, starting a group or checking a photo is refused with PIXEL_TRACE_TURNED_OFF.
• Your server makes every call. Never put the key in a web page or a mobile app.
• A way to give the seller the camera link: a QR code (a square picture a phone scans) on a computer screen, or the link in a message or email. Nothing for the camera itself needs building: PCIFIC hosts it, in Safari on iPhone and Chrome on Android.
• Settings you may want to set first (listed next).

Set these on the dashboard, or with a test key that has the settings permission. The Shop configuration page has the full tables.

• minPhotos: how many photos a seller must take before they can confirm (1 to 12, default 1).
• captureMinutes: how long the seller has once they open the link (5 to 120, default 30).
• openWithinMinutes: how long the link waits to be opened (5 to 10,080, default 15 minutes for live listings).
• For do-it-later links, use a test key with the settings permission to PUT {"openWithinMinutes": 1440} to /api/v1/pixel-trace/settings?marketplaceId=<shop id> for one day. Any whole number from 5 to 10080 is allowed. The saved shop setting applies to new links. Existing saved lifetimes stay in place. The photo session still lasts 30 minutes by default, and confirmed groups must still be published within 1 day.
• photoSize: the longest side of each photo in pixels (1080, 1440, 1920 or 2560, default 1440).
• keepPhotos: true keeps photo files until you retract the group. false deletes the files when you publish and keeps only fingerprints, hashes and the checks (default true).
• publicLevels: which match levels the public certificate may show (none by default, so a certificate never says a photo was used before unless you choose).
• codePrefix: the 2 to 5 letters your codes start with (PCF by default).
• enabled: PixelTrace on or off (default on). While off, new groups and checks are refused.

How it works

A group's status moves capturing, ready, completed and, if you take it back, retracted. A capturing group can also move straight to retracted when cancelled. A group that is never confirmed, or confirmed and never published, is deleted when its time runs out.

Quickstart

Every call needs your key in the Authorization header. These examples use a test key kept in $PCIFIC_TEST_KEY.

Step 1: start a group

curl -X POST https://business.pcific.ai/api/v1/pixel-trace/captures \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"listingId":"listing-123","listingTitle":"Blue denim jacket"}'

{
  "id": "7d1c5e0a-3b64-4f43-9d71-2f5a9c0e8b11",
  "status": "capturing",
  "code": "PCF-IMG-K7M2QX-R4TN9B",
  "cameraUrl": "https://business.pcific.ai/pixel-trace/capture?c=7d1c5e0a-3b64-4f43-9d71-2f5a9c0e8b11#t=<the ticket>",
  "expiresAt": "2026-10-20T13:55:02.118203Z",
  "captureMinutes": 30,
  "minPhotos": 1,
  "maxPhotos": 12
}

Send the seller cameraUrl. Keep id: you need it to read, publish and retract the group. The code is already final, so you can store it now. expiresAt is when the link stops working if nobody opens it. Opening it starts the seller's own captureMinutes.

Step 2: wait for the seller

curl -X GET https://business.pcific.ai/api/v1/pixel-trace/captures/7d1c5e0a-3b64-4f43-9d71-2f5a9c0e8b11 \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY"

{
  "id": "7d1c5e0a-3b64-4f43-9d71-2f5a9c0e8b11",
  "status": "ready",
  "code": "PCF-IMG-K7M2QX-R4TN9B",
  "listingId": "listing-123",
  "listingTitle": "Blue denim jacket",
  "test": true,
  "demo": false,
  "createdAt": "2026-10-19T13:55:02.118203Z",
  "expiresAt": "2026-10-20T14:02:11.482913Z",
  "sealedAt": "2026-10-19T14:02:11.482913Z",
  "publishedAt": null,
  "certificateUrl": null,
  "badgeUrl": null,
  "camera": {
    "opened": true,
    "openedAt": "2026-10-19T13:58:40.907112Z",
    "device": {
      "userAgent": "Mozilla/5.0 (iPhone; ...)",
      "touchPoints": 5,
      "coarsePointer": true
    },
    "refusedOpens": 0
  },
  "trust": {
    "strong": 0,
    "normal": 1,
    "weak": 0
  },
  "photos": [
    {
      "id": "0b6f3a52-91c8-4d0e-a3f4-6c21d8e7b9a0",
      "position": 0,
      "width": 1440,
      "height": 1080,
      "bytes": 412331,
      "sha256": "9f2b6c1e0d4a7385b1c9e2f06a4d83715bc0e9d2a64f1837c5b09e2d4a6f1c83",
      "trust": "normal",
      "checks": [
        {
          "check": "real_tap",
          "outcome": "pass",
          "detail": "The shutter was pressed by a finger on the screen (contact 14 by 14)."
        },
        {
          "check": "phone",
          "outcome": "pass",
          "detail": "The camera page ran in a phone browser with a touch screen."
        }
      ],
      "matches": null,
      "files": {
        "preview": "https://files.example/preview?signature=...",
        "photo": "https://files.example/photo.jpg?signature=..."
      }
    }
  ],
  "manifest": "{\"version\":1,\"test\":true,\"code\":\"PCF-IMG-K7M2QX-R4TN9B\",\"group\":\"7d1c5e0a-3b64-4f43-9d71-2f5a9c0e8b11\",\"listingId\":\"listing-123\",\"sealedAt\":\"2026-10-19T14:02:11.482913+00:00\",\"photos\":[{\"id\":\"0b6f3a52-91c8-4d0e-a3f4-6c21d8e7b9a0\",\"position\":0,\"sha256\":\"9f2b6c1e0d4a7385b1c9e2f06a4d83715bc0e9d2a64f1837c5b09e2d4a6f1c83\",\"trust\":\"normal\"}]}",
  "signature": "Qm9n...base64url...",
  "keyId": "test"
}

The example is shortened: a real photo lists all eight checks, and the file links are long. While status is capturing, the photos listed so far are the ones saved. Do not publish before status is ready. photos[].files.photo is a link to the stored JPEG that works for 10 minutes, so you can download it and compare its hash with sha256.

Step 3: publish when the listing is live

curl -X POST https://business.pcific.ai/api/v1/pixel-trace/captures/7d1c5e0a-3b64-4f43-9d71-2f5a9c0e8b11/complete \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"marketplaceName": "Bramble", "listingUrl": "https://bramble.example/listing-123"}'

{
  "id": "7d1c5e0a-3b64-4f43-9d71-2f5a9c0e8b11",
  "status": "completed",
  "code": "PCF-IMG-K7M2QX-R4TN9B",
  "listingId": "listing-123",
  "listingTitle": "Blue denim jacket",
  "test": true,
  "demo": false,
  "createdAt": "2026-10-19T13:55:02.118203Z",
  "expiresAt": null,
  "sealedAt": "2026-10-19T14:02:11.482913Z",
  "publishedAt": "2026-10-19T14:20:45.330118Z",
  "certificateUrl": "https://business.pcific.ai/pixel-trace/certificates/PCF-IMG-K7M2QX-R4TN9B",
  "badgeUrl": "https://business.pcific.ai/api/v1/pixel-trace/certificates/PCF-IMG-K7M2QX-R4TN9B/badge.svg",
  "camera": {
    "opened": true,
    "openedAt": "2026-10-19T13:58:40.907112Z",
    "device": {
      "userAgent": "Mozilla/5.0 (iPhone; ...)",
      "touchPoints": 5,
      "coarsePointer": true
    },
    "refusedOpens": 0
  },
  "trust": {
    "strong": 0,
    "normal": 1,
    "weak": 0
  },
  "photos": [
    {
      "id": "0b6f3a52-91c8-4d0e-a3f4-6c21d8e7b9a0",
      "position": 0,
      "width": 1440,
      "height": 1080,
      "bytes": 412331,
      "sha256": "9f2b6c1e0d4a7385b1c9e2f06a4d83715bc0e9d2a64f1837c5b09e2d4a6f1c83",
      "trust": "normal",
      "checks": [
        {
          "check": "real_tap",
          "outcome": "pass",
          "detail": "The shutter was pressed by a finger on the screen (contact 14 by 14)."
        },
        {
          "check": "phone",
          "outcome": "pass",
          "detail": "The camera page ran in a phone browser with a touch screen."
        }
      ],
      "matches": {
        "level": "same_photo",
        "message": "This is the same photo as one published before.",
        "found": [
          {
            "level": "same_photo",
            "distance": 0,
            "code": "PCF-IMG-H3RWD8-N6VKA2",
            "photoId": "c41e7d90-5a2b-4e86-b0f3-8d19a6c2e754",
            "marketplaceName": "Bramble",
            "listingUrl": "https://bramble.example/listing-88",
            "preview": "https://files.example/preview?signature=..."
          }
        ]
      },
      "files": {
        "preview": "https://files.example/preview?signature=...",
        "photo": "https://files.example/photo.jpg?signature=..."
      }
    }
  ],
  "manifest": "{\"version\":1,\"test\":true,\"code\":\"PCF-IMG-K7M2QX-R4TN9B\",\"group\":\"7d1c5e0a-3b64-4f43-9d71-2f5a9c0e8b11\",\"listingId\":\"listing-123\",\"sealedAt\":\"2026-10-19T14:02:11.482913+00:00\",\"photos\":[{\"id\":\"0b6f3a52-91c8-4d0e-a3f4-6c21d8e7b9a0\",\"position\":0,\"sha256\":\"9f2b6c1e0d4a7385b1c9e2f06a4d83715bc0e9d2a64f1837c5b09e2d4a6f1c83\",\"trust\":\"normal\"}]}",
  "signature": "Qm9n...base64url...",
  "keyId": "test"
}

Here the photo matched one from an earlier listing. photos[].matches.level is the strongest match for that photo, and found lists up to 10 of them. Send the result to a person who looks at both photos. Publishing the same group again returns the same answer and finishes any photo that was not compared yet, so it is safe to retry. Send an Idempotency-Key header too.

Step 4: show the certificate

<a href="https://business.pcific.ai/pixel-trace/certificates/PCF-IMG-K7M2QX-R4TN9B"><img src="https://business.pcific.ai/api/v1/pixel-trace/certificates/PCF-IMG-K7M2QX-R4TN9B/badge.svg" alt="PixelTrace submitted evidence"></a>

curl https://business.pcific.ai/api/v1/pixel-trace/certificates/PCF-IMG-K7M2QX-R4TN9B

The certificate shows the listing, each photo's preview, trust level and checks, and the signed manifest. A match level appears on it only if the level is in your publicLevels setting (none are by default). A group made with a test key has a certificate too, and the page and the badge say it is a test. After a retraction, a previously published certificate says the group was retracted and its badge shows a cross. An unpublished group never gets a public certificate or badge.

Step 5: take a group back

curl -X POST https://business.pcific.ai/api/v1/pixel-trace/captures/7d1c5e0a-3b64-4f43-9d71-2f5a9c0e8b11/retract \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY"

Cancel a capturing group or take back a ready or published group with this call: its fingerprints leave the search, its photo files are deleted and status becomes retracted. Calling it again is safe. Its camera link immediately closes and refuses further photos with a cancellation message. Before confirming, the seller can also choose Cancel photo group below the camera page's photo controls. Starting a credit-billed live group is charged. Cancel or let it expire before any photo is accepted and processed by the server (checked, fingerprinted and stored), and the full creation charge is refunded. Once any photo was processed, or the group was confirmed, published or matched, there is no refund, even if all photos were deleted or the seller switched phones. The cancel response includes refunded (true/false) and refundReason in plain words. Test keys and unlimited accounts change no credits. Automatic refunds apply only to groups created after this fix; older live groups need PCIFIC support: contact support@pcific.co.uk with the group id for a refund review. Refunds restore the balance shown on Usage and GET /api/v1/usage, but original requests and gross spend still count toward rate limits, usage totals and spending limits.

Check one photo

curl -X POST https://business.pcific.ai/api/v1/pixel-trace/check \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

{
  "level": "same_photo",
  "message": "This is the same photo as one published before.",
  "matches": [
    {
      "level": "same_photo",
      "distance": 0,
      "code": "PCF-IMG-H3RWD8-N6VKA2",
      "photoId": "c41e7d90-5a2b-4e86-b0f3-8d19a6c2e754",
      "marketplaceName": "Bramble",
      "listingUrl": "https://bramble.example/listing-88",
      "preview": "https://files.example/preview?signature=..."
    }
  ],
  "searched": "this shop only, same key kind (test or live)"
}

{
  "level": "no_match",
  "message": "No published photo matches this one.",
  "matches": [],
  "searched": "this shop only, same key kind (test or live)"
}

Set the Content-Type to image/jpeg, image/png, image/webp. curl's --data-binary alone sends a form content type, which makes the bytes unreadable on the way, so always add the header. With the Node fetch function, pass the file's bytes (a Buffer) as the body.

Verify the signed record

Test and live certificates use independent signing keys. Test key IDs are test and test-YYYY-MM-DD; production IDs are pixel-trace-1 and pixel-trace-YYYY-MM-DD. Both are published at the same JWKS address, with no shared key material. New signed manifests include test: true or test: false. For production, use the example with --production: it requires a production key and the signed test: false flag. For a test integration, use --test. Changing the outer test or keyId fields cannot change the signed environment.

Older certificates, including test certificates signed with a production key before this fix, keep their original signed text and signature. Their key stays published while the group exists, unless it leaks. Run the example without an environment option to check that legacy signature. It reports that there is no signed environment, so it confirms only who signed the text. Older records have no signed test flag and must be rejected for production use, even if the outer test field says false. Fetch the public certificate to see its test label, or create a new capture with the intended API key for a record with a signed environment. Existing test groups still expire 24 hours after they start.

When the seller confirms, PCIFIC signs the manifest with its private key (Ed25519 is the kind of signature). The group and the certificate both return three things: manifest (the exact signed text), signature (base64url, a URL-safe form of base64) and keyId. PCIFIC publishes the matching public key at https://business.pcific.ai/.well-known/jwks.json, as a JWKS (a list of public keys). Each key's x value is the key and its kid is its name, which a record carries as keyId: pixel-trace-1 for the first key, then pixel-trace- and the day a later key was added, like pixel-trace-2026-10-22. The newest key in the matching environment signs new records, and an older key stays in the list while records it signed are kept, so always pick the key by kid, never the first in the list. If a key ever leaks, PCIFIC stops publishing it and signs its records again with the newest key for each group's environment: read the group or certificate again for its new signature and keyId.

• Take the manifest string exactly as returned. Do not parse it and write it out again: one changed space breaks the check.
• Fetch the JWKS and pick the key whose kid equals keyId.
• Check the signature (base64url) over the manifest's UTF-8 bytes with the Ed25519 key built from x.
• A valid result means PCIFIC signed exactly this text, so the code, listing, photo order, file hashes and trust levels are as they were when the seller confirmed. It does not prove where the photos came from.

// verify-pixeltrace.mjs. Run: node verify-pixeltrace.mjs group.json [--production|--test]
import { createPublicKey, verify } from "node:crypto";
import { readFile } from "node:fs/promises";

const group = JSON.parse(await readFile(process.argv[2], "utf8"));
const { keys } = await (await fetch("https://business.pcific.ai/.well-known/jwks.json")).json();
const jwk = keys.find((key) => key.kid === group.keyId);

if (!jwk) throw new Error("PCIFIC publishes no key called " + group.keyId + ". Fetch the certificate again for its current keyId and signature.");

const publicKey = createPublicKey({ key: jwk, format: "jwk" });
const signature = Buffer.from(group.signature, "base64url");
// The manifest is text. Check it exactly as it came, never parse it and write it again.
const signed = verify(null, Buffer.from(group.manifest, "utf8"), publicKey, signature);
const manifest = JSON.parse(group.manifest);
const testKey = jwk.kid === "test" || jwk.kid.startsWith("test-");
const mode = process.argv[3];
if (mode && !["--production", "--test"].includes(mode)) throw new Error("Unknown verification mode. Use --production for live records or --test for test records.");
const environmentMatches = mode === "--production" ? manifest.test === false && !testKey : mode === "--test" ? manifest.test === true && testKey : true;
const valid = signed && environmentMatches;

console.log(valid ? "Valid: PCIFIC signed exactly this manifest." : "NOT valid: do not trust this record. Fetch the certificate again and check its signature with the current published key.");
if (signed && !environmentMatches) console.log("Wrong signing environment for " + mode + ": the signing key and signed test flag on this certificate do not match this mode. Fetch a new certificate made with the intended API key.");
if (valid) console.log(manifest.test === true ? "Test certificate, never use as production evidence." : manifest.test === false && !testKey ? "Production certificate." : "Legacy signature only: no signed environment. Reject for production use.");
process.exitCode = valid ? 0 : 1;

curl https://business.pcific.ai/api/v1/pixel-trace/certificates/PCF-IMG-K7M2QX-R4TN9B > group.json
node verify-pixeltrace.mjs group.json

Request fields

Reading a group (GET /api/v1/pixel-trace/captures/{id}) and retracting it (POST .../retract) take no body. Settings are changed with GET and PUT /api/v1/pixel-trace/settings, which needs a test key with the settings permission or the dashboard: a live key can read settings but never change them.

Response fields

Each level comes from how close two photos' fingerprints are, so the same photo shrunk, cropped, turned, tilted or brightened is still found. Some edited copies are missed, and an unrelated photo can occasionally look similar, so a person always decides. A group is never matched with itself, and only published groups are searched.

• strong: reserved for future independently attested captures. Browser-only evidence never receives this level.
• normal: the highest level for browser-only submitted evidence, including when every check passed. Nothing failed, and at most one check could not be done. Many sellers do not allow motion. Without motion readings the two motion checks count as one check not done, so the photo can still be normal.
• weak: any check failed, or more than one could not be done.
• A weak photo is still saved and shown. The level is information for you, not a refusal.

Other things you can do

• Read a group again at any time: GET /api/v1/pixel-trace/captures/{id}. Test keys see only test groups and live keys only live groups.
• Publish again if an answer was lost: the same group returns the same answer.
• Test without a phone: with a test key, upload JPEG, PNG or WebP photos to a test group with POST /api/v1/pixel-trace/captures/{id}/test-photos (the photo's bytes, Content-Type image/jpeg, image/png or image/webp), then confirm it with POST /api/v1/pixel-trace/captures/{id}/test-confirm. Each photo is marked weak with the check test_upload. A live key is refused, and a test key never reaches a live group. A business holds at most 200 test photos and 50 test groups at once; retracting a test group frees its room, and test groups are deleted 24 hours after they start.
• Retract a group when its listing is removed: POST /api/v1/pixel-trace/captures/{id}/retract.
• Read a public certificate: GET /api/v1/pixel-trace/certificates/{code}, in any letter case, with no key. The badge is at .../certificates/{code}/badge.svg.
• Get the public keys: GET /.well-known/jwks.json, with no key. Fetch it again when a record names a keyId you have not seen.
• Change how PixelTrace behaves: GET and PUT /api/v1/pixel-trace/settings. A "mode" setting no longer exists: sending anything but "isolated" is refused, so nobody believes photos are shared.
• There is no route to download a photo from PCIFIC. A stored photo is the phone's own JPEG with its hidden details (camera, location, time) removed and PixelTrace's own record (the code and the certificate link) written in, not re-compressed and not encrypted. Use the 10 minute links in the group. Image tools that resize a photo often drop that record, which does not affect matching.

To try the test upload, set CAPTURE_ID to the id returned by Start a group. The PNG file must be 640 to 4096 pixels on its longest side and no more than 8 MB. Upload as many photos as your minPhotos setting requires, then confirm them in upload order.

curl -X POST "https://business.pcific.ai/api/v1/pixel-trace/captures/$CAPTURE_ID/test-photos" \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @photo.png

curl -X POST "https://business.pcific.ai/api/v1/pixel-trace/captures/$CAPTURE_ID/test-confirm" \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY"

Errors

Every error is JSON with error (what went wrong), code (a fixed name to branch on), tryThis (the next step) and sometimes problems (the exact fields at fault). A 4xx means fix the request. A 5xx means a problem on PCIFIC's side: send the same request again. The errors every address shares (UNAUTHORIZED, KEY_NOT_ALLOWED, RATE_LIMITED, BODY_TOO_LARGE, BACKEND_UNAVAILABLE and the rest) are on the Errors, limits and retries page. With a live key, starting a group and checking a photo can also be refused with OUT_OF_CREDITS or SPEND_LIMIT_REACHED. A key without the right permission is refused with KEY_NOT_ALLOWED: starting, reading, publishing, retracting and checking need pixel-trace, and settings need settings.

Most errors also have a docs link to their own section on PixelTrace errors, with the usual causes, how to fix it and a request that works. That page starts with the mistakes integrations make most often.

• PixelTrace errors

Orbit photo uploads and PixelTrace checks and camera uploads share a photo capacity limit per server: 16 requests and 128 MB of uploaded bytes, with at most 2 requests and 64 MB per business across its shops and keys. These limits include receiving and processing. Content-Length reserves bytes before the body is read; without it the call reserves its maximum body size. Actual streamed bytes are counted too. Uploads must arrive within 120 seconds and wait at most 20 seconds for a photo worker. Public demos use separate capacity: 2 requests, 16 MB and one photo worker. Demo traffic cannot take paid photo places. A busy refusal does not save photos. Wait Retry-After seconds before sending the same upload again.

What your seller might see

These come from the camera page on the seller's phone, not from your server, and the page shows each one with its next step. They are listed so your support team knows what a seller means. Most are fixed by reloading the page or taking the photo again. If a seller is stuck, start a new group and send a new link.

Limits

Words used on this page

Related guides

• Getting started
• Build it yourself
• API keys and permissions
• Shop configuration
• Errors, limits and retries
• Monitoring and privacy