# onOffice import

{/* AUTO-SYNCED SOURCE: this page lives in apps/app/src/modules/db-leads/docs/ and is mirrored into the docs app by `bun sync:module-docs`. Edit it in the module, not in apps/docs. */}

<Lead>
The onOffice import brings your **existing database** into DB-Leads, addresses plus activity history, and makes it searchable for the [database scan](/tools/db-leads/datenbank-scan). In the background, idempotent, and reliable even for very large address books.
</Lead>

## 1. Set up the connection

You configure the onOffice **connection** **once, centrally** under **Settings → Integrations → onOffice**, not in the tool. One connection every tool uses, kept safe in one place. Without a connection the tool imports nothing and tells you the source is missing. If you want to see the flow first, load **sample data** deliberately in the setup assistant: around 40 fictional contacts, labelled as such everywhere, removable with one click, and gone automatically the first time you sync against your real onOffice.

<ButtonLink href="/help/integrations/onoffice">Full onOffice guide</ButtonLink>

## 2. Map fields

Field mapping lives centrally with the onOffice integration (Settings, Integrations, onOffice): there you control which onOffice fields arrive in the central address book. The tool picks up the standard fields (first name, last name, email, phone, mobile, street, ZIP, city, customer no., contact person) from it automatically.

<Tip title="Customer number is the key">
The customer number (KdNr) is the external key the import uses to tell whether a lead already exists. That's why it's always requested, even without an explicit mapping.
</Tip>

## 2b. Release your own fields to the analysis

Under **Settings, Integrations, onOffice**, next to the field mapping, there is an **AI context** section. It lists every field of your onOffice account, including the ones you created yourself, grouped by category and searchable.

Whatever you tick there is read by the analysis as well, and it may quote it in the briefing under its onOffice name. If you have a custom field "Status Vorqualifizierung", the briefing will later say "Status Vorqualifizierung: Angeschrieben".

Three things worth knowing:

- **You do not pick a platform field.** The onOffice name carries the meaning. A tick is enough.
- **What is not ticked is never fetched.** The sync only asks onOffice for fields that are mapped or released.
- **Values arrive with the next sync.** Save, run one sync, then they sit on your contacts.

If a field name does not explain itself, you can add one sentence describing what it holds, right below the tick.

Fields whose content IS a protected characteristic (date of birth, age, gender, origin, religion, marital status, health) cannot be released. They appear in the list with a lock and a reason. You can still map them as a regular platform field: the lock only covers what the analysis evaluates.

## 3. Sync

Start the sync via the **Sync** button on the board or under **Settings → Synchronization → Sync**.

After the first full import, every further sync only fetches what changed in onOffice since the last one. That takes seconds, not hours, and reports its result when done. A sync without new records says "Everything up to date" and names how many contacts and entries it checked; the inventory stays fully intact. While a run is in progress, the arrows on the sync button spin.

<Steps>
  <Step title="First page instantly">
    The first page is imported immediately, so you see initial results right away.
  </Step>
  <Step title="The rest in the background">
    The large remainder continues as a background job in batches. The display names the current step (addresses first, then activities), how many of how many records are done, how long it has been running and roughly how much longer it will take.
  </Step>
  <Step title="Completion">
    At the end the status shows new and updated entries, plus any failed records with their reason.
  </Step>
</Steps>

<Callout tone="warning" title="Once a day at most">
A full sync can be started every 20 hours. This is not an arbitrary limit: a new run restarts the activity phase from the beginning, so with a large agents log a restart discards hours of work. If you start too early, the message tells you how long is left.

An interrupted run is not a problem. The next one resumes where the furthest previous run stopped.
</Callout>

<Callout tone="note" title="You can close this page">
The sync does not belong to the browser window. With a large address book the first run takes hours, and during that time you can close the page, reload it or open it on another device: the current state is always there, and the button cannot be pressed a second time by accident. If the background service goes quiet for more than five minutes, the page says so and names the point it stopped at.

When onOffice reports no total for a list, you see the number of records read so far instead of a percentage. That is deliberate: a percentage that is not based on a real total would be guesswork.
</Callout>

## What makes the import robust

<DefinitionList>
  <DefItem term="Idempotent">Re-syncing updates existing leads via the customer number instead of duplicating. A partial import that only carries an email never overwrites an existing phone.</DefItem>
  <DefItem term="Batched & resumable">The import runs in chunks over the background queue. No single call hits a time limit; an interrupted run resumes from the saved cursor.</DefItem>
  <DefItem term="Error capture">Failed records are recorded with their external id and reason. You see exactly which entries had trouble, not just an error count.</DefItem>
  <DefItem term="Stage on import">Imported contacts land in the first pipeline stage, not in limbo.</DefItem>
  <DefItem term="Activities included">After the addresses, a second phase pulls the onOffice activities (emails, calls, appointments, portal inquiries) and links them to the leads. That is the data foundation for the [database scan](/tools/db-leads/datenbank-scan) and the [acquisition agent](/tools/db-leads/akquise-agent): those texts are where the seller signals live. Shown as a second row in the Synchronization tab.</DefItem>
  <DefItem term="Deleted contacts leave too">When you delete a contact in onOffice, it disappears from DB-Leads after the next sync as well, together with its briefing, findings, history and property hints. The tool follows the central address book: first the platform's address sync verifies with onOffice that the contact no longer exists there, then the next DB-Leads sync removes it. Both steps have a safety limit above which they report instead of deleting; the step appears in the run's log.</DefItem>
</DefinitionList>

<Callout tone="note" title="Scales to 15,000+">
The import is built for very large address books: bulk writes instead of record-by-record, a continuation cursor, and a heartbeat that detects and cleanly finishes a run the background worker abandoned.
</Callout>

## After the sync: getting contacts rated

A sync does not start a scan. If you want new and changed contacts assessed automatically, set the **auto-scan** under **Settings, Database scan**: every automatic run syncs with onOffice first and rates afterwards. A scan started by hand under Findings does the same: sync first, rate second. Details under the [acquisition agent](/tools/db-leads/akquise-agent).

## Automatic lead import (optional)

The option **General settings → Lead import** pulls incoming portal inquiries into the pool automatically, recognized by property origin. To be honest: that feature addresses **new inquiries** and conceptually belongs to the planned inquiries tool; you don't need it for owner mining in your existing database. Details under [Settings in detail](/tools/db-leads/einstellungen).

## Frequently asked questions

<Faq>
  <FaqItem q="How do I recognise sample contacts?">
    By the notice above every view: it names the count and says these are not real customers. They are only loaded when you deliberately choose them in the setup assistant, and removed either with one click or automatically the first time you sync against your real onOffice.
  </FaqItem>
  <FaqItem q="The sync is stuck on 'running'. What now?">
    Large runs are continued by the background worker. If a run is interrupted, the next sync detects the stale run via the heartbeat and finishes it. Re-syncing is always safe (idempotent).
  </FaqItem>
  <FaqItem q="Do I need to re-scan after every sync?">
    Not strictly, but it pays off: thanks to the freshness check the database scan only analyzes contacts with new activities, so follow-up scans are fast and cheap.
  </FaqItem>
</Faq>