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 chain
VERIFIED_SUPPLY_CHAINOnly 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 detected
POTENTIAL_RISKWhen 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 flags
NO_OBVIOUS_RED_FLAGSWhen 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 information
INSUFFICIENT_INFORMATIONWhen 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 review
UNDER_REVIEWWhen 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. …" }| HTTP | code | Meaning |
|---|---|---|
| 400 | BAD_JSON · INVALID_TYPE · PHOTO_NOT_SUPPORTED · GTIN_REQUIRED · LOT_REQUIRED · BRAND_REQUIRED · QUERY_REQUIRED · INVALID_BRAND_ID · IDEMPOTENCY_KEY | The request is incomplete or malformed. Nothing is counted. |
| 401 | INVALID_API_KEY | The Authorization header is missing, or the key is unknown or revoked. |
| 403 | PARTNER_API_DISABLED | The partner API is not switched on (private pilot). |
| 403 | ORG_INACTIVE | Your organisation is not active. Contact VerifySkin. |
| 404 | NOT_FOUND | No such check for your organisation. |
| 413 | TOO_LARGE | The request body is larger than 8 KB. |
| 429 | RATE_LIMITED | More than 60 calls per minute on one key. Retry after 60 seconds (Retry-After header). |
| 429 | PARTNER_QUOTA | This key's monthly quota is used. It resets on the 1st, Bangladesh time. |
| 500 | PROCESSING_FAILED · SERVER_ERROR | The 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.