How it works
Nothing is written until someone has seen the diff.
One lifecycle, four ways out of it, and a verify step that refuses to take a directory's word for anything.
- authenticate Credentials the client owns. Delegated, never shared.
- discover Find the listing that already exists. Do not create a second one.
- read Pull current state. This is the baseline the diff is computed against.
- plan Compute the change as a reviewable diff. Still nothing written.
Name, address and phone changes stop here and wait for a person. A plan that nobody approves expires. There is no path around this step, including for us.
- T1 API write Sanctioned endpoint, rate-ceilinged.
- T2 Authenticated session Operator-driven, human-paced, one at a time.
- T3 Work item Prefilled payload and a deep link. A person completes it.
- T4 Batch feed Scheduled file on the directory’s own terms.
Every lane converges here. Request, response, read-back, screenshot, operator and timestamp — retained 24 months, and the reason a client report needs no manual screenshotting.
- settle Wait. Directories index on their own schedule, not ours.
- read again A fresh fetch. The apply response is not evidence of anything.
- compare Matches the canonical record, or raises drift and queues a fix.
The same verify pass, run on a schedule, is drift detection. It is one mechanism, not two.
The tier is a routing decision, not a ranking.
A directory's tier says how automated its write path can be, given what its terms actually permit. It does not say how much the listing matters. A T3 directory the client's customers actually use gets the same canonical data, the same evidence trail, and the same verify pass as a T1 — it just reaches the page through a person instead of an endpoint.
That is why the assisted-manual queue is built as a first-class path rather than a to-do list. 55 directories were researched and 38 of them landed at T3. A system that treats those as second-class is a system that quietly stops managing most of the map.
What the orchestrator never knows
Every directory is reached through the same interface, whatever its tier. The part of the system that decides what to write cannot tell whether the change will land through a REST call or a person with a checklist — and that is what keeps the long tail from rotting. The interface itself, the field maps and the per-directory access research stay in the private repo.