Developers · API Reference

Identification ID API

A simple REST API to read your product registry, verify products, and pull live stats. JSON responses, one X-API-Key header.

Get API access →Interactive API (Swagger) ↗View plans

Getting started

  1. 1Register & choose a plan. Create a manufacturer account and pick a plan that includes API access (Best Value or Enterprise).
  2. 2Create an API key. In your dashboard, open API Access and generate a key. It's shown once — store it securely.
  3. 3Call the API. Send your key in the X-API-Key header on every request. That's it.

Base URL

All endpoints are relative to:

https://api.identificationid.com/v1

All responses are JSON with the shape { "success": true, "data": … }.

Authentication

Pass your API key in the X-API-Key header on every request. Keys look like iid_live_… and can be revoked anytime from your dashboard.

Example request
curl https://api.identificationid.com/v1/stats \
  -H "X-API-Key: iid_live_your_key_here"

A missing or invalid key returns 403 (see Errors).

API key security

Treat your API key like a password. A few rules:

  • •Shown once. The full key is displayed only when you create it. Copy and store it immediately — we keep only a hashed prefix and can't show it again.
  • •Keep it server-side. Never embed a key in frontend/browser code, mobile apps, or public repositories. Call the API from your backend only.
  • •Store as a secret. Keep keys in environment variables or a secrets manager, not in source control.
  • •Revoke anytime. If a key is exposed, revoke it in your dashboard under API Access and issue a new one — revoked keys stop working immediately.
  • •One key per integration. Use separate keys per app or environment so you can rotate or revoke them independently.

Rate limits

Requests are rate-limited per API key. If you exceed your limit you'll receive a 429 response — back off and retry.

Best Value60 requests / minute
Enterprise600 requests / minute

Need higher limits? Talk to us about Enterprise.

List products

GET/products

Returns every product registered by your company, newest first.

Query parameters

statusOptional. Filter by published, draft, or hidden.
Request
curl "https://api.identificationid.com/v1/products?status=published" \
  -H "X-API-Key: iid_live_…"
Response 200
{
  "success": true,
  "data": [
    {
      "identification_id": "IID-4F9A-2K7Q",
      "name": "ProChef Air Fryer 5.5L",
      "category": "kitchen_appliances",
      "brand": "ACME",
      "model": "AF-550",
      "status": "published",
      "view_count": 128,
      "published_at": "2026-04-19T10:00:00+00:00",
      "created_at": "2026-04-01T09:00:00+00:00"
    }
  ]
}

Get a product

GET/products/{identification_id}

Full detail for one of your products, including images and every language translation.

Request
curl https://api.identificationid.com/v1/products/IID-4F9A-2K7Q \
  -H "X-API-Key: iid_live_…"
Response 200
{
  "success": true,
  "data": {
    "identification_id": "IID-4F9A-2K7Q",
    "name": "ProChef Air Fryer 5.5L",
    "category": "kitchen_appliances",
    "brand": "ACME",
    "model": "AF-550",
    "country_of_origin": "US",
    "status": "published",
    "view_count": 128,
    "published_at": "2026-04-19T10:00:00+00:00",
    "created_at": "2026-04-01T09:00:00+00:00",
    "images": [
      { "url": "https://…/photo.jpg", "alt_text": "Main view", "display_order": 0 }
    ],
    "translations": [
      {
        "lang": "en",
        "short_description": "Large 5.5L digital air fryer.",
        "full_description": "…",
        "usage_instructions": "…"
      }
    ]
  }
}

Verify / lookup

GET/lookup/{identification_id}

Verify that any published product is authentic and see which manufacturer owns it. Great for anti-counterfeit checks.

Request
curl https://api.identificationid.com/v1/lookup/IID-4F9A-2K7Q \
  -H "X-API-Key: iid_live_…"
Response 200
{
  "success": true,
  "data": {
    "identification_id": "IID-4F9A-2K7Q",
    "name": "ProChef Air Fryer 5.5L",
    "category": "kitchen_appliances",
    "brand": "ACME",
    "model": "AF-550",
    "country_of_origin": "US",
    "published_at": "2026-04-19T10:00:00+00:00",
    "manufacturer": "ACME Corp",
    "verified": true
  }
}

Stats

GET/stats

Aggregate counts for your company.

Request
curl https://api.identificationid.com/v1/stats \
  -H "X-API-Key: iid_live_…"
Response 200
{
  "success": true,
  "data": {
    "total_products": 12,
    "published": 9,
    "total_views": 384
  }
}

Webhooks

Register a URL in your dashboard (API Access → Webhooks) and we'll send a signed POST when a subscribed event happens.

Events

product.publishedA product was published
product.updatedA product's details changed
document.uploadedA document was uploaded to a product
Payload (POST body)
{
  "event": "product.published",
  "created_at": "2026-07-05T18:00:00+00:00",
  "data": {
    "identification_id": "IID-4F9A-2K7Q",
    "name": "ProChef Air Fryer 5.5L",
    "status": "published"
  }
}

Verify each delivery with the X-IID-Signature header — an HMAC-SHA256 of the raw body using your webhook signing secret:

Verify (Node.js)
const crypto = require("crypto");
const expected = "sha256=" + crypto
  .createHmac("sha256", WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");
// compare with req.headers["x-iid-signature"]

Errors

Errors return the matching HTTP status and a JSON body:

Error body
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Invalid API key",
    "details": {}
  }
}
403FORBIDDENMissing or invalid X-API-Key
404NOT_FOUNDNo product with that Identification ID
429RATE_LIMITEDToo many requests — slow down

Ready to build?

API access is included with the Best Value and Enterprise plans. Register, choose a plan, and generate your first key in seconds.

Get startedCompare plans

API provided by Global Product Identification Inc. · Canada 🇨🇦