REST API
Automate your workflow with the WonderAds REST API. Create accounts, keyword lists, combinations, and trigger generation programmatically.
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 useful 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.
- Generate an API key from the API page in your WonderAds dashboard (open the user menu at the bottom of the sidebar and choose "API keys"; requires Business plan).
- Store the key securely. It is shown only once at creation time.
- Include the header in every request: Authorization: Bearer YOUR_API_KEY
Treat your API key like a password. Never share it publicly, commit it to version control, or include it in client-side code. If a key is compromised, revoke it immediately and generate a new one.
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.
- Base URL: https://wonderads.org/api/v1/
- Success response: { "data": { ... } }
- Error response: { "error": "Description of what went wrong", "details": [...] }
- All request bodies must be sent as JSON with Content-Type: application/json.
Plan Limits and Billing Errors
The API follows the same plan limits as the dashboard. If a request would go over a limit on your plan, or your subscription is not active (for example a canceled subscription or an expired trial), nothing is created and the API responds with HTTP status 402 Payment Required.
- Response body: { "error": "You've reached the limit of 25 accounts on the Business plan. Upgrade to add more accounts.", "code": "account_limit", "currentPlan": "business" }
- The "error" field is a readable message you can show to the person running your integration.
- The "code" field tells your code what happened: account_limit, keyword_list_limit, keyword_limit, combination_limit, or asset_group_limit for plan limits; no_subscription, canceled, past_due, unpaid, or trialing (trial ended) when the subscription is not active.
- The "currentPlan" field is the plan on your subscription ("starter", "pro", or "business"), or null when there is no plan to report.
- Creating accounts, keyword lists, and combinations is checked against your limits. Generation requires an active subscription or a running trial.
Treat a 402 as a stop signal, not a retry signal. Retrying the same request will fail until you upgrade your plan, update your billing, or remove resources you no longer need.
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. Returns 402 if you already have as many accounts as your plan allows.
- Required: "name" (string). The account name.
- Optional: "domain", "phone", "infos" (array of strings), "ctas" (array of strings).
- Optional: "settings" object. matchTypes (array), splitMatchTypes ("none", "campaign", or "adgroup").
- 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.
- Required: "name" (string). The list name (must be unique within the account).
- Required: "keywords" (array). At least one keyword with a "text" field.
- Optional per keyword: "landingPath", "cpa" (number), "conversionRate" (number).
- 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.
- Required: "keywordListIds" (array of UUIDs). The keyword lists to combine, in order. The first list is the leading list.
- Required: "assets" (array). At least 3 headlines and 2 descriptions.
- Each asset needs: "type" ("headline" or "description"), "variant" ("long", "short", or "default"), and "text".
- Optional per asset: "pinPosition" (number, 0 = unpinned), "groupIndex" (number, groups related variants together).
- Optional: "path1" and "path2" (display path segments, max 15 characters each).
Use variables like {{lists.services}} or {{account.name}} in your asset text. They resolve to actual values during generation, just like in the dashboard.
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.
- Required: "combinationIds" (array of UUIDs). Which combinations to generate.
- Required: "matchTypes" (array of strings), for example ["exact", "phrase", "broad"].
- Optional: "split" ("none", "campaign", or "adgroup"). Controls how match types are split across campaigns. Defaults to "none".
- The response includes a "downloadUrl" pointing to the generated CSV file, ready for Google Ads Editor import.
- 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.
- Use the "downloadUrl" from the generate response. It includes the correct account ID and token.
- Include your API key in the Authorization header, same as other API requests.
- The file is returned as text/csv with a Content-Disposition header for download.
- Download links expire after 1 hour. After that, run generation again to get a new link.
You can pipe the download directly into a file: curl -o export.csv -H "Authorization: Bearer YOUR_KEY" "DOWNLOAD_URL"
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.
The API is designed for server-to-server communication. Never expose your API key in frontend JavaScript, mobile apps, or public repositories.