Common Use Cases

These recipes show end-to-end flows with full requests and responses. Each builds on the Integration Guide — we assume you have an API key and a brand with a connected ad platform.

1. Create a Link Clicks Campaign on Meta

Launch a campaign that drives link clicks to a Spotify release, targeting hip hop fans in the US.

Step 1: Search for interests

curl -X POST https://api.symphonyos.co/api/sym/v2/interest-search \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "adPlatform": "meta", "query": "hip hop" }'

Response:

{
  "success": true,
  "data": [
    { "id": "6003139266461", "type": "InterestAudience", "name": "Hip hop music" },
    { "id": "6003455790094", "type": "InterestAudience", "name": "Hip hop" },
    { "id": "6003232074834", "type": "InterestAudience", "name": "Rap music" }
  ]
}

Step 2: Search for geographies

curl -X POST https://api.symphonyos.co/api/sym/v2/geography-search \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "adPlatform": "meta", "query": "United States" }'

Response:

{
  "success": true,
  "data": [
    { "id": "US", "type": "country", "name": "United States" }
  ]
}

Step 3: Create the campaign

curl -X POST https://api.symphonyos.co/api/sym/v2/campaigns \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "adPlatform": "meta",
    "brandId": 12345,
    "campaignInput": {
      "name": "Hip Hop Release - US Link Clicks",
      "startDate": "2026-04-01T00:00:00.000Z",
      "endDate": "2026-04-14T00:00:00.000Z",
      "budget": 300,
      "currency": "USD",
      "promotedLink": "https://open.spotify.com/album/example",
      "captions": [
        "New music out now. Tap to listen.",
        "Fresh heat just dropped. Hit play."
      ],
      "callToAction": "LISTEN_NOW",
      "targetingConfig": {
        "geographies": [
          { "id": "US", "type": "country", "name": "United States", "percentage": 100 }
        ],
        "audiences": [
          { "id": "6003139266461", "type": "InterestAudience", "name": "Hip hop music" },
          { "id": "6003232074834", "type": "InterestAudience", "name": "Rap music" }
        ],
        "languages": [
          { "id": "6", "name": "English" }
        ],
        "genders": ["MALE", "FEMALE"]
      }
    }
  }'

const response = await fetch("https://api.symphonyos.co/api/sym/v2/campaigns", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    adPlatform: "meta",
    brandId: 12345,
    campaignInput: {
      name: "Hip Hop Release - US Link Clicks",
      startDate: "2026-04-01T00:00:00.000Z",
      endDate: "2026-04-14T00:00:00.000Z",
      budget: 300,
      currency: "USD",
      promotedLink: "https://open.spotify.com/album/example",
      captions: [
        "New music out now. Tap to listen.",
        "Fresh heat just dropped. Hit play."
      ],
      callToAction: "LISTEN_NOW",
      targetingConfig: {
        geographies: [
          { id: "US", type: "country", name: "United States", percentage: 100 }
        ],
        audiences: [
          { id: "6003139266461", type: "InterestAudience", name: "Hip hop music" },
          { id: "6003232074834", type: "InterestAudience", name: "Rap music" }
        ],
        languages: [
          { id: "6", name: "English" }
        ],
        genders: ["MALE", "FEMALE"]
      }
    }
  })
});
const data = await response.json();

Response:

{
  "success": true,
  "data": {
    "id": 98765,
    "name": "Hip Hop Release - US Link Clicks",
    "platform": "meta",
    "status": "TO_REVIEW",
    "startDate": "2026-04-01T00:00:00.000Z",
    "endDate": "2026-04-14T00:00:00.000Z",
    "budget": 300
  }
}

Async pattern: The campaign is created in the Symphony database immediately and returns with a status. The actual submission to Meta's Ads API happens asynchronously in the background. Use GET /campaigns/:campaignId or webhooks to track when it goes live.

Adding Conversion Tracking (Optional)

For Meta campaigns, you can include a Facebook Pixel for conversion tracking:

{
  "adPlatform": "meta",
  "brandId": 12345,
  "campaignInput": {
    "...all fields above...",
    "conversionConfig": {
      "pixelId": "123456789012345",
      "conversionEvent": "Purchase"
    }
  }
}

2. Create a TikTok Traffic Campaign

Launch a TikTok campaign using both interest and hashtag audiences.

Step 1: Search interests on TikTok

TikTok's interest search can return both InterestAudience and HashtagAudience types:

curl -X POST https://api.symphonyos.co/api/sym/v2/interest-search \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "adPlatform": "tiktok", "query": "pop music" }'

Response:

{
  "success": true,
  "data": [
    { "id": "25001", "type": "InterestAudience", "name": "Pop & Rock Music" },
    { "id": "ht_991234", "type": "HashtagAudience", "name": "#popmusic" },
    { "id": "ht_554321", "type": "HashtagAudience", "name": "#newmusic" }
  ]
}

TikTok-specific: Hashtag audiences (HashtagAudience type) are only available on TikTok. They let you target users who have engaged with specific hashtags.

Step 2: Create the campaign

