Integration Guide

This guide walks you through integrating the Symphony Advertising API from scratch — from getting your API key to launching your first campaign.

Step 1: Request API Access

Contact [email protected] with:

Your company name
A brief description of your use case (e.g., "We want to offer automated ad campaigns to our artist roster")
Expected volume (campaigns per month)

You'll receive an API key that authenticates all requests.

Step 2: Authenticate

All API requests require the x-api-key header.

Base URL: https://api.symphonyos.co/api/sym/v2/

Test your key:

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

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

Tip: Store your API key in an environment variable. Never commit it to source control.

Step 3: Create a Brand

A brand represents an artist or entity that owns ad accounts and campaigns. Create one:

curl -X POST https://api.symphonyos.co/api/sym/v2/brands \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

const response = await fetch("https://api.symphonyos.co/api/sym/v2/brands", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});
const { data } = await response.json();
console.log(data.id); // e.g., 12345

Response:

{
  "success": true,
  "data": {
    "id": 12345
  }
}

Save the id — you'll need it for all subsequent calls.

Step 4: Connect an Ad Platform

Connect the brand to Meta or TikTok by providing a platform access token. See Connecting Ad Platforms for the full OAuth flow to obtain tokens.

curl -X PUT https://api.symphonyos.co/api/sym/v2/brands \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": 12345,
    "adPlatform": "meta",
    "accessToken": "EAAxxxxxxx..."
  }'

await fetch("https://api.symphonyos.co/api/sym/v2/brands", {
  method: "PUT",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    brandId: 12345,
    adPlatform: "meta",
    accessToken: "EAAxxxxxxx..."
  })
});

Note: Ad platform connection is currently being finalized. During the beta period, you may need to coordinate with the Symphony team to complete setup.

Step 5: Search Targeting Inputs

Before creating a campaign, search for targeting parameters. All search endpoints accept { adPlatform, query }.

Search 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" }
  ]
}

Search 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" }
  ]
}

Search languages

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

Response:

{
  "success": true,
  "data": [
    { "id": "6", "name": "English" }
  ]
}

Step 6: Create Your First Campaign

With targeting data in hand, create a 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": "Summer Release Promo",
      "startDate": "2026-04-01T00:00:00.000Z",
      "endDate": "2026-04-14T00:00:00.000Z",
      "budget": 200,
      "currency": "USD",
      "promotedLink": "https://open.spotify.com/album/example",
      "captions": ["Check out our new summer release!"],
      "callToAction": "LISTEN_NOW",
      "targetingConfig": {
        "geographies": [
          { "id": "US", "type": "country", "name": "United States", "percentage": 100 }
        ],
        "audiences": [
          { "id": "6003139266461", "type": "InterestAudience", "name": "Hip hop music" }
        ],
        "languages": [
          { "id": "6", "name": "English" }
        ],
        "genders": ["MALE", "FEMALE"]
      }
    }
  }'

Response:

{
  "success": true,
  "data": {
    "id": 98765,
    "name": "Summer Release Promo",
    "platform": "meta",
    "status": "TO_REVIEW",
    "startDate": "2026-04-01T00:00:00.000Z",
    "endDate": "2026-04-14T00:00:00.000Z",
    "budget": 200
  }
}

Important: Campaign creation is asynchronous. The API returns immediately with the campaign record, but the actual submission to Meta/TikTok happens in the background. Monitor the campaign status via GET /campaigns/:campaignId or set up webhooks.

Step 7: Monitor Your Campaign

Check status

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

Get analytics

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

Set up webhooks

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"
  }'

See the full Webhooks guide for all event types and payload formats.

Next Steps

Common Use Cases — detailed worked examples for Meta, TikTok, managing campaigns, and webhooks
Connecting Ad Platforms — full Meta and TikTok OAuth setup
API Reference — complete endpoint documentation