ads

POST /v1/ads/connections/{connection_id}/prospecting

Start building a Prospecting campaign preview from intent groups (za-158).

All ads endpoints

All developer docs →

Zinn®, our Viking, hammering at his anvil beside an API endpoint sending events to several listeners.

Authentication

Send an API key as a bearer token. The key must carry the ads.manage permission; a key without it is refused with 403, not 404.

This endpoint takes no organisation id. Your key already identifies the organisation it belongs to, and the response is scoped to it.

Try it

Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.

curl -X POST https://api.zinndigital.com/v1/ads/connections/{connection_id}/prospecting \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "brand": <string>, "category": <string[]>, "final_url": <string>, "country": <string> }'

Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console

Details

Gated on ads.manage. Validates the template and its gates from stored rows, then STARTS the preview workflow and answers 202 with its preview_id; the account read (collision replay), the ONE batched translation and the ONE batched AI-writer request run in that workflow, never in the request. Poll getAdsProspectingPreview. The same input the same day is the same preview (a running or built one is not started again). The preview is one new Search campaign: a category group, a problem group, one <Rival> alternative group per PAID competitor (a free host is skipped, notPaidCompetitor; all are skipped without the competitor switch and plan, competitorsOff) and a brand group, every keyword on EXACT and PHRASE. The business type's starter negatives, plus the free-seeker class when paid is true; every negative passes the collision replay over the account's keywords and searches and the template's own keywords, and one that would block any of them is dropped with its reasons. Each group's ad names its topic and must reach GOOD (waiting, adBelowGood otherwise); the whole request passes the ad-quality gate (status: refused, refused). Refusals: prospectingInvalid (with the field), killed, notInGoodStanding, needsReconnect, prospectingUnavailable.

Parameters

NameTypeRequiredWhat it is
connection_id (path)stringYes—

Request body

NameTypeRequiredWhat it is
business_typestring<free_trial, freemium, lead_gen, ecommerce, local, b2b>No—
paidobjectNonull = the business type's default (freemium is not paid).
brandstringYes—
brand_termsstring[]No—
categorystring[]Yes—
problemsstring[]No—
competitorsstring[]No—
final_urlstringYes—
countrystringYesISO 3166-1 alpha-2.
languagestringNo—
daily_budget_minorobjectNoMinor units of the account currency; null = Recommended (five whole units, also the floor).
headlinesstring[]No—
descriptionsstring[]No—

Response

NameTypeRequiredWhat it is
dataobjectYes—

Errors this endpoint can return

401 · 403 · 404 · 422 · 429