curl -X POST https://api.symphonyos.co/api/sym/v2/campaigns \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "adPlatform": "tiktok",
    "brandId": 12345,
    "campaignInput": {
      "name": "Pop Single - TikTok Traffic",
      "startDate": "2026-04-01T00:00:00.000Z",
      "endDate": "2026-04-07T00:00:00.000Z",
      "budget": 150,
      "currency": "USD",
      "promotedLink": "https://open.spotify.com/track/example",
      "captions": [
        "This song is stuck in my head. Listen now."
      ],
      "callToAction": "LISTEN_NOW",
      "targetingConfig": {
        "geographies": [
          { "id": "US", "type": "country", "name": "United States", "percentage": 70 },
          { "id": "GB", "type": "country", "name": "United Kingdom", "percentage": 30 }
        ],
        "audiences": [
          { "id": "25001", "type": "InterestAudience", "name": "Pop & Rock Music" },
          { "id": "ht_991234", "type": "HashtagAudience", "name": "#popmusic" }
        ],
        "languages": [
          { "id": "6", "name": "English" }
        ],
        "genders": ["MALE", "FEMALE"]
      }
    }
  }'

Response:

{
  "success": true,
  "data": {
    "id": 98766,
    "name": "Pop Single - TikTok Traffic",
    "platform": "tiktok",
    "status": "TO_REVIEW",
    "startDate": "2026-04-01T00:00:00.000Z",
    "endDate": "2026-04-07T00:00:00.000Z",
    "budget": 150
  }
}

Key differences from Meta:

TikTok supports HashtagAudience targeting in addition to InterestAudience
Age range is currently hardcoded to 18–34 (no minAge/maxAge in the input)
No conversionConfig — TikTok campaigns are traffic/link-click focused

3. Monitor and Adjust a Running Campaign

Check campaign status

curl https://api.symphonyos.co/api/sym/v2/campaigns/98765 \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "id": 98765,
    "name": "Hip Hop Release - US Link Clicks",
    "platform": "meta",
    "status": "ACTIVE",
    "startDate": "2026-04-01T00:00:00.000Z",
    "endDate": "2026-04-14T00:00:00.000Z",
    "budget": 300
  }
}

Get performance analytics

curl https://api.symphonyos.co/api/sym/v2/campaigns/98765/analytics \
  -H "x-api-key: YOUR_API_KEY"

const analytics = await fetch(
  "https://api.symphonyos.co/api/sym/v2/campaigns/98765/analytics",
  { headers: { "x-api-key": "YOUR_API_KEY" } }
);
const { data } = await analytics.json();
console.log(data);

Increase the budget

curl -X PUT https://api.symphonyos.co/api/sym/v2/campaigns/98765 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "budget": 500 }'

Response:

{
  "success": true,
  "message": "Campaign 98765 updated successfully"
}

Extend the end date

curl -X PUT https://api.symphonyos.co/api/sym/v2/campaigns/98765 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "endDate": "2026-04-30" }'

Pause the campaign

curl -X PUT https://api.symphonyos.co/api/sym/v2/campaigns/98765 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "paused": true }'

Unpause the campaign

curl -X PUT https://api.symphonyos.co/api/sym/v2/campaigns/98765 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "paused": false }'

You can combine multiple update fields in a single request (e.g., increase budget and extend the end date at the same time).

4. Set Up Lifecycle Webhooks

Get notified automatically when campaign events occur, instead of polling.

Register webhooks for key events

# Notify when a campaign is created
curl -X POST https://api.symphonyos.co/api/sym/v2/webhooks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/symphony",
    "eventType": "campaign.created"
  }'

# Notify when a campaign is updated
curl -X POST https://api.symphonyos.co/api/sym/v2/webhooks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/symphony",
    "eventType": "campaign.updated"
  }'

# Notify on campaign failure
curl -X POST https://api.symphonyos.co/api/sym/v2/webhooks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/symphony",
    "eventType": "campaign.failed"
  }'

const eventTypes = ["campaign.created", "campaign.updated", "campaign.failed"];

for (const eventType of eventTypes) {
  await fetch("https://api.symphonyos.co/api/sym/v2/webhooks", {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      url: "https://your-app.com/webhooks/symphony",
      eventType
    })
  });
}

Example webhook payload

When an event fires, Symphony sends a POST request to your URL:

{
  "eventType": "campaign.created",
  "data": {
    "id": 98765,
    "name": "Hip Hop Release - US Link Clicks",
    "platform": "meta",
    "status": "TO_REVIEW",
    "startDate": "2026-04-01T00:00:00.000Z",
    "endDate": "2026-04-14T00:00:00.000Z",
    "budget": 300
  },
  "timestamp": "2026-04-01T00:01:23.456Z"
}

Headers included:

Content-Type: application/json
X-Symphony-Event: campaign.created

Handle webhooks in your server

app.post('/webhooks/symphony', (req, res) => {
  const eventType = req.headers['x-symphony-event'];
  const { data, timestamp } = req.body;

  switch (eventType) {
    case 'campaign.created':
      console.log(`Campaign ${data.id} created at ${timestamp}`);
      break;
    case 'campaign.updated':
      console.log(`Campaign ${data.id} updated`);
      break;
    case 'campaign.failed':
      console.error(`Campaign ${data.id} failed!`);
      // Alert your team, retry, etc.
      break;
  }

  // Respond 200 to acknowledge receipt
  res.sendStatus(200);
});

See the full Webhooks reference for all event types and management endpoints.