Guides
Start typing to search…

Common Use Cases

Example 1: Create a Complete Pre-Save Page

// Step 1: Get track details from Spotify URL
const spotifyUrl = 'https://open.spotify.com/track/1cTZMwcBJT0Ka3UJPXOeeN';

// Step 2: Generate streaming links
const linksResponse = await fetch(
  'https://api.symphonyos.co/v2/sym/v2/streaming-links',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ spotifyUrl: spotifyUrl })
  }
);
const { data: streamingLinks } = await linksResponse.json();

// Step 3: Create website with pre-save
const websiteResponse = await fetch(
  'https://api.symphonyos.co/v2/sym/v2/website',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      brandId: 123,
      slug: 'drake-new-album-presave',
      status: 'published',
      websiteContent: [
        {
          type: 'image',
          content: { imageUrl: 'https://i.scdn.co/image/album_artwork.jpg' }
        },
        {
          type: 'text',
          content: {
            title: 'New Album Coming Soon',
            subtitle: 'Pre-save now to hear it first',
            isSubtitle: true
          }
        },
        {
          type: 'presave',
          content: {
            release_date: '2025-12-01T00:00:00Z',
            release_url_upc_isrc: spotifyUrl,
            platforms: [
              { name: 'spotify', isEnabled: true },
              { name: 'apple_music', isEnabled: true }
            ],
            boosts: {
              collect_emails: true,
              boost_follows: true
            }
          }
        },
        {
          type: 'streamingPlatforms',
          content: {
            platforms: Object.entries(streamingLinks).map(([name, link]) => ({
              name,
              link,
              isEnabled: true
            }))
          }
        }
      ],
      websiteStyle: {
        backgroundColor: '#000000',
        secondaryColor: '#1DB954',
        textColor: '#FFFFFF',
        fontFamily: 'Helvetica',
        textAlign: 'center'
      }
    })
  }
);

const { data: website } = await websiteResponse.json();
console.log('Pre-save page created:', website.url);

Example 2: Track Website Performance

async function trackWebsitePerformance(websiteId) {
  // Fetch analytics
  const response = await fetch(
    `https://api.symphonyos.co/v2/sym/v2/website/analytics/${websiteId}`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        timezone: 'America/Los_Angeles',
        startDate: '2024-01-01',
        endDate: '2024-01-31'
      })
    }
  );

  const { data: analytics } = await response.json();

  // Calculate key metrics
  const conversionRate = analytics.contentAnalytics.collectData
    ? (analytics.contentAnalytics.collectData.submissions / analytics.summary.uniqueVisitors) * 100
    : 0;

  const topPlatform = Object.entries(analytics.clicksByPlatform)
    .sort((a, b) => b[1] - a[1])[0];

  return {
    totalViews: analytics.summary.pageViews,
    uniqueVisitors: analytics.summary.uniqueVisitors,
    totalClicks: analytics.summary.totalClicks,
    signups: analytics.summary.signups,
    conversionRate: conversionRate.toFixed(2) + '%',
    topPlatform: topPlatform[0],
    topPlatformClicks: topPlatform[1],
    topCountry: analytics.geography.byCountry[0]?.country
  };
}

Example 3: Export Leads for CRM

async function exportLeadsToCRM(websiteId) {
  const response = await fetch(
    `https://api.symphonyos.co/v2/sym/v2/website/collected-data/${websiteId}`,
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );

  const { data: collectedData } = await response.json();

  // Transform for your CRM format
  const leads = [];
  for (const [collectorId, submissions] of Object.entries(collectedData)) {
    for (const submission of submissions) {
      leads.push({
        email: submission.email,
        phone: submission.phone,
        name: submission.name,
        source: 'SymphonyOS',
        sourceId: websiteId,
        collectorId: collectorId,
        timestamp: submission.timestamp,
        tags: ['website-signup', 'music-fan']
      });
    }
  }

  // Send to your CRM
  await yourCRM.importContacts(leads);

  return { imported: leads.length };
}

Quick Start Tutorials

These tutorials walk through common workflows step-by-step, showing you exactly how to use the API for real-world use cases.

Tutorial 1: Music Link Analytics

Goal: Create a universal music link hub and track which platforms fans prefer.

Steps:

  1. Generate Universal Links
curl -X POST https://api.symphonyos.co/v2/sym/v2/streaming-links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "spotifyUrl": "https://open.spotify.com/track/1cTZMwcBJT0Ka3UJPXOeeN"
  }'

Response:

