Favorites

Add a favorite ad

Saves an ad to the requested workspace or delegated-user favorites scope. Existing favorites are returned idempotently without creating an audit mutation event. Deprecated: favorites are now V3 boards; use /v1/boards. This endpoint is a compatibility facade over boards: folder ids are board ids (migrated V2 folder UUIDs are still accepted), saved favorite ids are board item ids, and favorites without a folder live in the scope's "Unsorted" board.

post/v1/favorites/ads

Request

  • Base URL: https://api.trendtrack.io (the document declares no server; this is the origin it was published from)
  • URL: https://api.trendtrack.io/v1/favorites/ads
  • Auth: HTTP bearer

Request body

scope'workspace' | 'personal' required
adIdstring required

Composite public ad identifier, for example facebook_123 or tiktok_123.

folderIdobject nullable

Favorite ads folder id (board id, or migrated V2 folder UUID). Null or omitted saves the ad in the scope's "Unsorted" board.

Example request

{
  "adId": "facebook_1234567890"
}

Response

Favorite ad mutation response. The response also includes the X-Request-Id header.

requestIdstring required
createdboolean required

True when this call created a favorite; false when the favorite already existed.

Example response

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": "board_item_3f1c2b7e-8d4a-4f0e-9b1a-2c3d4e5f6a7b",
    "scope": "workspace",
    "savedAt": "2026-04-20T10:00:00.000Z",
    "folder": {
      "id": "board_8b7c6d5e-4f3a-4b2c-9d1e-0f1a2b3c4d5e",
      "name": "Winning Creatives",
      "parentId": "board_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
    },
    "ad": {
      "id": "facebook_123456789",
      "collationId": "3810635369204881",
      "platform": "facebook",
      "status": "active",
      "createdAt": "2026-04-18T12:30:00.000Z",
      "firstSeenAt": "2026-04-10T00:00:00.000Z",
      "lastSeenAt": "2026-04-19T00:00:00.000Z",
      "daysRunning": 9,
      "media": {
        "type": "video",
        "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",
        "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"
      },
      "advertiser": {
        "id": "1234567890",
        "name": "Example Brand",
        "logoUrl": "https://cdn.example.com/pages/example-brand.png",
        "facebookPageId": "1234567890",
        "liveAdsCount": 42,
        "reach30d": 152340,
        "totalReach": 842100,
        "countriesCount": 8,
        "facebookLikes": 125000,
        "instagramFollowers": 89000
      },
      "content": {
        "title": "Summer Sale",
        "body": "Up to 30% off selected products.",
        "transcript": "Save 30% on every order.",
        "callToAction": "Shop now",
        "landingPageUrl": "https://example.com/products/summer-sale",
        "landingPageDomain": "example.com",
        "ctaDescription": "Free shipping on orders over $50.",
        "ctaLinkDescription": "Shop the full collection"
      },
      "metrics": {
        "reach": 152340,
        "aggregatedReach": 284100,
        "estimatedSpend": 4262,
        "duplicates": 4,
        "reachDelta1d": 1200,
        "reachDelta7d": 8200,
        "reachDelta30d": 38400
      },
      "audience": {
        "targetedCountries": [
          "US",
          "FR"
        ],
        "mainCountry": "FR",
        "gender": "all",
        "ageMin": 18,
        "ageMax": 65
      },
      "rank": {
        "positionInPage": 3,
        "currentRank": 12,
        "rankDelta": -4,
        "improvementPct": 0.25
      },
      "flags": {
        "isEuAd": true,
        "hasPartnerBadge": true
      }
    }
  },
  "created": true
}

Changes

No recorded changes to this operation across all 1 revision of this API.