Skip to main content
VerifySkinCHECK • KNOW • USE SAFER

For marketplaces, couriers and commerce tools

VerifySkin partner API

Run the same authenticity-risk check a shopper runs on VerifySkin — by barcode, by LOT (batch) number or by product name — from your own system. You get the same evidence-based result, with the same honest categories and limitations.

Private pilot

The partner API is in a private pilot and not open for sign-up yet. If you run a marketplace, courier or commerce tool in Bangladesh and want to take part, contact us. The documentation below describes how it works.

The rule: results cannot be influenced

Money never touches a result. An API key buys metered access — nothing else. No partner, brand or shop can buy, change, hide or speed up a result, a category or a review. A check through the API runs the exact pipeline a shopper's check runs (rule version 2026-10-24.1), so the same input gives the same category.

Authentication

Every call carries your key in the Authorization header: Authorization: Bearer vs_live_…. Keys are issued per organisation by VerifySkin staff. A key is shown once, when it is created — we store only a one-way hash and the first 8 characters for display, so we cannot show it again. Keep it on your server (never in an app or web page). If it leaks, ask us to revoke it and issue a new one; a revoked key stops working at once.

Run a check — POST /api/partner/v1/checks

JSON body. type is barcode (needs gtin), lot (needs lot and brand or brandId) or search (needs query; brand optional). Photo checks are not available through the API (v1).

idempotencyKey (optional, 8–64 letters, digits, - or _): send the same key when you retry, and you get the first check back instead of a new one — and it is not counted again. Without it, every call is a new check.

curl -X POST https://<your-verifyskin-host>/api/partner/v1/checks \
  -H "Authorization: Bearer vs_live_XXXXXXXX..." \
  -H "Content-Type: application/json" \
  -d '{"type":"barcode","gtin":"8801234567890","idempotencyKey":"order-48213-item-1"}'
{"type":"lot","brand":"Brand name","lot":"AB1234"}          // or "brandId": "<uuid>"
{"type":"search","query":"Brand name Hydra Cream 50ml"}

Response: 201 for a new check, 200 for a replay of the same idempotencyKey.

HTTP/1.1 201 Created
{
  "success": true,
  "data": {
    "requestId": "3f0c2a8e-1b7d-4c55-9a51-2f7f0a6d9e10",
    "status": "completed",
    "category": "INSUFFICIENT_INFORMATION",
    "categoryLabel": "Insufficient information",
    "categoryCaveat": "This means neither genuine nor fake.",
    "explanation": "…",
    "checksPerformed": [{ "key": "identifier_lookup", "label": "Barcode lookup", "outcome": "…", "detail": "…" }],
    "checksUnavailable": [{ "key": "…", "label": "…", "reason": "…" }],
    "limitations": ["A barcode identifies a product; it does not prove it is genuine."],
    "nextSteps": ["…"],
    "ruleVersion": "2026-10-24.1",
    "product": { "brand": "…", "name": "…" },
    "decidedBy": "rules",
    "createdAt": "2026-10-23T09:15:02.000Z"
  }
}

status is completed or under_review (a person will look; fetch it again later). decidedBy is rules, or reviewer after a human decision. product is null when the product could not be identified. Checks can take up to about a minute — set your HTTP timeout to at least 60 seconds.

Read a check and your usage

GET /api/partner/v1/checks/{requestId} returns the latest result of a check made with any key of your organisation (a reviewer may have revised it). GET /api/partner/v1/usage returns this month's count and quota for the calling key. Reads are not counted against the quota.

curl https://<your-verifyskin-host>/api/partner/v1/checks/3f0c2a8e-1b7d-4c55-9a51-2f7f0a6d9e10 \
  -H "Authorization: Bearer vs_live_XXXXXXXX..."

curl https://<your-verifyskin-host>/api/partner/v1/usage \
  -H "Authorization: Bearer vs_live_XXXXXXXX..."
