Create campaigns
There are two groups of campaigns:
- Facebook campaigns (do not generate a direct spend, paid campaigns run directly on your Facebook ad account)
- Symphony campaigns (require an instant direct payment)
There are metadata attributes every campaign needs when creating it:
{
"campaign_type": "get_playlisted",
"provider": "symphony",
"campaign_name": "campaign getPlaylisted API",
"metadata": {
"spotify_id": "3rmGAbshQvQHhy3sgHidNT",
"tier": "30000_followers",
"pitch_notes": "test pitch notes"
}
}campaign_type: there are 5 possible values for this:- record_streams
- boost_instagram
- link_clicks
- get_playlisted
- increase_video_views
provider: there are two values for this, representing the two group of campaign mentioned before:- symphony
campaign_name: it can be any name you want for your campaign.metadata: the specific values for each campaign, this will be covered in more detail in each campaign type creation flow
Meta (IG/FB) Campaigns API
Common attributes for every Meta (Facebook) campaign.
Requirements
In order to create a Meta campaign you need to have completed one of the connection options before. Connection Options
Payments
- Handled via Facebook Ad account when campaigns start running
- Bill is sent by Facebook on a monthly cadence to partner / ad account owner
Metadata
These metadata attributes are used by all three Meta campaigns. Examples are provided inside each specific campaign type description
{
"budget": {
"value": number,
"currency": string // e.g. USD, MXN, INR, JPY
},
"start_date": string, // date in ISO format
"end_date": string, // date in ISO format
"call_to_action": string, // e.g. LEARN_MORE, SHOP_NOW
"instagram_post_id": string, // id provided by meta
"public_video_links": [
{
"url": string, // public url for video
"name": string,
"thumbnail?": string // optional public url for thumbnail
}
],
"public_image_links": [
{
"url": string, // public url for image
"name": string,
"thumbnail": string // optional public url for thumbnail
}
],
"targeting_countries": [
{
"name": string,
"budget": number, // from 0 - 1 represents percentage
"locations": [
{
"value": string, // provided by Meta
"label": string, // provided by Meta
"type": string, // provided by Meta
"region_id": string, // provided by Meta
"country_code": string // provided by Meta
},
]
}
],
"targeting_audiences": [
{
"fbId": string, // optional, provided by Meta
"name": string // provided by Meta
},
],
"targeting_demographic": {
"age": {
"min": number, // min 18
"max": number // max 65
},
"gender": string, // All, Male, Female
"languages": [
{
"key": number, // provided by Meta
"name": string, // provided by Meta
},
]
}
}Budget
value: number representing the amount of money the campaign will spend in its entirely lifetime, it has a minimum constraint of 10 USD dollars a day, or its equivalent in the chosen currency.currency: the currency code that is used in the ad account that is connected to the brand, if a different currency is set, the request will return a 400 error asking to match currencies.
Assets
The request requires a media field, which can be either an instagram_post_id, public_video_links or public_image_links but not the three of them as you see in the example. If more than one is passed, only one is going to be taken when creating the ad, the order in priority comes like this: instagram_post_id > public_video_links > public_image_links . The instagram_post_id represents a post from your instagram account linked to a facebook page that is connected to your ad account, which you can retrieve by listing posts through the following endpoint:
curl -X GET {{ADVERTISING_API}}/v1/meta/instagram/posts \-
The response will provide.
{ "id": "string", "ig_id": "string", "permalink": "string", "caption": "string", "media_product_type": "string", "media_type": "string", "media_url": "string", "is_shared_to_feed": true, "like_count": 0, "comments_count": 0, "thumbnail_url": "string", "timestamp": "2025-01-25T21:41:30.107Z", "username": "string" }
If you prefer to upload a video or image, you should provide the public URL(s) of the video(s)/image(s) in the public_video_links, public_image_links fields, which are arrays that can contain up to three videos/images. The thumbnail field is optional, if it is a video you can specify a format_type of content or the manner in which the video will be displayed, such as a reel, story, or feed.
-
Request example:
curl -X POST {{ADVERTISING_API}}/v1/campaign \ -H 'Content-Type: application/json' \ -d '{ "provider": "facebook", "campaign_type": "boost_instagram", "campaign_name": "test create campaign boost", "metadata": { "budget": { "value": 190, "currency": "MXN" }, "start_date": "2024-10-04T05:00:00.000Z", "end_date": "2024-10-05T05:00:00.000Z", "call_to_action": "LEARN_MORE", "public_video_links": [ { "format_type": "story", "name": "phoneVideo", "thumbnail": "https://res.cloudinary.com/symphonyos/video/upload/c_limit,h_60,w_90/v1722633952/symphony/phoneVideo_o5ncrd.jpg", "url": "https://res.cloudinary.com/symphonyos/video/upload/v1722633952/symphony/phoneVideo_o5ncrd.mp4" } ] }'
Targeting
The targeting options are separated in 3 sections:
-
targeting_countries: A list of maximum 3 objects, each object represent a Campaign in Facebook (we call it Markets), this means that if you add more than one market, you’ll have more than one campaign created in Facebook, and the difference between them will be only the geographic targeting. The attributes for this targeting option are:name: the name of the market, this is the name that will identify your market, as well as it’s id once is created in Facebook.budget: takes a number between0and1, represents the percentage of the overall budget you set to your campaign, if you add more than one Market, the sum of every budget attribute in all your Markets should be equal to1, representing that all Markets together use the 100% of the campaign budget.locations: this is a list of locations that your campaign will run in, you can set countries, regions and cities, to get the locations data you need to set here, you can retrieve them from the following endpoint
curl -X GET {{ADVERTISING_API}}/[v1/meta/locations/search](https://development.partner.symphonyos.co/advertising/v1/meta/locations/search) \ -H 'accept: application/json' \ -H 'x-api-key: {{partner_api_key}}'Request example:
curl -X GET {{ADVERTISING_API}}/[v1/meta/locations/search](https://development.partner.symphonyos.co/advertising/v1/meta/locations/search)?keyword=US \ -H 'accept: application/json' \ -H 'x-api-key: {{partner_api_key}}'The response will provide.
{ "data": [ { "key": "794449", "name": "Us", "type": "city", "country_code": "FR", "country_name": "Francia", "region": "Île-de-France", "region_id": 1078, "supports_region": true, "supports_city": true }, { "key": "SE", "name": "Suecia", "type": "country", "country_code": "SE", "country_name": "Suecia", "supports_region": true, "supports_city": true }, { "key": "3889", "name": "Virginia", "type": "region", "country_code": "US", "country_name": "Estados Unidos", "supports_region": true, "supports_city": true }, { "key": "3876", "name": "North Carolina", "type": "region", "country_code": "US", "country_name": "Estados Unidos", "supports_region": true, "supports_city": true }, { "key": "CH", "name": "Suiza", "type": "country", "country_code": "CH", "country_name": "Suiza", "supports_region": true, "supports_city": true }, { "key": "3853", "name": "Georgia", "type": "region", "country_code": "US", "country_name": "Estados Unidos", "supports_region": true, "supports_city": true }, { "key": "2533778", "name": "Carlota Amalia", "type": "city", "country_code": "VI", "country_name": "Islas Vírgenes de Estados Unidos", "region": "US Virgin Islands", "region_id": 5045, "supports_region": false, "supports_city": true }, { "key": "2708436", "name": "Saint John", "type": "city", "country_code": "VI", "country_name": "Islas Vírgenes de Estados Unidos", "region": "US Virgin Islands", "region_id": 5045, "supports_region": false, "supports_city": true }, { "key": "2420379", "name": "Los Ángeles", "type": "city", "country_code": "US", "country_name": "Estados Unidos", "region": "California", "region_id": 3847, "supports_region": true, "supports_city": true }, { "key": "3875", "name": "New York", "type": "region", "country_code": "US", "country_name": "Estados Unidos", "supports_region": true, "supports_city": true } ], "status": 200 }Default value for
targeting_countries:[ { "type": "country", "label": "Australia", "value": "AU", "region_id": null, "country_code": null, }, { "type": "country", "label": "Canada", "value": "CA", "region_id": null, "country_code": null, }, { "type": "country", "label": "Germany", "value": "DE", "region_id": null, "country_code": null, }, { "type": "country", "label": "France", "value": "FR", "region_id": null, "country_code": null, }, { "type": "country", "label": "United Kingdom", "value": "GB", "region_id": null, "country_code": null, }, { "type": "country", "label": "New Zealand", "value": "NZ", "region_id": null, "country_code": null, }, { "type": "country", "label": "United States of America", "value": "US", "region_id": null, "country_code": null, }, ] -
targeting_audiences: a list of interest you want your targeting audience to have, this can be from artists, to music genres, to hobbies. To get the interest data you need to set here, you can retrieve them from the following endpoint:curl -X GET {{ADVERTISING_API}}/v1/meta/interest/search \ -H 'accept: application/json' \ -H 'x-api-key: {{partner_api_key}}'Request example:
curl -X GET {{ADVERTISING_API}}/v1/meta/interest/search?keyword=indie%20pop \ -H 'accept: application/json' \ -H 'x-api-key: {{partner_api_key}}'The response will provide.
{ "data": [ { "id": "6003278637610", "name": "Indie pop", "audience_size_lower_bound": 74537074, "audience_size_upper_bound": 87655600, "path": [ "Intereses", "Otros intereses", "Indie pop" ], "description": null, "topic": "News and entertainment" } ], "status": 200 }The
idattribute maps tofbIdin ourtargeting_audiencesDefault value for
targeting_audiencesif not passed: Symphony will add interest audiences based on the spotify artist you are promoting only if your target is to small that your campaign will not be able to run with the provided budget. -
targeting_demographic: represents you demographic audience,- age: you can go from
18as minimum, to65 - gender: options are
All,Male,Female. - languages: to get the languages data you need to retrieve them from the following endpoint.
curl -X GET {{ADVERTISING_API}}/v1/meta/language/search \ -H 'accept: application/json' \ -H 'x-api-key: {{partner_api_key}}'Request example:
curl -X GET {{ADVERTISING_API}}/v1/meta/language/search?keyword=english \ -H 'accept: application/json' \ -H 'x-api-key: {{partner_api_key}}'The response will provide.
{ "data": [ { "name": "English (US)", "key": 6 }, { "name": "English (UK)", "key": 24 } ], "status": 200 }- Default value for
targeting_demographicif not passed:
{ "age": { "max": 28, "min": 18, }, "gender": "All", "languages": [ { "key": 6, "name": "English (US)", "selected": true, }, { "key": 24, "name": "English (UK)", "selected": true, }, ], } - age: you can go from
Note: The budget.currency must match the currency set in your Facebook ad account; otherwise, an error will be triggered.
Increase Music Streams
This playbook is geared towards running IG ads to DSPs, to drive Spotify, Apple, or any other streaming service.
Symphony’s API automatically configures campaigns, adsets, audiences, and ads in the partner’s ad account - and provides a seamless way to access realtime stats.
- A specific Spotify account or URL is required
- Facebook Ad account link is required
To create a campaign that increases music streams (record_streams), you should follow the same metadata as before but with the addition of two fields: spotify_link, which is the URL of the release you want to promote, and spotify_external_platforms.
Steps
-
Select the content to advertise. We will expose an endpoint to return the albums and tracks linked to the artist through the Spotify account previously configured under
/advertising/v1/brand_content/record/streamscurl -X GET {{ADVERTISING_API}}/v1/brand_content/record_streams?keyword=${slug_or_name_of_release}-
The response will provide a list of releases that closely match your keyword. You should select the
idof the release you wish to promote, along with any associated external platforms, if available.{ "id": 41388, "brand_id": 358, "type": "record_streams", "name": "Entre Roma y Viena", "slug": "entre-roma-y-viena", "createdAt": "2023-01-09T08:11:53.986Z", "updatedAt": "2024-03-27T18:20:18.388Z", "url": "skrlth-entre-roma-y-viena", "spotify_id": "78TWg6fTRLxGKYN5RiSsQt", "record_url": "https://open.spotify.com/album/78TWg6fTRLxGKYN5RiSsQt", "release_date": "2023-01-11", "thumbnail_url": "https://i.scdn.co/image/ab67616d0000b273b6cada9f4c723d8645647508", "external_links": [ { "url": "https://music.amazon.com/albums/B0BRXRQ3BF", "name": "amazon_music", "type": "amazon_music", "enabled": true } ] }
-
-
Select the media. Users can decide between
- Existing Instagram post. No params are required as they will be pulled from the account linked in the onboarding setup
- Create a new one by link provided. Provide a valid url to a video or image that follows the Facebook practices listed here
Media - Instagram Platform - Documentation - Meta for Developers
-
Select platforms. At least one is required.
- Spotify
- Apple Music
- Youtube
- Custom Link
-
Select Budget
- With start date and end date
-
Select Targeting. (Optional, Symphony will provide default values for this)
-
Similar Artists. We will expose an endpoint to search for interest on Facebook. It can be by only providing the name in an Array. E. g.
["Bad Bunny", "Summer Walker", "Ice Spice"] -
Locations
-
Age. To target people between the age of 18 - 65
-
Gender. All, Male or Female
-
Languages. Array of languages to use. E. g.
["English", "Spanish"]
-
-
Create Campaign. Send all the previous information collected to this endpoint
/advertising/v1/campaign.-
e. g.
curl -X POST {{ADVERTISING_API}}/v1/campaign \ -H "Content-Type: application/json" \ -d '{ "provider": "facebook", "campaign_type": "record_streams", "campaign_name": "campaign Record Stream from API", "metadata": { "budget": { "value": 12, "currency": "USD" }, "start_date": "2024-08-20T05:00:00.000Z", "end_date": "2024-08-21T05:00:00.000Z", "call_to_action": "LEARN_MORE", "instagram_post_id": "17921761666746619", "public_video_links": [ { "url": "https://res.cloudinary.com/symphonyos/video/upload/v1721403225/symphony/car2_aroyzh.webm", "name": "video test loading", "thumbnail": "https://res.cloudinary.com/symphonyos/video/upload/c_limit,h_60,w_90/v1721403225/symphony/car2_aroyzh.jpg" } ], "public_image_links": [ { "url": "https://res.cloudinary.com/symphonyos/image/upload/v1721403225/symphony/car2_aroyzh.webm", "name": "image test loading", "thumbnail": "https://res.cloudinary.com/symphonyos/image/upload/c_limit,h_60,w_90/v1721403225/symphony/car2_aroyzh.jpg" } ], "spotify_id": "2M4ujJtsYiiUISmuntBJn7", "spotify_external_platforms": [ "https://www.youtube.com/watch?v=EpAkZtsYU3U", "https://geo.music.apple.com/tr/album/_/1541250609?i=1541250816&mt=1&app=music&ls=1" ], "targeting_countries": [ { "name": "Recommended Markets", "budget": 1, "locations": [ { "value": "US", "label": "United States of America", "type": "country", "region_id": null, "country_code": null }, { "value": "3847", "label": "California", "type": "region", "country_code": "US" }, { "value": "2420379", "label": "Los Angeles", "type": "city", "region_id": 3847, "country_code": "US" }, { "value": "GB", "label": "United Kingdom", "type": "country", "region_id": null, "country_code": null } ] } ], "targeting_audiences": [ { "fbId": "6003317001363", "name": "Zendaya" }, { "fbId": "6003278637610", "name": "Indie pop" } ], "targeting_demographic": { "age": { "min": 18, "max": 35 }, "gender": "All", "languages": [ { "key": 6, "name": "English (US)", "selected": true }, { "key": 24, "name": "English (UK)", "selected": true } ] } } }'
-
Instagram Boost
Boost your Instagram profile engagement by putting your content in front of new followers using automated highly-targeted, Instagram ads.
- Facebook Ad account linked is required
Steps
- Select the media. Users can decide between
-
Existing Instagram post. No params are required as they will be pull from the account linked in the onboarding setup
-
Create a new one by link provided. Provide a valid url to a video or image that follows the Facebook practices listed here.
Media - Instagram Platform - Documentation - Meta for Developers
-
- Select Budget
- With start date and end date
- Select Targeting. (Optional, Symphony will provide default values for this)
-
Similar Artists. We will expose an endpoint to search for interest on Facebook. It can be by only providing the name in an Array. E. g.
["Bad Bunny", "Summer Walker", "Ice Spice"] -
Locations
-
Age. To target people between the age of 18 - 65
-
Gender. All, Male or Female
-
Languages. Array of languages to use. E. g.
["English", "Spanish"]
-
- Create Campaign. Send all the previous information collected to this endpoint
/advertising/v1/campaign.-
e.g.
curl -X POST {{ADVERTISING_API}}/v1/campaign \ -H 'Content-Type: application/json' \ -d '{ "provider": "facebook", "campaign_type": "boost_instagram", "campaign_name": "test create campaign boost", "metadata": { "budget": { "value": 12, "currency": "USD" }, "start_date": "2024-08-20T05:00:00.000Z", "end_date": "2024-08-21T05:00:00.000Z", "call_to_action": "LEARN_MORE", "instagram_post_id": "17921761666746619", "public_video_links": [ { "url": "https://res.cloudinary.com/symphonyos/video/upload/v1721403225/symphony/car2_aroyzh.webm", "name": "video test loading", "thumbnail": "https://res.cloudinary.com/symphonyos/video/upload/c_limit,h_60,w_90/v1721403225/symphony/car2_aroyzh.jpg" } ], "public_image_links": [ { "url": "https://res.cloudinary.com/symphonyos/image/upload/v1721403225/symphony/car2_aroyzh.webm", "name": "image test loading", "thumbnail": "https://res.cloudinary.com/symphonyos/image/upload/c_limit,h_60,w_90/v1721403225/symphony/car2_aroyzh.jpg" } ], "spotify_id": "2M4ujJtsYiiUISmuntBJn7", "spotify_external_platforms": [ "https://www.youtube.com/watch?v=EpAkZtsYU3U", "https://geo.music.apple.com/tr/album/_/1541250609?i=1541250816&mt=1&app=music&ls=1" ], "targeting_countries": [ { "name": "Recommended Markets", "budget": 1, "locations": [ { "value": "US", "label": "United States of America", "type": "country", "region_id": null, "country_code": null }, { "value": "3847", "label": "California", "type": "region", "country_code": "US" }, { "value": "2420379", "label": "Los Angeles", "type": "city", "region_id": 3847, "country_code": "US" }, { "value": "GB", "label": "United Kingdom", "type": "country", "region_id": null, "country_code": null } ] } ], "targeting_audiences": [ { "fbId": "6003317001363", "name": "Zendaya" }, { "fbId": "6003278637610", "name": "Indie pop" } ], "targeting_demographic": { "age": { "min": 18, "max": 35 }, "gender": "All", "languages": [ { "key": 6, "name": "English (US)", "selected": true }, { "key": 24, "name": "English (UK)", "selected": true } ] } } }'
-
Link Clicks
Drive highly-targeted traffic from Instagram to your merch store, tickets page, or anywhere else.
- Facebook Ad account linked is required
To create a campaign with the goal of increases link cliks (link_clicks), you should follow the same metadata as before but with the addition of two fields: link_to_boost, and caption caption.
Steps
- Select a valid link to promote. E.g. https://skrlth.bigcartel.com/
- Select the media. Users can decide between
-
Existing Instagram post. No params are required as they will be pull from the account linked in the onboarding setup
-
Create a new one by link provided. Provide a valid url to a video or image that follows the Facebook practices listed here.
Media - Instagram Platform - Documentation - Meta for Developers
-
- Select Budget
- With start date and end date
- Select Targeting. (Optional, Symphony will provide default values for this)
-
Similar Artists. We will expose an endpoint to search for interest on Facebook. It can be by only providing the name in an Array. E. g.
["Bad Bunny", "Summer Walker", "Ice Spice"] -
Locations
-
Age. To target people between the age of 18 - 65
-
Gender. All, Male or Female
-
Languages. Array of languages to use. E. g.
["English", "Spanish"]
-
- Create Campaign. Send all the previous information collected to this endpoint
/advertising/v1/campaign.-
e.g.
curl -X POST {{ADVERTISING_API}}/v1/campaign \ -H "Content-Type: application/json" \ -d '{ "provider": "facebook", "campaign_type": "link_clicks", "campaign_name": "campaign Link clicks from API", "metadata": { "budget": { "value": 12, "currency": "USD" }, "start_date": "2024-08-20T05:00:00.000Z", "end_date": "2024-08-21T05:00:00.000Z", "call_to_action": "LEARN_MORE", "instagram_post_id": "17921761666746619", "public_video_links": [ { "url": "https://res.cloudinary.com/symphonyos/video/upload/v1721403225/symphony/car2_aroyzh.webm", "name": "video test loading", "thumbnail": "https://res.cloudinary.com/symphonyos/video/upload/c_limit,h_60,w_90/v1721403225/symphony/car2_aroyzh.jpg" } ], "public_image_links": [ { "url": "https://res.cloudinary.com/symphonyos/video/upload/v1721403225/symphony/car2_aroyzh.webm", "name": "video test loading", "thumbnail": "https://res.cloudinary.com/symphonyos/video/upload/c_limit,h_60,w_90/v1721403225/symphony/car2_aroyzh.jpg" } ], "link_to_boost": "https://www.goodreads.com/book/show/5907.The_Hobbit?ref=rae_2", "caption": "test caption", "targeting_countries": [ { "name": "Recommended Markets", "budget": 1, "locations": [ { "value": "US", "label": "United States of America", "type": "country", "region_id": null, "country_code": null }, { "value": "3847", "label": "California", "type": "region", "country_code": "US" }, { "value": "2420379", "label": "Los Angeles", "type": "city", "region_id": 3847, "country_code": "US" }, { "value": "GB", "label": "United Kingdom", "type": "country", "region_id": null, "country_code": null } ] } ], "targeting_audiences": [ { "fbId": "6003317001363", "name": "Zendaya" }, { "fbId": "6003278637610", "name": "Indie pop" } ], "targeting_demographic": { "age": { "min": 18, "max": 35 }, "gender": "All", "languages": [ { "key": 6, "name": "English (US)", "selected": true }, { "key": 24, "name": "English (UK)", "selected": true } ] } } }'
-
Playlist + YouTube Campaigns
Get Playlisted
Grow your Spotify monthly listeners & followers by pitching potential listeners on high-traffic user-generated Spotify playlists.
- Spotify account linked is required
Payments
- Handled by Symphony’s Stripe account
- For every campaign created we will charge the amount to the partners customer account previously configured in the onboarding setup
Steps
- Select the content to advertise. We will expose an endpoint to return the albums and tracks linked to the artist through the Spotify account previously configured under
/advertising/brand_content/record/streams - Select Campaign Goal
- 30K Followers
- Pitch your song to playlists with a combined following of over 30K followers.
- 100K Followers
- Pitch your song to playlists with a combined following of over 100K followers.
- 300K Followers
- Pitch your song to playlists with a combined following of over 300K followers.
- 600K Followers
- Pitch your song to playlists with a combined following of over 600K followers.
- 1M Followers
- Pitch your song to playlists with a combined following of over 1M followers.
- 30K Followers
- TBD. Create campaign.
Increase Video Views
Grow your YouTube video views & subscribers by targeting high-value fans with smart YouTube ads.
- Youtube account linked is required
Payments
- Handled by Symphony’s Stripe account
- For every campaign created we will charge the amount to the partners customer account previously configured in the onboarding setup
Steps
-
Select youtube video.
- From partners artist youtube account. We will expose an endpoint to return videos in order to select one under
/advertising/youtube/videosNo params are required as they will be pull from the account linked in the onboarding setup
- From partners artist youtube account. We will expose an endpoint to return videos in order to select one under
-
Select Campaign Type
- Cheapest views
- More Engagement
-
Select Locations
- Global Markets
- English-speaking Markets
- Custom
-
Select Targeting. We will expose an endpoint to search for youtube channels to target. It can be by only providing the names in an Array. E. g.
["Bad Bunny", "Summer Walker", "Ice Spice"] -
Select Budget
- With start date and end date
-
TBD. Create campaign.
Response
Campaign Creation Response
Upon successfully creating a campaign, the API will return a response in the following format:
{
"data": {
"id": 1234,
"type": "boost_instagram",
"status": "ACTIVE",
"provider": "facebook"
},
"status": 200
}Fields Explained:
id: Unique identifier of the campaign.type: Type of campaign created (e.g.,boost_instagram,record_streams).status: Current campaign status, typicallyACTIVEorIN_REVIEWafter creation.provider: Campaign provider,facebookorsymphony.status: HTTP response code indicating the success of the request (200for success).
Asynchronous Processing
Campaign creation is an asynchronous process, as Facebook may require time to prepare assets (e.g., videos, images) or validate campaign configurations. Due to this delay, attempting to execute the campaign immediately after creation may result in errors.
To handle this, the API notifies the campaign's lifecycle stages through webhooks. These webhooks allow you to monitor the progress and status of campaigns seamlessly.
Campaigns Management
The scope of these endpoints is built depending on the partner’s needs for reporting, as well as the editing functionality they’d like to expose:
- Retrieve Campaign: 3.2 Get Campaign Details
- Analytics: 3.2.3 Fetch Campaign-Level Analytics
- Edit Budget and End Date: Budget/End Date
- Edit Locations: Locations
- Pause and Unpause: Pause/Resume Location
Edit Campaigns
Budget/End Date
Requirements
You must have received a webhook with the event: campaign.completed to perform this operation over a campaign.
Endpoint: PUT /advertising/v1/campaign/{id}
Description: Updates campaign End Date, Budget or both.
Request Example:
curl -X 'PUT' \
'{{ADVERTISING_API}}/v1/campaign/5017' \
-H 'accept: application/json' \
-H 'x-api-key: {{YOUR_API_KEY}}' \
-d '{
"end_date": "2025-05-05T00:00:00Z",
"budget": {
"currency": "MXN",
"value": 2010
}
}'Locations
Requirements
You must have received a webhook with the event: campaign.completed to perform this operation over a campaign.
Add location
Endpoint: PATCH /advertising/v1/campaign/{id}/location/add
Description: Adds one or multiple locations to campaign’s targeting options
Payload:
- market_id represents the campaignId from facebook, you can get it from
campaign_metadata>platform_details>campaignsMapping>fbCampaign>idby consulting the campaign details 3.2.1 Fetch Campaign Information - locations: you can obtain locations by calling the corresponding meta resource endpoint.
Request Example:
curl -X 'PUT' \
'{{ADVERTISING_API}}/v1/campaign/5017/location/add' \
-H 'accept: application/json' \
-H 'x-api-key: {{YOUR_API_KEY}}' \
-d '{
"market_id": "6676212031486",
"locations": [
{
"key": "689194",
"name": "Madrid",
"type": "city",
"region": "Comunidad de Madrid",
"region_id": 1019,
"country_code": "ES",
"country_name": "España",
"supports_city": true,
"supports_region": true
}
]
}'Pause/Resume Location
Endpoint: PUT /advertising/v1/campaign/{id}/location/PAUSED
Description: Pause or resume provided location
Payload:
- market_id represents the campaignId from facebook, you can get it from
campaign_metadata>platform_details>campaignsMapping>fbCampaign>idby consulting the campaign details 3.2.1 Fetch Campaign Information - location_key: you can obtain locations by consulting your campaign details 3.2.1 Fetch Campaign Information
Request Example:
curl -X 'PUT' \
'{{ADVERTISING_API}}/v1/campaign/5017/location/PAUSED' \
-H 'accept: application/json' \
-H 'x-api-key: {{YOUR_API_KEY}}' \
-d '{
"location_key": "689194",
"market_id": "6676212031486"
}'Pause/Resume Campaign
You can call this endpoint on a campaign that hasn’t been completed yet, or when it is completed and running, if you call it before it is completed, symphony will not process the campaign next time until you resume it. For campaigns that are already running it will simply pause it or resume it.
Endpoint: PUT /advertising/v1/campaign/{id}/{status}
Description: Pause or resume provided campaign
Payload:
- Status:
PAUSE|ACTIVE
Request Example:
curl -X 'PUT' \
'{{ADVERTISING_API}}/v1/campaign/5017/PAUSE' \
-H 'accept: application/json' \
-H 'x-api-key: {{YOUR_API_KEY}}' Webhook Updates
Updated about 2 months ago