> ## Documentation Index > Fetch the complete documentation index at: https://docs.attensira.com/llms.txt > Use this file to discover all available pages before exploring further. # Directory listings > How a listing or a profile update on a directory or review site gets filed: the copy kit you file yourself, the connected route where a site has one, and how we check it went live. A listing on a directory or review site, such as G2, Capterra or Product Hunt, is often one of the pages an AI answer quotes. Attensira prepares the listing, you approve it, and then it is filed in the way that site's [policy](https://docs.attensira.com/agent/site-policies.md) allows. Today that means **you file it yourself from a copy kit**. No agent signs in to, types into or submits a form on another company's site. ## What starts a listing When the [deciding-sources map](https://docs.attensira.com/measure/deciding-sources.md) shows a directory deciding answers to your tracked questions, Attensira drafts a listing for it and puts it in your Inbox as a Change. It knows the forms for G2, Capterra, GetApp, Product Hunt, AlternativeTo, Clutch and Slashdot. The values come from your [Brand Book](https://docs.attensira.com/brand-book/overview.md). Anything it cannot answer is left blank and named as blank, never guessed. A listing makes claims about your product under your name, so it waits for a person's approval like any other claim. The [off-site rules](https://docs.attensira.com/agent/off-site.md#the-rules-that-bind-every-off-site-channel) apply: a daily cap per workspace, and the first listing in a workspace is always filed by a person. ## How it is filed On your approval, the site's row in the [site policies](https://docs.attensira.com/agent/site-policies.md) table, as it applies to your workspace now, decides the route. | The site's mode | What happens | | - | - | | `api_oauth` | It is filed through the site's official integration, on a connection you made under **Customize › Connectors**. It counts as filed only when the site answers. A site that answers nothing is not marked filed. | | Any other mode | You get a copy kit and file it yourself on your own account. | | A site with no row | Treated as `copy_kit`. | No listing site has an `api_oauth` row or an integration that can file it today, so **every listing is a copy kit**. A site in a browser mode would also get the copy kit: there is no route that files a listing in a browser. The policy is read again at the moment of filing. If a site's row was downgraded after you approved, for example because its terms changed, the stricter mode applies. ## The copy kit The copy kit is everything you need to file the listing by hand, in your own browser: | Field | What it is | | - | - | | `site`, `site_name` | The site the kit is for. | | `url` | Where you start: the submission page for a new listing, or your own profile page for an update. | | `action` | `create_listing`, `update_profile` or `submit_launch`. | | `fields` | Each value to paste, as `{label, value, fact_ref}`. `fact_ref` names the Brand Book fact the value comes from. The values are the ones you approved, word for word. | | `steps` | What you do, in order: the site's own steps from its policy row, and always last, marking it sent. | | `needs_account` | `true` when the start page creates an account. | | `note` | One thing about the site worth knowing before you start, for example that one Capterra vendor account also covers GetApp and Software Advice. | In the app the Change shows the kit as a card, with a copy button on each value, the site's steps, and **I sent it**. Everywhere else, the kit is in the Change's timeline as plain text. ### Accounts are always yours An agent never creates an account. If the start page is a sign-up or registration page, the kit's first step is to create your own vendor account there, with your own work email. That holds whatever the site's mode is. ### Saying you sent it A listing counts as filed only when you say so. We never mark it for you. * In the app: **I sent it** on the copy kit card, or **mark sent** in the Inbox. * Over MCP: `act` with `mark_sent` on the change. * Over REST: [`POST /v1/actions`](https://docs.attensira.com/api/endpoints#post-/v1/actions) with `mark_sent`. This needs a person, or a key or connection that may **steer**. The key whose own run filed the change cannot say it was sent. ## Updating a profile you already have When a fact changes and a directory profile you already have shows the old one, the Change is a profile update. Before it is filed, Attensira reads your public profile page, so the Change shows what the page says now next to the new value. It reads the name from the page title and the tagline or description from the page description. A field the page does not carry reads as blank, never as a guess. The kit then points at your profile page with the new value to paste. ## How we check it went live After you mark it sent, we check the live page. A listing is **placed** once the page shows your brand name or a link to your domain, and **verified** once an AI answer cites that page. The full rules are in [How a placement is verified](https://docs.attensira.com/agent/off-site.md#how-a-placement-is-verified). ### Checking the listing against your Brand Book Once a day we also read the public page of every listing and profile update you delivered, and compare it with your Brand Book. The result is the listing's `verification`. The change's [receipt](https://docs.attensira.com/measure/receipts.md) carries it too: `live_status` is `live` once the page shows the listing, `no_longer_live` once the site rejected it, and `live_check` holds the page and the sentence. **Which page we read.** For a profile update, your profile page. For a new listing, the page the site's integration returned, or otherwise the profile on that site listed in your Brand Book under **On the web › Directory profiles**. Never the submission form. If we do not know the page, you get one Inbox step asking you to add its link there. **What we compare.** For a new listing: the name and tagline in your Brand Book, and a link to your site. For a profile update: the value you approved. **What we may read.** The site's [policy](https://docs.attensira.com/agent/site-policies.md) row and its `robots.txt` decide. A site whose effective mode is `never` or `read_licensed`, or whose `robots.txt` does not let our reader in, is not read, and nothing changes. **When a read fails.** A timeout, a `408`, a `429` or a `5xx` is tried again up to three times, waiting 5 then 10 seconds. A read that still fails changes nothing, and we try again the next day. | `state` | What it means | What happens | | - | - | - | | `pending` | Delivered, not read yet. | We read it within a day. | | `live_verified` | The page shows the listing as your Brand Book has it, or shows the value you approved. | The receipt's live check reads **live**. We read it again once a week. | | `mismatch` | The page shows the listing, but a field differs from your Brand Book. | One profile-update Change is filed for the first field that differs, and waits for your approval like any listing. While it is open, no second one is filed. | | `not_up_yet` | The page is missing or does not show you yet, within 14 days of delivery. | Sites take time to approve a listing. We read it again the next day. | | `rejected` | The site says it rejected or removed the listing, or the page is still missing 14 days after delivery. | You get one Inbox step quoting the site's reason, with what to do on your own vendor account. Nobody on our side handles it. | | `needs_address` | We do not know the listing's public page. | You get one Inbox step to add its link to your Brand Book. | | `not_read` | The site's policy or its `robots.txt` does not let us read the page. | Nothing changes. | Apart from a verified one, a listing is read every day for 60 days after delivery. ### Measuring a verified listing A listing only takes effect once it is live, so its [before-and-after checks](https://docs.attensira.com/measure/before-and-after.md) start from the read that verified it, not from the day you marked it sent. Once a day, every delivered listing whose last read is `live_verified` and which names the tracked prompts it was meant to move gets its **+3**, **+7**, **+14** and **+30** checks, booked once. The same goes for a profile update and for a [Brand Book fact carried to a profile elsewhere](https://docs.attensira.com/brand-book/entity-sync.md) when the listing route filed it. A listing with no tracked prompts is not checked. Each check's live test is our last read of the listing page, not a search of your own site. While that read is `live_verified`, the check measures your answers as any other check does. When a later read finds a `mismatch`, a rejection or a page that no longer shows you, the check stops as **Not live** with that read's sentence and no verdict, so a listing that failed its live check is never counted as a result, on your receipt or in the [playbook win rates](https://docs.attensira.com/measure/playbook-win-rates.md). ## Asking for reviews Review platforms are often the page an AI answer quotes, and a profile with few or old reviews says little. Attensira prepares the ask. **You send it.** No agent sends an invite, creates or claims an account on a review platform, or opens a browser there. ### What the agent drafts Once a week, for each review platform whose [site policy](https://docs.attensira.com/agent/site-policies.md) row allows `request_reviews` (today G2, Capterra, Trustpilot and Google Business Profile), Attensira drafts one **review request** Change if your Brand Book names your profile on that platform under **On the web › Directory profiles**. It drafts at most one per platform per calendar quarter, and none while an earlier one still waits on you. A platform whose row does not allow invites gets none. Yelp, whose rules forbid asking for reviews at all, never gets one. The Change is a kit: * **Where to start**: the platform's own business console, where its invite tool and your review link live, and the steps to use them: G2 and Capterra's review collection pages, Trustpilot's **Get reviews**, and Google Business Profile's **Ask for reviews**. We never make up a review link. The copy has a placeholder where you paste yours. * **Invite copy**: a subject and a short message asking for an honest review, signed with your company's name as your Brand Book states it (your workspace's name if it states none). * **The rules**: send it to every customer on your list, offer nothing in exchange, and never write or post a review yourself. The platform's own rule from its policy row is added. Before the Change is filed, the copy is checked twice. It must not offer anything for a review (a gift card, a discount, a raffle, a credit, "in exchange") or ask only the customers you expect to be happy ("if you enjoyed", "happy customers", NPS promoters, "5-star"). Every claim in it must [trace to a fact or a source](https://docs.attensira.com/agent/approval.md#every-claim-traces-to-a-fact-or-a-source). A kit that fails either check is not filed. An untraced claim gets you one question naming it and asking for the fact behind it, as any draft's does. A review request is a claim made in your name, so it waits for your approval like any listing. It is in the off-site lane, and its `kind` is `review_request`. You approve a kit as it was written; it can't be edited before approving. The kit is a fixed template: once approved, you copy it and can adjust the wording in your own email before you send it, as long as it still goes to every customer and offers nothing. If you don't want to send it, decline it. A decline and its note are recorded, but they do not rewrite the kit. No new kit for that platform is drafted until the next calendar quarter, and it is written from the same template. An edit sent anyway (an `edit` action, or approving with an edited value) is refused with a `400`. If the edit offers something for a review or asks only happy customers, the error names each phrase that broke the rule, with `details.reason` set to `incentive_or_gating`. ### Sending it Send the invite to your whole customer list, from your own email or through the platform's own invite tool. Do not pick who gets it, and do not filter by a survey score: review platforms ban selective asks and incentives, and so does the FTC's guidance on endorsements. Then mark it sent: * In the app: **I sent it** on the Change. * Over MCP: `act` with `mark_sent` on the change. * Over REST: [`POST /v1/actions`](https://docs.attensira.com/api/endpoints#post-/v1/actions) with `mark_sent`. Marking it sent is the only thing that closes a review request. It cannot be marked shipped, because it has no page. Like a listing, it needs a person, or a key or connection that may **steer**, and the key whose run filed it cannot say it was sent. ### How the receipt is measured Once a week we read your profile on the platform, from the day the request is filed until a year after you marked it sent. Each read records the **review count**, the **average rating** (with the platform's top rating) and the **date of the newest review**, as the page itself states them in its structured data. We never infer a number from the page's text. The read follows the platform's [policy](https://docs.attensira.com/agent/site-policies.md) row and its `robots.txt`, the same way the listing check does. A profile we may not read, cannot reach, or that states no review count is recorded as `not_measurable` with the reason. It is never recorded as zero reviews. The change's [receipt](https://docs.attensira.com/measure/receipts.md) counts from the day you marked it sent. Its `reviews` shows the **baseline**, the last measured read on or before that day (or the first one after, if none came before), the **latest** read, and the difference in review count and average rating between the newest measured read and the baseline. ## Read it yourself `GET /v1/listings` lists the directories agents prepare listings for, each with its fields, its policy `mode` and `effective_mode`, whether an integration can file it (`toolkit`), the steps you take, the `verification` of your newest delivered listing on it, and the `reviews` read for your newest review request on it. Trustpilot and Google Business Profile are listed too, with no form fields, because they take review requests. Review requests themselves are changes: `GET /v1/changes?kind=review_request` lists them, and over MCP `list` with type `change` and kind `review_request`. See [Directory listings](https://docs.attensira.com/api/endpoints.md#directory-listings) in the API reference. Over MCP, `list` with type `listing` and `get` on `attensira://{workspace}/listing/{domain}` read the same. `GET /v1/listings`, `GET /v1/listings/{domain}` and `GET /v1/changes` are served on `webapp.attensira.com`: send them there with the same key. They are not on `api.attensira.com` yet, which answers `404`. The MCP reads work today. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.