Available

Matching

post/v1/matching/candidates

The best swap candidates for one of your listings, within its visibility (PRIVATE, GLOBAL or BOTH), ranked by Trade Compatibility Score — only listings open to swaps (TRADE or BOTH), in the same currency, from other sellers. A SALE listing has none.

curl -X POST https://api.tbbnetwork.com/v1/matching/candidates \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "listingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "limit": 1
}'

Request body

Field	Type	Required
listingId	string (uuid)	yes
limit	integer	—

Response (201)

Field	Type	Required
listingId	string (uuid)	—
candidates	object[]	—

Example 201 response

{
  "listingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "candidates": [
    {
      "listingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "title": "title",
      "category": "category",
      "subcategory": null,
      "brand": null,
      "condition": null,
      "originalPrice": 1,
      "requestedAmount": null,
      "willingToPay": null,
      "currency": "USD",
      "listingType": "TRADE",
      "images": [],
      "sellerName": null,
      "merchantDisplayName": null,
      "merchantLogoUrl": null,
      "locationLabel": null,
      "locationCountry": null,
      "sellerIdentityVerified": false,
      "score": 1,
      "breakdown": {
        "wantsMatch": 1,
        "categoryMatch": 1,
        "brandMatch": 1,
        "conditionMatch": 1,
        "valueMatch": 1,
        "geographyMatch": 1,
        "reputationMatch": 1
      }
    }
  ]
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/matching/score

Direct pairwise Trade Compatibility Score for two known listings — used to preview compatibility before sending an offer

curl -X POST https://api.tbbnetwork.com/v1/matching/score \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "listingIdA": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "listingIdB": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}'

Request body

Field	Type	Required
listingIdA	string (uuid)	yes
listingIdB	string (uuid)	yes

Response (201)

Field	Type	Required
score	number	—
breakdown	CompatibilityBreakdown	—

Example 201 response

{
  "score": 1,
  "breakdown": {
    "wantsMatch": 1,
    "categoryMatch": 1,
    "brandMatch": 1,
    "conditionMatch": 1,
    "valueMatch": 1,
    "geographyMatch": 1,
    "reputationMatch": 1
  }
}

Possible errors

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}