REST API v1

Server-to-server access

RFC 9727 Discovery

RFC 7807 Errors

CheckWarranty API Documentation

Programmatic, high-throughput REST API for enterprise hardware warranty verification, specification decoding, and entitlement retrieval across Lenovo, HP, Dell, and Apple.

Get API Key Interactive Swagger UI OpenAPI Spec RFC 9727 Catalog

Base URLhttps://checkwarranty.info/api/v1

Content-Typeapplication/json

Character EncodingUTF-8

Authentication & Headers

Every request to the CheckWarranty API must include authentication via API keys using X-API-Key or Authorization: Bearer cw_*. Webhook management uses a signed-in account JWT. API keys can be generated instantly from your Dashboard → API Keys.

Supported Authentication Headers

You may use either header format. Server-to-server systems typically use X-API-Key.

# Option A: Recommended custom header

X-API-Key: cw_live_xxxxxxxxxxxxxxxxxxxxxxxx

# Option B: Standard Authorization Bearer header

Authorization: Bearer cw_live_xxxxxxxxxxxxxxxxxxxxxxxx

# Required for all mutating requests (prevents duplicate charges):

Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

Sandbox & Test Environment

Test your integration end-to-end without consuming scan credits. The same per-key rate limits apply. Keys prefixed with cw_test_ return simulated device data in sandbox mode and return deterministic mock payloads for designated test serials.

Test Serial Number	Brand	Simulated Result	Credit Cost
TEST-LENOVO-001	lenovo	Active Warranty (ThinkPad T14 Gen 3)	0 credits (Free)
TEST-HP-001	hp	Expired Warranty (EliteBook 840 G9)	0 credits (Free)
TEST-DELL-001	dell	Active ProSupport (Latitude 5540)	0 credits (Free)
TEST-APPLE-001	apple	Active AppleCare+ (MacBook Pro 14")	0 credits (Free)
TEST-NOTFOUND-001	any	200 OK with warranty.status = not_found	0 credits (Free)
TEST-ERROR-001	any	503 Service Unavailable (Upstream outage simulation)	0 credits (Free)

API Endpoints

All endpoints are versioned under /api/v1.

GET

/api/v1/devices/brands

Retrieve the catalog of supported hardware manufacturers, active parsers, and serial number validation hints.

curl -X GET "https://checkwarranty.info/api/v1/devices/brands" \
  -H "X-API-Key: cw_live_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "brands": [
    {
      "id": "lenovo",
      "name": "Lenovo",
      "serialRegex": "^[A-Z0-9]{8}$",
      "example": "PF4XXXXX"
    },
    {
      "id": "hp",
      "name": "HP (Hewlett Packard)",
      "serialRegex": "^[A-Z0-9]{10}$",
      "example": "5CGXXXXXXX"
    },
    {
      "id": "dell",
      "name": "Dell",
      "serialRegex": "^[A-Z0-9]{7}$",
      "example": "8HG76F2"
    },
    {
      "id": "apple",
      "name": "Apple",
      "serialRegex": "^[A-Z0-9]{10,12}$",
      "example": "C02GXXXXMD6R"
    }
  ],
  "autoDetectSupported": true
}

POST

/api/v1/devices/lookup

1 Credit

Sync Wait

Perform a single synchronous serial number lookup. Submits the scan and holds the HTTP connection using PostgreSQL LISTEN/NOTIFY until the scraper finishes (30s timeout fallback to 202 Accepted).

Request Body Parameters

Parameter	Type	Requirement	Description
serialNumber	string	Required	Hardware device serial number or Service Tag. Example: `PF4XXXXX`
brand	string	Required	Manufacturer brand key. Allowed:`lenovohpdellapple`
pn	string	Optional	Product number for HP serials matching multiple products.
forceRefresh	boolean	Optional	Force bypass global cache and query live vendor servers (default: false).

curl -X POST "https://checkwarranty.info/api/v1/devices/lookup" \
  -H "X-API-Key: cw_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -H "Content-Type: application/json" \
  -d '{
    "serialNumber": "PF4XXXXX",
    "brand": "lenovo"
  }'

Scrape finished within sync wait window. Result returned. Check dataQuality.warrantyVerified and limitations; completed describes processing, not data completeness.

{
  "status": "completed",
  "batchId": "6c40a5a3-764f-4d33-91ee-b6eef7699411",
  "serialNumber": "PF4XXXXX",
  "brand": "lenovo",
  "device": {
    "model": "ThinkPad T14 Gen 3",
    "productNumber": "21AH001CUS",
    "brand": "lenovo",
    "serialNumber": "PF4XXXXX",
    "manufactureDate": "2023-04-12"
  },
  "warranty": {
    "status": "active",
    "coverageType": "Premier Support Plus",
    "startDate": "2023-04-12T00:00:00.000Z",
    "endDate": "2026-04-11T23:59:59.000Z"
  },
  "credits": {
    "used": 1,
    "remaining": 489
  }
}

POST

/api/v1/devices/auto-detect

3 Credits (Refund on Not Found)

Look up hardware without knowing the brand. Evaluates serial number syntax patterns across all parsers concurrently.

Parameter	Type	Requirement	Description
serialNumber	string	Required	Unknown device serial number. Example: `5CG1234567`
candidates	array	Optional	Optional subset of candidate brands to probe. If omitted, probes all supported brands. Allowed:`lenovohpdellapple`
pn	string	Optional	Product number for HP serials matching multiple models.
forceRefresh	boolean	Optional	Force bypass cache and query live vendor servers (default: false).

curl -X POST "https://checkwarranty.info/api/v1/devices/auto-detect" \
  -H "X-API-Key: cw_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"serialNumber": "5CG1234567"}'

