Prepare & launch advertising
Campaign preparation is asynchronous. Delivery starts only after the existing business checks pass.
The simple path: launch_ads
After setup_business, the business has a pack of ads ready for its trade. launch_ads (daily_budget_cents) sets all the ready ads at that total daily budget across the business's cities. Agree the budget with the owner first, repeat it back and wait for an explicit yes.
The ads go live once:
- money has been added for ads (
fund_adsreturns the browser link; first top-up $100 minimum), - the ads agreement is signed in the dashboard,
- any required license is verified.
get_overview lists what is still blocking, each with its link. pause_ads pauses every running campaign of the business. set_cities changes the service cities (and optionally the radius around them) for the site and the next launch; a running campaign keeps its areas until it is launched again.
Before creating a campaign by hand
- Read
get_overviewandget_workspace_requirements. - Check the money for ads returned by
list_campaigns. - Select owned creatives (the ads from the business's pack).
- Obtain the user's authorization for the total daily budget and intended locations.
The initial public API manages the existing managed-advertising flow. A catalog flag for Google Search does not expose a Google Ads deployment endpoint. Connecting an agent does not grant access to Facebook pages or advertising accounts.
Create in pause
create_campaign (POST /v1/campaigns) validates creative ownership, license, and funding rules, then queues preparation with launch disabled.
Send the selected creative IDs and the total dailyBudgetCents according to the request schema. Use a unique Idempotency-Key for that intended campaign and reuse it for retries.
The response is 202 with a job. The durable job performs preparation and stores checkpoints so a transient provider failure can resume.
Monitor the job
curl https://api.benjiads.com/v1/jobs/JOB_UUID \
-H "Authorization: Bearer $BENJIADS_API_KEY"| Status | Meaning |
|---|---|
queued | Waiting for execution |
running | Preparing or resuming the campaign |
ready | Prepared; delivery has not been activated by this job |
live | The job activated delivery |
failed | Needs attention; provider objects may already exist |
cancelled | Execution stopped; this does not prove provider objects were removed |
hold: "license" indicates a pack prepared under a license hold. Follow the dashboard verification and redeployment flow.
Launch explicitly
Inspect the prepared campaign, confirm the saved budget with the user, and call launch_campaign with its campaign ID and a new action key.
Activation checks the billing pause, available funding, current license requirements, and preparation state. Location packs must be complete. An initial onboarding pack launches once money is added for ads and the ads agreement is signed.
The daily budget is the total across locations. For example, a $30/day budget across three equal locations is $10/day each, subject to the existing minimum budget validation. Adding locations does not turn it into $90/day.
Pause and measure
pause_campaign pauses the selected campaign using the existing access rules. list_campaigns returns saved campaign state and spend. get_metrics returns site/lead performance, and list_leads returns lead contacts in full: BenjiAds is free and never masks leads.
The v1 does not expose creative generation, domain purchases, payments (adding money for ads happens in the browser), campaign deletion, or arbitrary provider operations. The dashboard remains available for those supported product actions.