Prepare & launch advertising
Campaign preparation is asynchronous. Delivery starts only after the existing business checks pass.
Before creating a campaign
- Read
get_workspaceandget_workspace_requirements. - Check
get_subscriptionand the balance returned bylist_campaigns. - Prepare and select owned creatives in the dashboard.
- 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 the existing subscription, 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 subscription, billing pause, available funding, current license requirements, and preparation state. Location packs must be complete. An initial onboarding pack additionally needs the existing verified payment authorization.
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 preserves subscription-based masking.
The initial v1 does not expose creative generation, domain purchases, wallet top-ups, campaign deletion, or arbitrary provider operations. The dashboard remains available for those supported product actions.