{
  "data": {
    "spotify": "https://open.spotify.com/track/1cTZMwcBJT0Ka3UJPXOeeN",
    "apple_music": "https://music.apple.com/us/album/...",
    "youtube": "https://youtube.com/watch?v=...",
    "tidal": "https://tidal.com/browse/track/...",
    "deezer": "https://www.deezer.com/track/...",
    "amazon_music": "https://music.amazon.com/albums/..."
  },
  "message": "Streaming links retrieved successfully",
  "isError": false
}
  1. Create a Website with Streaming Links
curl -X POST https://api.symphonyos.co/v2/sym/v2/website \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": 123,
    "slug": "artist-new-single",
    "status": "published",
    "websiteContent": [
      {
        "type": "text",
        "content": {
          "title": "Listen Now",
          "isSubtitle": false
        }
      },
      {
        "type": "streamingPlatforms",
        "content": {
          "platforms": [
            {"name": "spotify", "link": "https://open.spotify.com/track/...", "isEnabled": true},
            {"name": "apple_music", "link": "https://music.apple.com/...", "isEnabled": true},
            {"name": "youtube", "link": "https://youtube.com/...", "isEnabled": true},
            {"name": "tidal", "link": "https://tidal.com/...", "isEnabled": true}
          ]
        }
      }
    ],
    "websiteStyle": {
      "backgroundColor": "#000000",
      "secondaryColor": "#1DB954",
      "textColor": "#FFFFFF",
      "fontFamily": "Inter",
      "textAlign": "center"
    }
  }'

Response:

{
  "data": {
    "id": 456,
    "brandId": 123,
    "slug": "artist-new-single",
    "status": "published",
    "url": "https://symphony.is/yourBrand/artist-new-single",
    "websiteContent": [...],
    "websiteStyle": {...},
    "createdAt": "2025-11-10T12:00:00Z",
    "updatedAt": "2025-11-10T12:00:00Z"
  },
  "message": "Website created successfully",
  "isError": false
}
  1. Get Analytics to See Platform Performance
curl -X POST https://api.symphonyos.co/v2/sym/v2/website/analytics/456 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "America/New_York",
    "startDate": "2025-11-01",
    "endDate": "2025-11-10"
  }'

Response:

{
  "data": {
    "summary": {
      "pageViews": 5420,
      "uniqueVisitors": 4103,
      "totalClicks": 2891,
      "signups": 0
    },
    "clicksByPlatform": {
      "spotify": 1245,
      "apple_music": 892,
      "youtube": 534,
      "tidal": 220
    },
    "geography": {
      "byCountry": [
        {"country": "United States", "views": 2103, "clicks": 1245},
        {"country": "United Kingdom", "views": 892, "clicks": 534},
        {"country": "Canada", "views": 445, "clicks": 267}
      ]
    },
    "devices": {
      "mobile": 3892,
      "desktop": 1420,
      "tablet": 108
    }
  },
  "message": "Queried website analytics",
  "isError": false
}

Key Insights: You can now see that Spotify gets the most clicks (1,245), followed by Apple Music (892). Most traffic is mobile (3,892 views) and comes from the US (2,103 views).

Tutorial 2: Link-in-Bio Page with Analytics

Goal: Create a comprehensive link-in-bio page with streaming links, social media, and tour dates.

Steps:

  1. Create Link-in-Bio Website
curl -X POST https://api.symphonyos.co/v2/sym/v2/website \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": 123,
    "slug": "artist-links",
    "status": "published",
    "websiteContent": [
      {
        "type": "image",
        "content": {
          "imageUrl": "https://cdn.example.com/artist-photo.jpg",
          "alt": "Artist Name"
        }
      },
      {
        "type": "text",
        "content": {
          "title": "Artist Name",
          "subtitle": "Official Links",
          "isSubtitle": true
        }
      },
      {
        "type": "streamingPlatforms",
        "content": {
          "platforms": [
            {"name": "spotify", "link": "https://open.spotify.com/artist/...", "isEnabled": true},
            {"name": "apple_music", "link": "https://music.apple.com/artist/...", "isEnabled": true},
            {"name": "youtube", "link": "https://youtube.com/@artist", "isEnabled": true}
          ]
        }
      },
      {
        "type": "socialPlatforms",
        "content": {
          "platforms": [
            {"name": "instagram", "link": "https://instagram.com/artist", "isEnabled": true},
            {"name": "tiktok", "link": "https://tiktok.com/@artist", "isEnabled": true},
            {"name": "twitter", "link": "https://twitter.com/artist", "isEnabled": true}
          ]
        }
      },
      {
        "type": "externalLinks",
        "content": {
          "title": "More Links",
          "style": "stackedRounded",
          "platforms": [
            {"title": "Shop Merch", "link": "https://shop.example.com", "isEnabled": true},
            {"title": "Newsletter", "link": "https://newsletter.example.com", "isEnabled": true}
          ]
        }
      },
      {
        "type": "collectData",
        "content": {
          "id": "email-collector-1",
          "title": "Join My Mailing List",
          "buttonText": "Subscribe",
          "postSubscribeMessage": "Thanks for subscribing!",
          "info": [
            {"title": "Email", "type": "email", "placeholder": "[email protected]"}
          ]
        }
      }
    ],
    "websiteStyle": {
      "backgroundColor": "#1a1a1a",
      "secondaryColor": "#ff6b6b",
      "textColor": "#ffffff",
      "fontFamily": "Inter",
      "textAlign": "center"
    }
  }'