POST

/api/v1/devices/bulk

Max 500 Serials

Async

Submit up to 500 serial numbers for background processing. Each item uses its own brand, and paid items reserve credits atomically; previously viewed cached items may be free.

Parameter	Type	Requirement	Description
items	array	Required	List of items to verify (max 500 items).
items[].serialNumber	string	Required	Serial number.
items[].brand	string	Optional	Brand for this item. If omitted, inherits the first specified item brand, or Lenovo when none is specified. Allowed:`lenovohpdellapple`
items[].clientRefId	string	Optional	Customer asset ID.
callbackUrl	string	Optional	Public HTTPS URL receiving a scan.completed POST after all items finish. Must be an externally resolvable HTTPS target (SSRF validator rejects localhost and private IPs with HTTP 422). Retried with backoff on failure. Example: `https://your-domain.com/webhooks/checkwarranty`

Mixed-brand batches are supported. The callback payload contains the batch ID, final status, and each item’s brand, serial number, client reference, and result. A callback is sent when the batch is completed, partially completed, or failed.

curl -X POST "https://checkwarranty.info/api/v1/devices/bulk" \
  -H "X-API-Key: cw_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "serialNumber": "PF4A1234", "brand": "lenovo", "clientRefId": "unit-01" },
      { "serialNumber": "5CG1234567", "brand": "hp", "clientRefId": "unit-02" },
      { "serialNumber": "8HG76F2", "brand": "dell", "clientRefId": "unit-03" }
    ],
    "callbackUrl": "https://api.yourcompany.com/webhooks/warranty"
  }'

{
  "status": "pending",
  "batchId": "11111111-2222-4333-8444-555555555555",
  "itemCount": 3,
  "estimatedCredits": 3
}

GET

/api/v1/devices/scans/:batchId

Poll batch scan status and retrieve paginated item results.

curl -X GET "https://checkwarranty.info/api/v1/devices/scans/11111111-2222-4333-8444-555555555555?page=1&limit=50" \
  -H "X-API-Key: cw_live_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "batchId": "11111111-2222-4333-8444-555555555555",
  "status": "completed",
  "progress": {
    "total": 3,
    "completed": 3,
    "failed": 0,
    "pending": 0
  },
  "items": [
    {
      "serialNumber": "PF4A1234",
      "brand": "lenovo",
      "clientRefId": "unit-01",
      "status": "completed",
      "warranty": {
        "status": "active",
        "endDate": "2026-10-01"
      }
    }
  ],
  "createdAt": "2026-10-14T00:00:00.000Z",
  "completedAt": "2026-10-14T00:00:05.000Z"
}

GET

/api/v1/account/balance

Query current remaining scan balance and reservation status.

curl -X GET "https://checkwarranty.info/api/v1/account/balance" \
  -H "X-API-Key: cw_live_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "scanBalance": 1250,
  "reservedCredits": 0,
  "currency": "credits",
  "userId": "40a91b50-5b8c-46f9-837d-6c0522ffab89",
  "balance": 1250
}

GET

/api/v1/account/usage

Retrieve API usage telemetry, success rates, and credit consumption metrics.

curl -X GET "https://checkwarranty.info/api/v1/account/usage" \
  -H "X-API-Key: cw_live_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "totalRequests": 1250,
  "requests": 1250,
  "total": 1250,
  "successRate": 98.4,
  "creditsUsed": 320,
  "used": 320,
  "period": "all_time",
  "recent24h": {
    "requests": 45,
    "creditsUsed": 38
  }
}

Webhooks & HMAC Signatures

When asynchronous batch scans finish, CheckWarranty delivers a signed HTTP POST notification to your registered endpoint with HMAC-SHA256 verification.

Webhook Signature Verification (Node.js)

Validate the X-Webhook-Signature header to ensure payloads originate securely from CheckWarranty.

import crypto from 'crypto';

app.post('/webhooks/checkwarranty', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const rawBody = req.rawBody;
  const webhookSecret = process.env.CW_WEBHOOK_SECRET;

  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(rawBody);
  console.log('Batch completed:', event.data.batchId);
  res.sendStatus(200);
});

Idempotency & Replays

To prevent accidental double-billing upon network retries, all mutating requests (/lookup, /auto-detect, /bulk) require an Idempotency-Key header.

Stable Operation Replay

Replaying a request with the same Idempotency-Key and matching payload returns the original cached response with zero additional credits deducted.

Payload Mismatch (HTTP 409 Conflict)

If you send the same key with a modified request body, the API returns 409 Conflict to protect audit ledger integrity.

Rate Limits & Headers

API requests are governed by a per-key rate limiter. Standard tier keys allow 60 requests/minute. Every response includes standard rate limit headers:

X-RateLimit-Limit: 60

X-RateLimit-Remaining: 54

X-RateLimit-Reset: 1790102400

# On breach (HTTP 429 Too Many Requests):

Retry-After: 12

Error Catalog (RFC 7807)

CheckWarranty standardizes all API errors under IETF RFC 7807 Problem Details (application/problem+json).

Missing mandatory Idempotency-Key or malformed serial number syntax.

{
  "type": "https://checkwarranty.info/errors/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "Missing required 'Idempotency-Key' HTTP header for mutating lookup.",
  "errors": [
    {
      "field": "header.idempotency-key",
      "message": "Header is required"
    }
  ]
}

Machine Discovery (RFC 9727 & MCP)

Autonomous AI agents and SDK generators can automatically discover CheckWarranty capabilities via machine discovery manifests.

GET /.well-known/api-catalog

Accept: application/linkset+json

GET /.well-known/mcp/server-card.json

Accept: application/json