---
title: "Read Google's Ads Transparency record for an advertiser domain (1 on-demand check)"
method: POST
path: "/projects/{project_id}/advertisers/{domain}/identity"
tags: ["Advertiser identity"]
---

# Read Google's Ads Transparency record for an advertiser domain (1 on-demand check)

`POST /projects/{project_id}/advertisers/{domain}/identity`

## Request

- Base URL: `https://adslighthouse.com/api/v1`
- URL: `https://adslighthouse.com/api/v1/projects/{project_id}/advertisers/{domain}/identity`
- Auth: HTTP bearer

Queues a lookup of the Google Ads Transparency Center record for an advertiser domain that the project's saved ads used (other domains are refused). A new lookup uses 1 on-demand check from the account's allowance, reserved before anything runs; quota_exceeded means none are left and nothing was queued. A result younger than 30 days is returned without a new lookup unless refresh is true; a lookup already running is joined; repeating the idempotency key returns the same lookup. Each of those returns outcome cached, pending or replayed and uses nothing. The lookup usually finishes within a few minutes: poll get_advertiser_identity. If it could not start, the check is given back. Requires the write scope and an idempotency key. Confirm with the user before calling, because it uses their allowance.

## Path parameters

- `project_id` string, required: The project: its id, its brand domain (for example nike.example) or its exact project or brand name. Unknown or ambiguous references return not_found; call list_projects then.
- `domain` string, required: Advertiser domain as it appears in list_advertisers, such as summit-outdoors.com.

## Headers

- `Idempotency-Key` string, required: A unique value you choose for this request, such as a UUID. Repeating the same key returns the first result instead of starting paid work again.

## Request body

- object
  - `refresh` union: Buy a new lookup even when a result younger than 30 days exists. Default false.
    - boolean
    - 'true' | 'false'

## Response `202`

Read Google's Ads Transparency record for an advertiser domain (1 on-demand check)

- object
  - `outcome` 'created' | 'pending' | 'cached' | 'replayed', required: created: a new lookup was queued and 1 on-demand check used. pending: one was already running. cached: a recent result is returned. replayed: this idempotency key was used before. Only created uses a check.
  - `lookup_id` string, required
  - `identity` object, required
    - `domain` string, required
    - `state` 'none' | 'pending' | 'found' | 'not_found' | 'failed', required: The headline state: pending while a lookup runs; otherwise the latest attempt: found, not_found (Google listed no advertiser), failed (the record could not be read; never the same as not_found) or none (never looked up).
    - `result` object, nullable, required: The latest lookup that read Google's record. Kept when a later refresh failed.
      - `lookup_id` string, required
      - `status` 'found' | 'not_found', required
      - `looked_up_at` string, required
      - `stale` boolean, required: Older than 30 days; a request without refresh buys a new lookup.
      - `advertisers` object[], required: Most ads first; the first is the primary advertiser. Empty when not_found.
        - `advertiser_id` string, required: Google Ads Transparency Center advertiser ID, such as AR01234567890123456789.
        - `name` string, required: The advertiser name Google lists; the name verified with Google when verified is true.
        - `verified` boolean, required: True when Google lists the advertiser as verified.
        - `country` string, nullable, required: ISO country code where Google says the advertiser is based; null when not reported.
        - `ads_seen` integer, required: This advertiser's ads among the 40 most recent ads Google lists for the domain (all Google platforms).
        - `approx_ads_count` integer, nullable, required: Google's approximate count of all the advertiser's ads; null when not reported.
        - `first_shown` string, nullable, required: Earliest first-shown time of the sampled ads.
        - `last_shown` string, nullable, required: Latest last-shown time of the sampled ads.
        - `transparency_url` string, required: The advertiser's page in Google Ads Transparency Center.
    - `latest_failure` object, nullable, required: The latest lookup when it failed after (or without) a result.
      - `lookup_id` string, required
      - `failure` 'unavailable' | 'provider_error' | 'timeout' | 'unconfirmed', required: unavailable: the lookup could not start, nothing was charged and the check was given back. provider_error, timeout, unconfirmed: the record could not be read and the check was used.
      - `attempted_at` string, required
      - `check_returned` boolean, required
    - `pending` object, nullable, required
      - `lookup_id` string, required
      - `requested_at` string, required
      - `trigger` 'manual' | 'automatic' | 'api', required
    - `transparency_search_url` string, required: Google Ads Transparency Center search for this domain, to check the record yourself.
  - `request_id` string

## Other responses

- `400`: Invalid parameters, cursor or body.
- `401`: Missing, invalid, expired or revoked credential.
- `403`: The credential lacks the write scope, the plan does not include the API, or the allowance is used up.
- `404`: Unknown project, keyword or run in this account.
- `409`: The idempotency key was already used for a different request.
- `429`: Rate limit reached. Retry after the Retry-After seconds.
- `503`: The requested service or file is temporarily unavailable.

---

[API](https://skmtc.dev/adslighthouse/apis/ads-lighthouse-api.md) · [All operations](https://skmtc.dev/adslighthouse/apis/ads-lighthouse-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adslighthouse/apis/ads-lighthouse-api/revisions/e1a4a40b11a9?raw)