Response:

{
  "data": {
    "id": 789,
    "brandId": 123,
    "slug": "artist-links",
    "status": "published",
    "url": "https://symphony.is/yourBrand/artist-links",
    "createdAt": "2025-11-10T12:00:00Z"
  },
  "message": "Website created successfully",
  "isError": false
}
  1. Track Overall Performance
curl -X POST https://api.symphonyos.co/v2/sym/v2/website/analytics/789 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "America/Los_Angeles",
    "startDate": "2025-11-01",
    "endDate": "2025-11-10"
  }'

Response:

{
  "data": {
    "summary": {
      "pageViews": 12450,
      "uniqueVisitors": 9823,
      "totalClicks": 5621,
      "signups": 892
    },
    "dailyStats": [
      {"date": "2025-11-01", "pageViews": 1203, "clicks": 534, "signups": 89},
      {"date": "2025-11-02", "pageViews": 1456, "clicks": 678, "signups": 102}
    ],
    "clicksByPlatform": {
      "spotify": 1834,
      "instagram": 1245,
      "tiktok": 923,
      "apple_music": 678,
      "twitter": 445,
      "youtube": 496
    },
    "contentAnalytics": {
      "streamingPlatforms": {
        "clicks": 3008,
        "clicksByPlatform": {
          "spotify": 1834,
          "apple_music": 678,
          "youtube": 496
        }
      },
      "collectData": {
        "submissions": 892,
        "conversionRate": 9.08
      }
    },
    "geography": {
      "byCountry": [
        {"country": "United States", "views": 5234, "clicks": 2891},
        {"country": "United Kingdom", "views": 2103, "clicks": 1023}
      ]
    }
  },
  "message": "Queried website analytics",
  "isError": false
}
  1. Export Collected Email Leads
curl -X GET https://api.symphonyos.co/v2/sym/v2/website/collected-data/789 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": {
    "email-collector-1": [
      {
        "email": "[email protected]",
        "timestamp": "2025-11-10T14:23:45Z"
      },
      {
        "email": "[email protected]",
        "timestamp": "2025-11-10T15:12:33Z"
      }
    ]
  },
  "message": "Retrieved collected data successfully",
  "isError": false
}

Key Insights: Your link-in-bio page got 12,450 views and 892 email signups (9.08% conversion rate). Instagram and Spotify are the most clicked links. You can now export these emails to your CRM.

Tutorial 3: Pre-Save Campaign with Analytics

Goal: Launch a pre-save campaign for an upcoming release and track fan engagement.

Steps:

  1. Create Pre-Save Website
curl -X POST https://api.symphonyos.co/v2/sym/v2/website \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": 123,
    "slug": "new-album-presave",
    "status": "published",
    "websiteContent": [
      {
        "type": "image",
        "content": {
          "imageUrl": "https://cdn.example.com/album-cover.jpg",
          "alt": "New Album Cover"
        }
      },
      {
        "type": "text",
        "content": {
          "title": "New Album: Coming December 1st",
          "subtitle": "Pre-save now to hear it first on release day",
          "isSubtitle": true
        }
      },
      {
        "type": "presave",
        "content": {
          "release_date": "2025-12-01T00:00:00Z",
          "release_url_upc_isrc": "https://open.spotify.com/album/...",
          "platforms": [
            {"name": "spotify", "isEnabled": true},
            {"name": "apple_music", "isEnabled": true},
            {"name": "deezer", "isEnabled": true}
          ],
          "boosts": {
            "auto_presaves": false,
            "boost_follows": true,
            "collect_emails": true
          },
          "redirect_url": "https://yoursite.com/thank-you",
          "is_real_time_release": false
        }
      },
      {
        "type": "socialPlatforms",
        "content": {
          "platforms": [
            {"name": "instagram", "link": "https://instagram.com/artist", "isEnabled": true},
            {"name": "tiktok", "link": "https://tiktok.com/@artist", "isEnabled": true}
          ]
        }
      }
    ],
    "websiteStyle": {
      "backgroundColor": "#0B0D17",
      "secondaryColor": "#6C5CE7",
      "textColor": "#FFFFFF",
      "fontFamily": "Helvetica",
      "textAlign": "center"
    },
    "scheduledDate": null
  }'

