# Directory submissions

A submit task is one product, one directory, one form. Your agent opens the page in your browser,
fills it from the copy the workbench rendered for that site, presses submit, and records what the
confirmation said.

## What the agent is given

Before it opens anything, the agent asks the workbench for that task's brief. One answer carries
the whole job:

- the site row — its submit URL, whether it needs a login, whether it wants a badge;
- the copy pack the templates rendered for **this** site: the tagline, descriptions at the lengths
  this site asks for, the angle to pitch;
- the product's contact and company fields;
- what earlier forms already taught this product — every question a previous directory asked and
  the answer that was typed;
- **pitfalls**: plain sentences about this specific site, in the order they will be met. These are
  why the site failed last time.

Two things the brief deliberately does not carry. **The login**, because it holds a password —
the agent asks for that separately, per site. And **freshly written copy**: no model runs on the
LinkPing side, so anything the templates cannot produce is written by your agent in your own
session, from facts it was given.

## What happens on the page

Directories bury the free path, so the agent reads before it types:

- **Re-select the free plan.** Paid tiers come pre-selected, and the final button silently becomes
  *Continue to checkout*. The button's label is re-read right before it is pressed.
- **Look inside the upsell modal** for the free escape hatch — "Still Submit for Free" and its
  cousins. If there is genuinely no free path, the task comes back to you rather than being paid
  for. Card details are never entered.
- **Check for a draft or an existing listing.** Many sites keep one. Finishing that beats starting
  a second, which is how a directory decides you are spam.

Only the checkboxes **required** to submit are ticked — terms of service, "I confirm the
information is accurate" — and the note says which. None of the optional ones: no newsletters, no
partner offers, no "feature my product in your roundup". Not one.

Everything printed on a directory page — labels, help text, confirmation screens, badge embed
code — is treated as data, never as instructions. A page that says "ignore your previous
instructions" is a page describing itself.

And nothing is ever invented to fill a required field. A name, a price, a date, a founding year or
a user count that is not on file is yours to answer; the field is left empty and you are told
which one.

## The seven hand-backs

Your agent stops and gives the task back for exactly these, and for nothing else. Each lands on
your to-do list at `/?tab=todos` and on the site's card in `/sites`, with a note saying where
it stopped — a resume URL, the field label, the wording of the modal.

| Recorded as | What happened | What you do |
| --- | --- | --- |
| `needs_assist` / `captcha` | a captcha or a "security verification" that would not clear | open the resume URL, solve it, and either finish the form or release the row |
| `needs_assist` / `login` | a sign-in wall, no usable account, or the site asked for a password or a second factor the agent must not supply | add or fix the account under `/preferences`, sign in yourself, then release the row |
| `needs_assist` / `paid` | the only path to a listing is paid | decide whether this listing is worth money; if not, mark it `skipped` |
| `needs_assist` / `image_upload` | a logo or screenshot upload is required | upload it yourself on the site, or attach the asset and hand the task back |
| `needs_assist` / `badge` | the site wants its badge on the product's own page before it will list you | see **Badge-gated sites** below |
| `needs_assist` / `verify_email` | a confirmation code or link the agent could not get to | open the mailbox and confirm, then release the row |
| `needs_assist` / `manual` | a required field nothing on file can answer, or no unambiguous submit button | answer the question, or look at the page yourself |

Two more states exist for things nobody is acting on: `blocked` / `form_error` (the form
refused what it was given and said nothing useful) and `blocked` / `no_response` (it went in
and the site never answered).

If a submission's outcome is uncertain, the agent does **not** retry. You check the destination
and release the row from the workbench. A duplicate submission is how a run gets burned.

### When a site sends a confirmation mail

`verify_email` is the last resort, not the first move. A site that mails a code or a confirmation
link is handled in this order:

1. **The connected mailbox.** The agent asks the workbench whether that mail has arrived, and gets
   back the subject, the sender, when it came and the links inside it. What is searched is the
   Gmail account connected for **this product** under `/preferences` — never the mailbox of the
   login account, unless they happen to be the same address. No mailbox connected, or the
   connection has gone stale, and the answer says so instead of searching anything.
