Skip to main content
A prospect audit is an audit of a domain you do not work on yet. It runs under your account, is kept with your account, and can be shared with the prospect. When the prospect becomes a client, one call turns the audit into a client workspace that starts from what the audit found. The free audit is anonymous and keeps nothing. A prospect audit is the version for an agency: it is stored, listed, shared and converted.

​
What an audit does

An audit runs three stages, in order: Each question’s verdict uses the same words and colours as the Scoreboard:
  • recommended (green): named and linked.
  • mentioned (amber): named, not linked.
  • absent (red): answered, and the brand was not in it.
  • not_read: no engine answered it. It has no colour and is never counted as absent.
Each question is read once per engine. One reading shows where the brand stands in that answer. It does not show how stable that answer is.

​
Starting one

POST /v1/prospect_audits with {"domain": "example.com"}. The audit runs in the background. Read it with GET /v1/prospect_audits/{id} until state is ready or partial.
  • It runs on your plan. An account with no plan is refused with a 402 that says to pick one. An account whose balance is spent is refused the same way any new work is.
  • It waits for a trial to convert. A prospect audit is work for a domain that is not yours, and a trial monitors only. During the trial the call is a 409 with details.reason trial_monitoring_only, and nothing is started. If billing cannot say whether your account is on its trial, the call is refused (503) rather than guessed at.
  • Your account has its own limit: 20 audits at once, then one every 3 minutes. Over it, the call is a 429 rate_limited with retry_after, and nothing is started. This limit is separate from the free audit’s and from the assistant connectors’.
  • The same domain is not audited twice by accident. While a domain’s last audit is still running, starting it again returns that audit (200). If a stage of that audit failed and will not be retried, starting it again runs that stage again (200). Otherwise a new audit starts (201).

​
When a stage fails

A stage that fails because a model, an engine or our store did not answer is retried by itself, with a growing wait, up to four more times. While it waits, the stage shows will_retry: true and the audit stays running. A homepage that refuses to be read does not stop the audit. The draft stage ends partial with code: "homepage_unreadable" and a reason, the Brand Book draft stays empty, and the questions and the read still run, so the audit ends partial. Starting the same domain again later begins a new audit. Any other stage that cannot succeed by waiting stops and says why in reason. To run a stopped stage again, start the audit for the same domain again. Nobody on our side has to step in. state is:
  • running: a stage has not finished, or is waiting to be retried. This holds even after an earlier stage stopped: the audit is running until every stage has ended.
  • ready: every stage did everything it was for.
  • partial: every stage ended, and at least one did less than a full run. For example, the homepage could not be read, or some answers could not be read. reason says which.
  • failed: nothing is still running, and a stage stopped and will not run again until you start the audit again. reason says why.

​
Sharing it with the prospect

Every audit has a share_token. GET /v1/public/prospect_audits/{token} returns the audit to anyone who has the token, with no login. The response carries your branding (your name, logo, colour and whether white-label is on), the domain, the Brand Book draft, the rivals, the questions with their verdicts and the totals. It carries no ids: not your account’s, not the audit’s and not a workspace’s. An unknown token is a 404. The same audit opens as a page at app.attensira.com/r/audit/<share_token>, or at https://<your portal host>/r/audit/<share_token> when you have a custom domain. Send the prospect either address. The page is under your branding: your name, logo and colour at the top, and with white-label on, no mention of Attensira. It shows the totals, the questions best verdict first with each engine’s verdict, the rivals and the Brand Book draft with the page each value came from. While the audit is still running, the page shows what has been read so far and says the audit is still running.

​
Download it as a PDF

The page has a Download PDF link. It points at /api/pdf/prospect_audit/<share_token> on the same host, and anyone with the link can open that address directly, with no login.
  • The PDF is the page itself, printed on white paper with your branding. On your portal host it is made from the page on your host, so a white-labelled PDF names nobody but you. The file is called audit.pdf.
  • If making the PDF fails in a way that waiting can fix, such as a timeout, it is tried once more on its own.
  • If there is still no PDF, you go back to the page and your browser’s print dialog opens. Choose Save as PDF there. The page prints with the same layout as the PDF.
  • An unknown token is a 404, and nothing is made.
  • The same link opened again within five minutes gets the same PDF.

​
Turning it into a client

POST /v1/prospect_audits/{id}/convert, or over MCP act with ref attensira://{workspace}/prospect_audit/{id} and action convert, creates one client workspace in your account for the audit’s domain:
  • The Brand Book draft is written onto the workspace’s profile as drafts. A field that already holds a value is never written over.
  • The rivals are added as candidates for you to confirm or drop.
  • The questions come first in the workspace’s starting questions, word for word, up to your account’s prompt slots.
The workspace then sets itself up like any new workspace: it reads its site and fills its starting questions. Converting again returns the same workspace (200; the first convert answers 201). The audit’s id is what makes the repeat safe. If your account already has a workspace for that domain, the audit becomes that workspace. Your plan and any workspace still waiting for payment are never a reason to refuse it. While the audit is still choosing its questions, the call is a 409 state_conflict that says to wait, and nothing is created. Converting adds a workspace whose questions are read from its first run onward, so it needs a balance that is not spent.

​
Over MCP and REST

Audits belong to your account, not to one workspace: the {workspace} in a URI only says which of your workspaces the call is made from, and every one reads the same audits. The fields are in the endpoint reference.