> ## 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.

# Entity sync

> When you change a fact in your Brand Book, every profile of your company that shows it gets one Change: Wikidata, Crunchbase, LinkedIn and your directory listings. What each profile's status means, and how to retry one.

Assistants describe your company from many places at once: your Wikidata item, your Crunchbase profile, your LinkedIn page, your G2 or Capterra listing. When those disagree with each other, or with you, the answer can be wrong. Entity sync keeps them in step with one record, your Brand Book.

## The entity

Your Brand Book is the record. Entity sync reads these facts from it. Only facts you **confirmed** count. A value we drafted from your site is our guess, and it never goes out under your name.

| Fact | Where it lives in the Brand Book | Kind |
| - | - | - |
| Name | On the web → Name (empty means your workspace's name, which is shown but never sent to a profile) | claim |
| Legal name | The company → Legal name | claim |
| Founded | The company → Founded | claim |
| Headquarters | The company → Headquarters | claim |
| Founders | On the web → Founders | claim |
| Logo | Brand → Logo URL | safe |
| Description | Positioning → One line | claim |
| Pricing | What you sell → How it is priced | claim |
| Social profiles | On the web → Social profiles | safe |
| Same as | On the web → Same as | safe |
| Wikidata item | On the web → Wikidata item | safe |
| Crunchbase profile | On the web → Crunchbase profile | safe |
| LinkedIn company | On the web → LinkedIn company | safe |
| Directory profiles | On the web → Directory profiles | safe |

A **claim** is something you could be held to: a date, a place, a price, a person. A claim stays at "Ship after 48 hours unless stopped" (L3) or lower wherever it goes, whatever your off-site lane is set to. A **safe** fact is an identifier or a link.

## Targets

A target is a profile your Brand Book names, plus Wikidata, which is always there. Nothing is ever planned on a site you are not on.

* **Wikidata**, always. When you give your Wikidata item (a Q-number), the target is that item. When you do not, the target is the [new-item kit](#when-you-have-no-wikidata-item): nothing is planned on it, and it shows whether your company is ready for an item of its own.
* **Crunchbase**, when you give your Crunchbase profile.
* **LinkedIn**, when you give your LinkedIn company id or vanity name.
* **Each directory** in your directory profile links, such as `g2.com` or `capterra.com`. Two links to the same site are one target.

Each target shows only some facts. A fact a target does not show plans nothing there.

| Fact | Wikidata | Crunchbase | LinkedIn | Each directory |
| - | - | - | - | - |
| Name | Yes | Yes | Yes | Yes |
| Legal name | Yes | Yes | No | No |
| Founded | Yes | Yes | Yes | Yes |
| Headquarters | Yes | Yes | Yes | Yes |
| Founders | Yes | Yes | No | No |
| Logo | Yes | Yes | Yes | Yes |
| Description | Yes | Yes | Yes | Yes |
| Pricing | No | No | No | Yes |
| Social profiles | Yes | Yes | No | Yes |
| Same as | Yes | No | No | No |
| Crunchbase profile | Yes | No | No | No |
| LinkedIn company | Yes | No | No | No |

Wikidata carries your other profiles too, so changing your Crunchbase profile or LinkedIn company also plans a Change on your Wikidata item.

## What happens when you change a fact

When you type or confirm a new value, entity sync plans **exactly one Change per target that shows the fact**. Each Change is held to that site's mode in the [site policies](https://docs.attensira.com/agent/site-policies.md) table:

| Site mode | What the Change is | Who finishes it |
| - | - | - |
| `copy_kit` | A customer step: the value and the steps to file it on your own account. Never a browser run. | You |
| `browser_assist` | An agent fills in the form on your account. | You click submit |
| `browser_full` | An agent updates the profile in a browser on your account, with consent you recorded. | The agent |
| `api_oauth` | An agent updates the profile through the site's API, on access you granted. | The agent |
| `read_licensed`, `never` | Nothing. The target is blocked. | No one |

Every site entity sync can target is `copy_kit` today (Wikidata has no row of its own and gets the `copy_kit` default), so today every Change is a customer step.

Each Change waits for whatever your off-site lane's level gives it, exactly like any other off-site Change. Every Change carries the playbook `offpage.entity-sync` ([what it does](https://docs.attensira.com/agent/lever-playbooks.md#your-company-facts)), and is held to that playbook's quality checks. If you change the same fact again before a Change is approved, that Change is revised to carry the new value. You never get two. A Change already approved is left alone.

Clearing a fact never empties a profile. That target's fact is blocked with `fact_cleared`.

When you add a new target, such as a new Wikidata item or a new directory link, every fact that target shows is planned for it too, so it joins in step.

## Wikidata rules

Wikidata is a public knowledge base that assistants read, and it is edited by people who watch for companies editing about themselves. So for Wikidata, Attensira drafts a **copy kit** and you make every edit yourself. Attensira never edits Wikidata or Wikipedia, in a browser or through an API, and holds no Wikimedia account or access for you.

* **You make every edit, from your own account.** Each Wikidata Change is a customer step. Sign in to your own account on wikidata.org (Attensira never creates one for you), add what the kit drafted, check each value, then mark it sent in [Work](https://docs.attensira.com/agent/inbox.md) so we start measuring it.
* **Disclose the paid contribution first.** Wikimedia's [Terms of Use](https://foundation.wikimedia.org/wiki/Policy:Terms_of_Use) require anyone paid to contribute, which includes editing about your own employer or client, to disclose it. The kit drafts that disclosure for you. Publish it on your Wikidata user page before your first edit, and write "paid contribution, disclosed on my user page" in each edit summary.
* **Every statement needs a reference.** The kit drafts these facts as statements: founded (inception, P571), legal name (official name, P1448), your Crunchbase profile (P2088) and your LinkedIn company (P4264). A statement is ready only with a source that states the value: an independent publication or a page on your own site. Wikipedia, Wikidata and other wikis, social profiles (LinkedIn, X, Facebook and the like), Reddit, Quora, blog platforms such as Medium or Substack, Crunchbase, Product Hunt, GitHub and press-release wires are refused as sources, because anyone, including you, can write there. A statement with no allowed source is not ready, and says what to add. Add each ready statement with its source as "reference URL" (P854) and today as "retrieved" (P813). Other facts, such as your name and description, are labels with no reference; edit those yourself or leave them.
* **One item, yours to create.** When your Brand Book gives your item's Q-number, the kit covers that item only, and no second item is ever drafted. When it does not, Attensira drafts a new item for you to create yourself, but only once your company passes the notability check below. Attensira never creates a Wikidata item.
* **Claims wait for a person.** Every fact Wikidata shows, apart from your logo and links, is a claim, so it stays at "Ship after 48 hours unless stopped" (L3) or lower, as above.
* **Wikipedia is never edited.** Wikipedia is not an entity sync target, and the kit tells you not to edit the article about your company. Its [site policy](https://docs.attensira.com/agent/site-policies.md) is read only, and no agent edits an article about you or your rivals.

### The kit for your item

With a Q-number, the kit is in `wikidata` on the Wikidata target (`GET /v1/entity-sync/wikidata`):

| Field | What it is |
| - | - |
| `item_url` | Your item on wikidata.org. |
| `disclosure` | The paid-contribution disclosure for your user page. |
| `statements` | One per fact the kit drafts that your Brand Book states: `field`, `property` and `property_label` (for example `P571`, `inception`), `value`, `reference_url`, `ready`, and when it is not ready, `reason` (`wikidata_no_reference` or `wikidata_reference_not_allowed`) and `fix`. |
| `steps` | What to do, in order, on your own account. |

A statement's source is the first allowed one among the `Source:` lines on its Change's evidence.

### When you have no Wikidata item

With no Q-number in your Brand Book, the Wikidata target is the new-item kit. It is always there: `GET /v1/entity-sync/wikidata` never answers `404`, and the list includes it first. It plans no Change and has no facts, and a retry plans nothing; it reads the kit afresh.

Wikidata deletes items about companies with no independent coverage, so the kit starts with a **notability check**. Your company passes with at least two independent, reliable sources on two different sites. The sources checked are the pages your Brand Book lists under Same as and the `Source:` lines on your entity sync Changes. Your own site, your directory profile links, and the refused sources above never count, and two pages on one site (even on different subdomains) count once. Any other site is taken as reliable.

* **Below the bar**, nothing is drafted. The target is `blocked` with reason `not_ours_to_do`, and the kit shows which independent sources were found.
* **Passing it**, the target is `awaiting_customer` with reason `wikidata_new_item`, held to `copy_kit` as a customer step. The kit drafts the label (your name), a short description (your one line, without its final full stop, at most 250 characters), one statement, "instance of" (P31) = business (Q4830453), referenced by every independent source found, and the disclosure. The steps: sign in with your own account, publish the disclosure on your user page, create the item at [Special:NewItem](https://www.wikidata.org/wiki/Special:NewItem) with the label and description, add the statement with one "reference URL" (P854) per source (pick another class if "business" does not describe you), write "paid contribution, disclosed on my user page" in the edit summary, and add the new item's Q-number to your Brand Book. From then on, the target is your item.

The new-item kit is in `wikidata_item` on the Wikidata target:

| Field | What it is |
| - | - |
| `notability` | `passes`, `independent` (the sources that counted) and, below the bar, `reason: "not_ours_to_do"`. |
| `label`, `description`, `disclosure` | The drafts above. Empty below the bar. |
| `statements` | The P31 statement, with `reference_url` (the first source) and `references` (every source). Empty below the bar. |
| `steps` | The steps above. Empty below the bar. |

The target's `profile_url` is then Special:NewItem, and its `customer_steps` are the kit's steps. `wikidata_item` appears only when your Brand Book gives no Q-number, and `wikidata` only when it does.

## Status

Each target has a status, and so does each fact on it:

| Status | Meaning |
| - | - |
| `in_sync` | The Change carrying the Brand Book's value is live. |
| `drift` | The profile does not carry the Brand Book's value and nothing planned will change it: the Change was declined, or it is gone. Retry plans it again. |
| `pending` | A Change is planned and the agent carries it out. A target with no Change yet is also `pending`, with reason `not_planned`. |
| `awaiting_customer` | The Change is prepared and the last step is yours. `customer_steps` says what to do. A Wikidata new-item kit ready to file has reason `wikidata_new_item`. |
| `blocked` | Nothing can be done there. `reason` says why: `site_read_only`, `no_profile_update` (the site takes no profile edit, Product Hunt for example), `lane_watch_only` (your off-site lane is at Watch or Advise, so nothing is drafted), `fact_cleared`, `policy_unreadable`, `filing_failed`, or, on the Wikidata new-item kit, `not_ours_to_do` (your company is below the notability bar). |

A target's status is the status of the fact on it that most needs someone, in this order: `blocked`, `drift`, `awaiting_customer`, `pending`, `in_sync`.

## Drift: profiles that changed after the fact

A profile can stop saying what your Brand Book says after its Change went live: someone edits it, a directory rewrites it, or an old copy comes back. Once a week, entity sync checks.

**Directories are read.** For each directory profile your Brand Book links, we read the public page, but only when that site's [policy](https://docs.attensira.com/agent/site-policies.md) allows a public read (anything except `read_licensed` and `never`) and its robots.txt allows our reader. We compare only what a page states in a form we can read:

| Fact | Drift when |
| - | - |
| Name | The page does not show it anywhere. |
| Description | The page does not show your one line anywhere. |
| Founded | The page states a founding year ("Founded 2017") and your Brand Book's founding year is a different year. A page that states no year is not drift. |

Headquarters, logo, pricing and social links are not compared, because a page does not state them in a form we can read without guessing.

A drifted fact gets a Change, filed the same way as a fact edit: one row per target and fact, held to the site's mode and your off-site lane. The Change's current value is what the page shows, and its evidence names the page and the day we read it. When the same drift turns up the next week, nothing new is filed. A Change that is still open is the one that carries the fix. Nothing is filed for a fact when:

* you **declined** the Change carrying that value. That decision stays yours, and a [retry](#read-and-retry-it-yourself) plans it again.
* the Change carrying that value went live **less than 14 days ago**. Directory moderation and your own edits take days to show.

When the page is gone (404 or 410), or we could not read it, nothing is filed.

**LinkedIn and Crunchbase are never read.** Instead, their target carries `profile_kit`: every fact that profile shows, as your Brand Book states it, with the Brand Book field each comes from and the site's steps. Check your profile against it and fix anything that differs on your own account. A fact you change still gets its own Change as described [above](#what-happens-when-you-change-a-fact).

```json theme={null}
"profile_kit": {
  "site": "LinkedIn",
  "profile_url": "https://www.linkedin.com/company/acme-inc",
  "facts": [
    { "field": "name", "label": "Name", "value": "Acme", "fact_ref": "entity/public-name" },
    { "field": "founded", "label": "Founded", "value": "2019", "fact_ref": "company/founded" }
  ],
  "steps": ["..."]
}
```

Wikidata has its own copy kit and is not part of the drift check.

## Read and retry it yourself

The entity sync routes are not on `api.attensira.com` yet: send them to `https://webapp.attensira.com` with the same key. That host answers errors in its [own envelope](https://docs.attensira.com/api/errors.md#errors-from-the-webapp-host).

```bash theme={null}
# Every target and its status
curl "https://webapp.attensira.com/v1/entity-sync" \
  -H "Authorization: Bearer atn_live_..."

# Only the ones that need something
curl "https://webapp.attensira.com/v1/entity-sync?status=blocked" \
  -H "Authorization: Bearer atn_live_..."

# One target (wikidata is always there; a profile your Brand Book does not name is a 404)
curl "https://webapp.attensira.com/v1/entity-sync/wikidata" \
  -H "Authorization: Bearer atn_live_..."

# Plan one target again
curl -X POST "https://webapp.attensira.com/v1/entity-sync/g2.com/retry" \
  -H "Authorization: Bearer atn_live_..."
```

Over MCP, `list` with type `entity_sync`, `get` on `attensira://{workspace}/entity_sync/{target}` and `act` with `action: "retry"` on that ref do the same. Reads need the `read` scope. A retry needs `steer`, because it files Changes. It approves none of them.

A retry plans every fact on the target that is blocked, has drifted or was never planned, or whose planned value is no longer the Brand Book's. A fact whose Change is open or live with the current value is left alone.

During a [trial](https://docs.attensira.com/account/plans.md#the-trial), entity sync files nothing: a profile edit is off-site work, which waits for the trial to convert. A confirmed fact plans no Change, the drift check still reads each directory and reports what it shows, and a retry answers `409` with `details.reason: "trial_monitoring_only"`. Once the trial converts, retry a target to plan it from the Brand Book as it stands then.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.