Launch Campaigns

The Launch API endpoint runs your ads through the template you've created at Scalemate

Endpoint Details

URL: https://api.scalemate.co/api/external/v1/launch Method: POST

Headers

Content-Type: application/json
X-Api-Key: <YOUR_API_KEY>

You can generate the API Key at the Settings page under API Key section

Parameters

file_links	Mixed (required) string[] OR { url, title, description, destination_url }[]	List of URLs pointing to files needed for the workflow. Each link should be accessible from this endpoint. Custom descriptions supported only for Meta Ads templates url - Required title - Optional description - Optional destination_url - Optional If optional fields not passed Scalemate will use data from template
destination_url	string (Optional)	Valid URL to page you want to promote
template_id	string (Required)	Specifies the template ID to use for the workflow. It can be found at the end of the URL.
schedule_date	string (Optional)	Specifies the scheduled launch time for the campaign in ISO 8601 format.
max_creatives_per_adset	number (Optional)	Rewrites Ad set configuration max number ads
pac_rules	object (Optional) stories: string | undefined feed: string | undefined search: string | undefined	Defines the rules for distributing ad creatives across different placements by using Placement Asset Customization. Supports only the following placement keys: stories, feed, and search. Each key accepts a string value that should contain part of the asset’s name to help identify which asset should be used for which placement. This field can be an empty string or entirely omitted if no customization is required for a specific placement. Example: {"stories": "16x9", "feed": "4x3", "search": "1x1" }
webhook_url	string (Optional)	The URL that will receive the webhook callback. Once the event is triggered, a POST request will be sent to this URL containing the relevant payload. This must be a publicly accessible HTTPS endpoint.
campaign_name_override	string (Optional)	Override campaign name created during launch. Meta Ads Only
adset_name_override	string (Optional)	Override ALL ad set names created during launch. Meta Ads Only
config_id	string (Optional)	ID of a saved Configuration to overrides to the launch. Will override the template's settings for ALL adsets created in the launch. Meta Ads Only

Example Request Body

You can locate the template_id at the end of the URL within the Scalemate app. For example, in the URL https://app.scalemate.co/workflow/builder/912, the template_id is 912.

{
  "file_links": [
    "https://drive.google.com/file/d/1JbpRSvif7wR-6vwNA51A5pHcyHViSQ7d/view?usp=drive_link",
    { // Supported only for Meta Ads
      "url": "https://drive.google.com/file/d/1AkhHSkmPTZDVTeOGUvegy0gRNk-qVyaF/view?usp=drive_link",
      "title": "Custom Title",
      "description": "Custom Description"
    },
  ],  
  "template_id": "123",
  "schedule_date": "2024-12-13T12:12:00+01:00", // optional
  "max_creatives_per_adset": 1, // optional
  "destination_url": "https://q.acme.com", // optional
  "campaign_name_override": "CAMPAIGN NAME OVERRIDE", // optional
  "adset_name_override": "ADSET NAME OVERRIDE", // optional
  "config_id": "123", // optional
  "webhook_url": "https://webhook.site/your-webhook-url"
}

Example cURL Request

curl --location 'https://api.scalemate.co/api/external/v1/launch' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <YOUR_API_KEY>' \
--data '{
    "file_links": [
        "https://drive.google.com/file/d/1JbpRSvif7wR-6vwNA51A5pHcyHViSQ7d/view?usp=drive_link",
        { // Supported only for Meta Ads
            "url": "https://drive.google.com/file/d/1AkhHSkmPTZDVTeOGUvegy0gRNk-qVyaF/view?usp=drive_link",
            "title": "Custom Title",
            "description": "Custom Description"
        },
    ],
    "template_id": "123",
    "schedule_date": "2024-12-13T12:12:00+01:00",
    "max_creatives_per_adset": 1,
    "campaign_name_override": "CAMPAIGN NAME OVERRIDE",
    "adset_name_override": "ADSET NAME OVERRIDE",
    "webhook_url": "https://webhook.site/your-webhook-url"
}'

Example Response

{
  "job_id": "63267564-2c14-4ccc-ab60-1a61a950a25d",
  "status": "accepted",
  "message": "Launch job has been accepted and is being processed"
}

Webhook Response

{
  "job_id": "<JOB_ID>",
  "launch_id": "<ID>",
  "status": "success" | "failure",
  "campaigns": [
    {
      "remote_id": "<CAMPAIGN_ID>",
      "name": "<CAMPAIGN_NAME>",
      "adsets": [
        {
          "remote_id": "<ADSET_ID>",
          "name": "<ADSET_NAME>",
          "ads": [
            {
              "remote_id": "<AD_ID>",
              "name": "<FILE_NAME>",
              "bucket_url": "<FILE_URL>"
            }
          ]
        },
		    ...
      ]
    }
  ],
  "error": null,
  "completed_at": "<DATE>"
}