How to Use the AdAlign API to QA New Ads Before Launch

The short answer: when new creatives arrive faster than anyone can check them, the check has to move into code, before launch. If your combined Meta and Google spend sits between €75,000 and €250,000 a month, that is AdAlign's Scale plan. It starts from €1,290 a month on an annual contract billed monthly (checked on 27 October 2026 on the pricing page). It includes a REST API with 1,500 evaluations a month, per the developers page. That is enough to score every draft against its page before it goes live. Try the scorer by hand on the free audit first. The steps: create a key, check the quota, and send each draft with its page to the analysis endpoint. Handle the replies that carry no score, gate the launch on the score and pull the fixes. Let an agent draft the ticket, have a person approve it, and keep the record.

Disclosure: I earn a commission if you buy AdAlign through a link on this page, and this page recommends it. Every claim about AdAlign links to AdAlign's own pages.

Check the fit before writing any code:

1. The quota, worked out. For example, 60 new creatives a week, each checked against one page, is 60 x 4 = 240 evaluations in a four-week month. That is well inside Scale's allowance. Failed evaluations are refunded, and the limit resets on the 1st of each month (UTC), says the developers page.
2. What you already have. A public URL for each creative file, the landing page named in the brief, and somewhere to run a workflow: n8n, a scheduled script, or a CI job.
3. The two numbers to track. The share of drafts that pass the gate on the first try. And the score of each launched ad a month later.

The API scores pairs and returns fixes. Its four endpoints on the developers page analyse, count usage, list history and fetch fixes. It does not sync ad accounts or total spend at risk; those live in the connected product described in the AdAlign glossary entry. The two fit together. The API checks what is about to launch, and the connected app watches what already runs.

Step 1: Create a key with the right scopes

Be on Scale or above. Open Settings, then API Keys, and create a key. Send it as a Bearer token; keys start with adal_. Each endpoint needs its own scope (analyze, usage, history, fixes), and Scale allows 20 keys (developers page).

Step 2: Check the quota before each batch

GET /api/check-usage returns what you have used, your limit, what remains, whether you can evaluate, and when the count resets, per the OpenAPI spec. Stop the batch when canEvaluate is false.

Step 3: Send each draft and its page

POST /api/analyze-ad takes three things: the ad as an image or video URL (or the ad's own URL, which AdAlign screenshots), the platform, and the landing page URL. The platform sets the scoring weights. Passing the ad copy as text in adTextFields improves message match compared with reading it off the image, per the OpenAPI spec. The landing page is captured on mobile for Meta and TikTok, and on desktop otherwise, unless you set viewport.

curl -X POST https://app.adalign.io/api/analyze-ad \
  -H "Authorization: Bearer adal_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"adData": {"imageUrl": "https://cdn.example.com/draft-0412.png",
                  "platform": "meta",
                  "adTextFields": {"headline": "The corner sofa, in stock",
                                   "ctaType": "SHOP_NOW"}},
       "landingPageData": {"url": "https://www.example.com/sofas/corner"}}'

Step 4: Handle the replies with no score

Two replies come back with status 200 and no score, and neither counts against the quota. url_only means the page blocked every capture. link_broken means it answers 404 or 410, its domain does not exist, or its certificate is refused (OpenAPI spec). A success code on a dead page is still a dead page, so do not let the workflow read it as a pass. Treat a broken link as a failed QA check in its own right. A 400 means bad input: an unsafe URL, no ad asset, or an ad URL that could not be captured. 429 means the month's limit is reached. A 500 is safe to retry, and not counted.

Step 5: Gate the launch on the score

overallScore runs 0 to 10 in half-point steps. For an ad that serves in several placements it is the weakest placement's score, with the others in alternateScores (OpenAPI spec). Build the gate on AdAlign's own lines from How it works and it becomes a traffic light: below 5 holds the launch, 5 to 7 goes to a reviewer, above 7 passes. Then one override. Hold anything with a conversionRisks entry marked CRITICAL, such as an offer mismatch, whatever the score.

Step 6: Pull the fixes for every held draft

GET /api/fixes?action=list&evaluationId=... returns the fixes for one evaluation, high priority first. Each one names the element, its current and suggested value, the reasoning, a confidence score and the trade-off. It also names the direction: change the page, the ad, the routing, or both. Fixes carry a status (pending, applied, dismissed, expired), so the record shows what was done with each (OpenAPI spec).

Step 7: Let an agent draft the ticket, and a person send it

The developers page pitches the API at tools, scripts and AI agents, and n8n is one documented way to wire that up. Its HTTP Request node can import the curl command above, and can be attached to an AI Agent node as a tool. The flow: a new file in the launch folder triggers the workflow, and the agent calls the analysis endpoint. It reads the score and the weakest dimension, pulls the fixes for anything held, and drafts a ticket for the page owner or a note for the creative team.

The agent could file that ticket itself. It does not get to. n8n's human-in-the-loop for tools pauses the workflow before a chosen tool runs and asks a person to approve or deny it in Slack or chat. Put the tool that files the ticket behind that review. The reviewer reads the agent's draft next to AdAlign's reasoning, edits what is wrong, then approves. The agent never edits the ad, the page or the campaign.

Step 8: Keep the record

GET /api/user-history lists past evaluations newest first, up to 100 per page, with each sub-score and the screenshots (OpenAPI spec). Store the evaluationId with the launch record. When someone asks why an ad went live, the record shows the score it had on the day.

Mistakes the documentation points at

• Calling without a key. The request runs anonymously at 1 evaluation per IP address a month, not against your plan (developers page).
• Leaving out the platform. AdAlign then detects it from the URLs, or falls back to default weights (OpenAPI spec).
• Pages behind a cookie banner. Elements hidden by a consent modal are marked obscured and not scored, per the same spec. Check that the page loads cleanly for a first-time visitor.
• Old field names. informationScent is a deprecated alias for above-the-fold continuity, and contextualMatch is a legacy average. The same spec flags both.

AdAlign keeps the API on Scale, the tier above Growth. At list price that is 1,290 - 590 = €700 a month more than the connected product without it, per the pricing page. That page sets the band by spend, and it does not say whether an account under €75,000 a month can take Scale for the API alone. Ask before you build.

Free test first, then the plan

Test the request shape for free. The anonymous call scores one pair a month per IP address, and the free audit checks five a month by hand. For a small team, that is a real pre-launch check. When the volume of drafts passes what a person can score, AdAlign, which pays me a commission, starts with a 30-day pilot on your own accounts, booked from the demo page. The API comes with the Scale band after it. How to use AdAlign covers the connected side.

FAQ

Which plan includes the API?

Scale and above. Scale includes 1,500 evaluations a month and 20 keys. On Portfolio and Enterprise the evaluations are set per contract, with 50 keys (developers page).

Does a failed evaluation count against the quota?

No. A 500 error is refunded. A page that blocks capture or is dead returns no score and is not counted, per the OpenAPI spec.

Can the API score TikTok, LinkedIn or Reddit ads?

Yes. The platform field accepts meta, facebook, instagram, tiktok, linkedin, google and reddit, and picks the weights for each (OpenAPI spec).