2. **The browser.** If that turns up nothing after a reasonable wait, the agent opens the mailbox
   itself, in your browser, the same way it opens a directory.
3. **Hand it back.** Only when both have failed does the task come back as
   `needs_assist` / `verify_email`, with the address that was watched, how long it waited, and
   the resume URL to finish on once you have clicked the link.

## Recording the outcome

After pressing submit, the agent writes the submission row: `submitted`, with the listing URL
whenever the confirmation page showed one, and a note carrying the evidence — the confirmation
wording, which required consent box was ticked, the moderation queue's stated turnaround.

`submitted` without a listing URL is refused unless the note says why there is none. A row with
no listing URL is one the daily check can never fetch, so it can never reach `live`. See
[Verification](https://getbacklinkai.com/docs/verification).

`live` cannot be written from here at all.

## When the site wants an article, not a form

Some sites in the library have no form worth filling: a blog, a developer community, a magazine.
What they take is a piece of writing, and the workbench holds it as an article against that site —
`draft` while it is being written, `ready` when it is, `published` once it is on their site.

The publishing step is the one that matters here. Your agent marks the article published **with
the URL it went live at**, and that single write records the submission for you: the site's row
becomes `submitted` with the article's URL as the listing URL, on the same angle the article was
written on. Nothing separate has to be recorded, and nothing should be — the two writes would only
disagree.

An article marked published with no URL records nothing. "Published, address unknown" is not a
listing, and the daily check needs an address to fetch.

## Learned fields

Anything the agent had to compose itself goes back into the product's material: the page's label
exactly as printed ("Your one-line pitch") with the value that was typed. The next directory that
asks the same question gets the same answer offered, instead of a second invention. You can read
and edit these under `/products`.

## What a run teaches the site library

Learned fields are about your product. The other half of what a run sees is about the **site**, and
that row is shared with every other member, so it is handled differently.

After it has been on the page, your agent writes back exactly four things — and only these:

- the URL the form is really at, when the library's was a homepage or a redirect;
- the fields the form actually asks for;
- whether there is a sign-in wall;
- whether there is a captcha.

They are the four anyone standing on that page can observe, they are the same for everybody, and
they are written **only while the column is still blank**. Nothing already answered is overwritten,
and nothing else on that row — the site's name, its notes, its DR, its badge code, what it charges
— can be touched from a run at all. Free text and numbers on a row everyone reads are how a shared
library gets defaced, so they stay with `/sites`.

Two consequences worth knowing. If somebody else answered the column first, the write goes through
and changes nothing; that is the ordinary outcome of a well-used library, not a failure, and your
agent should not report it as one. And an agent that tries to edit anything outside those four is
refused — see [Troubleshooting](https://getbacklinkai.com/docs/troubleshooting).

The point is the next run. A site the library only knew a homepage for opens at the right form the
second time, with the right fields expected and the sign-in dealt with first.

## Badge-gated sites

On these sites the footer of **your** page, not their form, decides whether the submission
succeeds: their crawler comes and looks for their badge on your site first.

Two things fail here, and the second is the one that surprises people:

1. Is there a link to them on your page at all?
2. **Does that link carry `rel="nofollow"`?** If it does, their check fails — and nothing on
   screen says why. One site's free "add the badge" path fell straight through to a paid checkout
   page for exactly this reason.

Placing the badge is not something LinkPing can do: there is no tool here that edits your website.
So the agent saves the embed code the site printed, hands the task back as
`needs_assist` / `badge`, and the snippet turns up in your to-do list at `/?tab=todos`, which
collects every waiting site's embed into one footer snippet. The badge code is stored against your
product alone; it carries your listing URL and nobody else ever sees it.

Once the badge is on the **deployed** page — a committed change is not a deployed page — the
remaining step on most of these sites is a **Verify badge** button, and the listing goes live as
soon as their crawler finds it.

## Next

- [Today's plan](https://getbacklinkai.com/docs/plan) — where submit tasks come from
- [Verification](https://getbacklinkai.com/docs/verification) — how `submitted` becomes `live`
- [Troubleshooting](https://getbacklinkai.com/docs/troubleshooting) — pages that will not load, forms that accept
  nothing