# → {"success":true,"data":{"month":"2026-10","used":412,"quota":1000,"remaining":588,"resetsAt":"…","rateLimitPerMinute":60,"key":{"prefix":"vs_live_ab12cd34…","name":"Production server"}}}

What the result categories mean

Five categories only. None of them is a guarantee, and you must not present them as one to your customers. In particular, "No obvious red flags" does not mean "genuine", and "Potential risk" does not mean "fake".

  • Verified supply chainVERIFIED_SUPPLY_CHAIN

    Only when the product is identified and a high-reliability source such as the manufacturer or an authorised distributor has confirmed that specific batch — or our reviewer has decided citing such evidence.

    What it does not mean: This does not mean no single unit could ever be fake.

  • Potential risk detectedPOTENTIAL_RISK

    When at least one important risk sign is found: a match with a verified official notice (banned, recalled or warning), a recorded recalled or counterfeit batch, a mismatch with a reliable LOT format rule, an expired or impossible printed date, or specific visible discrepancies in the photo.

    What it does not mean: This does not mean the product is definitely fake.

  • No obvious red flagsNO_OBVIOUS_RED_FLAGS

    When at least one meaningful check (such as a readable photo analysis or a reliable LOT format rule) was completed and no warning sign was found.

    What it does not mean: This does not mean the product is genuine.

  • Insufficient informationINSUFFICIENT_INFORMATION

    When the product could not be identified, the batch code is not in our records, the photo could not be read — or only the barcode matched (a barcode identifies a product, it does not prove it is genuine).

    What it does not mean: This means neither genuine nor fake.

  • Under reviewUNDER_REVIEW

    When a person needs to look — for example a match with a list still under review, or you asked for a review.

    What it does not mean: This is not a final result.

Full rules: methodology.

Quotas and limits

  • Each key has a monthly quota (default 1,000 checks), counted per calendar month, Bangladesh time.
  • One new check = one unit. Replays of an idempotencyKey, rejected requests (4xx) and failed checks are not counted. Reads are free.
  • At most 60 calls per minute per key (all endpoints).
  • Partner checks are never charged to a shopper and do not use any shopper's free checks.

Errors

Errors use the same envelope with a stable code and an English message:

HTTP/1.1 429 Too Many Requests
{ "success": false, "code": "PARTNER_QUOTA", "error": "This key's monthly quota of 1000 checks is used. …" }
HTTPcodeMeaning
400BAD_JSON · INVALID_TYPE · PHOTO_NOT_SUPPORTED · GTIN_REQUIRED · LOT_REQUIRED · BRAND_REQUIRED · QUERY_REQUIRED · INVALID_BRAND_ID · IDEMPOTENCY_KEYThe request is incomplete or malformed. Nothing is counted.
401INVALID_API_KEYThe Authorization header is missing, or the key is unknown or revoked.
403PARTNER_API_DISABLEDThe partner API is not switched on (private pilot).
403ORG_INACTIVEYour organisation is not active. Contact VerifySkin.
404NOT_FOUNDNo such check for your organisation.
413TOO_LARGEThe request body is larger than 8 KB.
429RATE_LIMITEDMore than 60 calls per minute on one key. Retry after 60 seconds (Retry-After header).
429PARTNER_QUOTAThis key's monthly quota is used. It resets on the 1st, Bangladesh time.
500PROCESSING_FAILED · SERVER_ERRORThe check could not be completed. Nothing is counted; retry with the same idempotencyKey.

Privacy

  • Send only what the check needs: a barcode, a LOT number with a brand, or a product name. Do not send your customers' personal data.
  • The response carries the same fields as a VerifySkin share link: category, explanation, checks, limitations, next steps and the product identity. It never includes evidence documents, reviewer notes or the text of the AI web search.
  • You can read only checks made with your own organisation's keys.
  • Results are about a product and its evidence — never a judgement about a seller. Do not use them to publicly accuse a seller; VerifySkin does not.