Response:

{
  "data": {
    "id": 991,
    "brandId": 123,
    "slug": "new-album-presave",
    "status": "published",
    "url": "https://symphony.is/yourBrand/new-album-presave",
    "websiteContent": [...],
    "createdAt": "2025-11-10T12:00:00Z"
  },
  "message": "Website created successfully",
  "isError": false
}
  1. Monitor Pre-Save Performance
curl -X POST https://api.symphonyos.co/v2/sym/v2/website/analytics/991 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "America/New_York",
    "startDate": "2025-11-10",
    "endDate": "2025-11-30"
  }'

Response:

{
  "data": {
    "summary": {
      "pageViews": 28934,
      "uniqueVisitors": 23421,
      "totalClicks": 15632,
      "signups": 8934
    },
    "dailyStats": [
      {"date": "2025-11-10", "pageViews": 1456, "clicks": 823, "signups": 445},
      {"date": "2025-11-11", "pageViews": 1823, "clicks": 1034, "signups": 567}
    ],
    "contentAnalytics": {
      "presave": {
        "submissions": 8934,
        "byPlatform": {
          "spotify": 5623,
          "apple_music": 2456,
          "deezer": 855
        }
      }
    },
    "clicksByPlatform": {
      "spotify": 5623,
      "apple_music": 2456,
      "deezer": 855,
      "instagram": 3245,
      "tiktok": 3453
    },
    "geography": {
      "byCountry": [
        {"country": "United States", "views": 12456, "clicks": 7234},
        {"country": "United Kingdom", "views": 5623, "clicks": 3245},
        {"country": "Canada", "views": 3892, "clicks": 2103}
      ],
      "byCity": [
        {"city": "Los Angeles", "country": "United States", "views": 3456},
        {"city": "New York", "country": "United States", "views": 2891},
        {"city": "London", "country": "United Kingdom", "views": 2345}
      ]
    },
    "devices": {
      "mobile": 21456,
      "desktop": 6234,
      "tablet": 1244
    }
  },
  "message": "Queried website analytics",
  "isError": false
}
  1. Export Pre-Save Fan Data

Pre-save data is stored as collected data. Fetch it using:

curl -X GET https://api.symphonyos.co/v2/sym/v2/website/collected-data/991 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": {
    "presave-collector": [
      {
        "email": "[email protected]",
        "platform": "spotify",
        "timestamp": "2025-11-10T14:23:45Z"
      },
      {
        "email": "[email protected]",
        "platform": "apple_music",
        "timestamp": "2025-11-10T15:12:33Z"
      }
    ]
  },
  "message": "Retrieved collected data successfully",
  "isError": false
}

Key Insights: Your pre-save campaign generated 8,934 pre-saves from 23,421 unique visitors (38.1% conversion rate). Spotify is the most popular platform (5,623 pre-saves), followed by Apple Music (2,456). You collected 8,934 fan emails that you can now use for future marketing campaigns.

Developer Tips

Combining Workflows

You can combine these workflows for even more powerful use cases:

Example: Pre-Save → Link-in-Bio Transition

  1. Create a pre-save website before release
  2. On release day, use PUT /sym/v2/website/:websiteId to update the content
  3. Replace the pre-save block with streaming links
  4. Keep the same URL so all your marketing links still work
# Update website on release day
curl -X PUT https://api.symphonyos.co/v2/sym/v2/website/991 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "websiteContent": [
      {
        "type": "text",
        "content": {"title": "New Album Out Now!", "isSubtitle": false}
      },
      {
        "type": "streamingPlatforms",
        "content": {
          "platforms": [
            {"name": "spotify", "link": "https://open.spotify.com/album/...", "isEnabled": true},
            {"name": "apple_music", "link": "https://music.apple.com/album/...", "isEnabled": true}
          ]
        }
      }
    ]
  }'

Webhooks for Automation

Set up webhooks to automate your workflow:

curl -X POST https://api.symphonyos.co/v2/sym/v2/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/symphony",
    "eventType": "lead.captured"
  }'

Now every time a fan signs up, we'll POST to your endpoint in real-time:

{
  "event": "lead.captured",
  "timestamp": "2025-11-10T14:23:45Z",
  "data": {
    "websiteId": 991,
    "brandId": 123,
    "email": "[email protected]",
    "collectDataId": "presave-collector"
  }
}

You can then automatically add fans to your CRM, send welcome emails, or trigger other automations.

Document Version: 2.0
Last Updated: November 10, 2025
Contact: [email protected]

Updated about 1 month ago