Vereev authentication API

Send the photos you already take for a listing. Receive the verdict by signed webhook. Show the official record and the live badge. Three calls cover a complete integration.

Early access

The API is not open yet. This page is the version 1 design, published so your developers can review it before you commit. Keys will be issued to approved businesses when access opens, and details may change until then. What works today without a key: ordering on the web or in the app, the public record pages, and the store badge.

Request API access

How an integration works

01
Create
When a seller lists an item, send its photo URLs to Vereev with your own reference.
02
Wait for the webhook
Vereev reviews the item and calls your server with the result, signed so you can trust it.
03
Show the proof
Publish the listing with the record link and badge that came in the webhook.

Basics

Base URL: https://api.vereev-ai.com/v1 over HTTPS. Requests and responses are JSON.
Keys: Send your secret key as a Bearer token from your server only. Never place it in a web page or an app.
Test mode: Keys that begin vk_test_ never spend tokens and never reach a reviewer. Use the test brands test_authentic, test_replica, test_more_photos and test_indefinable to receive each outcome on demand.
Safe retries: Send an Idempotency-Key on every POST. Repeating a request with the same key returns the first result and never creates a second order or a second charge.
Photos: 6 to 15 per item, as HTTPS URLs to JPEG or PNG files. Vereev copies each photo once at creation, so the URLs can expire afterwards.
Errors: Standard HTTP status codes with a JSON body: a stable error code, a plain message, and the field at fault where there is one.

Create an authentication

The response arrives immediately; the result arrives later by webhook. Photo labels follow the Vereev photo guide for the item type.

Request

curl https://api.vereev-ai.com/v1/authentications \
  -H "Authorization: Bearer vk_test_..." \
  -H "Idempotency-Key: listing-48213" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "louis_vuitton",
    "reference": "SKU-48213",
    "photos": [
      { "label": "Front Overview", "url": "https://yourstore.com/img/48213-1.jpg" },
      { "label": "Date Code",      "url": "https://yourstore.com/img/48213-2.jpg" }
    ]
  }'

Response · 202 Accepted

{
  "id": "5B0E6F0C-2A51-4C3E-9B7A-0D4C1E9F2A10",
  "status": "in_process",
  "brand": "louis_vuitton",
  "reference": "SKU-48213",
  "token_cost": 2,
  "photos_received": 8,
  "created_at": "2026-11-10T09:14:02Z"
}

Receive the result

Every webhook is signed with your webhook secret. Check the signature before you act on it. Failed deliveries are retried with increasing delays, and each event has an ID so a repeat can be ignored.

Webhook

POST https://yourstore.com/webhooks/vereev
Vereev-Signature: t=1794302042,v1=5f2b...c9

{
  "type": "authentication.completed",
  "data": {
    "id": "5B0E6F0C-2A51-4C3E-9B7A-0D4C1E9F2A10",
    "reference": "SKU-48213",
    "status": "authentic",
    "reviewed_at": "2026-11-10T10:02:44Z",
    "record_url": "https://www.vereev-ai.com/verify/5B0E6F0C-2A51-4C3E-9B7A-0D4C1E9F2A10",
    "badge_url": "https://www.vereev-ai.com/badge/5B0E6F0C-2A51-4C3E-9B7A-0D4C1E9F2A10.svg"
  }
}

Verify the signature · Node.js

import crypto from "node:crypto";

// header: the Vereev-Signature value. body: the raw request body, before JSON parsing.
export function isFromVereev(header, body, secret) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${body}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Events

authentication.more_photos_needed: Extra photos were requested. Includes the request list and the reviewer's note.
authentication.completed: A final result: authentic, replica or indefinable.
authentication.updated: A published result was corrected. Rare; update what you show.

When Vereev asks for more photos

A reviewer may need an angle that was not in the first set. The webhook names each requested photo. Send them to the same authentication and it returns to review; no new order and no extra tokens.

Answer a request for more photos

curl https://api.vereev-ai.com/v1/authentications/5B0E6F0C-.../photos \
  -H "Authorization: Bearer vk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "photos": [ { "request_id": "req_1", "url": "https://yourstore.com/img/48213-9.jpg" } ] }'

Endpoints

POST/v1/authentications
Create an authentication from 6 to 15 photo URLs. Tokens are debited once, when the order is accepted.
GET/v1/authentications/{id}
Read one authentication: status, review date, record and badge links.
GET/v1/authentications
List your authentications. Filter by status or by your own reference.
POST/v1/authentications/{id}/photos
Answer a request for more photos.
GET/v1/brands
The brands you can submit, each with its key and token cost.
GET/v1/balance
Your current token balance.

Statuses

in_process: Accepted and under review.
more_photos_needed: Vereev has asked for specific extra photos. The webhook lists each one.
authentic: Final. A public record and badge exist.
replica: Final. A public record exists. The badge stays neutral.
indefinable: Final. The evidence cannot support a reliable decision. The tokens are returned and there is no public record.

Build with us

Businesses that ask now are first in line for test keys and help shape what ships. No commitment is needed to ask. Tell us what your listing flow looks like.

Request API access Use the badge today