## Send the NFON phone book now (tenant:settings:write)

`POST /api/crm/v1/nfon/sync`

Module: CRM · operationId: `syncNfonPhoneBook` · Tag: NFON telephony · Auth: access token (`Authorization: Bearer <accessToken>`)

Builds the tenant's phone book (see the NFON phone book above) and sends it to comms, which
writes it to NFON in the background; the answer is the run (`entries` sent, numbers left out in
`entryErrors` with action `SKIP`). `full=true` sends it as a full run instead (same as
`syncNfonPhoneBookFull`, answered with `202`). The phone book must be active (`422`
otherwise); while another run of the tenant runs the answer is `409`; without comms `503`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `full` | query | string |  | `true` runs a full sync. (one of `true`, `false`; default `"false"`) |

### Responses

- **200** Run log (`application/json`)
- **202** `full=true`: the full run was sent (see `syncNfonPhoneBookFull`). (`application/json`)
- **401** Missing, invalid or expired token (no body).
- **403** The token lacks the permission (`insufficient permissions`) or has no active tenant.
 (`application/json`)
- **409** Another sync of the tenant is running (on any instance, manual or scheduled). (`application/json`)
- **422** The NFON phone book is not active (`not_configured`). (`application/json`)
- **500** The run aborted (contacts or masterdata unreachable, run log not writable), code
`sync_failed`; nothing was sent. `details.log` is the logged run. A failed contact listing never
deletes phone book entries.
 (`application/json`)
- **503** CRM has no connection to comms, so the phone book cannot be sent (`comms_unavailable`). (`application/json`)

Fields of the 200 answer:

- `chunks` (integer, required): Parts the entries were sent in (500 entries each).
- `durationMs` (integer (int64), required): Duration in milliseconds.
- `endTime` (string (date-time), required): End of the run.
- `entries` (integer, required): Phone book entries sent.
- `skipped` (integer, required): Numbers that could not be normalised.
- `startTime` (string (date-time), required): Start of the run.
- `status` (string, required): `SUCCESS`: the phone book was sent to comms; `FAILED`: nothing was sent (`error`). (one of `SUCCESS`, `FAILED`)
- `trigger` (string, required): Started by hand or by a schedule. (one of `MANUAL`, `SCHEDULED`)
- `type` (string, required): `FULL`: comms empties and rebuilds the NFON phone book. (one of `INCREMENTAL`, `FULL`)
- `entryErrors` (array of NfonSyncEntryError): Numbers left out (at most 500 are kept); omitted when none.
  - `action` (string, required): `SKIP`: the number could not be normalised and is not in the phone book. (one of `SKIP`)
  - `message` (string, required): Why the number was left out.
  - `displayName` (string): Name of the contact the number belongs to.
  - `number` (string): The number as stored.
  - `sourceId` (string): The contact the number comes from: `address:<id>`, `contact:<id>` (masterdata) or `lead:<id>`.
- `error` (string): Why the run failed; omitted when it was sent.
- `errors` (array of string): The run-level error; omitted when none.
- `id` (string): Run ID (a decimal number as string).
- `runId` (string (uuid)): The run as comms knows it (a UUIDv7); omitted for a failed run.

Example 200 answer:

```json
{
  "chunks": 1,
  "durationMs": 1834,
  "endTime": "2026-11-18T06:00:01Z",
  "entries": 122,
  "entryErrors": [
    {
      "action": "SKIP",
      "displayName": "Max Muster (Bergmann Bürobedarf KG)",
      "message": "Rufnummer kann nicht in das internationale Format (E.164) gebracht werden",
      "number": "0941/600700 Zentrale",
      "sourceId": "contact:7c9e6679-7425-40de-944b-e07fc1f90ae7"
    }
  ],
  "id": "4711",
  "runId": "01a1c67f-4f22-7d4d-9670-e186b38b7055",
  "skipped": 1,
  "startTime": "2026-11-18T06:00:00Z",
  "status": "SUCCESS",
  "trigger": "SCHEDULED",
  "type": "INCREMENTAL"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/crm/v1/nfon/sync' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
