Link submission

Not everything you need reviewed exists as a file. A landing page, a live promotion, a design still in Figma, or a document in Google Drive can be submitted as a link. Adclear captures it and hands back an uploadId, which you use exactly like one from the File API.

Create the promotion with the fileFormat value from the capture response, not a fixed one. A screenshot and a Figma frame are always "image", but a Google Drive file can be any supported format, and native Google Docs, Sheets and Slides arrive as "pdf".

Which links are supported

Link	How it is captured	Response
Any `http(s)` page	Full-page screenshot	`201` — ready immediately
A Figma frame	Exported through the Figma API	`202` — poll until ready
A Google Drive file, or a Google Doc, Sheet or Slides deck	Imported through the Google Drive API	`202` — poll until ready

Figma files and Google files must be shared with anyone with the link. Adclear cannot read private files submitted through the API, because the API has no connected Figma or Google account of its own.

Always poll the statusUrl returned by POST /v1/links exactly as given. It carries the information the poll needs to find your import. Building the URL yourself can return a misleading completed before the file has finished importing.

Capturing a web page

A capture runs while you wait and can take up to two minutes, so set a generous client timeout. Request:

POST https://public-api.adclear.ai/v1/links

{
  "url": "https://example.com/summer-campaign"
}

Response:

{
  "uploadId": "a1b2c3d4-...",
  "status": "completed",
  "fileFormat": "image",
  "source": "screenshot",
  "sourceUrl": "https://example.com/summer-campaign",
  "originalFileName": "screenshot-example.com.png",
  "previewUrl": "https://storage.googleapis.com/...",
  "correlationId": "..."
}

previewUrl is a time-limited signed link for previewing the capture. Don’t store it — it expires. The uploadId does not.

curl -s -X POST "$API_BASE/v1/links" \
  -H "Authorization: Bearer $ADCLEAR_API_KEY" \
  -H "X-External-User-ID: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/summer-campaign" }'

const res = await fetch(`${API_BASE}/v1/links`, {
  method: "POST",
  headers,
  body: JSON.stringify({ url: "https://example.com/summer-campaign" }),
  signal: AbortSignal.timeout(180_000),
});
if (!res.ok) throw new Error(`Capture failed (${res.status})`);
const { uploadId } = await res.json();

res = requests.post(
    f"{API_BASE}/v1/links",
    headers=headers,
    json={"url": "https://example.com/summer-campaign"},
    timeout=180,
)
res.raise_for_status()
upload_id = res.json()["uploadId"]

Capturing a Figma frame

A Figma link identifies a file; Adclear needs to know which frame to import. Provide it either way:

Paste a frame link — in Figma, right-click a frame and choose Copy link to selection. The URL carries a node-id, which Adclear reads automatically.
Or send the file URL plus an explicit figmaFrameId, discovered with frame lookup.

Sending a file-level URL with no frame returns 400, pointing you at the frame lookup endpoint.

Start the import

Request:

POST https://public-api.adclear.ai/v1/links

{
  "url": "https://www.figma.com/design/AbC123/Campaign?node-id=1-2"
}

Response:

{
  "uploadId": "e5f6a7b8-...",
  "status": "processing",
  "fileFormat": "image",
  "source": "figma",
  "sourceUrl": "https://www.figma.com/design/AbC123/Campaign?node-id=1-2",
  "frameId": "1:2",
  "frameName": "Hero Banner",
  "statusUrl": "/v1/links/e5f6a7b8-...",
  "correlationId": "..."
}

Unlike a web page, a Figma import runs in the background and returns 202.

Poll until it is ready

Request the statusUrl from the previous response.

GET https://public-api.adclear.ai/v1/links/{uploadId}

{
  "uploadId": "e5f6a7b8-...",
  "status": "completed",
  "finalUploadId": "c3d4e5f6-...",
  "correlationId": "..."
}

Poll every couple of seconds while status is processing. When it reaches completed, use finalUploadId when creating the promotion. It can differ from the ID you polled. On failed, errorMessage explains why.

