Verify Code

POST /api/v1/code/verify

Verify the authenticity of an Optropic code. Returns a verdict (AUTHENTIC, COUNTERFEIT, or SUSPICIOUS) along with detailed check results.

Request

Headers

Header	Required	Description
x-api-key	Yes	Your Optropic API key
Content-Type	Yes	Must be application/json

Body Parameters

Parameter	Type	Required	Description
url	string	Yes*	The complete GS1 Digital Link URL
content	string	Yes*	Alternative: raw QR code content

*Provide either url or content, not both.

Example Request

curl -X POST https://api.optropic.com/api/v1/code/verify \
  -H "x-api-key: optr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://id.optropic.com/01/04260799580008/21/SN-2026-001/10/BATCH-A?sig=Kx7mN2..."
  }'

Response

Success (200 OK)

{
  "verdict": "AUTHENTIC",
  "confidence": 0.95,
  "gtin": "04260799580008",
  "serial": "SN-2026-001",
  "batch": "BATCH-A",
  "checks": {
    "signature": {
      "passed": true,
      "keyId": "key_abc123",
      "algorithm": "Ed25519"
    },
    "format": {
      "passed": true,
      "standard": "GS1_DIGITAL_LINK"
    },
    "scanPattern": {
      "passed": true,
      "scanNumber": 3,
      "riskLevel": "low"
    }
  },
  "metadata": {
    "firstSeen": "2026-02-15T08:00:00Z",
    "lastSeen": "2026-02-18T10:30:00Z",
    "totalScans": 3
  },
  "riskIndicators": []
}

Response Fields

Field	Type	Description
verdict	string	AUTHENTIC, COUNTERFEIT, or SUSPICIOUS
confidence	number	Confidence score (0.0 to 1.0)
gtin	string	Extracted GTIN
serial	string	Extracted serial number
batch	string	Extracted batch number
checks	object	Individual verification checks
metadata	object	Scan history metadata
riskIndicators	array	List of detected risk factors

Verdicts

Verdict	Meaning	Action
AUTHENTIC	Code is valid, signature verified	Safe to sell/use
COUNTERFEIT	Signature invalid or unknown key	Investigate immediately
SUSPICIOUS	Valid signature but unusual patterns	Review manually

Checks Explained

signature

Verifies the Ed25519 digital signature against registered public keys.

{
  "passed": true,
  "keyId": "key_abc123",
  "algorithm": "Ed25519"
}

format

Validates GS1 Digital Link URL structure and encoding.

{
  "passed": true,
  "standard": "GS1_DIGITAL_LINK"
}

scanPattern

Analyzes scan history for anomalies (e.g., excessive scans, geographic impossibilities).

{
  "passed": true,
  "scanNumber": 3,
  "riskLevel": "low"
}

Risk Indicators

When verdict is SUSPICIOUS, check riskIndicators:

Indicator	Description
EXCESSIVE_SCANS	Unusually high scan count
GEOGRAPHIC_IMPOSSIBILITY	Scans from impossible locations in timeframe
KNOWN_COUNTERFEIT_PATTERN	Matches known counterfeit signatures
EXPIRED_CODE	Code past its valid date

Errors

Code	HTTP Status	Description
INVALID_URL	400	URL is malformed or missing signature
MISSING_SIGNATURE	400	No sig parameter in URL
KEY_NOT_FOUND	404	Signing key not registered
RATE_LIMITED	429	Verify rate limit exceeded

Code Examples

JavaScript

async function verifyCode(url) {
  const response = await fetch('https://api.optropic.com/api/v1/code/verify', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.OPTROPIC_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url }),
  });

  const result = await response.json();

  if (result.verdict === 'AUTHENTIC') {
    console.log('✅ Product is authentic');
  } else if (result.verdict === 'COUNTERFEIT') {
    console.log('❌ WARNING: Counterfeit detected!');
  } else {
    console.log('⚠️ Suspicious - manual review needed');
    console.log('Risk indicators:', result.riskIndicators);
  }

  return result;
}

Python

import requests
import os

def verify_code(url: str) -> dict:
    response = requests.post(
        'https://api.optropic.com/api/v1/code/verify',
        headers={
            'x-api-key': os.environ['OPTROPIC_API_KEY'],
            'Content-Type': 'application/json',
        },
        json={'url': url}
    )
    response.raise_for_status()
    return response.json()

# Usage
result = verify_code('https://id.optropic.com/01/...')

if result['verdict'] == 'AUTHENTIC':
    print('Product verified as authentic')
elif result['verdict'] == 'COUNTERFEIT':
    print('WARNING: Counterfeit detected!')

Offline Verification

Because Optropic uses Ed25519 signatures, verification can be performed offline if you have the public key. See Offline Verification for details.