REST API

Overview

The WonderAds REST API lets you automate your entire campaign-building workflow programmatically. You can create accounts, add keyword lists with synonyms, set up keyword combinations with RSA assets, and trigger generation — all via HTTP requests. This is ideal for integrating WonderAds into your own tools, scripts, or third-party platforms.

Authentication

All API requests require authentication via an API key. Include your key in the Authorization header of every request as a Bearer token. API keys are tied to your user account and grant access to the same accounts you can access in the dashboard.

1. Generate an API key from your WonderAds account settings.
2. Store the key securely — it is shown only once at creation time.
3. Include the header in every request: Authorization: Bearer YOUR_API_KEY

Base URL and Response Format

All endpoints are available under /api/v1/. Successful responses return a JSON object with a "data" key containing the result. Error responses return a JSON object with an "error" message and optionally a "details" array with validation issues.

1. Base URL: https://your-domain.com/api/v1/
2. Success response: { "data": { ... } }
3. Error response: { "error": "Description of what went wrong", "details": [...] }
4. All request bodies must be sent as JSON with Content-Type: application/json.

Create an Account

POST /api/v1/accounts — Creates a new WonderAds account with optional settings and targeting configuration. You become the owner of the newly created account.

1. Required: "name" (string) — the account name.
2. Optional: "domain", "phone", "infos" (array of strings), "ctas" (array of strings).
3. Optional: "settings" object — matchTypes (array), splitMatchTypes ("none", "campaign", or "adgroup").
4. Optional: "targeting" object — language (default "en"), country (default "DE").

Create a Keyword List

POST /api/v1/accounts/{accountId}/keyword-lists — Creates a keyword list with keywords and optional synonyms. You must be a member of the account.

1. Required: "name" (string) — the list name (must be unique within the account).
2. Required: "keywords" (array) — at least one keyword with a "text" field.
3. Optional per keyword: "landingPath", "cpa" (number), "conversionRate" (number).
4. Optional per keyword: "synonyms" (array of objects with "text") — alternative keyword versions placed in the same ad group.

Create a Combination

POST /api/v1/accounts/{accountId}/combinations — Creates a keyword combination with RSA assets (headlines and descriptions). The keyword lists are combined via cartesian product.

1. Required: "keywordListIds" (array of UUIDs) — the keyword lists to combine, in order. The first list is the leading list.
2. Required: "assets" (array) — at least 3 headlines and 2 descriptions.
3. Each asset needs: "type" ("headline" or "description"), "variant" ("long", "short", or "default"), and "text".
4. Optional per asset: "pinPosition" (number, 0 = unpinned), "groupIndex" (number, groups related variants together).
5. Optional: "path1" and "path2" (display path segments, max 15 characters each).

Trigger Generation

POST /api/v1/accounts/{accountId}/generate — Starts generation for one or more combinations. The API processes the generation synchronously and returns the plan details with estimated counts, plus a downloadUrl for the generated CSV file.

1. Required: "combinationIds" (array of UUIDs) — which combinations to generate.
2. Required: "matchTypes" (array of strings) — e.g. ["exact", "phrase", "broad"].
3. Optional: "split" ("none", "campaign", or "adgroup") — how to split match types across campaigns. Defaults to "none".
4. The response includes a "downloadUrl" pointing to the generated CSV file, ready for Google Ads Editor import.
5. Download links expire after 1 hour. Use the URL with the same API key in the Authorization header.

Download CSV

GET /api/v1/accounts/{accountId}/download/{token} — Downloads the generated CSV file using the token returned in the generate response. The file is formatted for direct import into Google Ads Editor.

1. Use the "downloadUrl" from the generate response — it includes the correct account ID and token.
2. Include your API key in the Authorization header, same as other API requests.
3. The file is returned as text/csv with a Content-Disposition header for download.
4. Download links expire after 1 hour. After that, run generation again to get a new link.

Rate Limits and Best Practices

While WonderAds does not currently enforce strict rate limits, we recommend keeping API usage reasonable. For large-scale automation, batch your keyword list creation rather than creating one keyword at a time. Generation can take longer for large combinations, so plan accordingly.