Discovering frames

To let someone choose a frame, list what the file contains: Request:

POST https://public-api.adclear.ai/v1/links/figma/frames

{
  "url": "https://www.figma.com/design/AbC123/Campaign"
}

Response:

{
  "fileName": "Campaign",
  "pages": [
    {
      "id": "0:1",
      "name": "Page 1",
      "frames": [
        { "frameId": "1:2", "name": "Hero Banner", "width": 1200, "height": 628 }
      ]
    }
  ],
  "correlationId": "..."
}

Pass any frameId back as figmaFrameId when submitting the link.

Importing from Google Drive or Docs

Submit a drive.google.com or docs.google.com link and Adclear downloads the file itself, rather than screenshotting the Drive preview page. Native Google Docs, Sheets and Slides are converted to PDF. Images, video, audio and PDFs are imported in their original format. Plain text files (.txt) are the one exception: they return 422. A text promotion takes its content inline rather than as an upload, so fetch the text yourself and pass it as content with "fileFormat": "text". See Promotions. The file must be shared with anyone with the link. The API has no connected Google account, so a private file, or one shared only with named people, cannot be reached. See Which Google files can I import? below.

Start the import

Request:

POST https://public-api.adclear.ai/v1/links

{
  "url": "https://docs.google.com/document/d/AbC123xyz/edit"
}

Response:

{
  "uploadId": "f7a8b9c0-...",
  "status": "processing",
  "fileFormat": "pdf",
  "source": "gdrive",
  "sourceUrl": "https://docs.google.com/document/d/AbC123xyz/edit",
  "originalFileName": "Q3 brief.pdf",
  "sizeBytes": 245760,
  "previewUrl": "https://lh3.googleusercontent.com/...",
  "statusUrl": "/v1/links/f7a8b9c0-...?source=gdrive",
  "correlationId": "..."
}

Note the fileFormat here is "pdf", because the link points at a native Google Doc. Read it from the response rather than assuming a value.

Poll until it is ready

Request the statusUrl exactly as returned, including its query string.

GET https://public-api.adclear.ai/v1/links/{uploadId}?source=gdrive

{
  "uploadId": "f7a8b9c0-...",
  "status": "completed",
  "finalUploadId": "f7a8b9c0-...",
  "correlationId": "..."
}

Poll every couple of seconds while status is processing. Large files take longer, since Adclear downloads the whole file. For a Google import finalUploadId matches the ID you polled, but read it from the response so the same code works for every link type.

Importing one tab of a multi-tab Google Doc is not yet available through the API. If you share a link that already points at a tab (the URL contains ?tab=), that tab is imported on its own. Otherwise the whole document is imported.

Creating a promotion from a captured link

Identical to a file upload. The capture is just another uploadId:

POST https://public-api.adclear.ai/v1/promotions

{
  "uploadIds": ["a1b2c3d4-..."],
  "fileFormat": "image",
  "promotionName": "Summer campaign landing page",
  "channelIds": ["..."],
  "productIds": ["..."],
  "jurisdictionId": "..."
}

Use the fileFormat from the capture response. For a screenshot or a Figma frame that is always "image", so the example above holds. For a Google Drive file it varies, and a native Google Doc needs "fileFormat": "pdf". Wait for status to reach completed before creating the promotion. An upload that is still importing has no file behind it yet. From here, trigger an evaluation as usual.

The submitted URL is not stored on the promotion. To keep it alongside the review, pass it in metadata — it is echoed back in webhook payloads.

Rate limits

Captures call third-party services, so they are limited more tightly than the rest of the API: 10 requests per minute per API key across POST /v1/links and POST /v1/links/figma/frames, whatever kind of link you submit. Polling GET /v1/links/{uploadId} is not affected and falls under the standard 60/minute limit. A 429 includes a Retry-After header. See Errors & rate limits.

Common error scenarios

