API Documentation

1
GET /api/v1/inventory

1
POST /api/v1/inventory
2
Content-Type: application/json
3
 
4
{
5
  "playerName": "Mike Trout",
6
  "year": 2023,
7
  "brand": "Topps Chrome",
8
  "cardNumber": "1",
9
  "sport": "baseball",
10
  "condition": "psa10",
11
  "price": 150.00
12
}

1
GET /api/v1/buyer-requests

1
POST /api/v1/buyer-requests
2
Content-Type: application/json
3
 
4
{
5
  "playerName": "Shohei Ohtani",
6
  "year": 2023,
7
  "sport": "baseball",
8
  "conditionMin": "psa9",
9
  "maxPrice": 200.00,
10
  "expiresAt": "2026-12-31T23:59:59Z"
11
}

1
POST /api/v1/matches/run
2
Content-Type: application/json
3
 
4
{
5
  "inventoryIds": ["uuid-1", "uuid-2"]
6
}

1
{
2
  "data": {
3
    "matchRunId": "run_abc123",
4
    "matchPacksCreated": 5,
5
    "totalMatches": 12,
6
    "notificationsSent": 3
7
  }
8
}

1
DRAFT → NEGOTIATING → TERMS_AGREED → FUNDED → SHIPPED →
2
IN_INSPECTION → ACCEPTED → SETTLED → CLOSED
3
                 └→ DISPUTED → RESOLVED → SETTLED → CLOSED

1
GET /api/v1/trades

1
POST /api/v1/trades
2
Content-Type: application/json
3
 
4
{
5
  "sellerUserId": "user-uuid",
6
  "items": [
7
    {
8
      "inventoryId": "inv-uuid",
9
      "agreedPriceAmount": 15000,
10
      "agreedPriceCurrency": "USD",
11
      "quantity": 1
12
    }
13
  ],
14
  "matchPackId": "match-pack-uuid",
15
  "buyerRequestId": "request-uuid"
16
}

1
PATCH /api/v1/trades/{tradeId}
2
Content-Type: application/json
3
 
4
{
5
  "status": "SHIPPED",
6
  "trackingNumber": "1Z999AA10123456784",
7
  "shippingCarrier": "UPS"
8
}

1
GET /api/v1/notifications

1
PATCH /api/v1/notifications
2
Content-Type: application/json
3
 
4
{
5
  "ids": ["notif-uuid-1", "notif-uuid-2"]
6
}

1
{ "markAll": true }

1
{
2
  "id": "evt_xxxxx",
3
  "type": "trade.status_changed",
4
  "timestamp": "2026-02-26T12:00:00Z",
5
  "data": {
6
    "tradeId": "trade-uuid",
7
    "fromStatus": "FUNDED",
8
    "toStatus": "SHIPPED",
9
    "trackingNumber": "1Z999AA10123456784"
10
  }
11
}

1
import { createHmac } from 'crypto';
2
 
3
function verifyWebhook(payload: string, signature: string, secret: string): boolean {
4
  const expected = createHmac('sha256', secret).update(payload).digest('hex');
5
  return signature === expected;
6
}

1
npm install @collectiq/sdk

1
import { CollectIQ } from '@collectiq/sdk';
2
 
3
const ciq = new CollectIQ({
4
  apiKey: 'ciq_live_xxxxxxxxxxxxx',
5
});

1
const { data } = await ciq.inventory.list({
2
  sport: 'baseball',
3
  limit: 50,
4
});
5
console.log(data);

1
const request = await ciq.buyerRequests.create({
2
  playerName: 'Shohei Ohtani',
3
  year: 2023,
4
  sport: 'baseball',
5
  conditionMin: 'psa9',
6
  maxPrice: 200_00, // cents
7
});

1
const result = await ciq.matches.run();
2
console.log(`Created ${result.matchPacksCreated} match packs`);

1
// 1. Add inventory
2
const inv = await ciq.inventory.create({
3
  playerName: 'Shohei Ohtani',
4
  year: 2023,
5
  brand: 'Topps Chrome',
6
  sport: 'baseball',
7
  condition: 'psa10',
8
  price: 150.00,
9
});
10
 
11
// 2. Matches run automatically on inventory insert
12
// (or trigger manually)
13
const matchResult = await ciq.matches.run({
14
  inventoryIds: [inv.id],
15
});
16
 
17
// 3. Create a trade from a match
18
const trade = await ciq.trades.create({
19
  sellerUserId: 'seller-uuid',
20
  items: [{ inventoryId: inv.id, agreedPriceAmount: 15000 }],
21
});
22
 
23
// 4. Progress through trade lifecycle
24
await ciq.trades.update(trade.id, { status: 'NEGOTIATING' });
25
await ciq.trades.update(trade.id, { status: 'TERMS_AGREED' });
26
await ciq.trades.update(trade.id, { status: 'FUNDED' });
27
await ciq.trades.update(trade.id, {
28
  status: 'SHIPPED',
29
  trackingNumber: '1Z999AA10123456784',
30
});

1
{
2
  "error": {
3
    "code": "validation_error",
4
    "message": "sellerUserId and at least one item are required."
5
  }
6
}