Scenario	HTTP status	Error code	What to do
Page not found, or the domain doesn’t resolve	400	`INVALID_REQUEST`	The message carries the reason from the capture service — check the URL
Site blocks automated access	400	`INVALID_REQUEST`	The page can’t be captured; upload a screenshot via the File API instead
Non-`http(s)` URL	400	`VALIDATION_ERROR`	Only `http` and `https` are supported
Figma link with no frame	400	`VALIDATION_ERROR`	Use a “copy link to selection” URL, or supply `figmaFrameId`
Figma file is private	403	`FORBIDDEN`	Share it with “anyone with the link”
Figma file or frame missing	404	`NOT_FOUND`	Check the URL and that the frame still exists
Google link Adclear can’t read a file ID from	400	`INVALID_REQUEST`	Copy the link from Google’s Share dialog rather than the browser address bar
Google file access refused	403	`FORBIDDEN`	Check the sharing settings on the file
Google file is not public	404	`NOT_FOUND`	Set sharing to “anyone with the link”. A file shared only with named people can’t be reached
Google file type unsupported, or too large	422	`INVALID_REQUEST`	The message names the limit or the type. Convert the file, or upload it via the File API
Google Drive file is plain text (`.txt`)	422	`INVALID_REQUEST`	Fetch the text and pass it as `content` with `"fileFormat": "text"` instead
Google import temporarily unavailable	503	`UPSTREAM_ERROR`	Retry after a short delay
Capture took too long	504	`UPSTREAM_ERROR`	Retry; if it persists the page is likely too heavy to capture

For cross-cutting errors (401, 403, 429, 502), see Errors & rate limits.

Frequently asked questions

Is the page captured again when I create the promotion?

No. The capture happens once, when you call POST /v1/links. The promotion references that stored image, so a later change to the page does not alter what was reviewed.

Can I reuse one capture across several promotions?

Yes. The returned upload ID behaves like any other — reference it from as many promotions or versions as you like.

Why is a screenshot immediate but Figma and Google Drive are not?

A screenshot is captured inline while the request is open. Figma frames and Google Drive files are fetched from their provider and processed in the background, so they return 202 with a statusUrl to poll.

Which Google files can I import?

Any file shared with anyone with the link: images, video, audio and PDFs come across in their original format, and native Google Docs, Sheets and Slides are converted to PDF. Plain text files return 422, because a text promotion takes its content inline rather than as an upload.Private files, and files shared only with named people, cannot be imported. Adclear’s API has no Google account of its own to authenticate as, so it can only reach files that are public to anyone holding the link. To review a private file, download it and upload it via the File API.

Can I import a single tab of a Google Doc?

Only by sharing a link that already points at the tab. Google puts a ?tab= parameter in the URL when you copy a link to a specific tab, and Adclear imports just that tab. Choosing a tab through the API is not supported yet, so any other Docs link imports the whole document.

My Figma frame fails as too large. Why?

Very large frames (over roughly 6 megapixels) need a conversion step that isn’t available through the API yet. Export the frame as an image and upload it via the File API, or import it through the Adclear app.

Can I submit a PDF by URL?

A link to a PDF is captured as a screenshot of the rendered page, not downloaded as a PDF. To have the PDF itself reviewed, fetch it yourself and upload it via the File API.

Get started

Fundamentals

Adclear API

File API

Which links are supported

Capturing a web page

Capturing a Figma frame

Discovering frames

Importing from Google Drive or Docs

Creating a promotion from a captured link

Rate limits

Common error scenarios

Frequently asked questions

​Which links are supported

​Capturing a web page

​Capturing a Figma frame

​Discovering frames

​Importing from Google Drive or Docs

​Creating a promotion from a captured link

​Rate limits

​Common error scenarios

​Frequently asked questions

Which links are supported

Capturing a web page

Capturing a Figma frame

Discovering frames

Importing from Google Drive or Docs

Creating a promotion from a captured link

Rate limits

Common error scenarios

Frequently asked questions