**גרסאות API** · **V2 (Latest)** · [V1](/integrations/v1/docs?lang=he)

# Contacts

OpenAPI 3.0.3 · API 2.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v2",
    "description": "API"
  }
]
```

Donors / members of the org — a rich write surface with clean English field names (firstName, lastName, gender "M"/"F", email, phone, birthDate, tags, customFields, relationship SPOUSE/PARENT/CHILD…). Read (list/search/get), CRUD identity (create = fill-if-empty upsert with phone/email dedup; PATCH = explicit override), and sub-resources (addresses / phones / emails / tags / typed custom fields / family links / children / interactions / documents). `tags` are boolean labels; `customFields` are typed key/value pairs — do not confuse them. Interactions are logged touchpoints (calls, visits, notes) in their own history. Documents are files attached to the contact (receipts, ID scans…): upload via POST /uploads/pdf|image then attach with its filename, or attach an http(s) url directly. Plus a guided spreadsheet workflow: `get_contact_import_schema` (the field catalogue + aliases to map your columns), `normalize_contacts` (pure per-column cleaning: phone→E.164, email, birthDate→ISO, civility→gender), `lookup_contacts` (batch dedup, no write), and `import_contacts` (bulk upsert ≤ 500 rows, with a per-line `dryRun` plan). Typical Excel flow: get import schema → map columns → normalize → lookup → import dryRun → fix errors → import. Scopes: `contacts:read`/`contacts:write`.

## פעולות

## GET /contacts

List contacts

`list_contacts`

Required scope: `contacts:read`. Lists/filters the org's contacts, each returned in the rich shape (identity + sub-collections). `email`/`phone` here are EXACT scalar matches (for a fuzzy dedup lookup use GET /contacts/search instead). Paginated.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Number of results per page"
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Opaque cursor returned by the previous request"
}
```

```json
{
  "name": "createdAfter",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "date-time"
  },
  "description": "Filter: created after this date (ISO 8601)"
}
```

```json
{
  "name": "updatedAfter",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "date-time"
  },
  "description": "Only contacts edited after this date."
}
```

```json
{
  "name": "email",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Exact (lower-cased) primary-email match."
}
```

```json
{
  "name": "phone",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Exact primary-phone match."
}
```

```json
{
  "name": "tag",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Filter by a category tag (normalised, e.g. \"Donateur\" → DONATEUR)."
}
```

```json
{
  "name": "isLocal",
  "in": "query",
  "schema": {
    "type": "boolean"
  },
  "description": "Filter by the « local » proximity flag (true/false)."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Contact"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts

Create or upsert a contact

`create_contact`

Required scope: `contacts:write`. INTELLIGENT UPSERT: if a contact with this `phone` or `email` (normalised) already exists, it is UPDATED fill-if-empty — existing identity values are NEVER overwritten, secondary phones/emails/addresses/tags/customFields are appended, and the response is `created:false`. Only a real insertion emits the `contact.created` webhook. Pass `?forceCreate=true` to always insert a new doc. To OVERWRITE a known identity value use PATCH /contacts/{id} instead. On a fresh create with no `tags`, the source tag `#API` is set. Formats: `gender` "M"/"F"/null (never a civility string), `phone` any format → E.164, `birthDate` ISO. `tags` are boolean labels; `customFields` are typed key/value pairs (upsert-by-key; NUMBER/DATETIME stored as TEXT).

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "forceCreate",
  "in": "query",
  "schema": {
    "type": "boolean"
  },
  "description": "true → always insert a new contact, even if a phone/email match exists."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_e4688e4bc822e21f91a3"
      },
      "example": {
        "firstName": "david",
        "lastName": "levy",
        "gender": "M",
        "email": "David.Levy@GMAIL.com ",
        "phone": "06 11 22 33 44",
        "tags": [
          "Donateur"
        ],
        "customFields": [
          {
            "key": "classe",
            "type": "TEXT",
            "value": "CM2"
          }
        ]
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "created": {
                "type": "boolean",
                "description": "true = a new contact was inserted; false = an existing one was upserted fill-if-empty."
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "VALIDATION_ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "VALIDATION_ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /contacts/search

Find a contact by tel/email (dedup)

`search_contacts`

Required scope: `contacts:read`. Dedup pre-create lookup: normalises `email`/`phone` and returns the single matching contact (`{found, contact}`) — NOT a paginated list. Use it before create_contact to know whether a contact already exists. Provide at least one of `email` or `phone`.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "email",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Email to match (normalised)."
}
```

```json
{
  "name": "phone",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Phone to match (normalised)."
}
```

```json
{
  "name": "phoneCountry",
  "in": "query",
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z]{2}$"
  },
  "description": "ISO country used to normalise a local phone number."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "found": {
                "type": "boolean"
              },
              "contact": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Contact"
                  }
                ],
                "nullable": true
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "MISSING_QUERY",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_QUERY"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/import/schema

Discover importable fields & options

`get_contact_import_schema`

Required scope: `contacts:read`. The self-describing import guide — call this FIRST to discover every importable field (with aliases to match your spreadsheet columns) and the available options, THEN normalize → lookup → import dryRun → import. Returns `fields[]` ({key, label, type, kind, multi, example, description, aliases[]}) and `options` (dedupStrategy, defaultPhoneCountry, dateFormat, requireContact, applyTags). Mirrors the admin ImportPage mapping step.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/ContactImportSchema"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/normalize

Normalise raw spreadsheet rows (pure)

`normalize_contacts`

Required scope: `contacts:read`. PURE per-column normalisation of dirty spreadsheet rows — NO database, NO org data touched. For each row it cleans phone→E.164 (+ detected country), email, birthDate→ISO, and civility→`gender` "M"/"F", and flags per-row `issues`. STEP 2 of the Excel import flow (after get_contact_import_schema; then lookup_contacts, then import_contacts dryRun). Example row `{phone:"06 12 34 56 78", birthDate:"15/03/1990", gender:"Mme", firstName:"sarah", category:"Séder night"}` → `{phone:{e164:"+33612345678", country:"FR", valid:true}, birthDate:{value:"1990-03-15", valid:true}, gender:"F", firstName:"Sarah", tags:["SEDER_NIGHT"]}`.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_f3635fecc6f75b85ba0f"
      },
      "example": {
        "rows": [
          {
            "phone": "06 12 34 56 78",
            "birthDate": "15/03/1990",
            "gender": "F",
            "firstName": "sarah",
            "category": "Séder night"
          }
        ],
        "defaultPhoneCountry": "FR"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/NormalizeResult"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## POST /contacts/lookup

Batch dedup lookup (no write)

`lookup_contacts`

Required scope: `contacts:read`. For each item, finds the matching contact of the org WITHOUT writing anything (a soft-deleted contact is never resurrected). STEP 3 of the Excel import flow: run it after normalize_contacts to learn which rows already exist (`matchedContactId`) before importing.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "phone": {
                  "type": "string",
                  "description": "Phone to match (normalised to E.164 before lookup)."
                },
                "email": {
                  "type": "string",
                  "description": "Email to match (lower-cased before lookup)."
                }
              },
              "additionalProperties": false
            }
          },
          "defaultPhoneCountry": {
            "type": "string",
            "description": "ISO country to normalise local phones. Default \"ZZ\"."
          }
        },
        "required": [
          "items"
        ],
        "additionalProperties": false,
        "description": "Batch dedup — for each item, find the matching contact of the org WITHOUT writing anything. Use it after normalize and before import to know which rows already exist (matchedContactId)."
      },
      "example": {
        "items": [
          {
            "phone": "+33611223344"
          },
          {
            "email": "david.levy@gmail.com"
          }
        ],
        "defaultPhoneCountry": "FR"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/LookupResult"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## POST /contacts/import

Bulk import contacts (dry-run + real)

`import_contacts`

Required scope: `contacts:write`. Bulk upsert of up to 500 rows (500+ → 400 IMPORT_TOO_LARGE; paginate the file yourself). STEP 4 of the Excel flow: call with `dryRun:true` FIRST to get the per-line PLAN (`report.lines[].action` = create/update/skip/error + `issues`) WITHOUT writing anything, fix the rows flagged `error`, then re-call with `dryRun:false`. `options.dedupStrategy` = skip|update|create (default update). Example dry-run `{contacts:[{__row:2, lastName:"cohen", phone:"061122", birthDate:"32/13/1990"}], dryRun:true}` → `report.lines:[{row:2, action:"error", issues:[{field:"phone", reason:"INVALID_PHONE", severity:"error"}, {field:"birthDate", reason:"INVALID_DATE", severity:"error"}]}]`.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_7ef2b58154210ab6fbbe"
      },
      "example": {
        "contacts": [
          {
            "__row": 2,
            "firstName": "sarah",
            "lastName": "cohen",
            "phone": "06 12 34 56 78",
            "birthDate": "15/03/1990"
          }
        ],
        "options": {
          "dedupStrategy": "update",
          "applyTags": [
            "Import 2026"
          ]
        },
        "dryRun": true
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/ImportResult"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "IMPORT_TOO_LARGE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "IMPORT_TOO_LARGE"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /contacts/{id}

Get a contact

`get_contact`

Required scope: `contacts:read`. Returns the full rich contact (identity + addresses/secondaryPhones/secondaryEmails/tags/customFields/familyLinks). 404 (never 403) if the id belongs to another org.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/Contact"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## PATCH /contacts/{id}

Update a contact's identity (override)

`update_contact`

Required scope: `contacts:write`. EXPLICIT OVERRIDE of identity fields (whitelisted + re-normalisation) — unlike create_contact this REPLACES the stored value. Sub-collections (secondary phones/emails/addresses/tags/customFields) are NOT touched — use the dedicated sub-resource endpoints. An empty string ("") means « leave untouched » (append-only: identity is never erased). Invalid email/phone/birthDate → 400.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_731434cf8427fd36cfcb"
      },
      "example": {
        "lastName": "LEVY",
        "gender": "M",
        "email": "d.levy@pro.com"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_EMAIL, INVALID_PHONE or INVALID_DATE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INVALID_EMAIL, INVALID_PHONE or INVALID_DATE"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/{id}/addresses

Add an address

`add_contact_address`

Required scope: `contacts:write`. Adds an address: the PRIMARY one if the contact has none (or `main:true`), otherwise a deduped SECONDARY address (which carries a stable id, patchable later).

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "main": {
            "type": "boolean",
            "description": "Force this as the PRIMARY address (overwrites the flat one)."
          },
          "label": {
            "type": "string",
            "description": "Free label (e.g. « Bureau »)."
          },
          "type": {
            "type": "string",
            "description": "PRO | PERSO."
          },
          "address": {
            "type": "string",
            "description": "Street address (required)."
          },
          "postalCode": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "region": {
            "type": "string",
            "description": "State / region / province."
          },
          "country": {
            "type": "string",
            "description": "Country (default \"France\")."
          },
          "companyId": {
            "type": "string",
            "description": "Company registration number (for a PRO address)."
          },
          "note": {
            "type": "string"
          }
        },
        "required": [
          "address"
        ],
        "additionalProperties": false,
        "description": "An address to add. If the contact has no primary address (or `main:true`), it becomes the primary; otherwise it is added as a deduped secondary address."
      },
      "example": {
        "label": "Bureau",
        "type": "PRO",
        "address": "12 rue de la Paix",
        "postalCode": "75002",
        "city": "Paris"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "MISSING_ADDRESS",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_ADDRESS"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## PATCH /contacts/{id}/addresses/{addressId}

Edit a secondary address

`update_contact_address`

Required scope: `contacts:write`. Merges the supplied fields into the SECONDARY address identified by `addressId` (a UUID from `adresses[].id`). Only supplied fields change. The PRIMARY address has no id and cannot be edited here — use PATCH /contacts/{id} or POST /contacts/{id}/addresses with main:true. 404 ADDRESS_NOT_FOUND if the id is not a secondary address of this contact.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

```json
{
  "name": "addressId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "The secondary address's id (from `adresses[].id`)."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "description": "PRO | PERSO."
          },
          "address": {
            "type": "string"
          },
          "postalCode": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "region": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "companyId": {
            "type": "string"
          },
          "note": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "description": "Whitelisted fields to merge into a SECONDARY address (targeted by its `addressId` UUID). Only supplied fields change. The PRIMARY address has no id and cannot be patched here (use PATCH /contacts/{id} or POST /contacts/{id}/addresses with main:true)."
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND or ADDRESS_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND or ADDRESS_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/{id}/phones

Add a secondary phone

`add_contact_phone`

Required scope: `contacts:write`. Appends a SECONDARY phone (E164, deduped). The primary phone is set via create_contact / update_contact. 400 INVALID_PHONE if unparseable.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "phone": {
            "type": "string",
            "description": "Phone (any format; normalised to E.164; 400 INVALID_PHONE if unparseable)."
          },
          "phoneCountry": {
            "type": "string",
            "description": "ISO country code to normalise a local number."
          }
        },
        "required": [
          "phone"
        ],
        "additionalProperties": false,
        "description": "A SECONDARY phone to append (deduped). The primary phone is set via POST/PATCH /contacts."
      },
      "example": {
        "phone": "06 98 76 54 32",
        "phoneCountry": "FR"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_PHONE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INVALID_PHONE"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## POST /contacts/{id}/emails

Add a secondary email

`add_contact_email`

Required scope: `contacts:write`. Appends a SECONDARY email (deduped). The primary email is set via create_contact / update_contact. 400 INVALID_EMAIL if invalid.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "Email (lower-cased; 400 INVALID_EMAIL if invalid)."
          }
        },
        "required": [
          "email"
        ],
        "additionalProperties": false,
        "description": "A SECONDARY email to append (deduped). The primary email is set via POST/PATCH /contacts."
      },
      "example": {
        "email": "perso@gmail.com"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_EMAIL",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INVALID_EMAIL"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## POST /contacts/{id}/tags

Add category tag(s)

`add_contact_tags`

Required scope: `contacts:write`. Adds one or more category TAGS (idempotent — re-adding is a no-op). Each is normalised (upper-cased, de-accented, spaces→`_`, e.g. "Séder night" → SEDER_NIGHT). A tag is a boolean label — NOT a key/value custom field (see POST /contacts/{id}/custom-fields).

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Tags, e.g. [\"Donateur\", \"Séder night\"] → stored DONATEUR, SEDER_NIGHT."
          }
        },
        "required": [
          "tags"
        ],
        "additionalProperties": false,
        "description": "One or more category TAGS to attach (idempotent — re-adding a tag is a no-op). Each is normalised (upper-cased, de-accented, spaces → `_`). System tags (#FORM/#PAIEMENT/#ABONNEMENT/#ACCOUNT/currency codes) are allowed too. A tag is a boolean label — NOT a key/value custom field (see ContactCustomFieldsInput)."
      },
      "example": {
        "tags": [
          "Donateur régulier",
          "Séder night"
        ]
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "MISSING_TAGS",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_TAGS"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## DELETE /contacts/{id}/tags/{tag}

Remove a category tag

`remove_contact_tag`

Required scope: `contacts:write`. Removes ONE category tag from the contact (no-op if absent). `tag` is a free string (URL-encode `#FORM` etc.); it is normalised the same way as when added.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

```json
{
  "name": "tag",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string"
  },
  "description": "The category tag to remove (URL-encoded; normalised server-side)."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "delete",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/{id}/custom-fields

Set custom fields (upsert-by-key)

`set_contact_custom_fields`

Required scope: `contacts:write`. Upserts typed custom fields BY KEY (writing the same key twice updates the single field, never duplicates). `override` (default true — explicit edit) overwrites the value; false only fills empty fields. `type` is reduced to TEXT/DATE/BOOL — NUMBER/DATETIME are stored as TEXT. Custom fields are distinct from category tags.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_b743641a58b8fd5cb226"
      },
      "example": {
        "customFields": [
          {
            "key": "classe",
            "type": "TEXT",
            "value": "CM2"
          },
          {
            "key": "casher",
            "type": "BOOL",
            "value": true
          }
        ]
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "MISSING_CUSTOM_FIELDS",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_CUSTOM_FIELDS"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## DELETE /contacts/{id}/custom-fields/{key}

Remove a custom field

`remove_contact_custom_field`

Required scope: `contacts:write`. Removes a custom field by key (case- and separator-insensitive: `_` and `-` are equivalent). No-op if absent.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

```json
{
  "name": "key",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string"
  },
  "description": "The field key to remove (URL-encoded; case/separator-insensitive)."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "delete",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/{id}/family

Add a family link

`add_contact_family_link`

Required scope: `contacts:write`. Adds a BIDIRECTIONAL family link between this contact and `relatedContactId` (the reverse link is added automatically). `relatedContactId` MUST belong to the same org (else 404 — no cross-tenant oracle). 400 UNKNOWN_RELATIONSHIP for an out-of-enum `relationship`; 400 SELF_LINK if it targets itself.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "relationship": {
            "type": "string",
            "enum": [
              "SPOUSE",
              "PARENT",
              "CHILD",
              "SIBLING",
              "GRANDPARENT",
              "GRANDCHILD",
              "IN_LAW",
              "EX",
              "COUSIN",
              "FRIEND"
            ],
            "description": "The link FROM this contact TO `relatedContactId`: SPOUSE, PARENT (this contact is the parent → reverse CHILD), CHILD, SIBLING, GRANDPARENT (→ reverse GRANDCHILD), GRANDCHILD, IN_LAW, EX, COUSIN, FRIEND."
          },
          "relatedContactId": {
            "type": "string",
            "format": "uuid",
            "description": "The other contact's id (must belong to the org)."
          }
        },
        "required": [
          "relationship",
          "relatedContactId"
        ],
        "additionalProperties": false,
        "description": "A bidirectional family link between the contact and `relatedContactId`. The reverse link is added automatically (PARENT↔CHILD and GRANDPARENT↔GRANDCHILD are asymmetric; the other types are symmetric). `relatedContactId` MUST belong to the same org (else 404)."
      },
      "example": {
        "relationship": "PARENT",
        "relatedContactId": "b3f1c2d4-5678-49ab-8cde-0123456789ab"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UNKNOWN_RELATIONSHIP or SELF_LINK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "UNKNOWN_RELATIONSHIP or SELF_LINK"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND or RELATED_CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND or RELATED_CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## DELETE /contacts/{id}/family/{relatedContactId}

Remove a family link

`remove_contact_family_link`

Required scope: `contacts:write`. Removes the family link (and its reverse) between this contact and `relatedContactId`. `?relationship` precises which link to remove. `relatedContactId` must belong to the org (404 otherwise).

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

```json
{
  "name": "relatedContactId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "The related contact's id."
}
```

```json
{
  "name": "relationship",
  "in": "query",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "SPOUSE",
      "PARENT",
      "CHILD",
      "SIBLING",
      "GRANDPARENT",
      "GRANDCHILD",
      "IN_LAW",
      "EX",
      "COUSIN",
      "FRIEND"
    ]
  },
  "description": "The relationship to remove (REQUIRED — omitting it returns 400 UNKNOWN_RELATIONSHIP)."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UNKNOWN_RELATIONSHIP",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "UNKNOWN_RELATIONSHIP"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND or RELATED_CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND or RELATED_CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "delete",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/{id}/children

Add a child

`add_contact_child`

Required scope: `contacts:write`. Adds a « baby » child (no phone/email) whose parents are this contact + its detected SPOUSE. Deduped by first name against the parents: an existing child is reused (`created:false`), else a new child contact is created. A PARENT↔CHILD link is set automatically. Example `{firstName:"Rivka", birthDate:"2015-09-01"}`.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "Child's first name (used for dedup)."
          },
          "lastName": {
            "type": "string",
            "description": "Child's last name (upper-cased)."
          },
          "birthDate": {
            "type": "string",
            "format": "date",
            "description": "Date of birth (ISO)."
          }
        },
        "required": [
          "firstName"
        ],
        "additionalProperties": false,
        "description": "A « baby » child to attach to the contact (and its detected SPOUSE) as parents. Deduped by first name against the parents: an existing child is reused (created:false), otherwise a new child contact is created without phone/email. A PARENT↔CHILD link is set automatically."
      },
      "example": {
        "firstName": "Rivka",
        "birthDate": "2015-09-01"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "created": {
                "type": "boolean",
                "description": "false = an existing child was reused."
              },
              "childId": {
                "type": "string"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "MISSING_FIRST_NAME",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_FIRST_NAME"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /contacts/{id}/interactions

List a contact's interactions

`list_contact_interactions`

Required scope: `contacts:read`. Returns the logged touchpoints (calls, visits, notes) for this contact, most recent first, cursor-paginated. An interaction is a `contact_activity` entry — distinct from a custom field or a category.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Number of results per page"
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Opaque cursor returned by the previous request"
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactInteraction"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/{id}/interactions

Log an interaction

`add_contact_interaction`

Required scope: `contacts:write`. Records a touchpoint with the contact (a call, a visit, a note). `type` is required — reuse one from GET /contacts/{id}/interactions/types for consistency. Example `{type:"Appel", content:"Rappelé pour la campagne de Pessah", actions:["Discussion"]}`.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Kind of interaction (free label), e.g. « Appel », « Visite », « Rencontre »."
          },
          "content": {
            "type": "string",
            "description": "Free-text notes about the interaction."
          },
          "actions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional string tags, e.g. [« Tefiline », « Discussion »]."
          }
        },
        "required": [
          "type"
        ],
        "additionalProperties": false,
        "description": "A new interaction to log against the contact. Use it to record a call/visit/note from an automation. Reuse a `type` from GET /contacts/{id}/interactions/types for consistency instead of inventing a new label each time."
      },
      "example": {
        "type": "Appel",
        "content": "Rappelé pour la campagne de Pessah",
        "actions": [
          "Discussion"
        ]
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/ContactInteraction"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "MISSING_TYPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_TYPE"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /contacts/{id}/interactions/types

List interaction types

`list_contact_interaction_types`

Required scope: `contacts:read`. Returns the distinct interaction `type` labels already used in the organisation (plus common defaults like « Appel », « Visite »). Pick one of these when logging an interaction so the CRM stays consistent instead of accumulating near-duplicate labels.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/{id}/documents

List a contact's documents

`list_contact_documents`

Required scope: `contacts:read`. Files attached to the contact (receipts, ID scans, signed mandates…), most recent first. Each has an `id` (to delete it), a `name`, a hosted `filename` and a download `url`.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ContactDocument"
                }
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/{id}/documents

Attach a document

`create_contact_document`

Required scope: `contacts:write`. Attaches a document to the contact. « Upload first, place after »: provide EITHER a `filename` already hosted via POST /uploads/pdf|image, OR an http(s) `url` re-hosted server-side (image/PDF only). An optional `name` labels it.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "description": "Hosted filename returned by POST /uploads/pdf or /uploads/image (md5.ext). Must belong to this org."
          },
          "url": {
            "type": "string",
            "description": "Public http(s) URL of an image or PDF to download & host. Use this from an MCP/AI agent that cannot stream a binary."
          },
          "name": {
            "type": "string",
            "description": "Optional human label for the document (defaults to the filename)."
          }
        },
        "additionalProperties": false,
        "description": "Attach a document to the contact. Provide EXACTLY ONE of `filename` (a file already hosted via POST /uploads/pdf|image) or `url` (an http(s) link, re-hosted server-side — image/PDF only, the MCP/AI path). Image & PDF only (a contact document is a scan, not a video). The typical flow is « upload first, place after »: POST /uploads/pdf → take its `filename` → POST here."
      },
      "example": {
        "url": "https://example.com/receipt-2026.pdf",
        "name": "Reçu fiscal 2026"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/ContactDocument"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "MISSING_FILE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_FILE"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## DELETE /contacts/{id}/documents/{docId}

Detach a document

`delete_contact_document`

Required scope: `contacts:write`. Removes a document from the contact by its `docId` (the file itself stays hosted). 404 if the contact or the document id is unknown here.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

```json
{
  "name": "docId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Document id returned by GET /contacts/{id}/documents."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "deleted": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "DOCUMENT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "DOCUMENT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "delete",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/chlihout-settings

Read Schlihus types and levels

`get_chlihout_settings`

Required scope: `contacts:read`. Returns the connected organisation’s settings and revision. Campaign-restricted keys are rejected. Only the organisation vocabulary is exposed; no contact religious practice values, notes, search, statistics or webhooks are exposed by these operations. Array order is display order. Labels are organisation-authored text, not translations; an empty label restores the built-in translation for CHABBAT/CACHEROUT/TAHARAT/ECOLE or levels 0/1/3/5/7/10. Other labels must be nonblank. Levels are common to all types; zero always means unknown. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Organisation settings.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ChlihoutSettingsResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid settings.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentication required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Insufficient authority.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CHLIHOUT_SETTINGS_CONFLICT: reload settings before editing again.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Internal error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## PUT /contacts/chlihout-settings

Customize Schlihus types and levels

`update_chlihout_settings`

Required scopes: `contacts:read` and `contacts:write`. Organisation keys or an active ADMIN OAuth actor only; campaign-restricted keys and secondary actors are rejected. Read get_chlihout_settings first, then send the entire types/levels arrays and that revision. IDs and numeric values are stable keys: never change or remove an existing key. Set enabled:false to hide a choice reversibly, preserving its label and recorded contact data. At least one positive level and enabled zero are required. Add a type using a unique uppercase ID; add a level using an unused integer 1–100. Limit: 100 types and 30 levels. A successful write increments revision; a retry with the old revision returns 409, so read settings to verify a lost response. Only the organisation vocabulary is exposed; no contact religious practice values, notes, search, statistics or webhooks are exposed by these operations. Array order is display order. Labels are organisation-authored text, not translations; an empty label restores the built-in translation for CHABBAT/CACHEROUT/TAHARAT/ECOLE or levels 0/1/3/5/7/10. Other labels must be nonblank. Levels are common to all types; zero always means unknown. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": [
    "contacts:read"
  ]
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "revision": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740990
          },
          "types": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 80,
                  "pattern": "^[A-Z][A-Z0-9_-]*$"
                },
                "label": {
                  "type": "string",
                  "maxLength": 100
                },
                "enabled": {
                  "type": "boolean"
                }
              },
              "required": [
                "id",
                "label",
                "enabled"
              ],
              "additionalProperties": false
            }
          },
          "levels": {
            "type": "array",
            "minItems": 2,
            "maxItems": 30,
            "items": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100
                },
                "label": {
                  "type": "string",
                  "maxLength": 100
                },
                "enabled": {
                  "type": "boolean"
                }
              },
              "required": [
                "value",
                "label",
                "enabled"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "revision",
          "types",
          "levels"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Organisation settings.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ChlihoutSettingsResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid settings.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentication required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Insufficient authority.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CHLIHOUT_SETTINGS_CONFLICT: reload settings before editing again.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Internal error.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": true
  }
}
```

## POST /contacts/merges/preview

Preview one deliberate contact merge and its admitted financial links

`preview_contact_merge`

Requires explicit contacts:merge AND contacts:read AND contacts:write AND paiements:read AND paiements:write AND promesses:read AND promesses:write. contacts:merge is opt-in, never default. Campaign-restricted keys are refused. Read-only: choose survivorId and absorbedId explicitly after reviewing the proposed duplicate; a diagnostic is not evidence that two people are identical. Returns the native merged public profile, exact effect counts and a revision bound to both BSON profiles, current related records, key and scopes. The absorbed record will disappear if the later command succeeds. No preview is persisted, no contact changes and no pending effects execute. Preview is an observation, not a reservation or a global snapshot. Only one deliberate pair of distinct current active contact UUIDs in the same organisation is supported. No automatic duplicate choice or field choices. Survivor present scalar values win (false/0 survive), source objects overlay, native arrays/coordinates/categories are combined; the owner sets new:false and archived:false and physically deletes absorbedId. Account identities, family graphs, subscription contact/payload references and references not remapped by the native owner are refused before effect, including activity, communications, fiscal-document, Google-link and biometric references. Linked payment/pledge amounts and historical billing/fiscal snapshots remain unchanged. Every financial target must still be owned and available; forms require forms_submit:read/write, caisse targets caisses:read/write, campaign targets fundraising:read/write, referenced subscriptions abonnements:read. No raw private snapshots, address codes or reusable instrument is exposed. At most 2000 related records and 4 MiB per read; queries limited to 10000 ms. Unknown query/body properties are rejected. Only changes visible in the returned name, recorded gender, primary/secondary email/phone, primary address and category profile are admitted; a native change to another profile field refuses CONTACT_MERGE_PROFILE_CHOICE_UNSUPPORTED. Private or unreviewed profile changes are never applied silently. lockCleanup separately qualifies external lock cleanup as NOT_ATTEMPTED, RELEASED, RETAINED or UNKNOWN. A proved physical merge and acknowledged terminal journal remain APPLIED_PENDING_EFFECTS if cleanup is unknown; this never authorises replay or lock takeover. Unproved terminal business journalling remains state UNKNOWN. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:merge",
  "additional": [
    "contacts:read",
    "contacts:write",
    "paiements:read",
    "paiements:write",
    "promesses:read",
    "promesses:write"
  ]
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "survivorId": {
            "type": "string",
            "format": "uuid"
          },
          "absorbedId": {
            "type": "string",
            "format": "uuid"
          }
        },
        "required": [
          "survivorId",
          "absorbedId"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Native profile preview and current revision.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergePreviewResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid pair, unknown input or invalid command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentication required.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "All merge and related scopes are required; campaign restrictions are refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "A contact or command is unavailable in the current organisation/key.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Current identity, unsupported reference, revision, lock or idempotency conflict: review before any new intent.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Ambiguous, malformed or over-limit source; no partial merge is admitted.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Admission or receipt storage is unproved; never infer absence of effect.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:merge",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write",
    "paiements:read",
    "paiements:write",
    "promesses:read",
    "promesses:write"
  ],
  "x-unisoft-conditional-scopes": [
    {
      "condition": "forms are related",
      "scopes": [
        "forms_submit:read",
        "forms_submit:write"
      ],
      "allRequired": true
    },
    {
      "condition": "payment targets a caisse",
      "scopes": [
        "caisses:read",
        "caisses:write"
      ],
      "allRequired": true
    },
    {
      "condition": "payment or pledge targets a campaign",
      "scopes": [
        "fundraising:read",
        "fundraising:write"
      ],
      "allRequired": true
    },
    {
      "condition": "payment has abo",
      "scopes": [
        "abonnements:read"
      ],
      "allRequired": true
    }
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/merges

Apply a reviewed native contact merge once with durable outcome tracking

`merge_contacts`

Requires explicit contacts:merge AND contacts:read AND contacts:write AND paiements:read AND paiements:write AND promesses:read AND promesses:write. contacts:merge is opt-in, never default. Campaign-restricted keys are refused. Use preview_contact_merge first and preserve its exact survivorId, absorbedId and revision. idempotencyKey identifies this single intent. The command journals admission, acquires ordered per-contact external locks shared with external lifecycle/bulk commands, rechecks all sources and invokes native CRM.mergeContact with full expected BSON contacts and its snapshot/CAS journal. Internal writers remain active: atomicAcrossInternalWriters:false. Same key/content returns the receipt without invoking the owner again; changed content is IDEMPOTENCY_CONFLICT. APPLIED_PENDING_EFFECTS confirms physical merge and read-back of unchanged financial payloads; native derived effects are queued and are not executed inline (including geocoding). This does not confirm every derived projection is current. REJECTED occurred before invoking the owner. ADMITTING/RUNNING may be active or interrupted. UNKNOWN means an invoked effect/read-back is unproved and retains both external locks. success:true confirms a stored receipt, not a successful merge. canRetry:false in all states. After timeout or uncertainty call get_contact_merge_command with commandId; never retry another key, bypass locks, resume native work or infer failure from age. No automatic undo/recovery or stale-lock takeover is exposed. Only one deliberate pair of distinct current active contact UUIDs in the same organisation is supported. No automatic duplicate choice or field choices. Survivor present scalar values win (false/0 survive), source objects overlay, native arrays/coordinates/categories are combined; the owner sets new:false and archived:false and physically deletes absorbedId. Account identities, family graphs, subscription contact/payload references and references not remapped by the native owner are refused before effect, including activity, communications, fiscal-document, Google-link and biometric references. Linked payment/pledge amounts and historical billing/fiscal snapshots remain unchanged. Every financial target must still be owned and available; forms require forms_submit:read/write, caisse targets caisses:read/write, campaign targets fundraising:read/write, referenced subscriptions abonnements:read. No raw private snapshots, address codes or reusable instrument is exposed. At most 2000 related records and 4 MiB per read; queries limited to 10000 ms. Unknown query/body properties are rejected. Only changes visible in the returned name, recorded gender, primary/secondary email/phone, primary address and category profile are admitted; a native change to another profile field refuses CONTACT_MERGE_PROFILE_CHOICE_UNSUPPORTED. Private or unreviewed profile changes are never applied silently. lockCleanup separately qualifies external lock cleanup as NOT_ATTEMPTED, RELEASED, RETAINED or UNKNOWN. A proved physical merge and acknowledged terminal journal remain APPLIED_PENDING_EFFECTS if cleanup is unknown; this never authorises replay or lock takeover. Unproved terminal business journalling remains state UNKNOWN. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:merge",
  "additional": [
    "contacts:read",
    "contacts:write",
    "paiements:read",
    "paiements:write",
    "promesses:read",
    "promesses:write"
  ]
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "survivorId": {
            "type": "string",
            "format": "uuid"
          },
          "absorbedId": {
            "type": "string",
            "format": "uuid"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]{8,128}$"
          }
        },
        "required": [
          "survivorId",
          "absorbedId",
          "revision",
          "idempotencyKey"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Stored applied-pending-effects or rejected receipt; inspect state.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeReceiptResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "Stored in-flight or uncertain receipt; never replay.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid pair, unknown input or invalid command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentication required.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "All merge and related scopes are required; campaign restrictions are refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "A contact or command is unavailable in the current organisation/key.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Current identity, unsupported reference, revision, lock or idempotency conflict: review before any new intent.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Ambiguous, malformed or over-limit source; no partial merge is admitted.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Admission or receipt storage is unproved; never infer absence of effect.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:merge",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write",
    "paiements:read",
    "paiements:write",
    "promesses:read",
    "promesses:write"
  ],
  "x-unisoft-conditional-scopes": [
    {
      "condition": "forms are related",
      "scopes": [
        "forms_submit:read",
        "forms_submit:write"
      ],
      "allRequired": true
    },
    {
      "condition": "payment targets a caisse",
      "scopes": [
        "caisses:read",
        "caisses:write"
      ],
      "allRequired": true
    },
    {
      "condition": "payment or pledge targets a campaign",
      "scopes": [
        "fundraising:read",
        "fundraising:write"
      ],
      "allRequired": true
    },
    {
      "condition": "payment has abo",
      "scopes": [
        "abonnements:read"
      ],
      "allRequired": true
    }
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /contacts/merge-commands/{commandId}

Read a contact merge command outcome without replay

`get_contact_merge_command`

Requires explicit contacts:merge AND contacts:read AND contacts:write AND paiements:read AND paiements:write AND promesses:read AND promesses:write. contacts:merge is opt-in, never default. Campaign-restricted keys are refused. Use the returned commandId, not a contact UUID. Reads only this key and organisation’s durable external receipt. APPLIED_PENDING_EFFECTS describes verified state when the command executed; later internal changes remain possible. UNKNOWN/RUNNING/ADMITTING never authorise replay or lock takeover. Native history is retained privately for authorised Unisoft review. No command is resumed, effect executed, contact loaded, lock released or undo triggered. No query parameter or request body is accepted. canRetry:false. Only one deliberate pair of distinct current active contact UUIDs in the same organisation is supported. No automatic duplicate choice or field choices. Survivor present scalar values win (false/0 survive), source objects overlay, native arrays/coordinates/categories are combined; the owner sets new:false and archived:false and physically deletes absorbedId. Account identities, family graphs, subscription contact/payload references and references not remapped by the native owner are refused before effect, including activity, communications, fiscal-document, Google-link and biometric references. Linked payment/pledge amounts and historical billing/fiscal snapshots remain unchanged. Every financial target must still be owned and available; forms require forms_submit:read/write, caisse targets caisses:read/write, campaign targets fundraising:read/write, referenced subscriptions abonnements:read. No raw private snapshots, address codes or reusable instrument is exposed. At most 2000 related records and 4 MiB per read; queries limited to 10000 ms. Unknown query/body properties are rejected. Only changes visible in the returned name, recorded gender, primary/secondary email/phone, primary address and category profile are admitted; a native change to another profile field refuses CONTACT_MERGE_PROFILE_CHOICE_UNSUPPORTED. Private or unreviewed profile changes are never applied silently. lockCleanup separately qualifies external lock cleanup as NOT_ATTEMPTED, RELEASED, RETAINED or UNKNOWN. A proved physical merge and acknowledged terminal journal remain APPLIED_PENDING_EFFECTS if cleanup is unknown; this never authorises replay or lock takeover. Unproved terminal business journalling remains state UNKNOWN. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:merge",
  "additional": [
    "contacts:read",
    "contacts:write",
    "paiements:read",
    "paiements:write",
    "promesses:read",
    "promesses:write"
  ]
}
```

### פרמטרים

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Last durable receipt; no continuation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeReceiptResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "Uncertain or in-flight receipt; no continuation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid pair, unknown input or invalid command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentication required.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "All merge and related scopes are required; campaign restrictions are refused.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "A contact or command is unavailable in the current organisation/key.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Current identity, unsupported reference, revision, lock or idempotency conflict: review before any new intent.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Ambiguous, malformed or over-limit source; no partial merge is admitted.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Admission or receipt storage is unproved; never infer absence of effect.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:merge",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write",
    "paiements:read",
    "paiements:write",
    "promesses:read",
    "promesses:write"
  ],
  "x-unisoft-conditional-scopes": [
    {
      "condition": "forms are related",
      "scopes": [
        "forms_submit:read",
        "forms_submit:write"
      ],
      "allRequired": true
    },
    {
      "condition": "payment targets a caisse",
      "scopes": [
        "caisses:read",
        "caisses:write"
      ],
      "allRequired": true
    },
    {
      "condition": "payment or pledge targets a campaign",
      "scopes": [
        "fundraising:read",
        "fundraising:write"
      ],
      "allRequired": true
    },
    {
      "condition": "payment has abo",
      "scopes": [
        "abonnements:read"
      ],
      "allRequired": true
    }
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/{id}/notes

Read the general CRM note and its exact revision

`get_contact_notes`

One authenticated organisation only. Campaign-restricted keys, including empty restrictions, are refused. Contact, interaction and document UUIDs are separate identities and are re-admitted as exact scalar ids after Mongo; a stored link or name grants no authority. The general CRM note is contact.description, distinct from the address note. An interaction is a CRM record, never a payment, reminder, message send or proof that an event happened. Attachments belong to the CONTACT, with no native link to a specific interaction; this API never invents that link. No payment, pledge, subscription, fiscal document, member access, provider state or physical media file is deleted or changed. No request triggers a remote download, sends a message or calls a provider. Unknown query/body fields are rejected. API-key authentication can record usage telemetry. Requires contacts:read. Returns only the general note, its presence marker and revision. Missing/null history remains null, not a fabricated empty note. Address notes are managed separately.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "Exact contact UUID in this organisation.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Stored general CRM note without unrelated contact fields.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactNotesReadResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, input shape, revision, idempotency key, event date, unknown parameter or non-empty read body.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY. Do not bypass access restrictions.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, INTERACTION_NOT_FOUND or COMMAND_NOT_FOUND. Missing, deleted and foreign resources share the same refusal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Ambiguous or invalid stored history, IDEMPOTENCY_CONFLICT, CONTACT_MUTATION_BLOCKED, or an unavailable owner prerequisite. No partial private object is returned.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Read the command receipt before deciding whether a submitted write may have happened.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-mcp-output-schema": true
}
```

## PATCH /contacts/{id}/notes

Correct the general CRM note with a durable command

`edit_contact_notes`

Requires explicitly granted contacts:manage-interactions AND contacts:read AND contacts:write. Read the exact target first, then pass its expectedRevision and a stable idempotencyKey (8–128 ASCII letters/digits/._:-). The journal and an external per-contact lock precede the business effect. One exact BSON compare-and-set updates only the target fields; omitted fields and unrelated private metadata remain intact. Internal writers and other contacts remain active: this is not a transaction-wide lock or a future-state guarantee. Same key and intent returns the existing receipt without repeating the write; changed intent returns IDEMPOTENCY_CONFLICT. success:true confirms a command receipt, including a refused or uncertain command. APPLIED means one stored target update was acknowledged; NO_CHANGE means no mutation was needed; REJECTED made no business effect; CONFLICT lost the CAS; ADMITTING/RUNNING may be active or interrupted. UNKNOWN means the effect or final receipt is unproved and retains the external lock. canRetry:false is constant. Read get_contact_interaction_command; never use a new key, old unguarded endpoint or credentials to bypass uncertainty. No automatic retry, rollback, stale-lock takeover or recovery endpoint exists. One authenticated organisation only. Campaign-restricted keys, including empty restrictions, are refused. Contact, interaction and document UUIDs are separate identities and are re-admitted as exact scalar ids after Mongo; a stored link or name grants no authority. The general CRM note is contact.description, distinct from the address note. An interaction is a CRM record, never a payment, reminder, message send or proof that an event happened. Attachments belong to the CONTACT, with no native link to a specific interaction; this API never invents that link. No payment, pledge, subscription, fiscal document, member access, provider state or physical media file is deleted or changed. No request triggers a remote download, sends a message or calls a provider. Unknown query/body fields are rejected. API-key authentication can record usage telemetry. content is plain text up to 20000 characters. An explicit empty string clears this general note only. No address note, interaction or financial record is changed.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:manage-interactions",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "Exact contact UUID in this organisation.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$"
          },
          "content": {
            "type": "string",
            "maxLength": 20000
          }
        },
        "required": [
          "expectedRevision",
          "idempotencyKey",
          "content"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Conservative command status; inspect state instead of treating success:true as an applied edit.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionCommandResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "The existing command is admitting, running or interrupted; no second business execution is started.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, input shape, revision, idempotency key, event date, unknown parameter or non-empty read body.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY. Do not bypass access restrictions.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, INTERACTION_NOT_FOUND or COMMAND_NOT_FOUND. Missing, deleted and foreign resources share the same refusal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Ambiguous or invalid stored history, IDEMPOTENCY_CONFLICT, CONTACT_MUTATION_BLOCKED, or an unavailable owner prerequisite. No partial private object is returned.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Read the command receipt before deciding whether a submitted write may have happened.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE or CONTACT_MUTATION_FENCE_UNAVAILABLE. Do not substitute a new command to bypass an unknown receipt or unavailable admission guard.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:manage-interactions",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  },
  "x-unisoft-mcp-output-schema": true
}
```

## GET /contacts/{id}/interactions/{interactionId}

Read one existing CRM interaction and its time precision

`get_contact_interaction`

One authenticated organisation only. Campaign-restricted keys, including empty restrictions, are refused. Contact, interaction and document UUIDs are separate identities and are re-admitted as exact scalar ids after Mongo; a stored link or name grants no authority. The general CRM note is contact.description, distinct from the address note. An interaction is a CRM record, never a payment, reminder, message send or proof that an event happened. Attachments belong to the CONTACT, with no native link to a specific interaction; this API never invents that link. No payment, pledge, subscription, fiscal document, member access, provider state or physical media file is deleted or changed. No request triggers a remote download, sends a message or calls a provider. Unknown query/body fields are rejected. API-key authentication can record usage telemetry. Requires contacts:read. Resolve the interaction through the existing authorised list, then read it here for its revision. time.precision=DAY returns occurredOn only; the native noon UTC sorting anchor is not an event time and is never presented as one. INSTANT returns a qualified ISO instant. UNKNOWN preserves unavailable or inconsistent historical time. Staff access snapshots and AI/private metadata are excluded.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "Exact contact UUID in this organisation.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "interactionId",
  "in": "path",
  "required": true,
  "description": "Exact existing interaction UUID returned by the authorised interaction list; not the contact or command UUID.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Existing interaction with explicit day, instant or unknown time precision.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionReadResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, input shape, revision, idempotency key, event date, unknown parameter or non-empty read body.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY. Do not bypass access restrictions.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, INTERACTION_NOT_FOUND or COMMAND_NOT_FOUND. Missing, deleted and foreign resources share the same refusal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Ambiguous or invalid stored history, IDEMPOTENCY_CONFLICT, CONTACT_MUTATION_BLOCKED, or an unavailable owner prerequisite. No partial private object is returned.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Read the command receipt before deciding whether a submitted write may have happened.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-mcp-output-schema": true
}
```

## PATCH /contacts/{id}/interactions/{interactionId}

Correct an existing CRM interaction without creating another event

`edit_contact_interaction`

Requires explicitly granted contacts:manage-interactions AND contacts:read AND contacts:write. Read the exact target first, then pass its expectedRevision and a stable idempotencyKey (8–128 ASCII letters/digits/._:-). The journal and an external per-contact lock precede the business effect. One exact BSON compare-and-set updates only the target fields; omitted fields and unrelated private metadata remain intact. Internal writers and other contacts remain active: this is not a transaction-wide lock or a future-state guarantee. Same key and intent returns the existing receipt without repeating the write; changed intent returns IDEMPOTENCY_CONFLICT. success:true confirms a command receipt, including a refused or uncertain command. APPLIED means one stored target update was acknowledged; NO_CHANGE means no mutation was needed; REJECTED made no business effect; CONFLICT lost the CAS; ADMITTING/RUNNING may be active or interrupted. UNKNOWN means the effect or final receipt is unproved and retains the external lock. canRetry:false is constant. Read get_contact_interaction_command; never use a new key, old unguarded endpoint or credentials to bypass uncertainty. No automatic retry, rollback, stale-lock takeover or recovery endpoint exists. One authenticated organisation only. Campaign-restricted keys, including empty restrictions, are refused. Contact, interaction and document UUIDs are separate identities and are re-admitted as exact scalar ids after Mongo; a stored link or name grants no authority. The general CRM note is contact.description, distinct from the address note. An interaction is a CRM record, never a payment, reminder, message send or proof that an event happened. Attachments belong to the CONTACT, with no native link to a specific interaction; this API never invents that link. No payment, pledge, subscription, fiscal document, member access, provider state or physical media file is deleted or changed. No request triggers a remote download, sends a message or calls a provider. Unknown query/body fields are rejected. API-key authentication can record usage telemetry. changes supports only supplied type, content, actions, address and either occurredOn OR datetime. Text limits are type/action 100, content 20000, address 2000 characters; actions replaces the entire list, max 50 unique labels. occurredOn is an exact civil YYYY-MM-DD (years 1–9999); datetime is an ISO instant with timezone and at most three fractional digits. They are mutually exclusive. The native contact_activity_update owner preserves a known day for text-only edits and changes precision explicitly when a new day/instant is supplied. No author/source identity is forged and no interaction is created or deleted.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:manage-interactions",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "Exact contact UUID in this organisation.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "interactionId",
  "in": "path",
  "required": true,
  "description": "Exact existing interaction UUID returned by the authorised interaction list; not the contact or command UUID.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_4b1a347f28ed132dbea4"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Conservative command status; inspect state instead of treating success:true as an applied edit.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionCommandResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "The existing command is admitting, running or interrupted; no second business execution is started.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, input shape, revision, idempotency key, event date, unknown parameter or non-empty read body.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY. Do not bypass access restrictions.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, INTERACTION_NOT_FOUND or COMMAND_NOT_FOUND. Missing, deleted and foreign resources share the same refusal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Ambiguous or invalid stored history, IDEMPOTENCY_CONFLICT, CONTACT_MUTATION_BLOCKED, or an unavailable owner prerequisite. No partial private object is returned.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Read the command receipt before deciding whether a submitted write may have happened.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE or CONTACT_MUTATION_FENCE_UNAVAILABLE. Do not substitute a new command to bypass an unknown receipt or unavailable admission guard.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:manage-interactions",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  },
  "x-unisoft-mcp-output-schema": true
}
```

## GET /contacts/{id}/attachments

Read contact-level attachments and their exact set revision

`get_contact_attachments`

One authenticated organisation only. Campaign-restricted keys, including empty restrictions, are refused. Contact, interaction and document UUIDs are separate identities and are re-admitted as exact scalar ids after Mongo; a stored link or name grants no authority. The general CRM note is contact.description, distinct from the address note. An interaction is a CRM record, never a payment, reminder, message send or proof that an event happened. Attachments belong to the CONTACT, with no native link to a specific interaction; this API never invents that link. No payment, pledge, subscription, fiscal document, member access, provider state or physical media file is deleted or changed. No request triggers a remote download, sends a message or calls a provider. Unknown query/body fields are rejected. API-key authentication can record usage telemetry. Requires contacts:read. Returns at most 100 existing CRM attachment references with their set revision. Each available filename is admitted by the media owner for this organisation, regular storage, MIME/signature and image/PDF size at most 15 MiB. An unavailable or foreign historical file has filename:null and availability:UNAVAILABLE, never a private URL. recordedAt is the stored attachment/replacement date when valid, not proof of file upload or document issuance. Missing/invalid dates remain null. This read does not download media or prove antivirus, document authenticity or financial authority.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "Exact contact UUID in this organisation.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Contact attachment references; unavailable media stays hidden.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactAttachmentsReadResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, input shape, revision, idempotency key, event date, unknown parameter or non-empty read body.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY. Do not bypass access restrictions.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, INTERACTION_NOT_FOUND or COMMAND_NOT_FOUND. Missing, deleted and foreign resources share the same refusal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Ambiguous or invalid stored history, IDEMPOTENCY_CONFLICT, CONTACT_MUTATION_BLOCKED, or an unavailable owner prerequisite. No partial private object is returned.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Read the command receipt before deciding whether a submitted write may have happened.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-mcp-output-schema": true
}
```

## POST /contacts/{id}/attachments/commands

Add, correct or detach a contact-level CRM attachment

`edit_contact_attachments`

Requires explicitly granted contacts:manage-interactions AND contacts:read AND contacts:write. Read the exact target first, then pass its expectedRevision and a stable idempotencyKey (8–128 ASCII letters/digits/._:-). The journal and an external per-contact lock precede the business effect. One exact BSON compare-and-set updates only the target fields; omitted fields and unrelated private metadata remain intact. Internal writers and other contacts remain active: this is not a transaction-wide lock or a future-state guarantee. Same key and intent returns the existing receipt without repeating the write; changed intent returns IDEMPOTENCY_CONFLICT. success:true confirms a command receipt, including a refused or uncertain command. APPLIED means one stored target update was acknowledged; NO_CHANGE means no mutation was needed; REJECTED made no business effect; CONFLICT lost the CAS; ADMITTING/RUNNING may be active or interrupted. UNKNOWN means the effect or final receipt is unproved and retains the external lock. canRetry:false is constant. Read get_contact_interaction_command; never use a new key, old unguarded endpoint or credentials to bypass uncertainty. No automatic retry, rollback, stale-lock takeover or recovery endpoint exists. One authenticated organisation only. Campaign-restricted keys, including empty restrictions, are refused. Contact, interaction and document UUIDs are separate identities and are re-admitted as exact scalar ids after Mongo; a stored link or name grants no authority. The general CRM note is contact.description, distinct from the address note. An interaction is a CRM record, never a payment, reminder, message send or proof that an event happened. Attachments belong to the CONTACT, with no native link to a specific interaction; this API never invents that link. No payment, pledge, subscription, fiscal document, member access, provider state or physical media file is deleted or changed. No request triggers a remote download, sends a message or calls a provider. Unknown query/body fields are rejected. API-key authentication can record usage telemetry. First get_contact_attachments and use its whole-set revision. ADD accepts filename and optional name, creates one deterministic document UUID and refuses an already attached filename. EDIT selects an exact documentId and changes filename and/or name; other entries, that UUID and unrelated metadata remain intact. Replacing bytes reference updates the recorded attachment date; renaming alone preserves it. DETACH accepts only documentId and removes this CRM reference, never hosted bytes or a financial document. At most 100 attachments are allowed. filename must already be hosted for this organisation and pass canonical image/PDF validation at 15 MiB; no URL, path, remote rehosting or interaction attachment link is accepted. Uploading is a separate capability with its own scope. A filename/label saying receipt, mandate or ID does not issue/validate that document or activate a payment method.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:manage-interactions",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "Exact contact UUID in this organisation.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_891c98c82ce4abde0764"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Conservative command status; inspect state instead of treating success:true as an applied edit.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionCommandResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "The existing command is admitting, running or interrupted; no second business execution is started.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, input shape, revision, idempotency key, event date, unknown parameter or non-empty read body.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY. Do not bypass access restrictions.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, INTERACTION_NOT_FOUND or COMMAND_NOT_FOUND. Missing, deleted and foreign resources share the same refusal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Ambiguous or invalid stored history, IDEMPOTENCY_CONFLICT, CONTACT_MUTATION_BLOCKED, or an unavailable owner prerequisite. No partial private object is returned.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Read the command receipt before deciding whether a submitted write may have happened.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE or CONTACT_MUTATION_FENCE_UNAVAILABLE. Do not substitute a new command to bypass an unknown receipt or unavailable admission guard.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:manage-interactions",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  },
  "x-unisoft-mcp-output-schema": true
}
```

## GET /contacts/interaction-commands/{commandId}

Read a stored CRM correction command without retrying it

`get_contact_interaction_command`

Requires explicitly granted contacts:manage-interactions AND contacts:read AND contacts:write. Read the exact target first, then pass its expectedRevision and a stable idempotencyKey (8–128 ASCII letters/digits/._:-). The journal and an external per-contact lock precede the business effect. One exact BSON compare-and-set updates only the target fields; omitted fields and unrelated private metadata remain intact. Internal writers and other contacts remain active: this is not a transaction-wide lock or a future-state guarantee. Same key and intent returns the existing receipt without repeating the write; changed intent returns IDEMPOTENCY_CONFLICT. success:true confirms a command receipt, including a refused or uncertain command. APPLIED means one stored target update was acknowledged; NO_CHANGE means no mutation was needed; REJECTED made no business effect; CONFLICT lost the CAS; ADMITTING/RUNNING may be active or interrupted. UNKNOWN means the effect or final receipt is unproved and retains the external lock. canRetry:false is constant. Read get_contact_interaction_command; never use a new key, old unguarded endpoint or credentials to bypass uncertainty. No automatic retry, rollback, stale-lock takeover or recovery endpoint exists. One authenticated organisation only. Campaign-restricted keys, including empty restrictions, are refused. Contact, interaction and document UUIDs are separate identities and are re-admitted as exact scalar ids after Mongo; a stored link or name grants no authority. The general CRM note is contact.description, distinct from the address note. An interaction is a CRM record, never a payment, reminder, message send or proof that an event happened. Attachments belong to the CONTACT, with no native link to a specific interaction; this API never invents that link. No payment, pledge, subscription, fiscal document, member access, provider state or physical media file is deleted or changed. No request triggers a remote download, sends a message or calls a provider. Unknown query/body fields are rejected. API-key authentication can record usage telemetry. Reads only the command journal. A commandId differs from the contact, interaction and document UUIDs. A 404 or old RUNNING receipt does not prove that an earlier write failed. No lock is released or recovered by this read.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:manage-interactions",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### פרמטרים

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "description": "Command UUID returned by a CRM correction, not a contact or attachment UUID.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "The last stored command state; canRetry always remains false.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, input shape, revision, idempotency key, event date, unknown parameter or non-empty read body.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY. Do not bypass access restrictions.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, INTERACTION_NOT_FOUND or COMMAND_NOT_FOUND. Missing, deleted and foreign resources share the same refusal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Ambiguous or invalid stored history, IDEMPOTENCY_CONFLICT, CONTACT_MUTATION_BLOCKED, or an unavailable owner prerequisite. No partial private object is returned.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Read the command receipt before deciding whether a submitted write may have happened.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:manage-interactions",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-mcp-output-schema": true
}
```

## GET /contacts/sync/google/connections

Read qualified stored Google Contacts configuration

`list_contact_google_connections`

Requires contacts:read and explicitly granted contacts:sync:read; the latter is opt-in and never implied by contact rights. Campaign-restricted keys, including an empty campaign restriction, are refused because Google connections have no matching campaign fence. Read-only stored metadata of the current controlled Google Contacts integration in the authenticated organisation. This does not expose or invoke legacy Google synchronisation. No OAuth, token refresh, Google request, connection probe, worker wakeup, schedule change, import, confirmation, conflict decision, contact write or billing occurs; authentication can update key usage telemetry. No account email/subject, owner staff identity, environment/private callback, credentials, tokens, provider people data, photos, raw error, candidate coordinates, private proposal/prepared snapshot or reusable URL is returned. providerChecked:false and workerReadiness:null remain unverified even when status is CONNECTED or scheduleEnabled:true. Missing/malformed counters, booleans, states and non-native dates stay null, never manufactured zero/false or current timestamps. completeHistory:false: native runs/rows have retention and may expire; an empty result cannot prove no earlier import or no conflict. Every current connection/run parent is re-admitted as an exact scalar in the same organisation. A missing/inaccessible parent returns 404, not an empty successful page. limit 1–100, default 50; the source is capped at 5000 rows and 2 MiB projected metadata with 10000 ms per query. Overflow or inconsistent identity returns 422 without a partial catalogue; do not remove meaningful restrictions. Snapshot-bound cursor changes require a fresh first page. readAt is observation time, consistentSnapshot:false. Unknown/repeated query parameters, invalid IDs/types and every non-empty GET body are rejected. A 503 is a bounded read failure, never permission to start or retry an import. Connections are sorted ID_ASC. Only a complete stored configuration accepted by the real pure configuration validator is projected; missing/invalid configuration is null with UNAVAILABLE_OR_INVALID. No DEFAULT configuration, France country or missing policy is filled in. Fields and import-policy enums describe the stored inbound mapping, not outbound permission or execution readiness. groupIds are recorded Google contactGroups resource names, never Unisoft UUIDs; mappings retain their source/key/type pairs and exact category strings. Private runtime configuration is excluded. lastRunStats and lastRunState are the connection stored summary, not a recomputed live run or a guarantee of last successful import. hasImported is only a stored native boolean; absent remains null.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": [
    "contacts:sync:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  },
  "description": "Page size 1–100, default 50."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  },
  "description": "Opaque cursor bound to organisation, API key/scopes, parent selection and complete returned metadata snapshot. Restart when the recorded configuration/run/row output changes."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "A bounded qualified page of stored Google Contacts metadata.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncConnectionResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid identity, query, body or stale snapshot cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing explicit contact/synchronisation rights or unsupported campaign restriction.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Current connection or run is unavailable in this organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Stored source limit or inconsistent identities prevents a qualified page.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "The metadata read is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [
    "contacts:sync:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/sync/google/connections/{connectionId}/runs

Read recorded Google Contacts runs

`list_contact_google_runs`

Requires contacts:read and explicitly granted contacts:sync:read; the latter is opt-in and never implied by contact rights. Campaign-restricted keys, including an empty campaign restriction, are refused because Google connections have no matching campaign fence. Read-only stored metadata of the current controlled Google Contacts integration in the authenticated organisation. This does not expose or invoke legacy Google synchronisation. No OAuth, token refresh, Google request, connection probe, worker wakeup, schedule change, import, confirmation, conflict decision, contact write or billing occurs; authentication can update key usage telemetry. No account email/subject, owner staff identity, environment/private callback, credentials, tokens, provider people data, photos, raw error, candidate coordinates, private proposal/prepared snapshot or reusable URL is returned. providerChecked:false and workerReadiness:null remain unverified even when status is CONNECTED or scheduleEnabled:true. Missing/malformed counters, booleans, states and non-native dates stay null, never manufactured zero/false or current timestamps. completeHistory:false: native runs/rows have retention and may expire; an empty result cannot prove no earlier import or no conflict. Every current connection/run parent is re-admitted as an exact scalar in the same organisation. A missing/inaccessible parent returns 404, not an empty successful page. limit 1–100, default 50; the source is capped at 5000 rows and 2 MiB projected metadata with 10000 ms per query. Overflow or inconsistent identity returns 422 without a partial catalogue; do not remove meaningful restrictions. Snapshot-bound cursor changes require a fresh first page. readAt is observation time, consistentSnapshot:false. Unknown/repeated query parameters, invalid IDs/types and every non-empty GET body are rejected. A 503 is a bounded read failure, never permission to start or retry an import. Resolve connectionId from list_contact_google_connections. Runs are sorted by native BSON createdAt descending, with undated historical entries last and UUID ascending for ties; a null date is not assigned a chronological time. PREVIEW and IMPORT are distinct; a successful PREVIEW has not imported contacts. Stored loaded/created/updated/skipped/review/failed/pending counters preserve unknown values and do not assert all rows succeeded or bank/email activity. PARTIAL/FAILED/STOPPED and WRITE_UNCERTAIN require inspection; no retry/resume/confirm operation is exposed here. Error codes use an explicit allowlist; unsupported stored codes become UNKNOWN_STORED_CODE.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": [
    "contacts:sync:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "connectionId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Exact current Google connection/run UUID returned by this authorised metadata workflow; not a provider resource name, contact UUID or account subject."
}
```

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  },
  "description": "Page size 1–100, default 50."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  },
  "description": "Opaque cursor bound to organisation, API key/scopes, parent selection and complete returned metadata snapshot. Restart when the recorded configuration/run/row output changes."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "A bounded qualified page of stored Google Contacts metadata.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncRunResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid identity, query, body or stale snapshot cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing explicit contact/synchronisation rights or unsupported campaign restriction.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Current connection or run is unavailable in this organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Stored source limit or inconsistent identities prevents a qualified page.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "The metadata read is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [
    "contacts:sync:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/sync/google/connections/{connectionId}/runs/{runId}/conflicts

Read stored Google Contacts review reasons

`list_contact_google_conflicts`

Requires contacts:read and explicitly granted contacts:sync:read; the latter is opt-in and never implied by contact rights. Campaign-restricted keys, including an empty campaign restriction, are refused because Google connections have no matching campaign fence. Read-only stored metadata of the current controlled Google Contacts integration in the authenticated organisation. This does not expose or invoke legacy Google synchronisation. No OAuth, token refresh, Google request, connection probe, worker wakeup, schedule change, import, confirmation, conflict decision, contact write or billing occurs; authentication can update key usage telemetry. No account email/subject, owner staff identity, environment/private callback, credentials, tokens, provider people data, photos, raw error, candidate coordinates, private proposal/prepared snapshot or reusable URL is returned. providerChecked:false and workerReadiness:null remain unverified even when status is CONNECTED or scheduleEnabled:true. Missing/malformed counters, booleans, states and non-native dates stay null, never manufactured zero/false or current timestamps. completeHistory:false: native runs/rows have retention and may expire; an empty result cannot prove no earlier import or no conflict. Every current connection/run parent is re-admitted as an exact scalar in the same organisation. A missing/inaccessible parent returns 404, not an empty successful page. limit 1–100, default 50; the source is capped at 5000 rows and 2 MiB projected metadata with 10000 ms per query. Overflow or inconsistent identity returns 422 without a partial catalogue; do not remove meaningful restrictions. Snapshot-bound cursor changes require a fresh first page. readAt is observation time, consistentSnapshot:false. Unknown/repeated query parameters, invalid IDs/types and every non-empty GET body are rejected. A 503 is a bounded read failure, never permission to start or retry an import. Resolve connectionId then runId from the authorised metadata tools. Returns only stored rows whose state is REVIEW or resolution.kind is REVIEW, ordered row index then row ID. rowId is the native 64-character hash identity, not a contact UUID. A row can retain an old REVIEW resolution after a stored decision; this is a recorded review reason, not a promise of a current unresolved conflict. requiresHumanReview:true and canDecide:false: metadata does not grant an action, prove duplicate identity or permit applying a LINK/CREATE decision. Candidate IDs, counts, names, email/phone, source, proposal, prepared data and target hints are not returned, so no historical candidate reference grants current contact access. Reasons are explicit allowlisted native codes; unsupported values become UNKNOWN_STORED_CODE. Retained rows may expire independently of run summaries, so meta.total is the current retained review subset, not the original run conflict count.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": [
    "contacts:sync:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "connectionId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Exact current Google connection/run UUID returned by this authorised metadata workflow; not a provider resource name, contact UUID or account subject."
}
```

```json
{
  "name": "runId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Exact current Google connection/run UUID returned by this authorised metadata workflow; not a provider resource name, contact UUID or account subject."
}
```

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  },
  "description": "Page size 1–100, default 50."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  },
  "description": "Opaque cursor bound to organisation, API key/scopes, parent selection and complete returned metadata snapshot. Restart when the recorded configuration/run/row output changes."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "A bounded qualified page of stored Google Contacts metadata.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncConflictResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid identity, query, body or stale snapshot cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing explicit contact/synchronisation rights or unsupported campaign restriction.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Current connection or run is unavailable in this organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Stored source limit or inconsistent identities prevents a qualified page.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "The metadata read is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [
    "contacts:sync:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/{id}/communication-preferences

Read recorded communication refusals for a CRM contact

`get_contact_communication_preferences`

Requires contacts:read on the connected organisation and rejects every campaign-restricted key. The id is the exact CRM contact UUID, not a member account, send UUID or email. Read-only observation and preview for an explicit EMAIL unsubscribe. Returns a revision and the normalized email address for the command; this read creates neither consent nor a command. No body or query parameters are accepted. Only the current primary contact email is observed; no secondary address, parent or family email is substituted. EMAIL refusal is keyed by normalized address for the entire organisation, so every contact sharing that address is affected; a later contact email edit is not followed. RECORDED means a stored refusal in the native shared policy or mailing suppression list, while NOT_RECORDED is absence of a recorded refusal and never consent, opt-in, deliverability or permission to send. sharedPolicyOptOut is the shared blocked flag; historicalEmailRefusal includes old suppression addresses with case/outer-space variants recognized by that policy; legacyOptOut requires an exact normalized row actually used by legacy campaign preparation. These markers can disagree: a historical refusal alone does not prove every native sender excludes the address. Missing primary email yields ADDRESS_UNAVAILABLE and null evidence. SMS and WHATSAPP remain UNKNOWN/NO_CANONICAL_OPTOUT_OWNER with no mutation support; do not invent flags or delete coordinates to simulate a refusal. No resubscribe/opt-in operation exists. Reads re-admit exact scalar ownership and references after Mongo, at most 100 matching historical suppression rows and 10000 ms per read, with no globally atomic snapshot. A malformed or excessive source refuses the whole observation. No message is sent, no existing queue row is cancelled and no provider is contacted; the recorded refusal is not a guarantee that already prepared messages or every transactional sender will stop. Campaign audiences and exclusions remain owned by their existing workflows. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Observed refusals and supported command coverage; no consent or sending authorization is inferred.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCommunicationPreferencesResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, input, email, revision, idempotency key or missing acknowledgement; CHANNEL_OPTOUT_UNSUPPORTED rejects SMS/WHATSAPP. All query parameters and GET bodies are forbidden.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY; no contact or receipt grants additional authority.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND or PREFERENCE_COMMAND_NOT_FOUND. An absent receipt is not proof that another request made no effect.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "PREFERENCE_SOURCE_AMBIGUOUS or IDEMPOTENCY_CONFLICT; review source data or read the original receipt without changing its key/content.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "PREFERENCE_SOURCE_LIMIT: the whole observation is refused; no partial consent conclusion is returned.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR; no private exception or provider data is returned.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE: admission or outcome could not be proved. Read the original command; do not retry under a new key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/{id}/communication-preferences/unsubscribe

Record an explicit organisation-wide refusal for the reviewed contact email

`unsubscribe_contact_email`

Requires contacts:read on the connected organisation and rejects every campaign-restricted key. The id is the exact CRM contact UUID, not a member account, send UUID or email. Additionally requires explicitly granted contacts:unsubscribe, with no default grant. First read get_contact_communication_preferences. Supply channel EMAIL, its exact normalized address and revision, a stable idempotencyKey and acknowledgeSharedAddress:true after explaining the shared-address effect. The user must request this refusal; do not unsubscribe as a way to test sending. The server rechecks address/revision, records a durable receipt, obtains a per-address external lock and compare-and-sets ADMITTING to RUNNING before invoking the native recordUnsubscribe owner once. The owner blocks its shared policy first and writes the legacy suppression list second. Same key/content only reads the receipt; changed content yields IDEMPOTENCY_CONFLICT. ownerInvocationPossible:true means the owner was admitted and may have started, never proof of actual invocation or completion. No-op COMPLETED with ownerInvocationPossible:false means both stores were already observed blocked. COMPLETED verifies both stores for the explicitly reviewed address; it does not imply cancellation of queued sends or a global lock against internal writers. REJECTED means no native invocation; inspect error such as REVISION_CONFLICT, EMAIL_ADDRESS_CHANGED or PREFERENCE_COMMAND_BUSY. ADMITTING/RUNNING are pending or interrupted; elapsed time does not prove failure. PARTIAL/UNKNOWN retain the address lock and never authorize another attempt, new key or coordinate deletion. canRetry is always false; after a lost response read get_contact_communication_preference_command and request authorized review of uncertainty. If no commandId was received, repeat only the identical POST with its original key/content to retrieve the durable receipt; this never repeats the owner. success:true and HTTP 200 acknowledge a receipt, including REJECTED, so inspect state before claiming the refusal was fully recorded. Only the current primary contact email is observed; no secondary address, parent or family email is substituted. EMAIL refusal is keyed by normalized address for the entire organisation, so every contact sharing that address is affected; a later contact email edit is not followed. RECORDED means a stored refusal in the native shared policy or mailing suppression list, while NOT_RECORDED is absence of a recorded refusal and never consent, opt-in, deliverability or permission to send. sharedPolicyOptOut is the shared blocked flag; historicalEmailRefusal includes old suppression addresses with case/outer-space variants recognized by that policy; legacyOptOut requires an exact normalized row actually used by legacy campaign preparation. These markers can disagree: a historical refusal alone does not prove every native sender excludes the address. Missing primary email yields ADDRESS_UNAVAILABLE and null evidence. SMS and WHATSAPP remain UNKNOWN/NO_CANONICAL_OPTOUT_OWNER with no mutation support; do not invent flags or delete coordinates to simulate a refusal. No resubscribe/opt-in operation exists. Reads re-admit exact scalar ownership and references after Mongo, at most 100 matching historical suppression rows and 10000 ms per read, with no globally atomic snapshot. A malformed or excessive source refuses the whole observation. No message is sent, no existing queue row is cancelled and no provider is contacted; the recorded refusal is not a guarantee that already prepared messages or every transactional sender will stop. Campaign audiences and exclusions remain owned by their existing workflows. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:unsubscribe",
  "additional": [
    "contacts:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "channel": {
            "type": "string",
            "enum": [
              "EMAIL"
            ]
          },
          "address": {
            "type": "string",
            "maxLength": 320,
            "format": "email"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[a-zA-Z0-9._:-]{8,128}$"
          },
          "acknowledgeSharedAddress": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "channel",
          "address",
          "revision",
          "idempotencyKey",
          "acknowledgeSharedAddress"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Durable COMPLETED, REJECTED, PARTIAL or UNKNOWN receipt; inspect state and both verification flags.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCommunicationPreferenceReceiptResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "The same command remains ADMITTING or RUNNING; no native invocation was repeated.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCommunicationPreferenceReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, input, email, revision, idempotency key or missing acknowledgement; CHANNEL_OPTOUT_UNSUPPORTED rejects SMS/WHATSAPP. All query parameters and GET bodies are forbidden.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY; no contact or receipt grants additional authority.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND or PREFERENCE_COMMAND_NOT_FOUND. An absent receipt is not proof that another request made no effect.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "PREFERENCE_SOURCE_AMBIGUOUS or IDEMPOTENCY_CONFLICT; review source data or read the original receipt without changing its key/content.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "PREFERENCE_SOURCE_LIMIT: the whole observation is refused; no partial consent conclusion is returned.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR; no private exception or provider data is returned.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE: admission or outcome could not be proved. Read the original command; do not retry under a new key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:unsubscribe",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /contacts/{id}/communication-preferences/commands/{commandId}

Read a durable contact email refusal command without replay

`get_contact_communication_preference_command`

Requires contacts:read on the connected organisation and rejects every campaign-restricted key. The id is the exact CRM contact UUID, not a member account, send UUID or email. Additionally requires explicitly granted contacts:unsubscribe. Read the commandId UUID returned by unsubscribe_contact_email. A current same-organisation contact record is required; its later email change does not redirect the receipt address, and a soft-deleted same-organisation contact may still retain its receipt. No body/query is accepted. This returns the last durable state only, without reading providers, retrying the native owner or recovering a lock. ADMITTING/RUNNING may be in flight or interrupted. PARTIAL/UNKNOWN require authorized review; no new-key retry, age-based takeover or internal fallback is available. An absent receipt does not prove the original request made no effect. Only the current primary contact email is observed; no secondary address, parent or family email is substituted. EMAIL refusal is keyed by normalized address for the entire organisation, so every contact sharing that address is affected; a later contact email edit is not followed. RECORDED means a stored refusal in the native shared policy or mailing suppression list, while NOT_RECORDED is absence of a recorded refusal and never consent, opt-in, deliverability or permission to send. sharedPolicyOptOut is the shared blocked flag; historicalEmailRefusal includes old suppression addresses with case/outer-space variants recognized by that policy; legacyOptOut requires an exact normalized row actually used by legacy campaign preparation. These markers can disagree: a historical refusal alone does not prove every native sender excludes the address. Missing primary email yields ADDRESS_UNAVAILABLE and null evidence. SMS and WHATSAPP remain UNKNOWN/NO_CANONICAL_OPTOUT_OWNER with no mutation support; do not invent flags or delete coordinates to simulate a refusal. No resubscribe/opt-in operation exists. Reads re-admit exact scalar ownership and references after Mongo, at most 100 matching historical suppression rows and 10000 ms per read, with no globally atomic snapshot. A malformed or excessive source refuses the whole observation. No message is sent, no existing queue row is cancelled and no provider is contacted; the recorded refusal is not a guarantee that already prepared messages or every transactional sender will stop. Campaign audiences and exclusions remain owned by their existing workflows. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:unsubscribe",
  "additional": [
    "contacts:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Last durable receipt; no replay or recovery.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCommunicationPreferenceReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, input, email, revision, idempotency key or missing acknowledgement; CHANNEL_OPTOUT_UNSUPPORTED rejects SMS/WHATSAPP. All query parameters and GET bodies are forbidden.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY; no contact or receipt grants additional authority.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND or PREFERENCE_COMMAND_NOT_FOUND. An absent receipt is not proof that another request made no effect.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "PREFERENCE_SOURCE_AMBIGUOUS or IDEMPOTENCY_CONFLICT; review source data or read the original receipt without changing its key/content.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "PREFERENCE_SOURCE_LIMIT: the whole observation is refused; no partial consent conclusion is returned.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR; no private exception or provider data is returned.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE: admission or outcome could not be proved. Read the original command; do not retry under a new key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:unsubscribe",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/lists/{listId}/members

Read members of an authorised calculated contact list

`list_contact_list_members`

Requires contacts:read plus every source scope for the exact listId. Copy listId from list_contact_lists: form:<UUID>, product:<formUUID>:<productUUID>, cagnotte:<UUID>, event:<UUID> or fundraising:<UUID>; a source UUID alone is invalid. form/product require forms:read AND forms_submit:read; cagnotte requires caisses:read AND paiements:read; event requires all of those plus events:read; fundraising requires fundraising:read AND paiements:read AND abonnements:read AND promesses:read. The key's campaign restriction applies to fundraising sources. Uses the same canonical guarded discovery/CRM owners as search_contacts_advanced: current live sources, exact scalar references, active projection generation and every domain scope are re-admitted. No fake ADMIN context or stored contact.poles access grant is used. Default excludes archived contacts; archived:true selects archived contacts instead. Deleted contacts remain excluded. Results are minimal contact summaries in binary ID_ASC order; default limit 50, maximum 100. Preserve archived/limit and the opaque cursor until hasMore:false, including empty pages. meta.count is this page only, not the full membership total. Concurrent sources can change; listComputedAt is only a known last-success projection time and consistentSnapshot:false. A changed list generation invalidates continuation. Source reads are bounded to 20000 rows and 10000 ms each; a limit/error returns no invented partial membership. These lists are automatic participation/contribution projections, not editable manual lists, consent, staff approval or bank settlement. No owner supports manual creation/deletion of list definitions or direct add/remove of derived members; use the real form/payment/event source workflow when explicitly authorised, never simulate membership by writing projections. No sync, rebuild, source mutation, provider call or business effect occurs. No request body is accepted and only limit/cursor/archived query fields are allowed. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "listId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 400
  }
}
```

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  }
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  }
}
```

```json
{
  "name": "archived",
  "in": "query",
  "schema": {
    "type": "boolean"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified member page using the existing contact discovery response contract.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_MEMBERS_QUERY, INVALID_CONTACT_LIST_ID, INVALID_POLE_ID, INVALID_POLE_RULE_COMMAND, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_TAGS, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, INVALID_UUID or ACCESS_CHANGE_NOT_ACKNOWLEDGED: correct the declared input.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: current exact organisation and all relevant scopes are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "POLE_NOT_FOUND, CONTACT_LIST_UNAVAILABLE, CONTACT_POLE_UNAVAILABLE or COMMAND_NOT_FOUND: select a current authorised list, pole or receipt.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CONTACT_LIST_NOT_READY, CONTACT_LIST_HISTORY_INCOMPLETE, AMBIGUOUS_POLE_CONFIGURATION, INVALID_POLE_RULE_HISTORY or IDEMPOTENCY_CONFLICT: review the owner projection/history or retain the original command content.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "CONTACT_SEARCH_SOURCE_LIMIT, CONTACT_SEARCH_INVALID_SOURCE or CONTACT_SEARCH_AMBIGUOUS_ID: narrow the selection or correct its source identities; no truncated/partial member page is returned.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "CONTACT_LIST_OWNER_UNAVAILABLE, CONTACT_SEARCH_LIMIT_REACHED or POLE_RULE_JOURNAL_UNAVAILABLE: a qualified read or command outcome could not be proved; no automatic command replay.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-conditional-scopes": [
    {
      "condition": "listId is a form: list",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "listId is a product: list",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "listId is a cagnotte: list",
      "scopes": [
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "listId is a event: list",
      "scopes": [
        "events:read",
        "forms:read",
        "forms_submit:read",
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "listId is a fundraising: list",
      "scopes": [
        "fundraising:read",
        "paiements:read",
        "abonnements:read",
        "promesses:read"
      ],
      "allRequired": true
    }
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/poles/{poleId}/members

Read current derived membership of a contact pole

`list_contact_pole_members`

Requires contacts:read AND events:read AND forms:read AND forms_submit:read AND caisses:read AND paiements:read. Every campaign-restricted key is refused. poleId is a current pole UUID or MAIN for the default pole id:null. Computes current native membership from category rules and authorised business sources without repairing the stored pole projection. Uses the same canonical guarded discovery/CRM owners as search_contacts_advanced: current live sources, exact scalar references, active projection generation and every domain scope are re-admitted. No fake ADMIN context or stored contact.poles access grant is used. Default excludes archived contacts; archived:true selects archived contacts instead. Deleted contacts remain excluded. Results are minimal contact summaries in binary ID_ASC order; default limit 50, maximum 100. Preserve archived/limit and the opaque cursor until hasMore:false, including empty pages. meta.count is this page only, not the full membership total. Concurrent sources can change; listComputedAt is only a known last-success projection time and consistentSnapshot:false. A changed list generation invalidates continuation. Source reads are bounded to 20000 rows and 10000 ms each; a limit/error returns no invented partial membership. These lists are automatic participation/contribution projections, not editable manual lists, consent, staff approval or bank settlement. No owner supports manual creation/deletion of list definitions or direct add/remove of derived members; use the real form/payment/event source workflow when explicitly authorised, never simulate membership by writing projections. No sync, rebuild, source mutation, provider call or business effect occurs. No request body is accepted and only limit/cursor/archived query fields are allowed. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": [
    "events:read",
    "forms:read",
    "forms_submit:read",
    "caisses:read",
    "paiements:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "poleId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 40
  }
}
```

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  }
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  }
}
```

```json
{
  "name": "archived",
  "in": "query",
  "schema": {
    "type": "boolean"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified current pole-member page; no membership or projection write.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_MEMBERS_QUERY, INVALID_CONTACT_LIST_ID, INVALID_POLE_ID, INVALID_POLE_RULE_COMMAND, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_TAGS, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, INVALID_UUID or ACCESS_CHANGE_NOT_ACKNOWLEDGED: correct the declared input.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: current exact organisation and all relevant scopes are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "POLE_NOT_FOUND, CONTACT_LIST_UNAVAILABLE, CONTACT_POLE_UNAVAILABLE or COMMAND_NOT_FOUND: select a current authorised list, pole or receipt.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CONTACT_LIST_NOT_READY, CONTACT_LIST_HISTORY_INCOMPLETE, AMBIGUOUS_POLE_CONFIGURATION, INVALID_POLE_RULE_HISTORY or IDEMPOTENCY_CONFLICT: review the owner projection/history or retain the original command content.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "CONTACT_SEARCH_SOURCE_LIMIT, CONTACT_SEARCH_INVALID_SOURCE or CONTACT_SEARCH_AMBIGUOUS_ID: narrow the selection or correct its source identities; no truncated/partial member page is returned.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "CONTACT_LIST_OWNER_UNAVAILABLE, CONTACT_SEARCH_LIMIT_REACHED or POLE_RULE_JOURNAL_UNAVAILABLE: a qualified read or command outcome could not be proved; no automatic command replay.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [
    "events:read",
    "forms:read",
    "forms_submit:read",
    "caisses:read",
    "paiements:read"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/poles/{poleId}/category-rules

Read the category rule controlling derived contact pole membership

`get_contact_pole_category_rules`

Requires explicit contacts:manage AND contacts:read AND contacts:write; manage is opt-in and campaign-restricted keys (including empty restrictions) are refused. poleId is a current pole UUID; MAIN selects the native default pole id:null, not a custom UUID or the string null. Changes affect organisation contact visibility through the canonical category-based pole membership rule. Direct contact.poles assignment is unsupported: membership comes from any selected category OR eligible registration/payment sources. Existing catalogue operations list_contact_lists/list_contact_poles discover the identifiers; a tag and a list ID are different objects. Reads only contact category criteria, label, configuration presence and revision. No staff-access whitelist or private organisation configuration is exposed. Missing configuration means configured:false and tags:[], not a fabricated membership total. The native rule matches any tag; empty tags remove category-based membership only, while registrations/payments can still confer membership. This is not the full pole membership or a manual member list. projectionRefreshed:false means no stored projection rebuild is performed. No request body, query, source refresh, provider call or business mutation occurs.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:manage",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### פרמטרים

```json
{
  "name": "poleId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 40
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Current category rule and revision; no staff whitelist.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPoleRuleStateResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_MEMBERS_QUERY, INVALID_CONTACT_LIST_ID, INVALID_POLE_ID, INVALID_POLE_RULE_COMMAND, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_TAGS, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, INVALID_UUID or ACCESS_CHANGE_NOT_ACKNOWLEDGED: correct the declared input.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: current exact organisation and all relevant scopes are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "POLE_NOT_FOUND, CONTACT_LIST_UNAVAILABLE, CONTACT_POLE_UNAVAILABLE or COMMAND_NOT_FOUND: select a current authorised list, pole or receipt.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CONTACT_LIST_NOT_READY, CONTACT_LIST_HISTORY_INCOMPLETE, AMBIGUOUS_POLE_CONFIGURATION, INVALID_POLE_RULE_HISTORY or IDEMPOTENCY_CONFLICT: review the owner projection/history or retain the original command content.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "CONTACT_SEARCH_SOURCE_LIMIT, CONTACT_SEARCH_INVALID_SOURCE or CONTACT_SEARCH_AMBIGUOUS_ID: narrow the selection or correct its source identities; no truncated/partial member page is returned.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "CONTACT_LIST_OWNER_UNAVAILABLE, CONTACT_SEARCH_LIMIT_REACHED or POLE_RULE_JOURNAL_UNAVAILABLE: a qualified read or command outcome could not be proved; no automatic command replay.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:manage",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## PATCH /contacts/poles/{poleId}/category-rules

Replace a pole's category membership rule with a guarded command

`set_contact_pole_category_rules`

Requires explicit contacts:manage AND contacts:read AND contacts:write; manage is opt-in and campaign-restricted keys (including empty restrictions) are refused. poleId is a current pole UUID; MAIN selects the native default pole id:null, not a custom UUID or the string null. Changes affect organisation contact visibility through the canonical category-based pole membership rule. Direct contact.poles assignment is unsupported: membership comes from any selected category OR eligible registration/payment sources. Existing catalogue operations list_contact_lists/list_contact_poles discover the identifiers; a tag and a list ID are different objects. First get_contact_pole_category_rules; submit its revision, the complete replacement tags array (0–500 labels), stable idempotencyKey (8–128 ASCII letters/digits/._:-) and acknowledgeAccessChange:true after explaining the visibility effect. Existing exact observed/configured labels are preserved; new labels use canonical CRM formatting (uppercase, accents removed, spaces converted to underscores). Tags are de-duplicated/sorted. No contact tag is changed, no contact is directly assigned/removed and staff whitelist stays untouched. Empty tags disable only category-derived membership; it neither clears payment/registration membership nor deletes the pole/list. This adapts the canonical native pole config writer, with a durable command receipt/external per-pole lock before effect, revision check, exact BSON CAS for existing config and read-back. An absent config is created once with a deterministic Mongo identity; a concurrent native duplicate is detected after insertion and reported UNKNOWN, never silently chosen. Same key/content returns its receipt; changed content returns IDEMPOTENCY_CONFLICT. APPLIED/NO_CHANGE verify the stored criteria and return their canonical appliedTags; null means no qualified tag snapshot, never an empty rule. REJECTED made no effect, CONFLICT lost CAS and UNKNOWN retains the lock when effect/verification is unproved. ADMITTING/RUNNING may be in flight or interrupted. success:true confirms a receipt, not membership recalculation. canRetry:false: read get_contact_pole_rule_command after uncertainty and never repeat with a new key or mutate contact.poles as a workaround. No rollback, automatic recovery or stale-lock takeover exists. projectionRefreshed:false: as in the native config workflow, stored membership projections are not rebuilt here; member reads use live owners and may show changes independently. No provider, message or unrelated source mutation occurs. No query fields are accepted.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:manage",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### פרמטרים

```json
{
  "name": "poleId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 40
  }
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "tags": {
            "type": "array",
            "maxItems": 500,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[a-zA-Z0-9._:-]{8,128}$"
          },
          "acknowledgeAccessChange": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "tags",
          "revision",
          "idempotencyKey",
          "acknowledgeAccessChange"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Terminal stored rule-change receipt; no direct membership assignment.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPoleRuleReceiptResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "The existing command is ADMITTING or RUNNING; no effect replay.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPoleRuleReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_MEMBERS_QUERY, INVALID_CONTACT_LIST_ID, INVALID_POLE_ID, INVALID_POLE_RULE_COMMAND, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_TAGS, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, INVALID_UUID or ACCESS_CHANGE_NOT_ACKNOWLEDGED: correct the declared input.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: current exact organisation and all relevant scopes are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "POLE_NOT_FOUND, CONTACT_LIST_UNAVAILABLE, CONTACT_POLE_UNAVAILABLE or COMMAND_NOT_FOUND: select a current authorised list, pole or receipt.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CONTACT_LIST_NOT_READY, CONTACT_LIST_HISTORY_INCOMPLETE, AMBIGUOUS_POLE_CONFIGURATION, INVALID_POLE_RULE_HISTORY or IDEMPOTENCY_CONFLICT: review the owner projection/history or retain the original command content.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "CONTACT_SEARCH_SOURCE_LIMIT, CONTACT_SEARCH_INVALID_SOURCE or CONTACT_SEARCH_AMBIGUOUS_ID: narrow the selection or correct its source identities; no truncated/partial member page is returned.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "CONTACT_LIST_OWNER_UNAVAILABLE, CONTACT_SEARCH_LIMIT_REACHED or POLE_RULE_JOURNAL_UNAVAILABLE: a qualified read or command outcome could not be proved; no automatic command replay.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:manage",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /contacts/pole-rule-commands/{commandId}

Read the durable status of a pole category-rule command

`get_contact_pole_rule_command`

Requires explicit contacts:manage AND contacts:read AND contacts:write; manage is opt-in and campaign-restricted keys (including empty restrictions) are refused. poleId is a current pole UUID; MAIN selects the native default pole id:null, not a custom UUID or the string null. Changes affect organisation contact visibility through the canonical category-based pole membership rule. Direct contact.poles assignment is unsupported: membership comes from any selected category OR eligible registration/payment sources. Existing catalogue operations list_contact_lists/list_contact_poles discover the identifiers; a tag and a list ID are different objects. Use the commandId UUID returned by set_contact_pole_category_rules. Reads only the last durable receipt, rechecking current scopes and organisation. No request body/query is accepted. No retry, sync, projection rebuild or lock release occurs. ADMITTING/RUNNING can be interrupted; UNKNOWN remains uncertain and blocks a new-key rule command for this pole. Request authorised Unisoft review. Age, timeout or an absent receipt never proves no effect. appliedTags describes only the criteria verified at execution time, not a later live rule. A verified APPLIED rule does not prove a full membership refresh. canRetry:false in every state.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:manage",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### פרמטרים

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Last durable rule-change status; no replay or projection effect.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPoleRuleReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_MEMBERS_QUERY, INVALID_CONTACT_LIST_ID, INVALID_POLE_ID, INVALID_POLE_RULE_COMMAND, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_TAGS, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, INVALID_UUID or ACCESS_CHANGE_NOT_ACKNOWLEDGED: correct the declared input.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: current exact organisation and all relevant scopes are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "POLE_NOT_FOUND, CONTACT_LIST_UNAVAILABLE, CONTACT_POLE_UNAVAILABLE or COMMAND_NOT_FOUND: select a current authorised list, pole or receipt.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CONTACT_LIST_NOT_READY, CONTACT_LIST_HISTORY_INCOMPLETE, AMBIGUOUS_POLE_CONFIGURATION, INVALID_POLE_RULE_HISTORY or IDEMPOTENCY_CONFLICT: review the owner projection/history or retain the original command content.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "CONTACT_SEARCH_SOURCE_LIMIT, CONTACT_SEARCH_INVALID_SOURCE or CONTACT_SEARCH_AMBIGUOUS_ID: narrow the selection or correct its source identities; no truncated/partial member page is returned.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "CONTACT_LIST_OWNER_UNAVAILABLE, CONTACT_SEARCH_LIMIT_REACHED or POLE_RULE_JOURNAL_UNAVAILABLE: a qualified read or command outcome could not be proved; no automatic command replay.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:manage",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/households/capabilities

Discover CRM household membership and role commands

`get_contact_household_capabilities`

Requires contact_households:read AND contacts:read, both explicitly granted. A CRM household is the existing named grouping of contacts, not a member account, visitor family access, organisation or financial household ledger. A person may belong to several households. Membership, recorded household HEAD/MEMBER role, global contact.isGlobalFamilyHead flag and directed CRM relationship are separate facts: none grants a login, administrator role or financial permission. No gender, spouse, parent, guardianship or legal/tax role is inferred. id is the household UUID; contact IDs come from authorised contact tools. name is the stored household label; displayName follows the native display from the current member head's first/last name and may be empty. recordedHeadContactId is the admitted stored head even when not a member; headContactId is non-null only for a current member. headState UNASSIGNED/MEMBER/NOT_A_MEMBER qualifies that observation, not an access state. Null names/flags remain unknown. Details return only minimal member identity, opaque contact/household revisions, recorded relations between current household members and legacy parent IDs within that same membership. Relations outside the household are not listed and their absence is not historical absence. legacyParentContactIds is native child-to-parent storage, distinct from the explicit relationships list. Source PARENT means sourceContactId is the parent of relatedContactId; CHILD is its inverse. SPOUSE, SIBLING, GRANDPARENT/GRANDCHILD and other schema values retain their exact source direction. No raw CRM, coordinates, notes, documents, settings, passwords, sessions, credentials or money is returned. No payment, pledge, subscription, receipt, billing or member-account state is written. Member access from an external application remains deferred by product decision. Every returned identity is readmitted as an exact scalar in the authenticated organisation; campaign-restricted keys are refused because household membership has no independent campaign authority. Reads do not initialise, repair, infer/recover a family, synchronise, call a provider or mutate business data; authentication may update key telemetry. Unknown parameters/types and nonempty GET bodies are rejected. Live reads are not a transaction or historical snapshot. Details are bounded to 200 members, 200 memberships/legacy parents per contact, 2000 stored relations per contact and 1000 returned relation/legacy-parent entries combined; overflow refuses the whole result rather than truncating it. Static capability only: does not inspect any household/contact or calculate impact. Accepts no query/body. Campaign-restricted keys may discover this same static response but cannot read or change households. Roles are only the native HEAD and MEMBER; no custom family/account roles are created.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contact_households:read",
  "additional": [
    "contacts:read"
  ]
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Current authorised CRM household observation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactHouseholdCapabilities"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_HOUSEHOLD_QUERY, INVALID_HOUSEHOLD_CURSOR, INVALID_HOUSEHOLD_ID, INVALID_HOUSEHOLD_COMMAND or UNEXPECTED_REQUEST_BODY: use only the declared exact arguments.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: no household authority or account access is granted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "HOUSEHOLD_NOT_FOUND: a required household, contact, head or ancestry reference is absent, deleted, foreign or inadmissible.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Ambiguous identity/history, changed revision, head/membership/relation conflict, ancestry cycle, bounded graph/member overflow, concurrent or mismatched idempotent command. Inspect the exact error code; do not bypass it through legacy contact tools.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "HOUSEHOLD_READ_UNAVAILABLE or HOUSEHOLD_COMMAND_UNAVAILABLE: preserve a command's original identity on a lost/uncertain response; never infer that no effect occurred.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_households:read",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/households

List existing CRM household identifiers and labels

`list_contact_households`

Requires contact_households:read AND contacts:read, both explicitly granted. A CRM household is the existing named grouping of contacts, not a member account, visitor family access, organisation or financial household ledger. A person may belong to several households. Membership, recorded household HEAD/MEMBER role, global contact.isGlobalFamilyHead flag and directed CRM relationship are separate facts: none grants a login, administrator role or financial permission. No gender, spouse, parent, guardianship or legal/tax role is inferred. id is the household UUID; contact IDs come from authorised contact tools. name is the stored household label; displayName follows the native display from the current member head's first/last name and may be empty. recordedHeadContactId is the admitted stored head even when not a member; headContactId is non-null only for a current member. headState UNASSIGNED/MEMBER/NOT_A_MEMBER qualifies that observation, not an access state. Null names/flags remain unknown. Details return only minimal member identity, opaque contact/household revisions, recorded relations between current household members and legacy parent IDs within that same membership. Relations outside the household are not listed and their absence is not historical absence. legacyParentContactIds is native child-to-parent storage, distinct from the explicit relationships list. Source PARENT means sourceContactId is the parent of relatedContactId; CHILD is its inverse. SPOUSE, SIBLING, GRANDPARENT/GRANDCHILD and other schema values retain their exact source direction. No raw CRM, coordinates, notes, documents, settings, passwords, sessions, credentials or money is returned. No payment, pledge, subscription, receipt, billing or member-account state is written. Member access from an external application remains deferred by product decision. Every returned identity is readmitted as an exact scalar in the authenticated organisation; campaign-restricted keys are refused because household membership has no independent campaign authority. Reads do not initialise, repair, infer/recover a family, synchronise, call a provider or mutate business data; authentication may update key telemetry. Unknown parameters/types and nonempty GET bodies are rejected. Live reads are not a transaction or historical snapshot. Details are bounded to 200 members, 200 memberships/legacy parents per contact, 2000 stored relations per contact and 1000 returned relation/legacy-parent entries combined; overflow refuses the whole result rather than truncating it. Catalogue only: returns household UUIDs and stored labels, without member counts, heads or impact. limit defaults to 50, maximum 100. Sorts exact UUID ascending; preserve the opaque nextCursor with the same organisation, key and scopes until hasMore=false when a complete catalogue is needed. count is this page's size, never the organisation total. Membership can change between pages. No household creation is exposed by these tools.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contact_households:read",
  "additional": [
    "contacts:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  }
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "maxLength": 400,
    "pattern": "^[A-Za-z0-9_-]+$"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Current authorised CRM household observation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data",
          "meta"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactHouseholdSummary"
            }
          },
          "meta": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "count",
              "hasMore",
              "nextCursor"
            ],
            "properties": {
              "count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "hasMore": {
                "type": "boolean"
              },
              "nextCursor": {
                "type": "string",
                "nullable": true
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_HOUSEHOLD_QUERY, INVALID_HOUSEHOLD_CURSOR, INVALID_HOUSEHOLD_ID, INVALID_HOUSEHOLD_COMMAND or UNEXPECTED_REQUEST_BODY: use only the declared exact arguments.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: no household authority or account access is granted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "HOUSEHOLD_NOT_FOUND: a required household, contact, head or ancestry reference is absent, deleted, foreign or inadmissible.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Ambiguous identity/history, changed revision, head/membership/relation conflict, ancestry cycle, bounded graph/member overflow, concurrent or mismatched idempotent command. Inspect the exact error code; do not bypass it through legacy contact tools.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "HOUSEHOLD_READ_UNAVAILABLE or HOUSEHOLD_COMMAND_UNAVAILABLE: preserve a command's original identity on a lost/uncertain response; never infer that no effect occurred.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_households:read",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/households/{id}

Read one CRM household, its current members, head and family graph

`get_contact_household`

Requires contact_households:read AND contacts:read, both explicitly granted. A CRM household is the existing named grouping of contacts, not a member account, visitor family access, organisation or financial household ledger. A person may belong to several households. Membership, recorded household HEAD/MEMBER role, global contact.isGlobalFamilyHead flag and directed CRM relationship are separate facts: none grants a login, administrator role or financial permission. No gender, spouse, parent, guardianship or legal/tax role is inferred. id is the household UUID; contact IDs come from authorised contact tools. name is the stored household label; displayName follows the native display from the current member head's first/last name and may be empty. recordedHeadContactId is the admitted stored head even when not a member; headContactId is non-null only for a current member. headState UNASSIGNED/MEMBER/NOT_A_MEMBER qualifies that observation, not an access state. Null names/flags remain unknown. Details return only minimal member identity, opaque contact/household revisions, recorded relations between current household members and legacy parent IDs within that same membership. Relations outside the household are not listed and their absence is not historical absence. legacyParentContactIds is native child-to-parent storage, distinct from the explicit relationships list. Source PARENT means sourceContactId is the parent of relatedContactId; CHILD is its inverse. SPOUSE, SIBLING, GRANDPARENT/GRANDCHILD and other schema values retain their exact source direction. No raw CRM, coordinates, notes, documents, settings, passwords, sessions, credentials or money is returned. No payment, pledge, subscription, receipt, billing or member-account state is written. Member access from an external application remains deferred by product decision. Every returned identity is readmitted as an exact scalar in the authenticated organisation; campaign-restricted keys are refused because household membership has no independent campaign authority. Reads do not initialise, repair, infer/recover a family, synchronise, call a provider or mutate business data; authentication may update key telemetry. Unknown parameters/types and nonempty GET bodies are rejected. Live reads are not a transaction or historical snapshot. Details are bounded to 200 members, 200 memberships/legacy parents per contact, 2000 stored relations per contact and 1000 returned relation/legacy-parent entries combined; overflow refuses the whole result rather than truncating it. Supply an exact household UUID from list_contact_households or a contact's membership list. Accepts no query/body. Read revision freshly before a command. A recorded head who is not a current member is qualified NOT_A_MEMBER; do not invent a replacement from gender, names or the global family-head flag.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contact_households:read",
  "additional": [
    "contacts:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Current authorised CRM household observation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactHousehold"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_HOUSEHOLD_QUERY, INVALID_HOUSEHOLD_CURSOR, INVALID_HOUSEHOLD_ID, INVALID_HOUSEHOLD_COMMAND or UNEXPECTED_REQUEST_BODY: use only the declared exact arguments.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: no household authority or account access is granted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "HOUSEHOLD_NOT_FOUND: a required household, contact, head or ancestry reference is absent, deleted, foreign or inadmissible.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Ambiguous identity/history, changed revision, head/membership/relation conflict, ancestry cycle, bounded graph/member overflow, concurrent or mismatched idempotent command. Inspect the exact error code; do not bypass it through legacy contact tools.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "HOUSEHOLD_READ_UNAVAILABLE or HOUSEHOLD_COMMAND_UNAVAILABLE: preserve a command's original identity on a lost/uncertain response; never infer that no effect occurred.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_households:read",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/{contactId}/households

Read a contact's CRM household memberships and command revision

`get_contact_household_memberships`

Requires contact_households:read AND contacts:read, both explicitly granted. A CRM household is the existing named grouping of contacts, not a member account, visitor family access, organisation or financial household ledger. A person may belong to several households. Membership, recorded household HEAD/MEMBER role, global contact.isGlobalFamilyHead flag and directed CRM relationship are separate facts: none grants a login, administrator role or financial permission. No gender, spouse, parent, guardianship or legal/tax role is inferred. id is the household UUID; contact IDs come from authorised contact tools. name is the stored household label; displayName follows the native display from the current member head's first/last name and may be empty. recordedHeadContactId is the admitted stored head even when not a member; headContactId is non-null only for a current member. headState UNASSIGNED/MEMBER/NOT_A_MEMBER qualifies that observation, not an access state. Null names/flags remain unknown. Details return only minimal member identity, opaque contact/household revisions, recorded relations between current household members and legacy parent IDs within that same membership. Relations outside the household are not listed and their absence is not historical absence. legacyParentContactIds is native child-to-parent storage, distinct from the explicit relationships list. Source PARENT means sourceContactId is the parent of relatedContactId; CHILD is its inverse. SPOUSE, SIBLING, GRANDPARENT/GRANDCHILD and other schema values retain their exact source direction. No raw CRM, coordinates, notes, documents, settings, passwords, sessions, credentials or money is returned. No payment, pledge, subscription, receipt, billing or member-account state is written. Member access from an external application remains deferred by product decision. Every returned identity is readmitted as an exact scalar in the authenticated organisation; campaign-restricted keys are refused because household membership has no independent campaign authority. Reads do not initialise, repair, infer/recover a family, synchronise, call a provider or mutate business data; authentication may update key telemetry. Unknown parameters/types and nonempty GET bodies are rejected. Live reads are not a transaction or historical snapshot. Details are bounded to 200 members, 200 memberships/legacy parents per contact, 2000 stored relations per contact and 1000 returned relation/legacy-parent entries combined; overflow refuses the whole result rather than truncating it. Supply an authorised contact UUID. Returns contactRevision and admitted household IDs/labels, including an empty list for an existing contact without households. This revision is required as expectedContactRevision for ADD_MEMBER or REMOVE_MEMBER, in addition to the household's revision. No query/body is accepted.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contact_households:read",
  "additional": [
    "contacts:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "contactId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Current authorised CRM household observation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactHouseholdContactMemberships"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_HOUSEHOLD_QUERY, INVALID_HOUSEHOLD_CURSOR, INVALID_HOUSEHOLD_ID, INVALID_HOUSEHOLD_COMMAND or UNEXPECTED_REQUEST_BODY: use only the declared exact arguments.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: no household authority or account access is granted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "HOUSEHOLD_NOT_FOUND: a required household, contact, head or ancestry reference is absent, deleted, foreign or inadmissible.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Ambiguous identity/history, changed revision, head/membership/relation conflict, ancestry cycle, bounded graph/member overflow, concurrent or mismatched idempotent command. Inspect the exact error code; do not bypass it through legacy contact tools.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "HOUSEHOLD_READ_UNAVAILABLE or HOUSEHOLD_COMMAND_UNAVAILABLE: preserve a command's original identity on a lost/uncertain response; never infer that no effect occurred.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_households:read",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/households/{id}/commands

Change CRM household membership, recorded head, label or an exact family relation

`apply_contact_household_command`

Requires contact_households:write AND contact_households:read AND contacts:read AND contacts:write, all explicitly granted. Requires contact_households:read AND contacts:read, both explicitly granted. A CRM household is the existing named grouping of contacts, not a member account, visitor family access, organisation or financial household ledger. A person may belong to several households. Membership, recorded household HEAD/MEMBER role, global contact.isGlobalFamilyHead flag and directed CRM relationship are separate facts: none grants a login, administrator role or financial permission. No gender, spouse, parent, guardianship or legal/tax role is inferred. id is the household UUID; contact IDs come from authorised contact tools. name is the stored household label; displayName follows the native display from the current member head's first/last name and may be empty. recordedHeadContactId is the admitted stored head even when not a member; headContactId is non-null only for a current member. headState UNASSIGNED/MEMBER/NOT_A_MEMBER qualifies that observation, not an access state. Null names/flags remain unknown. Details return only minimal member identity, opaque contact/household revisions, recorded relations between current household members and legacy parent IDs within that same membership. Relations outside the household are not listed and their absence is not historical absence. legacyParentContactIds is native child-to-parent storage, distinct from the explicit relationships list. Source PARENT means sourceContactId is the parent of relatedContactId; CHILD is its inverse. SPOUSE, SIBLING, GRANDPARENT/GRANDCHILD and other schema values retain their exact source direction. No raw CRM, coordinates, notes, documents, settings, passwords, sessions, credentials or money is returned. No payment, pledge, subscription, receipt, billing or member-account state is written. Member access from an external application remains deferred by product decision. Every returned identity is readmitted as an exact scalar in the authenticated organisation; campaign-restricted keys are refused because household membership has no independent campaign authority. Reads do not initialise, repair, infer/recover a family, synchronise, call a provider or mutate business data; authentication may update key telemetry. Unknown parameters/types and nonempty GET bodies are rejected. Live reads are not a transaction or historical snapshot. Details are bounded to 200 members, 200 memberships/legacy parents per contact, 2000 stored relations per contact and 1000 returned relation/legacy-parent entries combined; overflow refuses the whole result rather than truncating it. Read the household freshly and pass its exact revision as expectedRevision; use a new UUID idempotencyKey for this exact intention and preserve it with all original arguments on a lost response. Only the declared action's fields are accepted; no query parameters. ADD_MEMBER/REMOVE_MEMBER additionally need the contact's exact expectedContactRevision from get_contact_household_memberships or its member row. ADD_MEMBER calls the native append/dedup owner; REMOVE_MEMBER removes only that grouping reference, never the contact, CRM relations or member access. Removing the recorded head is refused until SET_HEAD assigns another current member or explicitly clears it with contactId:null. SET_HEAD adapts the native stored household head field, requires a current member and refuses a conflicting household already headed by that contact; it does not change the global family-head flag or infer a parent/spouse. RENAME changes only the stored label (1–250 characters, nonempty, no control characters), not the native derived displayName. Already desired state returns 409 HOUSEHOLD_ALREADY_IN_STATE for a new command, never fabricated proof of a previous command. ADD_RELATION/REMOVE_RELATION require both exact contacts to be current members and the exact source-direction relationship. A pair cannot have conflicting types. The native owner maintains the inverse; never send a second reverse command. REMOVE_RELATION uses the native pair-only option applyMari=false: another spouse's parent relation is preserved. It does not change grouping membership or legacy parents. ADD_RELATION checks ancestry cycles through forward, reverse-only and legacy-parent links, including contacts outside this household, with a bound of 500 descendant nodes and a 5-second traversal budget per admission. Incomplete/foreign/ambiguous or oversized required graph returns 409/404, not a false acyclicity verdict. Native chef-family propagation may attach the pair to an already existing or newly native-created chef household; its actual identities are admitted, affected household IDs are reported in nativeHouseholdIds and no arbitrary recovery/rebuild owner is called. Global native ID uniqueness, organisation and all touched contacts are checked before effects. Exact contact locks are shared with member administration where contacts overlap; the household/ancestry/chef resources are also reserved before a durable journal and second admission. Each lock/journal reservation requires acknowledged:true plus its exact insertedId with writeConcern:{w:1,j:true}; inline CAS and terminal confirmation require a positive durable ACK. An apparently APPLIED journal with a retained command lock is still UNKNOWN on replay. Internal/legacy writers do not share all these locks; revisions are checked at admission, not an atomic multi-document transaction, as concurrentInternalChangesPossible=true states. APPLIED means the requested owner/conditional native CRUD returned and the required result was observed, not a full-family rebuild or a financial/access effect. resultRevision identifies that confirmed observation; household is a current fresh read and may differ on replay. NOT_APPLIED means second admission changed before effects. After second admission, the common external contact fence checks the exact admitted resources before any owner or inline CAS. CONTACT_MUTATION_BLOCKED or CONTACT_MUTATION_FENCE_UNAVAILABLE records NOT_APPLIED before effects; replay does not retry the refused intention. If owner/CAS and terminal journal were positively confirmed in this request, a failed lock cleanup preserves APPLIED with reason HOUSEHOLD_COMMAND_CLEANUP_UNCONFIRMED; retained locks do not permit another command. A later replay with retained locks remains UNKNOWN without fresh durable proof of terminal confirmation. UNKNOWN means partial/full effects or a lost durable confirmation are possible: retained locks prevent another command and the owner is never automatically replayed. A same-key same-intention replay returns its recorded outcome; a different intention conflicts. Preserve the original key, action, revision and references; never use a new key, adjusted revision, another organisation or legacy contact tools to bypass UNKNOWN or a pending lock. No account approval, session issuance/revocation, financial rewrite, provider call or notification is requested by this surface.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contact_households:write",
  "additional": [
    "contact_households:read",
    "contacts:read",
    "contacts:write"
  ]
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_f10a365c7bd580a11747"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Inspect APPLIED, NOT_APPLIED or UNKNOWN before reporting a household change.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "replayed",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "replayed": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/ContactHouseholdCommandResult"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_HOUSEHOLD_QUERY, INVALID_HOUSEHOLD_CURSOR, INVALID_HOUSEHOLD_ID, INVALID_HOUSEHOLD_COMMAND or UNEXPECTED_REQUEST_BODY: use only the declared exact arguments.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: no household authority or account access is granted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "HOUSEHOLD_NOT_FOUND: a required household, contact, head or ancestry reference is absent, deleted, foreign or inadmissible.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Ambiguous identity/history, changed revision, head/membership/relation conflict, ancestry cycle, bounded graph/member overflow, concurrent or mismatched idempotent command. Inspect the exact error code; do not bypass it through legacy contact tools.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "HOUSEHOLD_READ_UNAVAILABLE or HOUSEHOLD_COMMAND_UNAVAILABLE: preserve a command's original identity on a lost/uncertain response; never infer that no effect occurred.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_households:write",
  "x-unisoft-additional-scopes": [
    "contact_households:read",
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## POST /contacts/import-jobs

Stage an idempotent bounded contact import job

`create_contact_import_job`

A client-driven durable contact import job, private to the authenticated organisation AND stable API-key identity; no staff identity is borrowed and another key cannot read or execute it. The original source rows/options are persisted privately in an integration job record and never returned by status. Public row schemas/options are the existing ContactImportRowInput and ContactImportInput options, not a new business mapping. Read get_contact_import_schema and the import guide first; use normalise/lookup and inspect current primary addresses, because the existing bulk owner can replace a matched contact primary address. NUMBER/DATETIME custom import values follow the existing owner storage rules rather than becoming native numeric/date-time fields. Source row index is zero-based, stable in this job; sourceRow preserves the optional original __row label, otherwise index+1. Counts describe recorded row states, not a guarantee that every requested contact was imported. Only issue codes and current admitted target UUIDs are exposed, never source coordinates, raw errors, private provenance or provider secrets. matchedContactAvailable:null and meta.targetReferencesChecked:false mean a secondary reference read was unavailable; an acknowledged command is still returned, without converting known committed work into a generic failure. A newly created contact ID is not returned by the existing owner and stays unknown; do not invent it from matchedContactId:null. Fixed source rows are limited to 2000 and 2 MiB before staging. Status row pages are 1–100, default 50, ordered by index with an opaque job/key-bound cursor; source rows are immutable but statuses can change between pages (consistentSnapshot:false). Every command checks both contacts:write AND contacts:read, current ownership, revision and state. No daemon or implicit background run is created; GET never advances a job, starts an import, recovers a lease or calls a provider. 409 revision/busy/state/preview conflict requires reading the job before a new explicit command. An UNKNOWN row or expired execution lease is not a retryable row: it stops the job in ATTENTION_REQUIRED and cannot be re-executed by this API. Resolve uncertain contact effects through normal authorised read-back/manual review, never blindly submit that row again. The job does not erase its stored source rows automatically. Job insertion, command claims and every row/checkpoint CAS explicitly request majority+j:true durable write concern. Inserts require acknowledged===true and the exact insertedId; native findAndModify must return positive ok===1, lastErrorObject.n===1, updatedExisting===true and an exactly re-admitted resulting job before any owner call or next row. A plain document, w:0, absent/mismatched metadata or write-concern error never grants a claim. CONTACT_IMPORT_JOB_RESULT_UNCONFIRMED requires status inspection, without automatic replay; uncertainty after real owner entry is terminal UNKNOWN when it can be durably recorded. Requires contacts:write AND contacts:read. idempotencyKey identifies one immutable source payload for this organisation/key. Same key and payload replays the staged job; a different payload under that key gives 409. This stores a DRAFT job only: no contact lookup, preview or contact write runs yet. Retain the returned job UUID and read its revision before preview.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": [
    "contacts:read"
  ]
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_16f9ab52d2cb23a5f8eb"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Known durable job state and a bounded page of row outcomes.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid source row, options, job command or cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Required contact scopes or stable key context are missing.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Job unavailable for this organisation and key.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Idempotency, revision, preview, busy or attention-required conflict. No forbidden retry occurred.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source/job bounds or malformed stored data prevent the operation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Job storage or owner acknowledgement is unavailable. Read status before any new command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": true
  }
}
```

## GET /contacts/import-jobs/{jobId}

Read durable import progress and per-row outcomes

`get_contact_import_job`

A client-driven durable contact import job, private to the authenticated organisation AND stable API-key identity; no staff identity is borrowed and another key cannot read or execute it. The original source rows/options are persisted privately in an integration job record and never returned by status. Public row schemas/options are the existing ContactImportRowInput and ContactImportInput options, not a new business mapping. Read get_contact_import_schema and the import guide first; use normalise/lookup and inspect current primary addresses, because the existing bulk owner can replace a matched contact primary address. NUMBER/DATETIME custom import values follow the existing owner storage rules rather than becoming native numeric/date-time fields. Source row index is zero-based, stable in this job; sourceRow preserves the optional original __row label, otherwise index+1. Counts describe recorded row states, not a guarantee that every requested contact was imported. Only issue codes and current admitted target UUIDs are exposed, never source coordinates, raw errors, private provenance or provider secrets. matchedContactAvailable:null and meta.targetReferencesChecked:false mean a secondary reference read was unavailable; an acknowledged command is still returned, without converting known committed work into a generic failure. A newly created contact ID is not returned by the existing owner and stays unknown; do not invent it from matchedContactId:null. Fixed source rows are limited to 2000 and 2 MiB before staging. Status row pages are 1–100, default 50, ordered by index with an opaque job/key-bound cursor; source rows are immutable but statuses can change between pages (consistentSnapshot:false). Every command checks both contacts:write AND contacts:read, current ownership, revision and state. No daemon or implicit background run is created; GET never advances a job, starts an import, recovers a lease or calls a provider. 409 revision/busy/state/preview conflict requires reading the job before a new explicit command. An UNKNOWN row or expired execution lease is not a retryable row: it stops the job in ATTENTION_REQUIRED and cannot be re-executed by this API. Resolve uncertain contact effects through normal authorised read-back/manual review, never blindly submit that row again. The job does not erase its stored source rows automatically. Job insertion, command claims and every row/checkpoint CAS explicitly request majority+j:true durable write concern. Inserts require acknowledged===true and the exact insertedId; native findAndModify must return positive ok===1, lastErrorObject.n===1, updatedExisting===true and an exactly re-admitted resulting job before any owner call or next row. A plain document, w:0, absent/mismatched metadata or write-concern error never grants a claim. CONTACT_IMPORT_JOB_RESULT_UNCONFIRMED requires status inspection, without automatic replay; uncertainty after real owner entry is terminal UNKNOWN when it can be durably recorded. Requires contacts:read and this job owner key. Does not start, resume, retry, recover or mutate anything. A stale RUNNING row whose execution lease expired is presented as UNKNOWN/ATTENTION_REQUIRED without a database write. Rows with UNKNOWN, rejected previews or unavailable targets need explicit review; absence of an imported contact ID is not proof that no write occurred. A preview is a projected plan, while SUCCEEDED/SKIPPED describe the recorded acknowledged owner result. Do not conflate action:create with a known resulting contact UUID.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "jobId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Job UUID returned by create_contact_import_job for this same organisation and key."
}
```

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  }
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Known durable job state and a bounded page of row outcomes.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid source row, options, job command or cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Required contact scopes or stable key context are missing.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Job unavailable for this organisation and key.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Idempotency, revision, preview, busy or attention-required conflict. No forbidden retry occurred.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source/job bounds or malformed stored data prevent the operation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Job storage or owner acknowledgement is unavailable. Read status before any new command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/import-jobs/{jobId}/preview

Preview the next bounded rows of a staged contact import

`preview_contact_import_job`

A client-driven durable contact import job, private to the authenticated organisation AND stable API-key identity; no staff identity is borrowed and another key cannot read or execute it. The original source rows/options are persisted privately in an integration job record and never returned by status. Public row schemas/options are the existing ContactImportRowInput and ContactImportInput options, not a new business mapping. Read get_contact_import_schema and the import guide first; use normalise/lookup and inspect current primary addresses, because the existing bulk owner can replace a matched contact primary address. NUMBER/DATETIME custom import values follow the existing owner storage rules rather than becoming native numeric/date-time fields. Source row index is zero-based, stable in this job; sourceRow preserves the optional original __row label, otherwise index+1. Counts describe recorded row states, not a guarantee that every requested contact was imported. Only issue codes and current admitted target UUIDs are exposed, never source coordinates, raw errors, private provenance or provider secrets. matchedContactAvailable:null and meta.targetReferencesChecked:false mean a secondary reference read was unavailable; an acknowledged command is still returned, without converting known committed work into a generic failure. A newly created contact ID is not returned by the existing owner and stays unknown; do not invent it from matchedContactId:null. Fixed source rows are limited to 2000 and 2 MiB before staging. Status row pages are 1–100, default 50, ordered by index with an opaque job/key-bound cursor; source rows are immutable but statuses can change between pages (consistentSnapshot:false). Every command checks both contacts:write AND contacts:read, current ownership, revision and state. No daemon or implicit background run is created; GET never advances a job, starts an import, recovers a lease or calls a provider. 409 revision/busy/state/preview conflict requires reading the job before a new explicit command. An UNKNOWN row or expired execution lease is not a retryable row: it stops the job in ATTENTION_REQUIRED and cannot be re-executed by this API. Resolve uncertain contact effects through normal authorised read-back/manual review, never blindly submit that row again. The job does not erase its stored source rows automatically. Job insertion, command claims and every row/checkpoint CAS explicitly request majority+j:true durable write concern. Inserts require acknowledged===true and the exact insertedId; native findAndModify must return positive ok===1, lastErrorObject.n===1, updatedExisting===true and an exactly re-admitted resulting job before any owner call or next row. A plain document, w:0, absent/mismatched metadata or write-concern error never grants a claim. CONTACT_IMPORT_JOB_RESULT_UNCONFIRMED requires status inspection, without automatic replay; uncertainty after real owner entry is terminal UNKNOWN when it can be durably recorded. Requires contacts:write AND contacts:read. Supply the latest revision; limit 1–500 (default 500). A durable preview command checkpoint is stored before calling the existing runImport owner with dryRun:true, and no contact mutation occurs. Results preserve native projected actions/issues and are saved per row; at most ten issue details are returned with explicit issueCount/issuesTruncated. Current matched targets are readmitted before any plan is accepted. Continue preview commands with the returned revision until READY and retain previewFingerprint. A changed/failed preview is never an automatic execution. Recovering an expired PREVIEW lease only records recoverable job state and returns; issue a new explicit preview command for the remaining rows.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": [
    "contacts:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "jobId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Job UUID returned by create_contact_import_job for this same organisation and key."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "revision": {
            "type": "integer",
            "minimum": 1
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500,
            "default": 500
          }
        },
        "required": [
          "revision"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Known durable job state and a bounded page of row outcomes.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid source row, options, job command or cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Required contact scopes or stable key context are missing.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Job unavailable for this organisation and key.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Idempotency, revision, preview, busy or attention-required conflict. No forbidden retry occurred.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source/job bounds or malformed stored data prevent the operation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Job storage or owner acknowledgement is unavailable. Read status before any new command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": true
  }
}
```

## POST /contacts/import-jobs/{jobId}/execute

Execute an explicitly confirmed bounded import batch

`execute_contact_import_job`

A client-driven durable contact import job, private to the authenticated organisation AND stable API-key identity; no staff identity is borrowed and another key cannot read or execute it. The original source rows/options are persisted privately in an integration job record and never returned by status. Public row schemas/options are the existing ContactImportRowInput and ContactImportInput options, not a new business mapping. Read get_contact_import_schema and the import guide first; use normalise/lookup and inspect current primary addresses, because the existing bulk owner can replace a matched contact primary address. NUMBER/DATETIME custom import values follow the existing owner storage rules rather than becoming native numeric/date-time fields. Source row index is zero-based, stable in this job; sourceRow preserves the optional original __row label, otherwise index+1. Counts describe recorded row states, not a guarantee that every requested contact was imported. Only issue codes and current admitted target UUIDs are exposed, never source coordinates, raw errors, private provenance or provider secrets. matchedContactAvailable:null and meta.targetReferencesChecked:false mean a secondary reference read was unavailable; an acknowledged command is still returned, without converting known committed work into a generic failure. A newly created contact ID is not returned by the existing owner and stays unknown; do not invent it from matchedContactId:null. Fixed source rows are limited to 2000 and 2 MiB before staging. Status row pages are 1–100, default 50, ordered by index with an opaque job/key-bound cursor; source rows are immutable but statuses can change between pages (consistentSnapshot:false). Every command checks both contacts:write AND contacts:read, current ownership, revision and state. No daemon or implicit background run is created; GET never advances a job, starts an import, recovers a lease or calls a provider. 409 revision/busy/state/preview conflict requires reading the job before a new explicit command. An UNKNOWN row or expired execution lease is not a retryable row: it stops the job in ATTENTION_REQUIRED and cannot be re-executed by this API. Resolve uncertain contact effects through normal authorised read-back/manual review, never blindly submit that row again. The job does not erase its stored source rows automatically. Job insertion, command claims and every row/checkpoint CAS explicitly request majority+j:true durable write concern. Inserts require acknowledged===true and the exact insertedId; native findAndModify must return positive ok===1, lastErrorObject.n===1, updatedExisting===true and an exactly re-admitted resulting job before any owner call or next row. A plain document, w:0, absent/mismatched metadata or write-concern error never grants a claim. CONTACT_IMPORT_JOB_RESULT_UNCONFIRMED requires status inspection, without automatic replay; uncertainty after real owner entry is terminal UNKNOWN when it can be durably recorded. Requires contacts:write AND contacts:read. Requires latest revision, the exact READY previewFingerprint and confirm:true. limit 1–50, default 10. Each selected NOT_STARTED row is durably marked RUNNING with an attempt before any owner call, then freshly dry-run checked; a changed action/target stops in ATTENTION_REQUIRED with PREVIEW_CHANGED before a real write. The existing runImport owner is called on one row for the real application, preserving its native normalisation/deduplication/upsert semantics. Each acknowledgement is checkpointed before the next row. Owner exceptions, WRITE_FAILED, inconsistent reports or a lost checkpoint after the real owner was entered become UNKNOWN, including possible partial persisted contact changes; that row and job cannot be replayed. Successful native create actions have no returned resulting contact ID, so it remains unknown. Expired EXECUTE recovery records any in-flight row as UNKNOWN without another import call; it never assumes rollback. Terminal preview-rejected rows are not applied. COMPLETED means all rows have a known terminal outcome, which can include rejected/skipped rows; inspect counts and every relevant row. Never infer all contacts were created or that an UNKNOWN row is safe to retry. Immediately before the real import, after durable live-lease renewal, an organisation-wide passive mutation fence covers even creates whose resulting contact UUID is unknown. Only this exact server-admitted job ID is ignored to prevent self-blocking; client input cannot choose exclusions. Another unresolved job/lock gives CONTACT_MUTATION_BLOCKED (409), and an unavailable fence gives CONTACT_MUTATION_FENCE_UNAVAILABLE (503), with no real import call. A refusal before command admission leaves the row NOT_STARTED. After a command has been claimed, a late fence refusal records the row REJECTED and stops the job ATTENTION_REQUIRED when that record is acknowledged. Do not start a replacement job to bypass the fence.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": [
    "contacts:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "jobId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Job UUID returned by create_contact_import_job for this same organisation and key."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "revision": {
            "type": "integer",
            "minimum": 1
          },
          "previewFingerprint": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "confirm": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "default": 10
          }
        },
        "required": [
          "revision",
          "previewFingerprint",
          "confirm"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Known durable job state and a bounded page of row outcomes.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid source row, options, job command or cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Required contact scopes or stable key context are missing.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Job unavailable for this organisation and key.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Idempotency, revision, preview, busy or attention-required conflict. No forbidden retry occurred.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source/job bounds or malformed stored data prevent the operation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Job storage or owner acknowledgement is unavailable. Read status before any new command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": true
  }
}
```

## POST /contacts/{id}/timeline

Read a qualified contact chronology across explicitly authorised sources

`get_contact_timeline`

Requires contacts:read and every scope of every requested source, checked before source reads. sources is explicit: INTERACTION adds no scope; REGISTRATION requires forms:read AND forms_submit:read; PAYMENT requires paiements:read plus fundraising:read, promesses:read, forms:read, forms_submit:read and caisses:read; SUBSCRIPTION requires abonnements:read plus those same linked-domain scopes. The broad linked-domain rights are required to re-admit every current source object without silently hiding inaccessible activity. Missing rights give 403, never a partial timeline presented as complete. id is an existing current contact UUID in the authenticated organisation; explicit archives remain readable. Supply from/to as ISO instants with explicit timezone, from inclusive/to exclusive, at most 366 days. Only native BSON-date records are placed in this chronology; unsupportedDateCount reports non-BSON date values (including legacy date strings/numbers) for the admitted source/contact scope outside chronological placement, never a fabricated timestamp. General financial types GENERAL/CAMPAGNE/DETTE/FORM/CAISSE are supported; SERVICE, LIVRET and unknown financial types are excluded explicitly. With a campaign-restricted key, financial sources are further limited to direct CAMPAGNE records under the key, including an empty restriction; coverage says KEY_CAMPAIGNS_ONLY and does not imply no other contact activity. Each current form/submission/campaign/pledge/caisse target is re-admitted in this organisation, including campaign restrictions; an unavailable linked object gives 404 without a partial page. Subscription root contact is authoritative; a missing/null root can use a scalar legacy payload.contact with relation LEGACY_PAYLOAD_CONTACT, never an array or conflicting root. The root/payload amount fields are not interchanged. INTERACTION dates with datePrecision DAY preserve occurredOn; recordedAt can be the owner's noon sorting anchor and must not be described as a known time of day. REGISTRATION datetime is the recorded submission time, not event start; SUBSCRIPTION datetime is a contract anchor, not next due date or an instalment. Payment amounts are stored nominal attempt amounts in minor units, including pending/failed/refunded/technical attempts; subscription amounts are nominal contract payload.amount in minor units, never forecast receipts or paid instalments. Native currencies remain separate; unknown amounts/currencies/flags stay null. Imported is an explicit stored flag, never inferred false. IN_KIND is not cash; UNKNOWN instrument must not be assumed monetary. COMPLETED can be an Axepta authorisation before capture; paymentPhase interprets stored state only. No sum, conversion, fees, refund subtraction, bank settlement verification, calendar initialisation or provider call occurs. Labels contain only stored interaction type or the current authorised form label; note content, identity snapshots, document links, card/mandate/provider credentials and staff metadata are excluded. A source error fails the whole request (FAIL_CLOSED), unlike the legacy internal best-effort feed. limit 1–100 (default 50); order is recordedAt descending then source/recordId descending, with an opaque cursor bound to contact, organisation, key, scopes/restriction, source set and period. Continue with the same selection; invalid cursor requires restarting. readAt is observation time, not a historical source calculation; consistentSnapshot:false and completeContactHistory:false acknowledge concurrent changes, unsupported dates/types and excluded unrequested domains such as promises, reminders and email/phone-based approximations. An empty page proves only no placed records in this admitted selection. Each database query is limited to 10000 ms; 503 CONTACT_TIMELINE_LIMIT_REACHED requires a narrower legitimate period/selection. Unknown query/body fields, wrong types and impossible dates are rejected. No contact mutation, synchronisation, debit, refund, message, document emission or billing is triggered; authentication may update key usage telemetry.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "sources": {
            "type": "array",
            "minItems": 1,
            "maxItems": 4,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "INTERACTION",
                "REGISTRATION",
                "PAYMENT",
                "SUBSCRIPTION"
              ]
            }
          },
          "from": {
            "type": "string",
            "format": "date-time"
          },
          "to": {
            "type": "string",
            "format": "date-time"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          }
        },
        "required": [
          "sources",
          "from",
          "to"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "A qualified bounded page with explicit source/date/financial coverage.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTimelineResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid source selection, period, input type or cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTimelineError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTimelineError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "A requested source or linked-domain scope is missing.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTimelineError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "The contact or one linked current object is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTimelineError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Malformed source identity or relationship prevents a qualified page.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTimelineError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "At least one bounded source read failed; no partial timeline is returned.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTimelineError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-conditional-scopes": [
    {
      "condition": "sources contains INTERACTION",
      "scopes": [],
      "allRequired": true
    },
    {
      "condition": "sources contains REGISTRATION",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "sources contains PAYMENT",
      "scopes": [
        "paiements:read",
        "fundraising:read",
        "promesses:read",
        "forms:read",
        "forms_submit:read",
        "caisses:read"
      ],
      "allRequired": true
    },
    {
      "condition": "sources contains SUBSCRIPTION",
      "scopes": [
        "abonnements:read",
        "fundraising:read",
        "promesses:read",
        "forms:read",
        "forms_submit:read",
        "caisses:read"
      ],
      "allRequired": true
    }
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/bulk/preview

Preview changes to an explicit batch of contacts

`preview_contact_bulk_update`

Requires explicitly granted contacts:bulk AND contacts:read AND contacts:write; no default bulk permission. Rejects all campaign-restricted keys, even an empty restriction, with CAMPAIGN_RESTRICTED_KEY. Uses only explicit same-organisation contact UUIDs, 1–100 distinct IDs. Deleted contacts are refused; archived contacts may be edited. All query parameters are forbidden. changes accepts addTags/removeTags (1–50 labels each) and identity with firstName, lastName, gender M/F/null or hebrewFirstName only. Tags use canonical CRM formatting, de-duplicate and cannot be added and removed together. First/last names cannot be cleared; lastName becomes uppercase, firstName uses canonical capitalisation, gender:null explicitly clears gender, and hebrewFirstName may be empty. No gender is inferred. Coordinates, addresses, dates, tax/Gift Aid declarations, custom fields, family links, lifecycle, consent and member accounts require their dedicated workflows and are rejected here. This updates one common set of fields on the explicit selection; it is not an import, global tag rename, saved-list edit or merge. Read-only observation with no journal or business writes. All selected identities and stored edited-field types must be valid before any preview is returned. Canonical contactIds/changes, revision and per-contact WILL_CHANGE or NO_CHANGE are returned without exposing existing identity data. Use these canonical values in apply. The revision covers selected edited fields plus lifecycle and exact identities; unrelated field edits do not invalidate it. snapshotGuaranteed:false: internal writers remain active and no record is reserved. No provider is called.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:bulk",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "contactIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "changes": {
            "type": "object",
            "minProperties": 1,
            "properties": {
              "addTags": {
                "type": "array",
                "minItems": 1,
                "maxItems": 50,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 500
                }
              },
              "removeTags": {
                "type": "array",
                "minItems": 1,
                "maxItems": 50,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 500
                }
              },
              "identity": {
                "type": "object",
                "minProperties": 1,
                "properties": {
                  "firstName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "lastName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "gender": {
                    "type": "string",
                    "enum": [
                      "M",
                      "F",
                      null
                    ],
                    "nullable": true
                  },
                  "hebrewFirstName": {
                    "type": "string",
                    "maxLength": 200
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          }
        },
        "required": [
          "contactIds",
          "changes"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Canonical batch and observed per-contact changes; no mutation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactBulkPreviewResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_BULK_INPUT, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_CONTACT_IDS, INVALID_TAGS, INVALID_BULK_VALUE, CONFLICTING_TAG_CHANGES, EMPTY_CHANGES, INVALID_GENDER, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY or INVALID_UUID: correct the declared input.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: the three explicit scopes and an unrestricted same-organisation key are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND or COMMAND_NOT_FOUND: a contact is missing, deleted, foreign or outside exact authority, or a command receipt is inaccessible.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "AMBIGUOUS_CONTACT_ID, INVALID_STORED_CONTACT or IDEMPOTENCY_CONFLICT: review the source identity/data or retain the original idempotency content; no new effect is attempted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: private error details are withheld.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "BULK_JOURNAL_UNAVAILABLE: command admission or outcome recording could not be proved. Keep the same key; never repeat an uncertain effect with a new key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:bulk",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/bulk/apply

Apply a previewed contact batch with per-contact concurrency checks

`apply_contact_bulk_update`

Requires explicitly granted contacts:bulk AND contacts:read AND contacts:write; no default bulk permission. Rejects all campaign-restricted keys, even an empty restriction, with CAMPAIGN_RESTRICTED_KEY. Uses only explicit same-organisation contact UUIDs, 1–100 distinct IDs. Deleted contacts are refused; archived contacts may be edited. All query parameters are forbidden. changes accepts addTags/removeTags (1–50 labels each) and identity with firstName, lastName, gender M/F/null or hebrewFirstName only. Tags use canonical CRM formatting, de-duplicate and cannot be added and removed together. First/last names cannot be cleared; lastName becomes uppercase, firstName uses canonical capitalisation, gender:null explicitly clears gender, and hebrewFirstName may be empty. No gender is inferred. Coordinates, addresses, dates, tax/Gift Aid declarations, custom fields, family links, lifecycle, consent and member accounts require their dedicated workflows and are rejected here. This updates one common set of fields on the explicit selection; it is not an import, global tag rename, saved-list edit or merge. First preview, then submit canonical contactIds/changes, revision and a stable idempotencyKey (8–128 ASCII letters/digits/._:-). A durable receipt precedes every effect; its content is bound to the key. Same key/content returns the existing receipt without replay; changed content returns IDEMPOTENCY_CONFLICT. The revision is checked at admission. REVISION_CONFLICT creates a REJECTED receipt with no business effect. Each changed record then receives one atomic compare-and-set of its edited fields and lifecycle, scoped by exact organisation/ID/Mongo identity, followed by read-back. This is NOT an atomic transaction across the selection: another writer can cause a per-row CONFLICT while other rows apply. A durable per-contact bulk lock blocks a new-key invocation while an earlier effect is uncertain; no age-based lock takeover exists. Row states are APPLIED, NO_CHANGE, CONFLICT, BLOCKED, UNKNOWN or NOT_ATTEMPTED, with PENDING/RUNNING during execution. COMPLETED means all rows applied or already matched; PARTIAL means at least one CAS conflict or a contact blocked by an earlier bulk command; UNKNOWN means effect or read-back could not be proved and later rows stop. ADMITTING/RUNNING can be in flight or interrupted; age or timeout never proves failure. success:true confirms a stored receipt, including REJECTED/PARTIAL/UNKNOWN, not complete success. Inspect every row. canRetry:false; read get_contact_bulk_update after uncertainty. Never repeat an uncertain batch with a new key or silently omit conflicting contacts; report the exact result and obtain a new decision before a fresh preview of a known conflict. No automatic resume, provider call or rollback exists.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:bulk",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_835aa2faff08c42df4c5"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Durable terminal batch result; inspect overall and per-contact states.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactBulkReceiptResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "Existing batch is ADMITTING or RUNNING; no effect replay.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactBulkReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_BULK_INPUT, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_CONTACT_IDS, INVALID_TAGS, INVALID_BULK_VALUE, CONFLICTING_TAG_CHANGES, EMPTY_CHANGES, INVALID_GENDER, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY or INVALID_UUID: correct the declared input.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: the three explicit scopes and an unrestricted same-organisation key are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND or COMMAND_NOT_FOUND: a contact is missing, deleted, foreign or outside exact authority, or a command receipt is inaccessible.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "AMBIGUOUS_CONTACT_ID, INVALID_STORED_CONTACT or IDEMPOTENCY_CONFLICT: review the source identity/data or retain the original idempotency content; no new effect is attempted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: private error details are withheld.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "BULK_JOURNAL_UNAVAILABLE: command admission or outcome recording could not be proved. Keep the same key; never repeat an uncertain effect with a new key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:bulk",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /contacts/bulk/{commandId}

Read the durable status of one contact batch update

`get_contact_bulk_update`

Requires explicitly granted contacts:bulk AND contacts:read AND contacts:write; no default bulk permission. Rejects all campaign-restricted keys, even an empty restriction, with CAMPAIGN_RESTRICTED_KEY. Uses only explicit same-organisation contact UUIDs, 1–100 distinct IDs. Deleted contacts are refused; archived contacts may be edited. All query parameters are forbidden. Use the commandId UUID returned by apply. Rechecks current permissions before reading; old receipts grant no authority. No request body is accepted. Returns last durable overall/per-contact states, not a new read of all contacts. Reading never resumes, retries or rolls back a batch. APPLIED describes an acquired and verified edit, not a guarantee against later changes. ADMITTING/RUNNING may be interrupted; UNKNOWN remains uncertain, never a failed/no-effect declaration. A missing receipt does not prove a POST failed. Keep the original key and report unresolved rows; no new-key retry of an unknown effect.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:bulk",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### פרמטרים

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Last durable receipt; no replay or automatic continuation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactBulkReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_BULK_INPUT, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_CONTACT_IDS, INVALID_TAGS, INVALID_BULK_VALUE, CONFLICTING_TAG_CHANGES, EMPTY_CHANGES, INVALID_GENDER, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY or INVALID_UUID: correct the declared input.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: the three explicit scopes and an unrestricted same-organisation key are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND or COMMAND_NOT_FOUND: a contact is missing, deleted, foreign or outside exact authority, or a command receipt is inaccessible.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "AMBIGUOUS_CONTACT_ID, INVALID_STORED_CONTACT or IDEMPOTENCY_CONFLICT: review the source identity/data or retain the original idempotency content; no new effect is attempted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: private error details are withheld.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "BULK_JOURNAL_UNAVAILABLE: command admission or outcome recording could not be proved. Keep the same key; never repeat an uncertain effect with a new key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:bulk",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/{id}/coordinates

Read primary and secondary contact coordinates with stable selectors

`get_contact_coordinates`

Requires contacts:read. Reads one exact same-organisation contact UUID; deleted, foreign or array-valued identities are refused. Returns primary email, phone and flat address plus secondary records with stable UUIDs and a revision for editing. coordinateId:null selects the primary, which has no UUID. A secondary selector comes only from this result; a phone/email string is never a UUID. Missing scalar values remain null, never fabricated contact details. Historical strings are recorded values, not deliverability or consent proof. Invalid/duplicate secondary IDs, more than 100 records per kind or invalid stored types refuse the read with INVALID_COORDINATE_HISTORY. No request body is accepted. No message, provider request, geocoding, proximity recomputation, new consent, member-account edit or change of historical payment/receipt billing snapshots occurs. geographyRecomputed:false is explicit: these commands edit stored coordinates only and do not certify current map/proximity results. All query parameters are forbidden. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Stored coordinate values and current revision; no business mutation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCoordinateStateResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_COORDINATE_COMMAND, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_COORDINATE_ID, INVALID_UUID, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, SECONDARY_COORDINATE_REQUIRED, UNEXPECTED_COORDINATE_VALUE, INVALID_ADDRESS, INVALID_LABEL, INVALID_PHONE_COUNTRY, INVALID_COORDINATE_VALUE, INVALID_EMAIL, INVALID_PHONE or EMPTY_CHANGES: correct the declared input.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: current exact organisation and the declared scopes are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, COORDINATE_NOT_FOUND or COMMAND_NOT_FOUND: no current authorised contact, secondary coordinate or receipt was found.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "AMBIGUOUS_CONTACT_ID, INVALID_COORDINATE_HISTORY or IDEMPOTENCY_CONFLICT: review the stored identity/coordinate data or retain the original idempotency content.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: private diagnostics are withheld.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COORDINATE_JOURNAL_UNAVAILABLE: effect admission or outcome recording is uncertain. Retain the same key and read its receipt; no new-key retry.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## PATCH /contacts/{id}/coordinates

Edit, remove or select a contact's primary coordinate

`edit_contact_coordinate`

Requires explicit contacts:manage AND contacts:read AND contacts:write; manage is opt-in. Every campaign-restricted key, including an empty restriction, is refused. First get_contact_coordinates and pass its revision, a stable idempotencyKey (8–128 ASCII letters/digits/._:-), kind EMAIL/PHONE/ADDRESS, action EDIT/REMOVE/MAKE_PRIMARY and coordinateId (null for primary, an exact returned UUID for secondary). EDIT email/phone accepts value and optional secondary label; a primary has no label. Email uses canonical CRM validation/lowercase; a local phone requires an explicit real ISO alpha-2 phoneCountry, while an international phone starts with + and is normalised to E.164. No country or gender is inferred. EDIT address accepts only supplied address/postalCode/city/region/country/note fields, plus label/type/companyId for secondary addresses; no primary company metadata exists. Street cannot be emptied with EDIT: use REMOVE. REMOVE accepts no value/label/address, removes only the selected record, and never promotes a replacement automatically. MAKE_PRIMARY requires a secondary UUID, accepts no value, copies its stored coordinate into the flat primary and preserves its existing secondary record/UUID/metadata. The previous primary is retained as a secondary with a deterministic new UUID if not already present; a subsequent read obtains it. Primary address copies physical fields/note only; secondary company/type/label metadata remains on that preserved secondary record. A secondary edit/removal does not automatically edit/remove an equal primary copy: select coordinateId:null explicitly for that. At most 100 secondary records per kind; a promotion needing a 101st is rejected. Editing a phone/email preflights the canonical owner dedup lookup with exitDeleted:false; COORDINATE_IN_USE reveals no other contact identity. This observation is not a global uniqueness reservation. The command stores a receipt and external per-contact lock before effect, checks the revision, uses an atomic exact BSON CAS of coordinates/lifecycle, then reads back. Same key/content returns the receipt; different content returns IDEMPOTENCY_CONFLICT. APPLIED or NO_CHANGE are verified stored results; REJECTED made no effect, CONFLICT lost the CAS race, and UNKNOWN means effect/read-back was unproved and retains the external lock. ADMITTING/RUNNING can be in flight or interrupted. success:true confirms a receipt, including rejected/unknown results; inspect state. canRetry:false: read get_contact_coordinate_command, never replay uncertainty using a new key or an individual-contact workaround. No automatic recovery, rollback or stale-lock takeover exists. Internal writers remain active and can cause conflicts or later changes. No message, provider request, geocoding, proximity recomputation, new consent, member-account edit or change of historical payment/receipt billing snapshots occurs. geographyRecomputed:false is explicit: these commands edit stored coordinates only and do not certify current map/proximity results. All query parameters are forbidden. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:manage",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_3eb894b2a1f27c208752"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Terminal stored result; success confirms receipt storage, inspect state.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCoordinateReceiptResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "The existing command is ADMITTING or RUNNING; no owner/effect replay.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCoordinateReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_COORDINATE_COMMAND, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_COORDINATE_ID, INVALID_UUID, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, SECONDARY_COORDINATE_REQUIRED, UNEXPECTED_COORDINATE_VALUE, INVALID_ADDRESS, INVALID_LABEL, INVALID_PHONE_COUNTRY, INVALID_COORDINATE_VALUE, INVALID_EMAIL, INVALID_PHONE or EMPTY_CHANGES: correct the declared input.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: current exact organisation and the declared scopes are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, COORDINATE_NOT_FOUND or COMMAND_NOT_FOUND: no current authorised contact, secondary coordinate or receipt was found.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "AMBIGUOUS_CONTACT_ID, INVALID_COORDINATE_HISTORY or IDEMPOTENCY_CONFLICT: review the stored identity/coordinate data or retain the original idempotency content.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: private diagnostics are withheld.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COORDINATE_JOURNAL_UNAVAILABLE: effect admission or outcome recording is uncertain. Retain the same key and read its receipt; no new-key retry.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:manage",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /contacts/coordinate-commands/{commandId}

Read the durable status of a contact coordinate command

`get_contact_coordinate_command`

Requires explicit contacts:manage AND contacts:read AND contacts:write and no campaign restriction, rechecked before reading. Use the commandId UUID returned by edit_contact_coordinate; a coordinate UUID and command UUID are different objects. Reads only the last durable receipt without retrying a write, releasing a lock or refreshing client/provider state. ADMITTING/RUNNING may describe an interrupted call; an old receipt, lost response or 404 never establishes no effect. UNKNOWN remains uncertain and blocks another external coordinate invocation for that contact even with a new key; request authorised Unisoft review. canRetry:false in all states. No request body is accepted. No message, provider request, geocoding, proximity recomputation, new consent, member-account edit or change of historical payment/receipt billing snapshots occurs. geographyRecomputed:false is explicit: these commands edit stored coordinates only and do not certify current map/proximity results. All query parameters are forbidden. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:manage",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### פרמטרים

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Last durable coordinate-command receipt; no replay.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCoordinateReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_COORDINATE_COMMAND, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_COORDINATE_ID, INVALID_UUID, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, SECONDARY_COORDINATE_REQUIRED, UNEXPECTED_COORDINATE_VALUE, INVALID_ADDRESS, INVALID_LABEL, INVALID_PHONE_COUNTRY, INVALID_COORDINATE_VALUE, INVALID_EMAIL, INVALID_PHONE or EMPTY_CHANGES: correct the declared input.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: current exact organisation and the declared scopes are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, COORDINATE_NOT_FOUND or COMMAND_NOT_FOUND: no current authorised contact, secondary coordinate or receipt was found.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "AMBIGUOUS_CONTACT_ID, INVALID_COORDINATE_HISTORY or IDEMPOTENCY_CONFLICT: review the stored identity/coordinate data or retain the original idempotency content.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: private diagnostics are withheld.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COORDINATE_JOURNAL_UNAVAILABLE: effect admission or outcome recording is uncertain. Retain the same key and read its receipt; no new-key retry.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:manage",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/{id}/lifecycle

Read a contact's active, archived, trashed or merged lifecycle

`get_contact_lifecycle`

Requires contacts:read. Reads one exact same-organisation contact UUID, including a soft-trashed record, without exposing its identity/coordinates or linked business data. state is MERGED for a validated same-organisation mergedInto pointer, otherwise TRASHED when deleted:true, ARCHIVED when archived:true, and ACTIVE otherwise. Missing/null legacy deleted/archived flags mean false as in the native lifecycle; unknown deceased/isNew remain null and are never inferred. Trashed and archived flags are independent: restoring a trashed archived record returns it to ARCHIVED. A merged alias does not authorise resurrection or provide a merge undo; a physically removed absorbed record is 404. Invalid/array-valued identities, flags or merged references are refused. Returns a revision for a deliberate transition and permanentDeletionAvailable:false. No request body is accepted. Only the contact's lifecycle flags and edit timestamp can change. No linked payment, subscription, pledge, household, account, consent, identity or historical printed/fiscal snapshot is deleted or rewritten. No provider, message, merge undo, permanent erasure or automatic recovery is triggered. All query parameters are forbidden. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Current native lifecycle flags and revision; no mutation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactLifecycleStateResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_LIFECYCLE_COMMAND, INVALID_LIFECYCLE_ACTION, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_UUID, INVALID_REVISION or INVALID_IDEMPOTENCY_KEY: correct the declared command.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: current exact organisation and the declared scopes are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND or COMMAND_NOT_FOUND: no exact authorised contact or receipt was found. A physically removed merged contact is not resurrected.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "AMBIGUOUS_CONTACT_ID, INVALID_LIFECYCLE_HISTORY or IDEMPOTENCY_CONFLICT: review the stored identity/lifecycle or retain the original idempotency content.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: no private diagnostics are exposed.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "LIFECYCLE_JOURNAL_UNAVAILABLE: admission/outcome recording could not be proved; retain the same key, inspect the receipt and never assume no effect.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/{id}/lifecycle

Archive, unarchive, trash or restore one contact safely

`transition_contact_lifecycle`

Requires explicit contacts:manage AND contacts:read AND contacts:write; manage is opt-in. Every campaign-restricted key, including an empty restriction, is refused. First get_contact_lifecycle, then submit action ARCHIVE/UNARCHIVE/TRASH/RESTORE, its revision and a stable idempotencyKey of 8–128 ASCII letters/digits/._:-. ARCHIVE sets archived:true and clears the new marker; UNARCHIVE sets archived:false. TRASH soft-deletes with deleted:true and clears the new marker. RESTORE only sets deleted:false and preserves archived, deceased and all links; it does not restore an absorbed/physically removed merged record or undo a merge. Archive/unarchive of a trashed record is REJECTED/RESTORE_REQUIRED; restore first and inspect the resulting archived flag. MERGED_CONTACT_PROTECTED refuses every transition on a merged alias. An already satisfied state gives NO_CHANGE unless the native action also needs to clear the new marker. The server journals and takes an external per-contact lock before effect, checks the revision, atomically compares exact identities and lifecycle fields, then reads back. Same key/content returns its receipt without rewriting; changed content returns IDEMPOTENCY_CONFLICT. APPLIED/NO_CHANGE report a verified native lifecycleState; CONFLICT means a concurrent lifecycle change won the CAS race. REJECTED made no effect; UNKNOWN means effect/read-back is unproved and retains the lock. ADMITTING/RUNNING can be in flight or interrupted. success:true confirms receipt storage, not a successful transition; inspect state. canRetry:false; use get_contact_lifecycle_command after uncertainty. Never use another key to retry an unknown effect, bypass a lock through old CRUD tools or infer failure from age/timeout. No stale-lock takeover exists and internal writers remain active. Only the contact's lifecycle flags and edit timestamp can change. No linked payment, subscription, pledge, household, account, consent, identity or historical printed/fiscal snapshot is deleted or rewritten. No provider, message, merge undo, permanent erasure or automatic recovery is triggered. All query parameters are forbidden. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:manage",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "ARCHIVE",
              "UNARCHIVE",
              "TRASH",
              "RESTORE"
            ]
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[a-zA-Z0-9._:-]{8,128}$"
          }
        },
        "required": [
          "action",
          "revision",
          "idempotencyKey"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Terminal stored lifecycle receipt; inspect state and lifecycleState.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactLifecycleReceiptResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "The existing command is ADMITTING or RUNNING; no effect replay.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactLifecycleReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_LIFECYCLE_COMMAND, INVALID_LIFECYCLE_ACTION, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_UUID, INVALID_REVISION or INVALID_IDEMPOTENCY_KEY: correct the declared command.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: current exact organisation and the declared scopes are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND or COMMAND_NOT_FOUND: no exact authorised contact or receipt was found. A physically removed merged contact is not resurrected.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "AMBIGUOUS_CONTACT_ID, INVALID_LIFECYCLE_HISTORY or IDEMPOTENCY_CONFLICT: review the stored identity/lifecycle or retain the original idempotency content.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: no private diagnostics are exposed.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "LIFECYCLE_JOURNAL_UNAVAILABLE: admission/outcome recording could not be proved; retain the same key, inspect the receipt and never assume no effect.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:manage",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /contacts/lifecycle-commands/{commandId}

Read the durable status of a contact lifecycle transition

`get_contact_lifecycle_command`

Requires explicit contacts:manage AND contacts:read AND contacts:write with no campaign restriction, rechecked before reading. Use commandId UUID returned by transition_contact_lifecycle, not a contact UUID. Reads the last durable receipt only; no write, retry, restore or lock release occurs. ADMITTING/RUNNING may be in flight or interrupted; UNKNOWN remains uncertain and blocks another external lifecycle transition for this contact even with a new key. Request authorised Unisoft review. A missing receipt or lost response never proves no effect. APPLIED lifecycleState records verification at execution time, not a guarantee against later internal writes. canRetry:false in every state. No request body is accepted. Only the contact's lifecycle flags and edit timestamp can change. No linked payment, subscription, pledge, household, account, consent, identity or historical printed/fiscal snapshot is deleted or rewritten. No provider, message, merge undo, permanent erasure or automatic recovery is triggered. All query parameters are forbidden. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:manage",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### פרמטרים

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Last durable transition receipt; no continuation or replay.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactLifecycleReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_LIFECYCLE_COMMAND, INVALID_LIFECYCLE_ACTION, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_UUID, INVALID_REVISION or INVALID_IDEMPOTENCY_KEY: correct the declared command.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: current exact organisation and the declared scopes are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND or COMMAND_NOT_FOUND: no exact authorised contact or receipt was found. A physically removed merged contact is not resurrected.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "AMBIGUOUS_CONTACT_ID, INVALID_LIFECYCLE_HISTORY or IDEMPOTENCY_CONFLICT: review the stored identity/lifecycle or retain the original idempotency content.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: no private diagnostics are exposed.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "LIFECYCLE_JOURNAL_UNAVAILABLE: admission/outcome recording could not be proved; retain the same key, inspect the receipt and never assume no effect.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:manage",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/exports/postal

Read primary postal labels for contacts or explicit household grouping

`export_contact_postal_addresses`

Requires contacts:read. Read-only export of 1–2000 explicit current non-deleted contact UUIDs in the authenticated organisation, with every selected identity re-admitted before export. Archived contacts remain selectable; any unavailable contact refuses the whole selection with 404. Names and postal components remain unknown null when absent; no country, city, gender or coordinate is inferred. No private notes, address access codes, doors, tax identifiers, tokens, photo/document URLs or payment data are returned. Only canonical pure address/postal presentation owners are called; no geocoder, map provider, directions, route planning, billable lookup, contact write or synchronisation occurs. Authentication may update key usage telemetry. Source context is limited to 5000 contacts/derived rows and 4 MiB of projected data, with 422 rather than partial truncation. Queries are bounded to 10000 ms. limit 1–100 (default 50), with a cursor bound to organisation, key/scopes, selection, chosen mode and complete derived export snapshot. Changed address/household/coordinate output invalidates the cursor; restart before using a supposedly complete export. readAt is observation time and consistentSnapshot:false, not a historical address guarantee. Unknown query/body properties, arbitrary projections, invalid IDs/modes and wrong types are rejected. A source/related-family inconsistency refuses the qualified export; do not silently omit a household member to bypass it. CONTACT is the default and emits each selected contact primary address with recorded first/last names only; contacts without one are counted in skippedNoAddress, never replaced by an assumed secondary address. HOUSEHOLD must be explicit. It reuses the product buildPostalExportRows owner, including family-and-address deduplication and its representative choice. Current family records, members, heads and marriage-link closure are readmitted within the same organisation; unselected current members can supply the owner chosen household address. Distinct families sharing one address remain distinct labels. The returned recipient strips any owner inferred salutation and uses NAME_ONLY, so no demographic fact is manufactured. representativeContactId is returned only when the owner row maps uniquely to an admitted current context record; ambiguous identity remains null. familyLabel can be unknown. Household skippedNoAddress counts the owner target/family candidates without any eligible address, not necessarily distinct people. No family/merge mutation or persistent label file is created.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "contactIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 2000,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          },
          "mode": {
            "type": "string",
            "enum": [
              "CONTACT",
              "HOUSEHOLD"
            ],
            "default": "CONTACT"
          }
        },
        "required": [
          "contactIds"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "A bounded page of the admitted postal/map selection.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid selection, mode or changed-snapshot cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing contact scope or inconsistent organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "A selected contact, household member or current family is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source cap, malformed relationship or duplicate identity/address prevents the export.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "The bounded address read could not complete.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/exports/map

Read authorised stored address coordinates for a contact selection

`get_contact_address_map`

Requires contacts:read. Read-only export of 1–2000 explicit current non-deleted contact UUIDs in the authenticated organisation, with every selected identity re-admitted before export. Archived contacts remain selectable; any unavailable contact refuses the whole selection with 404. Names and postal components remain unknown null when absent; no country, city, gender or coordinate is inferred. No private notes, address access codes, doors, tax identifiers, tokens, photo/document URLs or payment data are returned. Only canonical pure address/postal presentation owners are called; no geocoder, map provider, directions, route planning, billable lookup, contact write or synchronisation occurs. Authentication may update key usage telemetry. Source context is limited to 5000 contacts/derived rows and 4 MiB of projected data, with 422 rather than partial truncation. Queries are bounded to 10000 ms. limit 1–100 (default 50), with a cursor bound to organisation, key/scopes, selection, chosen mode and complete derived export snapshot. Changed address/household/coordinate output invalidates the cursor; restart before using a supposedly complete export. readAt is observation time and consistentSnapshot:false, not a historical address guarantee. Unknown query/body properties, arbitrary projections, invalid IDs/modes and wrong types are rejected. A source/related-family inconsistency refuses the qualified export; do not silently omit a household member to bypass it. addressMode defaults to PRIMARY (addressId MAIN); ALL also includes current secondary address UUIDs. Each selected address produces a row even when coordinates are unavailable; contacts with no selected address are counted in contactsWithoutAddress. Stored geos are admitted only when latitude/longitude are native finite numbers in geographic bounds and the product owner verifies the stored geo query still matches that exact current address after its normalisation. Correct addressId alone is insufficient: stale-address coordinates and numeric strings/null are excluded. Unverified coordinates are both null with NO_VERIFIED_STORED_COORDINATE, never fabricated 0/0; valid stored 0 values remain valid observations when their address query matches. STORED_CURRENT_ADDRESS_MATCH does not assert rooftop accuracy, provider freshness or a new geocode. Only the selected contacts own addresses are used; this route does not expand household context, place a map pin externally or query address-access secrets.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "contactIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 2000,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          },
          "addressMode": {
            "type": "string",
            "enum": [
              "PRIMARY",
              "ALL"
            ],
            "default": "PRIMARY"
          }
        },
        "required": [
          "contactIds"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "A bounded page of the admitted postal/map selection.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMapExportResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid selection, mode or changed-snapshot cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing contact scope or inconsistent organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "A selected contact, household member or current family is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source cap, malformed relationship or duplicate identity/address prevents the export.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "The bounded address read could not complete.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/reconciliation

Reconcile a bounded current contact projection against a client manifest

`reconcile_contact_directory`

Requires contacts:read. Read-only reconciliation using the product directory manifest owner, not a timestamp journal or resumable change cursor. First call uses an empty body {}. Optionally restrict to 1–2000 explicit contactIds, including known IDs that may no longer be available; never infer their existence from the input. Later calls supply the exact prior data.scope and complete data.manifest as baseline, with the same optional selection. Each call re-reads the current non-deleted contacts in this organisation, including archives, and compares hashes of only the advertised projection fields. Maximum 10000 current contacts, baseline entries and returned manifest/upsert/removed entries, with an 8 MiB owner payload. A full organisation larger than 10000 gives 422 CONTACT_RECONCILIATION_LIMIT_EXCEEDED before returning any manifest, without truncation. Resolve a legitimate fixed explicit contactIds selection of at most 2000 instead; never silently discard rows or reuse an incomplete manifest. Use a legitimate fixed explicit selection or another supported exchange workflow when the complete directory exceeds that bound; do not silently drop contacts. A changed organisation/key/scopes/restriction/selection/projection changes scope and returns reset:true with no inferred removals. Replace the saved manifest only after receiving and applying a complete successful response. upserts contains new or changed projected rows, with unknown values null. removed contains prior-manifest IDs no longer in the current observation and reason:UNKNOWN; this can reflect deletion, merge, lost availability, selection change outside a retained baseline or concurrent activity, and never proves a deletion or identifies a surviving merge target. Do not automatically delete a remote person or reassign an external identifier based on removed. There is no completeChangeJournal, mergeHistoryAvailable or hardDeleteReasonAvailable; archiveCurrentStateIncluded means only the current recorded archive flag, not every archive/restore transition. No transient change reverted between observations, sub-resource field outside coverage, historical merge chain or tombstone is guaranteed. Baseline versions are projection hashes, never authorisation or server-issued event sequence numbers. observedAt is database observation time and consistentSnapshot:false; concurrent changes can occur during a read. Dates absent from historical data stay null. Malformed or duplicate identity data gives 422 rather than an apparently complete manifest. Unknown query/body fields, invalid/duplicate baseline IDs and wrong types are rejected. Database execution is bounded to 10000 ms; 503 CONTACT_RECONCILIATION_QUERY_LIMIT requires a smaller legitimate selection. No rebuild, sync, archive, restore, merge, deletion, provider call, business write or billing is triggered; authentication may update key usage telemetry. MCP output has an explicit trusted quota of 250000 JSON nodes and 16 MiB, with depth 40 unchanged; this is distinct from the lower 8 MiB owner cap. Very dense tag arrays can still exceed the transport quota. No partial result is published; retry only with a smaller legitimate explicit selection, preserving its meaning. No 20000-contact roundtrip is offered by this external contract.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "contactIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 2000,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "baseline": {
            "type": "object",
            "properties": {
              "scope": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "manifest": {
                "type": "array",
                "maxItems": 10000,
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "version": {
                      "type": "string",
                      "pattern": "^[a-f0-9]{64}$"
                    }
                  },
                  "required": [
                    "id",
                    "version"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "required": [
              "scope",
              "manifest"
            ],
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "A complete bounded reconciliation response for this projection.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactReconciliationResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid selection or baseline manifest.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactReconciliationError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactReconciliationError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing contact scope or inconsistent organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactReconciliationError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Directory size, payload cap or malformed historical identity prevents complete reconciliation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactReconciliationError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "The bounded directory read could not complete.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactReconciliationError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp-output-limits": {
    "maxNodes": 250000,
    "maxBytes": 16777216
  },
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/quality/inspect

Read bounded quality findings and duplicate candidates for selected contacts

`inspect_contact_quality`

Requires contacts:read. Read-only fresh diagnostics of 1–200 explicitly selected current non-deleted contacts in the authenticated organisation, using the product pure quality catalogue. Every selected UUID is admitted before analysis; any inaccessible contact gives 404 with no partial selection. Optional methods are limited to whitespace, email, phone, addresses, dates, customFields, categories, duplicates and completeness; no custom rules, arbitrary expressions, activity-source lookup, external enrichment or AI/provider call. phoneCountry is an optional known ISO alpha-2 uppercase country for phone diagnostics; do not guess it. Missing phone country can yield PHONE_REQUIRES_REVIEW instead of normalisation. Duplicate grouping is a heuristic proposal using names/coordinates and legacy owner phone matching; it is never a confirmed same-person decision or reliable country inference. General duplicate checks can include the owner child-identity safeguards, so method/reason codes may also identify those derived safeguards. Only finding ID, method, reasonCode, admitted contactIds, known severity and review flags are returned; before/after, commands, source evidence, staff notes, private analyses and suggested replacement values are excluded. requiresHumanReview:true and canApply:false are unconditional: this operation cannot apply, decide, merge, erase or fix anything. The coverage is SELECTED_CURRENT_CONTACTS_ONLY; it is not a complete organisation duplicate scan, family graph, activity-history analysis or stored staff-owned analysis. Missing family/source context limits conclusions; no findings does not prove clean data or absence of duplicates elsewhere. Explicit archives can be analysed, but owner generic duplicate grouping excludes archived/deleted contacts. limit 1–100, default 50, fixed finding-ID order. The cursor is bound to organisation, key, scopes, selected contacts, methods, phone country and their observed source snapshot; a changed contact requires a fresh first page. readAt dates observation, not a persistent analysis or guaranteed transaction snapshot. At most 2 MiB of projected source data and 10000 findings are admitted, without partial truncation; 422 CONTACT_QUALITY_SOURCE_LIMIT requires a smaller selection. Database queries are limited to 10000 ms; 503 CONTACT_QUALITY_LIMIT_REACHED requires narrowing selection. Unknown query/body fields, invalid types and unsupported methods are rejected. No analysis, decision, contact mutation, merge, provider call, geocoding, synchronisation or billing is persisted; authentication may update key usage telemetry.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "contactIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "methods": {
            "type": "array",
            "minItems": 1,
            "maxItems": 9,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "whitespace",
                "email",
                "phone",
                "addresses",
                "dates",
                "customFields",
                "categories",
                "duplicates",
                "completeness"
              ]
            }
          },
          "phoneCountry": {
            "type": "string",
            "pattern": "^[A-Z]{2}$"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          }
        },
        "required": [
          "contactIds"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified read-only diagnostics for the admitted selection.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReadResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid selection, method, phone country, limit or cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReadError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReadError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing contact scope or inconsistent organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReadError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "At least one selected contact is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReadError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source size, malformed identity or finding integrity prevents a qualified result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReadError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "The bounded quality owner could not complete.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReadError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/quality/reports/latest

Read the latest prepared contact quality report

`get_latest_contact_quality_report`

Requires contacts:read for the authenticated organisation. Reads prepared reports only: no calculation, source-history scan, AI call, queueing or contact mutation. global includes local; local uses the existing starred marker. all includes inactive contacts; active requires qualified business activity within 12 months. Activity is an organisation-wide derived classification, independent of payment scopes; no payment amounts, protected activity dates, source details or technical traces are returned. Counts can overlap across KPIs. score is null when no contact is evaluable; read coverage and unknown alongside it. Current contact visibility is applied before aggregation and pagination. Historical scope changes yield scope_changed with unavailable metrics and explanation; never treat this as a zero score. Explanations remain attached to their actual measuredAt revision. Cursors are opaque and bound to organisation, principal, report, current visibility and filters; keep filters unchanged, restart after a visibility change. No public report webhook is emitted. This is separate from inspect_contact_quality, which computes bounded diagnostics for an explicit selection.

Read this first for availability and the most recent prepared measurements. A pending or failed first preparation has null metrics.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "scope",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "global",
      "local"
    ],
    "default": "global"
  }
}
```

```json
{
  "name": "population",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "all",
      "active"
    ],
    "default": "all"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Prepared result in the current authorised scope.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid filters, limit, KPI or cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing contact scope or inconsistent organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Report unavailable in this organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "The report contact scope has changed.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Prepared report temporarily unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/quality/reports

List prepared contact quality report history

`list_contact_quality_reports`

Requires contacts:read for the authenticated organisation. Reads prepared reports only: no calculation, source-history scan, AI call, queueing or contact mutation. global includes local; local uses the existing starred marker. all includes inactive contacts; active requires qualified business activity within 12 months. Activity is an organisation-wide derived classification, independent of payment scopes; no payment amounts, protected activity dates, source details or technical traces are returned. Counts can overlap across KPIs. score is null when no contact is evaluable; read coverage and unknown alongside it. Current contact visibility is applied before aggregation and pagination. Historical scope changes yield scope_changed with unavailable metrics and explanation; never treat this as a zero score. Explanations remain attached to their actual measuredAt revision. Cursors are opaque and bound to organisation, principal, report, current visibility and filters; keep filters unchanged, restart after a visibility change. No public report webhook is emitted. This is separate from inspect_contact_quality, which computes bounded diagnostics for an explicit selection.

History is retained for 12 months. Items contain prepared measurement summaries; use get_contact_quality_report to load an explanation. Adding or retiring contacts does not rewrite past measurements. Results are ordered by measurement date descending, then report ID descending for equal dates. limit is 1–100, default 25.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "scope",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "global",
      "local"
    ],
    "default": "global"
  }
}
```

```json
{
  "name": "population",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "all",
      "active"
    ],
    "default": "all"
  }
}
```

```json
{
  "name": "limit",
  "in": "query",
  "required": false,
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 25
  }
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Prepared result in the current authorised scope.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportHistoryResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid filters, limit, KPI or cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing contact scope or inconsistent organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Report unavailable in this organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "The report contact scope has changed.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Prepared report temporarily unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/quality/reports/{reportId}

Read a dated contact quality report

`get_contact_quality_report`

Requires contacts:read for the authenticated organisation. Reads prepared reports only: no calculation, source-history scan, AI call, queueing or contact mutation. global includes local; local uses the existing starred marker. all includes inactive contacts; active requires qualified business activity within 12 months. Activity is an organisation-wide derived classification, independent of payment scopes; no payment amounts, protected activity dates, source details or technical traces are returned. Counts can overlap across KPIs. score is null when no contact is evaluable; read coverage and unknown alongside it. Current contact visibility is applied before aggregation and pagination. Historical scope changes yield scope_changed with unavailable metrics and explanation; never treat this as a zero score. Explanations remain attached to their actual measuredAt revision. Cursors are opaque and bound to organisation, principal, report, current visibility and filters; keep filters unchanged, restart after a visibility change. No public report webhook is emitted. This is separate from inspect_contact_quality, which computes bounded diagnostics for an explicit selection.

Use a reportId returned by latest or history to read that dated revision.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "reportId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[a-zA-Z0-9_.:-]{1,200}$"
  }
}
```

```json
{
  "name": "scope",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "global",
      "local"
    ],
    "default": "global"
  }
}
```

```json
{
  "name": "population",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "all",
      "active"
    ],
    "default": "all"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Prepared result in the current authorised scope.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid filters, limit, KPI or cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing contact scope or inconsistent organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Report unavailable in this organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "The report contact scope has changed.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Prepared report temporarily unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/quality/reports/{reportId}/contacts

List current contacts belonging to a report KPI

`list_contact_quality_report_contacts`

Requires contacts:read for the authenticated organisation. Reads prepared reports only: no calculation, source-history scan, AI call, queueing or contact mutation. global includes local; local uses the existing starred marker. all includes inactive contacts; active requires qualified business activity within 12 months. Activity is an organisation-wide derived classification, independent of payment scopes; no payment amounts, protected activity dates, source details or technical traces are returned. Counts can overlap across KPIs. score is null when no contact is evaluable; read coverage and unknown alongside it. Current contact visibility is applied before aggregation and pagination. Historical scope changes yield scope_changed with unavailable metrics and explanation; never treat this as a zero score. Explanations remain attached to their actual measuredAt revision. Cursors are opaque and bound to organisation, principal, report, current visibility and filters; keep filters unchanged, restart after a visibility change. No public report webhook is emitted. This is separate from inspect_contact_quality, which computes bounded diagnostics for an explicit selection.

Use an exact kpi code returned in metrics.kpis; omit kpi for all members of the selected view. search optionally matches current contact names, at most 150 characters. Contact IDs are ordered ascending. limit is 1–100, default 25. Only minimal current contact names and IDs are returned. measuredTotal is the dated authorised KPI population. unavailable counts its members no longer currently displayable, before search. total counts currently displayable contacts matching search; pagination returns only those contacts, never unavailable IDs. Re-read current rights and data before a Studio action.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "reportId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[a-zA-Z0-9_.:-]{1,200}$"
  }
}
```

```json
{
  "name": "scope",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "global",
      "local"
    ],
    "default": "global"
  }
}
```

```json
{
  "name": "population",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "all",
      "active"
    ],
    "default": "all"
  }
}
```

```json
{
  "name": "limit",
  "in": "query",
  "required": false,
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 25
  }
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  }
}
```

```json
{
  "name": "search",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "maxLength": 150
  }
}
```

```json
{
  "name": "kpi",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "pattern": "^[a-zA-Z0-9_:-]{1,100}$"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Prepared result in the current authorised scope.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportContactsResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid filters, limit, KPI or cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing contact scope or inconsistent organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Report unavailable in this organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "The report contact scope has changed.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Prepared report temporarily unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contact-suggestions

Read justified contact suggestions

`list_contact_suggestions`

Use this to prepare a conversation with an existing contact. Reading this list does not contact anyone or request a new calculation. Suggested contacts include situations awaiting verification; the review view is a subset. A score of 80 is an action priority, not an 80% chance of a donation. Contact grouping uses the highest eligible active or review reason, never a sum. Dashboard widgets only show active priorities of at least 60, so an empty widget can coexist with review results. The worker prepares and stores the daily report after 04:00 in the organisation time zone. Opening the page, changing filters and polling read stored results only. An explicit analysis request queues work while the previous report remains readable. Source access is still checked on every read.

Human-consented OAuth only. Manual keys, root/system tokens and old OAuth grants without dedicated consent are refused. Never supply actor/owner/organisation: the server binds the authenticated consenting user to this organisation and application. Requires all source read scopes: contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Current user rights, attribution, categories, poles and associations remain authoritative. Only contacts not deleted, archived or marked deceased and currently admitted by the owner are considered. Source scopes do not grant native rights. Campaign-restricted credentials are refused. Consent/token/scopes and native authority are rechecked before entry and publication; a revocation cannot undo a command already admitted. Only this user’s personal contributions and currently permitted common suggestions are accessible. Prompts, exact model contexts, audit logs, caches and encrypted data are never returned. This is an observation, not a transaction snapshot or a prediction of donation. Unknown/extra fields and malformed input are refused. 

local means effectively starred contacts (stared===true), never geographic proximity; global stays within the current organisation and user rights. view=motif lists individual reasons; contacts groups by person at the maximum active priority, never the sum. Priority 0–100 measures when to act, not a probability. review requires verification; unavailable/expired/paused/resolved do not imply successful contact. state=paused returns pause configurations (not an AI calculation). A common reason may still use this user’s private settings; never forward it as an organisation-wide result. List reads never run analyses. coverage partial/uncalculated and absent jobs must not be interpreted as zero opportunities. new means first detected in the last seven days. widget restricts to active priority >=60 and groups by contact. References are opaque, never access capabilities. For evidence.datePrecision=day, use occurredOn as a civil date; at may be a technical noon instant and is not the exact time of an exchange.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contact_suggestions:read",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "population",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "local",
      "global"
    ],
    "description": "local means contacts marked local (starred), not people nearby. global means all contacts allowed in the current organisation, never other organisations."
  }
}
```

```json
{
  "name": "contact",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 160
  }
}
```

```json
{
  "name": "volet",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "finance",
      "social"
    ],
    "description": "Finance and Social classify the purpose of a conversation. A person may have reasons in both sections."
  }
}
```

```json
{
  "name": "view",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "motif",
      "contacts"
    ]
  }
}
```

```json
{
  "name": "state",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "active",
      "review",
      "paused",
      "expired",
      "unavailable",
      "resolved",
      "all"
    ]
  }
}
```

```json
{
  "name": "scope",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "common",
      "personal"
    ],
    "description": "common means team instructions or pauses; personal means private to the consenting user. A common-labelled result may still use private adjustments and must not be redistributed as a public team result."
  }
}
```

```json
{
  "name": "family",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "recognition",
      "restart_support",
      "relevant_project",
      "lasting_support",
      "commitment",
      "obstacle",
      "welcome",
      "develop_link",
      "reconnect",
      "life_event",
      "support",
      "followup",
      "involvement",
      "acknowledge_help"
    ]
  }
}
```

```json
{
  "name": "q",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 160
  }
}
```

```json
{
  "name": "min",
  "in": "query",
  "required": false,
  "schema": {
    "type": "number",
    "minimum": 0,
    "maximum": 100
  }
}
```

```json
{
  "name": "new",
  "in": "query",
  "required": false,
  "schema": {
    "type": "boolean"
  }
}
```

```json
{
  "name": "widget",
  "in": "query",
  "required": false,
  "schema": {
    "type": "boolean"
  }
}
```

```json
{
  "name": "page",
  "in": "query",
  "required": false,
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100000
  }
}
```

```json
{
  "name": "size",
  "in": "query",
  "required": false,
  "schema": {
    "type": "integer",
    "enum": [
      3,
      20,
      50
    ]
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified result of the delegated operation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionListResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:read",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contact-suggestions/settings

Read common and personal suggestion instructions

`get_contact_suggestion_settings`

Read which contacts and instructions this person currently uses before proposing a configuration change. Team instructions are shared; personal instructions stay private. Each Finance/Social and team/personal combination has its own text. The standard criteria remain in use in every mode. An instruction draft is not necessarily active.

Human-consented OAuth only. Manual keys, root/system tokens and old OAuth grants without dedicated consent are refused. Never supply actor/owner/organisation: the server binds the authenticated consenting user to this organisation and application. Requires all source read scopes: contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Current user rights, attribution, categories, poles and associations remain authoritative. Only contacts not deleted, archived or marked deceased and currently admitted by the owner are considered. Source scopes do not grant native rights. Campaign-restricted credentials are refused. Consent/token/scopes and native authority are rechecked before entry and publication; a revocation cannot undo a command already admitted. Only this user’s personal contributions and currently permitted common suggestions are accessible. Prompts, exact model contexts, audit logs, caches and encrypted data are never returned. This is an observation, not a transaction snapshot or a prediction of donation. Unknown/extra fields and malformed input are refused. 

Only current delegated user settings. Compiled internal rule expressions and audit/model context are excluded; active.text/version identify the active instruction, draft/status identify pending interpretation.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contact_suggestions:read",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ]
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified result of the delegated operation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionSettingsResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:read",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contact-suggestions/settings

Update common or personal suggestion instructions

`update_contact_suggestion_settings`

Describe a concrete situation, the useful conversation and when to wait. For example: suggest thanking a first-time supporter, but check recent conversations first. Saving asks AI to interpret the text; it does not immediately activate it or send a message. The previous active version remains in use until the new interpretation is accepted. Tell the user whether this changes their private instructions or the team instructions before saving.

Human-consented OAuth only. Manual keys, root/system tokens and old OAuth grants without dedicated consent are refused. Never supply actor/owner/organisation: the server binds the authenticated consenting user to this organisation and application. Requires all source read scopes: contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Current user rights, attribution, categories, poles and associations remain authoritative. Only contacts not deleted, archived or marked deceased and currently admitted by the owner are considered. Source scopes do not grant native rights. Campaign-restricted credentials are refused. Consent/token/scopes and native authority are rechecked before entry and publication; a revocation cannot undo a command already admitted. Only this user’s personal contributions and currently permitted common suggestions are accessible. Prompts, exact model contexts, audit logs, caches and encrypted data are never returned. This is an observation, not a transaction snapshot or a prediction of donation. Unknown/extra fields and malformed input are refused. 

Common instructions require the current native ADMIN role; personal instructions affect only the consenting user. revision is an optimistic concurrency value read from get_contact_suggestion_settings (0 for an absent entry). Conflict requires rereading and deliberate reconciliation, not incrementing blindly. Text is interpreted asynchronously and may incur model cost; interpreting is not active. No raw rule/expression injection.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contact_suggestions:configure",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ]
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "volet": {
            "type": "string",
            "enum": [
              "finance",
              "social"
            ],
            "description": "Finance and Social classify the purpose of a conversation. A person may have reasons in both sections."
          },
          "scope": {
            "type": "string",
            "enum": [
              "common",
              "personal"
            ],
            "description": "common means team instructions or pauses; personal means private to the consenting user. A common-labelled result may still use private adjustments and must not be redistributed as a public team result."
          },
          "text": {
            "type": "string",
            "maxLength": 10000
          },
          "revision": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000
          }
        },
        "required": [
          "volet",
          "scope",
          "text",
          "revision"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified result of the delegated operation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionSettingsResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:configure",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": true
  }
}
```

## POST /contact-suggestions/preferences

Update the consenting user’s suggestion preferences

`update_contact_suggestion_preferences`

Choose the contact set and which extra instructions to use. Combined uses team and private instructions, with private instructions taking precedence on conflicts while staying private. Common uses team instructions only; personal uses private instructions only. These choices never disable the standard criteria and never make private text public. Changing the mode requests an analysis; the new results may not be ready immediately.

Human-consented OAuth only. Manual keys, root/system tokens and old OAuth grants without dedicated consent are refused. Never supply actor/owner/organisation: the server binds the authenticated consenting user to this organisation and application. Requires all source read scopes: contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Current user rights, attribution, categories, poles and associations remain authoritative. Only contacts not deleted, archived or marked deceased and currently admitted by the owner are considered. Source scopes do not grant native rights. Campaign-restricted credentials are refused. Consent/token/scopes and native authority are rechecked before entry and publication; a revocation cannot undo a command already admitted. Only this user’s personal contributions and currently permitted common suggestions are accessible. Prompts, exact model contexts, audit logs, caches and encrypted data are never returned. This is an observation, not a transaction snapshot or a prediction of donation. Unknown/extra fields and malformed input are refused. 

Population and per-section mode belong only to this user. volet and mode must appear together. A mode change queues an analysis; this is not immediate recalculation. Also requires contact_suggestions:analyse for that command.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contact_suggestions:configure",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read",
    "contact_suggestions:analyse"
  ]
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_0c53887249a3fdc8ad93"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified result of the delegated operation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionSettingsResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:configure",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read",
    "contact_suggestions:analyse"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": true
  }
}
```

## POST /contact-suggestions/analyses

Request a contact suggestion analysis

`request_contact_suggestion_analysis`

Request refreshed results only when needed. This may use the organisation AI budget and take time. Queued means waiting, running means in progress, and completed means the job ended, possibly with gaps. Check coverage before saying that all contacts were analysed. An unchanged valid analysis can be reused, so a new request does not guarantee a different score.

Human-consented OAuth only. Manual keys, root/system tokens and old OAuth grants without dedicated consent are refused. Never supply actor/owner/organisation: the server binds the authenticated consenting user to this organisation and application. Requires all source read scopes: contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Current user rights, attribution, categories, poles and associations remain authoritative. Only contacts not deleted, archived or marked deceased and currently admitted by the owner are considered. Source scopes do not grant native rights. Campaign-restricted credentials are refused. Consent/token/scopes and native authority are rechecked before entry and publication; a revocation cannot undo a command already admitted. Only this user’s personal contributions and currently permitted common suggestions are accessible. Prompts, exact model contexts, audit logs, caches and encrypted data are never returned. This is an observation, not a transaction snapshot or a prediction of donation. Unknown/extra fields and malformed input are refused. 

Queues a native analysis for the consenting user, subject to native deduplication, throttling, budgets and worker availability. May incur model cost. queued/running is not completed and does not guarantee the worker is enabled. Never launches a worker or calls models in the HTTP request. Repeated equivalent requests can return the same job; preserve its ID and poll status with a read scope.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contact_suggestions:analyse",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ]
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "population": {
            "type": "string",
            "enum": [
              "local",
              "global"
            ],
            "description": "local means contacts marked local (starred), not people nearby. global means all contacts allowed in the current organisation, never other organisations."
          },
          "volet": {
            "type": "string",
            "enum": [
              "finance",
              "social",
              "both"
            ]
          },
          "contact": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          }
        },
        "required": [
          "population",
          "volet"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified result of the delegated operation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionJobResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:analyse",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": true
  }
}
```

## GET /contact-suggestions/analyses/{id}

Read the consenting user’s analysis status

`get_contact_suggestion_analysis`

Use the existing job identifier to explain whether the requested calculation is waiting, running or finished. Do not create another job just to check progress. A finished job can still contain contacts that could not be analysed.

Human-consented OAuth only. Manual keys, root/system tokens and old OAuth grants without dedicated consent are refused. Never supply actor/owner/organisation: the server binds the authenticated consenting user to this organisation and application. Requires all source read scopes: contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Current user rights, attribution, categories, poles and associations remain authoritative. Only contacts not deleted, archived or marked deceased and currently admitted by the owner are considered. Source scopes do not grant native rights. Campaign-restricted credentials are refused. Consent/token/scopes and native authority are rechecked before entry and publication; a revocation cannot undo a command already admitted. Only this user’s personal contributions and currently permitted common suggestions are accessible. Prompts, exact model contexts, audit logs, caches and encrypted data are never returned. This is an observation, not a transaction snapshot or a prediction of donation. Unknown/extra fields and malformed input are refused. 

Only jobs owned by the consenting user in this organisation. A completed job may still have failed contacts; inspect failed and list coverage. Job identity never permits reading another user’s results.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contact_suggestions:read",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 160
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified result of the delegated operation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionJobResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:read",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contact-suggestions/sources/{collection}/{id}

Read a cited contact suggestion source

`get_contact_suggestion_source`

Read the current content of a source cited in a saved suggestion. Use the collection, source ID and contact ID returned by the suggestion. This read verifies current access and never starts analysis or sends a message. The source can differ from the excerpt saved at analyzedAt.

Human-consented OAuth only. Manual keys, root/system tokens and old OAuth grants without dedicated consent are refused. Never supply actor/owner/organisation: the server binds the authenticated consenting user to this organisation and application. Requires all source read scopes: contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Current user rights, attribution, categories, poles and associations remain authoritative. Only contacts not deleted, archived or marked deceased and currently admitted by the owner are considered. Source scopes do not grant native rights. Campaign-restricted credentials are refused. Consent/token/scopes and native authority are rechecked before entry and publication; a revocation cannot undo a command already admitted. Only this user’s personal contributions and currently permitted common suggestions are accessible. Prompts, exact model contexts, audit logs, caches and encrypted data are never returned. This is an observation, not a transaction snapshot or a prediction of donation. Unknown/extra fields and malformed input are refused. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contact_suggestions:read",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "collection",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "contact",
      "contact_activity",
      "paiements",
      "abonnements",
      "dettes_v2",
      "forms_submit",
      "rappel",
      "custom_rappels",
      "forms",
      "caisses",
      "campagnes"
    ]
  }
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 160
  }
}
```

```json
{
  "name": "contact",
  "in": "query",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 160
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified result of the delegated operation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionSourceResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:read",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contact-suggestions/pauses

Pause contact suggestion reasons

`pause_contact_suggestions`

Hide selected reasons temporarily, without marking them resolved. Explain who is affected and for how long before pausing: team pauses affect the team; private pauses affect this user only. Finance and Social are independent: a Social pause must not hide Finance. A contact-level pause also covers new matching reasons; an explicit reason list only covers those reasons. The user chooses 7 days, 30 days or a date in the organisation time zone; the page preselects 7 days, but API callers must make the choice explicit.

Human-consented OAuth only. Manual keys, root/system tokens and old OAuth grants without dedicated consent are refused. Never supply actor/owner/organisation: the server binds the authenticated consenting user to this organisation and application. Requires all source read scopes: contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Current user rights, attribution, categories, poles and associations remain authoritative. Only contacts not deleted, archived or marked deceased and currently admitted by the owner are considered. Source scopes do not grant native rights. Campaign-restricted credentials are refused. Consent/token/scopes and native authority are rechecked before entry and publication; a revocation cannot undo a command already admitted. Only this user’s personal contributions and currently permitted common suggestions are accessible. Prompts, exact model contexts, audit logs, caches and encrypted data are never returned. This is an observation, not a transaction snapshot or a prediction of donation. Unknown/extra fields and malformed input are refused. 

A personal pause is private; common/mixed additionally requires native contact.edit and affects the team. volets lists finance/social; omitted motifs pauses all reasons for the contact in those sections/scopes. Exactly one of days (7 or 30) and date (YYYY-MM-DD, through that local day) is required. Server organisation time zone is authoritative. operationKey is a caller UUID for the exact intention; preserve it across retries. partial=true with failed steps must never be described as fully saved. A pause is not a resolved interaction and sends no contact message.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contact_suggestions:pause",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ]
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "operationKey": {
            "type": "string",
            "format": "uuid"
          },
          "contact": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "volets": {
            "type": "array",
            "minItems": 1,
            "maxItems": 2,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "finance",
                "social"
              ],
              "description": "Finance and Social classify the purpose of a conversation. A person may have reasons in both sections."
            }
          },
          "scope": {
            "type": "string",
            "enum": [
              "common",
              "personal",
              "mixed"
            ]
          },
          "motifs": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 160
            }
          },
          "days": {
            "type": "integer",
            "enum": [
              7,
              30
            ]
          },
          "date": {
            "type": "string",
            "format": "date"
          }
        },
        "required": [
          "operationKey",
          "contact",
          "volets",
          "scope"
        ],
        "additionalProperties": false,
        "oneOf": [
          {
            "required": [
              "days"
            ],
            "not": {
              "required": [
                "date"
              ]
            }
          },
          {
            "required": [
              "date"
            ],
            "not": {
              "required": [
                "days"
              ]
            }
          }
        ]
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified result of the delegated operation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionPauseResultResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:pause",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  }
}
```

## POST /contact-suggestions/pauses/{id}/resume

Resume a contact suggestion pause

`resume_contact_suggestion_pause`

End the selected pause early and request updated analysis. This does not itself prove that a new suggestion is ready or that a conversation happened. Check the current result after the calculation.

Human-consented OAuth only. Manual keys, root/system tokens and old OAuth grants without dedicated consent are refused. Never supply actor/owner/organisation: the server binds the authenticated consenting user to this organisation and application. Requires all source read scopes: contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Current user rights, attribution, categories, poles and associations remain authoritative. Only contacts not deleted, archived or marked deceased and currently admitted by the owner are considered. Source scopes do not grant native rights. Campaign-restricted credentials are refused. Consent/token/scopes and native authority are rechecked before entry and publication; a revocation cannot undo a command already admitted. Only this user’s personal contributions and currently permitted common suggestions are accessible. Prompts, exact model contexts, audit logs, caches and encrypted data are never returned. This is an observation, not a transaction snapshot or a prediction of donation. Unknown/extra fields and malformed input are refused. 

Personal pause belongs to the consenting user; common pause additionally requires native contact.edit. Queues a fresh analysis and also requires contact_suggestions:analyse; expiry/resume does not prove new results are ready. No contact message. Read current state after an uncertain response before retrying.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contact_suggestions:pause",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read",
    "contact_suggestions:analyse"
  ]
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 160
  }
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified result of the delegated operation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionResumeResultResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:pause",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read",
    "contact_suggestions:analyse"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": true
  }
}
```

## GET /contact-suggestions/interactions/{key}

Check a suggestion interaction receipt

`get_contact_suggestion_interaction`

Check whether this exact conversation-recording command already has a receipt. This is a read operation: it cannot record a conversation. In the page, a person records an actual exchange through Add an interaction and selects the subjects discussed. Do not invent an equivalent MCP write action or treat a pause as proof of a conversation.

Human-consented OAuth only. Manual keys, root/system tokens and old OAuth grants without dedicated consent are refused. Never supply actor/owner/organisation: the server binds the authenticated consenting user to this organisation and application. Requires all source read scopes: contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Current user rights, attribution, categories, poles and associations remain authoritative. Only contacts not deleted, archived or marked deceased and currently admitted by the owner are considered. Source scopes do not grant native rights. Campaign-restricted credentials are refused. Consent/token/scopes and native authority are rechecked before entry and publication; a revocation cannot undo a command already admitted. Only this user’s personal contributions and currently permitted common suggestions are accessible. Prompts, exact model contexts, audit logs, caches and encrypted data are never returned. This is an observation, not a transaction snapshot or a prediction of donation. Unknown/extra fields and malformed input are refused. 

Reads only an existing canonical interaction receipt owned by the consenting user for the selected contact and exact operation key. Does not create an interaction or repair links. recorded=false is the current absence of this receipt, not proof that no conversation occurred.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contact_suggestions:read",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "key",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "contact",
  "in": "query",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 160
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified result of the delegated operation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionInteractionResultResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Refused input, missing consent/current rights, conflict or unavailable owner. No automatic retry after an uncertain command.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:read",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## PUT /contacts/external-identifiers

Attach an external system identifier to one resolved contact

`attach_contact_external_identifier`

External contact identifiers are explicit organisation/system namespaces managed by the Integrations API, not a canonical contact field, Google resource name, tax identifier, identity match or account link. system is a lowercase namespace (2–64 characters, a-z then a-z/0-9/._-), and externalId is an exact case-sensitive string (1–200 characters) without surrounding whitespace or control characters; no normalisation is performed. One (organisation,system,externalId) can reference at most one contact. Namespaces are shared by authorised keys within the organisation; the client must use its intended system namespace, not probe unrelated systems. Private provenance key IDs and database identifiers are never returned. Every linked contact must be a current non-deleted exact scalar UUID in this organisation; archived contacts remain readable. Reads and target checks are bounded to 10000 ms each; 503 requires a smaller selection or later verified recovery, never an assumed successful remapping. Unknown query/body fields, arbitrary filters and wrong types are rejected. No provider, Google sync, contact merge, canonical external-ID upsert, contact mutation, webhook producer, business payment or billing is triggered; authentication may update key usage telemetry. Mapping insertion explicitly requires majority+j:true durable write concern, acknowledged===true and the exact deterministic insertedId before success. Missing or mismatched acknowledgement yields CONTACT_EXTERNAL_ID_RESULT_UNCONFIRMED; no automatic second insert occurs. Mapping read-back uses majority read concern. Requires contacts:write AND contacts:read. Supply the already resolved contactId; this does not create or deduplicate a contact. A first successful attachment returns created:true. Replaying the same namespace/identifier/contact returns created:false without changing the stored mapping. A different contact for an existing identifier gives 409 CONTACT_EXTERNAL_ID_CONFLICT; never retry with a guessed contact or overwrite it. The unique deterministic mapping key arbitrates concurrent claims. Only a mapping record is inserted; no contact field is changed, no database index is created by the request and no migration is needed for uniqueness. Contact admission and insertion are separate reads/writes: a concurrent deletion can make a committed mapping unresolved later. Acknowledged insertions return their known result without a risky ancillary reread. After an uncertain timeout, lookup the same exact identifier and compare the returned contactId before considering an identical retry; a conflicting or unresolved outcome is not permission to remap. Before a new mapping insert, the passive contact mutation fence checks the exact contact for unresolved lifecycle/reference work. An already recorded identical mapping replays before that guard. CONTACT_MUTATION_BLOCKED gives 409 without an insert; CONTACT_MUTATION_FENCE_UNAVAILABLE gives 503 without an insert. Do not change the target or namespace to bypass uncertainty.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:write",
  "additional": [
    "contacts:read"
  ]
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "system": {
            "type": "string",
            "minLength": 2,
            "maxLength": 64,
            "pattern": "^[a-z][a-z0-9._-]{1,63}$"
          },
          "externalId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
          },
          "contactId": {
            "type": "string",
            "format": "uuid"
          }
        },
        "required": [
          "system",
          "externalId",
          "contactId"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified external-identifier mapping result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdAttachResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid namespace, identifier, contact UUID or request envelope.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Required contact scopes are missing or organisation context is inconsistent.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "The contact selected for attachment is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "The identifier is already attached to another contact, or an existing mapping is malformed. No overwrite occurs.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Malformed or ambiguous historical identity prevents a qualified lookup.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "The mapping operation could not complete; verify with lookup before retrying an uncertain attachment.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  }
}
```

## POST /contacts/external-identifiers/lookup

Resolve a bounded batch of external identifiers to current contacts

`lookup_contact_external_identifiers`

External contact identifiers are explicit organisation/system namespaces managed by the Integrations API, not a canonical contact field, Google resource name, tax identifier, identity match or account link. system is a lowercase namespace (2–64 characters, a-z then a-z/0-9/._-), and externalId is an exact case-sensitive string (1–200 characters) without surrounding whitespace or control characters; no normalisation is performed. One (organisation,system,externalId) can reference at most one contact. Namespaces are shared by authorised keys within the organisation; the client must use its intended system namespace, not probe unrelated systems. Private provenance key IDs and database identifiers are never returned. Every linked contact must be a current non-deleted exact scalar UUID in this organisation; archived contacts remain readable. Reads and target checks are bounded to 10000 ms each; 503 requires a smaller selection or later verified recovery, never an assumed successful remapping. Unknown query/body fields, arbitrary filters and wrong types are rejected. No provider, Google sync, contact merge, canonical external-ID upsert, contact mutation, webhook producer, business payment or billing is triggered; authentication may update key usage telemetry. Mapping insertion explicitly requires majority+j:true durable write concern, acknowledged===true and the exact deterministic insertedId before success. Missing or mismatched acknowledgement yields CONTACT_EXTERNAL_ID_RESULT_UNCONFIRMED; no automatic second insert occurs. Mapping read-back uses majority read concern. Requires contacts:read. Supply 1–200 distinct exact externalIds in one system namespace. Results preserve input order. RESOLVED means an admitted integration mapping currently points to an admitted contact in this organisation; only its UUID and known mapping creation time are returned. UNRESOLVED with contactId:null can mean no mapping, malformed mapping, missing/deleted/foreign target or otherwise unavailable target; it does not establish global absence, deletion or a merge. Never follow an old mergedInto reference or infer a surviving contact. Invalid dates remain null. The mapping and target reads are not one consistent snapshot, so consistentSnapshot:false. There is no arbitrary external-ID search across systems, fuzzy identity lookup, automated creation, reattachment or namespace takeover.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "system": {
            "type": "string",
            "minLength": 2,
            "maxLength": 64,
            "pattern": "^[a-z][a-z0-9._-]{1,63}$"
          },
          "externalIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
            }
          }
        },
        "required": [
          "system",
          "externalIds"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Qualified external-identifier mapping result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdLookupResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid namespace, identifier, contact UUID or request envelope.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Required contact scopes are missing or organisation context is inconsistent.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "The contact selected for attachment is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "The identifier is already attached to another contact, or an existing mapping is malformed. No overwrite occurs.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Malformed or ambiguous historical identity prevents a qualified lookup.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "The mapping operation could not complete; verify with lookup before retrying an uncertain attachment.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/exports

Read selected contact columns as a paginated export

`export_contacts`

Requires contacts:read. Read-only JSON export of 1–2000 distinct current contact UUIDs resolved in the authenticated organisation before pagination; any unavailable/deleted/foreign contact refuses the whole selection with 404 CONTACT_EXPORT_SELECTION_UNAVAILABLE. Resolve a legitimate selection with search_contacts_advanced and its catalogues first; do not enumerate unrelated contacts. Explicit archived IDs remain exportable; this route does not archive/restore or infer current membership. Choose 1–40 standard fields from the input enum, with optional exact customFields key/type pairs, maximum 40 columns total. Custom field pairs come from list_contact_custom_fields; unknown, missing or malformed stored values become null, not empty strings, false, zero or guessed dates. Duplicate stored entries for a custom key/type produce an array preserving their native values, including null for invalid entries; they are never silently overwritten or concatenated. TEXT remains text, NUMBER stays finite native numeric units without currency inference, BOOL preserves native/legacy Oui/Non meaning, DATE is an ISO UTC calendar date and DATETIME an explicit ISO instant. Gender is M/F only when recorded, otherwise null. Secondary coordinates and tags are arrays, never delimiter-joined cells. Standard fields include primary postal address text but no address access code, private note, fiscal identifier, payment total, token or reusable instrument. Arbitrary projections, database paths, expressions and unknown query/body properties are rejected. Results contain only selected columns, each row contactId and ordered cells with columnId/value. Retain actual contact IDs when exporting; columns do not prove bank settlement, consent or account status. limit 1–100, default 50. Opaque cursor uses fixed binary ID_ASC and is bound to organisation, key, scopes, exact selected IDs and chosen columns; continue with the same selection until hasMore:false. readAt is observation time; concurrent edits can occur between admission and page reads, so consistentSnapshot:false. This is not a chronological change, deletion or merge feed, and absence never authorises deletion elsewhere. Each query is limited to 10000 ms; 503 CONTACT_EXPORT_LIMIT_REACHED requires a smaller selection before retry. 422 CONTACT_EXPORT_INVALID_SOURCE/CONTACT_EXPORT_AMBIGUOUS_ID signals inconsistent identity data, not permission to invent or merge a person. No file is persisted, no provider/geocoder is called, no business write, synchronisation, billing or download delivery occurs; authentication may update key usage telemetry. MCP output has an explicit trusted quota of 50000 JSON nodes and 16 MiB, with depth 40 unchanged; the real 100-row/40-column scalar export is qualified under this quota. Very large secondary-coordinate, tag or repeated-custom-value arrays can still exceed it. No partial page is published on a quota failure; reduce the requested page size or selected columns while preserving the legitimate contact selection.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_4f53ab7a631d002ee822"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "A bounded page of the explicitly selected contact columns.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExportResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid or unknown selection, field, value type, limit or cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExportError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExportError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing contacts:read or inconsistent organisation context.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExportError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "At least one selected contact is unavailable; no partial selection is returned.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExportError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Malformed or duplicate historical identity prevents a qualified export.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExportError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "The bounded export query could not complete. Reduce the selection.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExportError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp-output-limits": {
    "maxNodes": 50000,
    "maxBytes": 16777216
  },
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/search-advanced

Search contacts by calculated list, live pole, category, typed field and flags

`search_contacts_advanced`

Read-only structured search in the authenticated organisation, requiring contacts:read. This is distinct from search_contacts (zero/one email/phone lookup) and list_contacts (legacy simple list). Filters are ANDed; tags/listIds use any by default, all requires every supplied value, none excludes every supplied value. tags are exact observed strings, including #; they are not UUIDs and are never silently normalised. listIds are opaque calculated-list identifiers such as form:<UUID>, product:<formUUID>:<productUUID>, cagnotte:<UUID>, event:<UUID>, fundraising:<UUID>; source UUIDs alone are invalid. Current source objects, organisation, active generation, list completeness and every linked membership are re-admitted before use. These are calculated participation/contribution lists, not editable manual lists or proof of current consent, payment settlement or account membership. Required conditional scopes: form/product= forms:read AND forms_submit:read; cagnotte= caisses:read AND paiements:read; event= events:read AND forms:read AND forms_submit:read AND caisses:read AND paiements:read; fundraising= fundraising:read AND paiements:read AND abonnements:read AND promesses:read. The fundraising key campaign restriction applies to each campaign source. poleIds require the event scope set and use current live contact-pole membership from registration/payment/category sources without repairing the projection; campaign-restricted keys cannot use poleIds (403 CONTACT_POLE_CAMPAIGN_SCOPE_UNSUPPORTED). Pole UUIDs select any current pole; null is the main pole. archived/deceased/isNew are independent recorded flags, never a fabricated overall contact status. Archived contacts are excluded unless archived:true; deceased and new are unfiltered when omitted. false means not marked true and includes missing legacy flags, whose returned value stays null. Typed customFields require exact observed key/type; TEXT values must occur in that pair and use exact case/accent matching, BOOL accepts native booleans and the owner legacy Oui/Non representation, NUMBER uses finite JSON numeric bounds in the field native units without currency inference, DATE bounds are inclusive UTC calendar days, DATETIME from is inclusive and to exclusive with explicit timezone. Every numeric/date filter needs at least one bound; duplicate key/type filters, invalid dates/types and unknown fields/values are rejected. Unsupported or text-stored numeric/date values are not coerced into typed matches. Maximum 10 custom filters, 20 selected values per set, limit 1–100 (default 50). Results are minimal contact summaries with unknown values null and no private notes, documents, address access codes, tokens or payment instruments. The opaque cursor follows fixed binary ID_ASC order and is tied to organisation, key, scopes, filters and active list generation; reuse it with the same filters. A changed list generation requires starting again without a cursor. readAt is observation time; listComputedAt is only the active projection last-success timestamp when known. Concurrent changes can occur; this is neither a consistent snapshot nor a reliable change/deletion/merge feed. It performs no synchronisation, merge, import, business write, provider call or billing; authentication may update key usage telemetry. Unknown query/body properties, wrong types and arbitrary Mongo conditions are rejected. 403 INSUFFICIENT_SCOPE means stop this unsupported selection; do not enumerate another source as a workaround. 404 CONTACT_LIST_UNAVAILABLE/CONTACT_TAG_UNAVAILABLE/CONTACT_FIELD_UNAVAILABLE/CONTACT_POLE_UNAVAILABLE means select a currently available exact catalogue value. 409 CONTACT_LIST_NOT_READY or CONTACT_LIST_HISTORY_INCOMPLETE requires the ordinary product owner to complete its projection/history, not a blind retry. Owner source reads are capped at 20000 rows and each query at 10000 ms: 422 CONTACT_SEARCH_SOURCE_LIMIT or 503 CONTACT_SEARCH_LIMIT_REACHED requires a narrower selection; no truncated page is returned. 422 CONTACT_SEARCH_INVALID_SOURCE/CONTACT_SEARCH_AMBIGUOUS_ID means inconsistent historical identity data, never permission to invent or merge a person. INVALID_CONTACT_SEARCH_CURSOR requires restarting this selection; absence from results does not authorise deletion elsewhere.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "filters": {
            "$ref": "#/components/schemas/UnisoftRequest_169b8464c56f9629f796"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          }
        },
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "A bounded page of admitted contact summaries.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid or unknown input, type, field range, list identifier or cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing contact/source scope, invalid organisation or unsupported pole campaign restriction.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "A selected source/list/pole/category/field is unavailable in this organisation and scope.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "The calculated-list projection is not ready or its historical membership is incomplete.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source size, malformed historical identity or duplicate logical identity prevents a qualified page.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "The bounded owner read could not complete. Narrow the selection before retrying.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-conditional-scopes": [
    {
      "condition": "filters.listIds contains a form: list",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "filters.listIds contains a product: list",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "filters.listIds contains a cagnotte: list",
      "scopes": [
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "filters.listIds contains a event: list",
      "scopes": [
        "events:read",
        "forms:read",
        "forms_submit:read",
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "filters.listIds contains a fundraising: list",
      "scopes": [
        "fundraising:read",
        "paiements:read",
        "abonnements:read",
        "promesses:read"
      ],
      "allRequired": true
    },
    {
      "condition": "filters.poleIds is present",
      "scopes": [
        "events:read",
        "forms:read",
        "forms_submit:read",
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    }
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/catalog/tags

Read exact observed contact categories

`list_contact_tags`

Requires contacts:read. Read-only authorised metadata in the authenticated organisation. No contact mutation, list rebuild, synchronisation, provider call or billing occurs; authentication may update key usage telemetry. Unknown/repeated query values, invalid types and any non-empty HTTP body are rejected. Pagination is binary ascending by exact catalogue value (key/type for fields, ID for lists/poles); limit 1–100, default 50. A cursor is bound to this organisation, key, scopes/restriction, catalogue and selection, including the active list generation where applicable. readAt is observation time, not a consistent snapshot. Queries are limited to 10000 ms; owner source lists/poles are capped at 20000 rows, with 422 on overflow and no truncated catalogue. A 503 CONTACT_CATALOG_LIMIT_REACHED requires a smaller legitimate selection; an invalid cursor requires a fresh first page. Never remove authorisation filters or probe another organisation as a workaround. Returns valid category strings observed on non-deleted contacts, including archived contacts. Preserve case, accents and the leading #; these are labels, not UUIDs. This is not a configured enum, consent state, donor status or guarantee that the tag is still present on a later search. No legacy RDV categories or private staff configuration are read. Use the exact returned tag in search_contacts_advanced or an authorised tag mutation.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  },
  "description": "Maximum page size, 1–100; default 50."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  },
  "description": "Opaque cursor from the same catalogue, organisation, key, scopes and selection. A changed active list generation requires restarting without a cursor."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "A bounded page of authorised contact metadata.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogTagResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid catalogue query or cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing contact/source scopes or unsupported pole campaign restriction.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Calculated-list generation is not ready.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source cap or inconsistent historical metadata prevents a qualified result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "The bounded catalogue read is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/catalog/custom-fields

Discover stored custom-field keys and native types

`list_contact_custom_fields`

Requires contacts:read. Read-only authorised metadata in the authenticated organisation. No contact mutation, list rebuild, synchronisation, provider call or billing occurs; authentication may update key usage telemetry. Unknown/repeated query values, invalid types and any non-empty HTTP body are rejected. Pagination is binary ascending by exact catalogue value (key/type for fields, ID for lists/poles); limit 1–100, default 50. A cursor is bound to this organisation, key, scopes/restriction, catalogue and selection, including the active list generation where applicable. readAt is observation time, not a consistent snapshot. Queries are limited to 10000 ms; owner source lists/poles are capped at 20000 rows, with 422 on overflow and no truncated catalogue. A 503 CONTACT_CATALOG_LIMIT_REACHED requires a smaller legitimate selection; an invalid cursor requires a fresh first page. Never remove authorisation filters or probe another organisation as a workaround. Returns exact observed (key,type) pairs with at least one supported native value on a non-deleted contact. A key can occur under multiple types; keep the pair. TEXT operators are any/all/none, BOOL uses value, NUMBER min/max in native unspecified units, DATE/DATETIME from/to. DATE is inclusive UTC calendar days; DATETIME has inclusive start/exclusive end with explicit timezone. NUMBER is not a currency amount. hasObservedValues:true indicates that list_contact_custom_field_values can enumerate TEXT values, not an editable enum. TEXT-stored numbers/dates do not become numeric/date fields; no inference or coercion is performed. Fields with only malformed, empty or unsupported values are omitted.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  },
  "description": "Maximum page size, 1–100; default 50."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  },
  "description": "Opaque cursor from the same catalogue, organisation, key, scopes and selection. A changed active list generation requires restarting without a cursor."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "A bounded page of authorised contact metadata.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogFieldResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid catalogue query or cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing contact/source scopes or unsupported pole campaign restriction.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Calculated-list generation is not ready.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source cap or inconsistent historical metadata prevents a qualified result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "The bounded catalogue read is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/catalog/custom-fields/values

Read observed text values for one exact contact field

`list_contact_custom_field_values`

Requires contacts:read. Read-only authorised metadata in the authenticated organisation. No contact mutation, list rebuild, synchronisation, provider call or billing occurs; authentication may update key usage telemetry. Unknown/repeated query values, invalid types and any non-empty HTTP body are rejected. Pagination is binary ascending by exact catalogue value (key/type for fields, ID for lists/poles); limit 1–100, default 50. A cursor is bound to this organisation, key, scopes/restriction, catalogue and selection, including the active list generation where applicable. readAt is observation time, not a consistent snapshot. Queries are limited to 10000 ms; owner source lists/poles are capped at 20000 rows, with 422 on overflow and no truncated catalogue. A 503 CONTACT_CATALOG_LIMIT_REACHED requires a smaller legitimate selection; an invalid cursor requires a fresh first page. Never remove authorisation filters or probe another organisation as a workaround. Requires key from the TEXT pair in list_contact_custom_fields. Returns distinct exact nonempty TEXT strings observed under that key, never configured allowed-value rules; case and accents are preserved. A numeric-looking string remains text. Empty results can mean no current supported value or an unavailable key and do not establish that the field never existed. Use only the returned value strings in an exact TEXT search. The cursor is also bound to key.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  },
  "description": "Maximum page size, 1–100; default 50."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  },
  "description": "Opaque cursor from the same catalogue, organisation, key, scopes and selection. A changed active list generation requires restarting without a cursor."
}
```

```json
{
  "name": "key",
  "in": "query",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 120
  },
  "description": "Exact key from an authorised TEXT custom-field catalogue pair; not a database path."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "A bounded page of authorised contact metadata.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogValueResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid catalogue query or cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing contact/source scopes or unsupported pole campaign restriction.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Calculated-list generation is not ready.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source cap or inconsistent historical metadata prevents a qualified result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "The bounded catalogue read is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/catalog/lists

Discover authorised calculated contact-list identifiers

`list_contact_lists`

Requires contacts:read. Read-only authorised metadata in the authenticated organisation. No contact mutation, list rebuild, synchronisation, provider call or billing occurs; authentication may update key usage telemetry. Unknown/repeated query values, invalid types and any non-empty HTTP body are rejected. Pagination is binary ascending by exact catalogue value (key/type for fields, ID for lists/poles); limit 1–100, default 50. A cursor is bound to this organisation, key, scopes/restriction, catalogue and selection, including the active list generation where applicable. readAt is observation time, not a consistent snapshot. Queries are limited to 10000 ms; owner source lists/poles are capped at 20000 rows, with 422 on overflow and no truncated catalogue. A 503 CONTACT_CATALOG_LIMIT_REACHED requires a smaller legitimate selection; an invalid cursor requires a fresh first page. Never remove authorisation filters or probe another organisation as a workaround. Returns only active-generation calculated lists whose current sources and every required source scope are available. IDs are form:<UUID>, product:<formUUID>:<productUUID>, cagnotte:<UUID>, event:<UUID>, fundraising:<UUID>; sourceId alone is not a list ID. requiredScopes lists all conditional source rights enforced by search_contacts_advanced. Form/product require forms:read and forms_submit:read; caisse requires caisses:read and paiements:read; event requires all those plus events:read; fundraising requires fundraising:read, paiements:read, abonnements:read and promesses:read. Campaign restrictions, including empty restrictions, constrain fundraising sources. No partial event or fundraising list is advertised when a source right is missing. historyIncomplete:true means availableForSearch:false: stop and resolve the history through the ordinary product owner. computedAt is only the last successful projection date when known; these lists are eventual participation/contribution observations, not bank settlement, consent or current account approval. Labels can be unknown null. Counts are not fabricated. No rebuild or source refresh is triggered.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  },
  "description": "Maximum page size, 1–100; default 50."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  },
  "description": "Opaque cursor from the same catalogue, organisation, key, scopes and selection. A changed active list generation requires restarting without a cursor."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "A bounded page of authorised contact metadata.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogListResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid catalogue query or cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing contact/source scopes or unsupported pole campaign restriction.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Calculated-list generation is not ready.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source cap or inconsistent historical metadata prevents a qualified result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "The bounded catalogue read is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-conditional-scopes": [
    {
      "condition": "advertise form: lists",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "advertise product: lists",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "advertise cagnotte: lists",
      "scopes": [
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "advertise event: lists",
      "scopes": [
        "events:read",
        "forms:read",
        "forms_submit:read",
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "advertise fundraising: lists",
      "scopes": [
        "fundraising:read",
        "paiements:read",
        "abonnements:read",
        "promesses:read"
      ],
      "allRequired": true
    }
  ]
}
```

## GET /contacts/catalog/poles

Read current contact pole identifiers

`list_contact_poles`

Requires contacts:read. Read-only authorised metadata in the authenticated organisation. No contact mutation, list rebuild, synchronisation, provider call or billing occurs; authentication may update key usage telemetry. Unknown/repeated query values, invalid types and any non-empty HTTP body are rejected. Pagination is binary ascending by exact catalogue value (key/type for fields, ID for lists/poles); limit 1–100, default 50. A cursor is bound to this organisation, key, scopes/restriction, catalogue and selection, including the active list generation where applicable. readAt is observation time, not a consistent snapshot. Queries are limited to 10000 ms; owner source lists/poles are capped at 20000 rows, with 422 on overflow and no truncated catalogue. A 503 CONTACT_CATALOG_LIMIT_REACHED requires a smaller legitimate selection; an invalid cursor requires a fresh first page. Never remove authorisation filters or probe another organisation as a workaround. Requires contacts:read plus events:read, forms:read, forms_submit:read, caisses:read and paiements:read, matching the live search policy. Campaign-restricted keys are rejected, including an empty campaign restriction. Returns current pole UUIDs and the main pole as id:null, main:true; its absent label remains null. These are identifiers for poleIds in search_contacts_advanced, not a contact-membership projection or staff-access whitelist. No contact membership, category configuration or access whitelist is returned or recomputed.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:read",
  "additional": [
    "events:read",
    "forms:read",
    "forms_submit:read",
    "caisses:read",
    "paiements:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  },
  "description": "Maximum page size, 1–100; default 50."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  },
  "description": "Opaque cursor from the same catalogue, organisation, key, scopes and selection. A changed active list generation requires restarting without a cursor."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "A bounded page of authorised contact metadata.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogPoleResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid catalogue query or cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing contact/source scopes or unsupported pole campaign restriction.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Calculated-list generation is not ready.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source cap or inconsistent historical metadata prevents a qualified result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "The bounded catalogue read is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [
    "events:read",
    "forms:read",
    "forms_submit:read",
    "caisses:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/tag-commands/capabilities

Check organisation tag administration capabilities

`get_contact_tag_command_capabilities`

Requires explicitly granted contacts:manage-tags AND contacts:read AND contacts:write. No default grant. Rejects any campaign-restricted key with CAMPAIGN_RESTRICTED_KEY. This authorises organisation-wide tag administration, including archived/deleted records and legacy stored appointments; no appointments API is opened. Tags are exact stored labels, never UUIDs, list IDs, pole IDs or custom-field keys. All query parameters are forbidden. Discovers preview/apply support and the observation limit without reading business records or starting a command. No request body is accepted. Native CRM propagation covers contacts, legacy appointments, shared tag sets and pole restrictions; rename/merge also updates access category restrictions. REMOVE intentionally preserves access category restrictions but removes the label from pole restrictions: poleRestrictionsEmptied warns when a pole loses its last category filter, which can broaden that pole's access. Saved campaign audiences, saved searches and automatic system-tag generators are unchanged: system tags can reappear on a later business action. No contact is deleted. This is not a globally atomic snapshot: internal writers are not locked and organisation-wide intent can include records created during the command. Counts and the revision describe observed tag-bearing records only, with at most 5000 records per observation. No provider is called. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:manage-tags",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Available tag command capabilities; no mutation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTagCommandCapabilitiesResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_COMMAND, INVALID_ACTION, INVALID_TAG, IDENTICAL_TAGS, UNEXPECTED_TARGET_TAG, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, INVALID_UUID or LIMITS_NOT_ACKNOWLEDGED: correct the declared input.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: the three explicit scopes and an unrestricted same-organisation key are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "TAG_NOT_FOUND, TARGET_TAG_NOT_FOUND or COMMAND_NOT_FOUND: use an existing exact label or an authorised command UUID.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_STORED_TAG_REFERENCE, TAG_COMMAND_TOO_LARGE or IDEMPOTENCY_CONFLICT: no new owner invocation; review the source data, narrow the operation or use the original idempotency content.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: no private error details are exposed.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE: outcome admission could not be proved. Read the original command status; never invent a new key to retry an uncertain effect.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:manage-tags",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/tag-commands/preview

Preview an organisation-wide tag rename, merge or removal

`preview_contact_tag_command`

Requires explicitly granted contacts:manage-tags AND contacts:read AND contacts:write. No default grant. Rejects any campaign-restricted key with CAMPAIGN_RESTRICTED_KEY. This authorises organisation-wide tag administration, including archived/deleted records and legacy stored appointments; no appointments API is opened. Tags are exact stored labels, never UUIDs, list IDs, pole IDs or custom-field keys. All query parameters are forbidden. Read-only impact observation. Supply action RENAME, MERGE or REMOVE and sourceTag. RENAME requires targetTag and applies canonical CRM formatting (uppercase, accents removed, spaces converted to underscores); MERGE requires the exact existing targetTag. REMOVE forbids targetTag. The result returns the canonical command, a revision and observed counts; use those command values and revision in apply. accessRestrictions is null on REMOVE because these restrictions are preserved and not scanned. No contact identities or private configuration are returned. A source/merge-target absence returns 404. Invalid scalar ownership, arrays or parent pole references refuse the whole preview. The preview does not reserve records and never persists a command. Native CRM propagation covers contacts, legacy appointments, shared tag sets and pole restrictions; rename/merge also updates access category restrictions. REMOVE intentionally preserves access category restrictions but removes the label from pole restrictions: poleRestrictionsEmptied warns when a pole loses its last category filter, which can broaden that pole's access. Saved campaign audiences, saved searches and automatic system-tag generators are unchanged: system tags can reappear on a later business action. No contact is deleted. This is not a globally atomic snapshot: internal writers are not locked and organisation-wide intent can include records created during the command. Counts and the revision describe observed tag-bearing records only, with at most 5000 records per observation. No provider is called. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:manage-tags",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "RENAME",
              "MERGE",
              "REMOVE"
            ]
          },
          "sourceTag": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "targetTag": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          }
        },
        "required": [
          "action",
          "sourceTag"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Observed impact and revision; no snapshot reservation and no mutation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTagCommandPreviewResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_COMMAND, INVALID_ACTION, INVALID_TAG, IDENTICAL_TAGS, UNEXPECTED_TARGET_TAG, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, INVALID_UUID or LIMITS_NOT_ACKNOWLEDGED: correct the declared input.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: the three explicit scopes and an unrestricted same-organisation key are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "TAG_NOT_FOUND, TARGET_TAG_NOT_FOUND or COMMAND_NOT_FOUND: use an existing exact label or an authorised command UUID.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_STORED_TAG_REFERENCE, TAG_COMMAND_TOO_LARGE or IDEMPOTENCY_CONFLICT: no new owner invocation; review the source data, narrow the operation or use the original idempotency content.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: no private error details are exposed.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE: outcome admission could not be proved. Read the original command status; never invent a new key to retry an uncertain effect.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:manage-tags",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/tag-commands/apply

Apply a previewed organisation-wide tag command with a durable receipt

`apply_contact_tag_command`

Requires explicitly granted contacts:manage-tags AND contacts:read AND contacts:write. No default grant. Rejects any campaign-restricted key with CAMPAIGN_RESTRICTED_KEY. This authorises organisation-wide tag administration, including archived/deleted records and legacy stored appointments; no appointments API is opened. Tags are exact stored labels, never UUIDs, list IDs, pole IDs or custom-field keys. All query parameters are forbidden. First obtain a preview. Submit its canonical action/sourceTag/targetTag, revision, a stable idempotencyKey of 8–128 ASCII letters/digits/._:- and acknowledgeLimits:true after disclosing the limits. The acknowledgement covers unchanged saved audiences, possible pole access broadening and organisation-wide concurrent additions; do not claim complete reference migration. The server stores a receipt before any business effect, serialises external tag commands per organisation, validates every observed owner reference and checks the revision at admission, then calls the canonical CRM owner once. Same key/content returns the existing receipt; a changed command/revision returns IDEMPOTENCY_CONFLICT. REJECTED means this invocation made no business effect; inspect error such as REVISION_CONFLICT or TAG_COMMAND_BUSY. ADMITTING/RUNNING are pending or interrupted, never proof of failure. COMPLETED means observed source removal and original-record target preservation were verified; it is not a guarantee against later internal writes. PARTIAL means verification found remaining/missing original records; UNKNOWN means an effect or its verification could not be proved. Both states retain the external organisation lock pending review. canRetry is always false. Never retry an uncertain/partial command with a new key or simulate it with per-contact loops; read get_contact_tag_command and request review through the authorised Unisoft workflow. No automatic recovery or stale-lock takeover exists. HTTP 200 with success:true confirms receipt storage only, including REJECTED; inspect data.state before claiming a mutation. Native CRM propagation covers contacts, legacy appointments, shared tag sets and pole restrictions; rename/merge also updates access category restrictions. REMOVE intentionally preserves access category restrictions but removes the label from pole restrictions: poleRestrictionsEmptied warns when a pole loses its last category filter, which can broaden that pole's access. Saved campaign audiences, saved searches and automatic system-tag generators are unchanged: system tags can reappear on a later business action. No contact is deleted. This is not a globally atomic snapshot: internal writers are not locked and organisation-wide intent can include records created during the command. Counts and the revision describe observed tag-bearing records only, with at most 5000 records per observation. No provider is called. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:manage-tags",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "RENAME",
              "MERGE",
              "REMOVE"
            ]
          },
          "sourceTag": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "targetTag": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[a-zA-Z0-9._:-]{8,128}$"
          },
          "acknowledgeLimits": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "action",
          "sourceTag",
          "revision",
          "idempotencyKey",
          "acknowledgeLimits"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Stored COMPLETED, REJECTED, PARTIAL or UNKNOWN result; inspect state before claiming an effect.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTagCommandReceiptResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "Existing command is ADMITTING or RUNNING; no owner replay occurred.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTagCommandReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_COMMAND, INVALID_ACTION, INVALID_TAG, IDENTICAL_TAGS, UNEXPECTED_TARGET_TAG, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, INVALID_UUID or LIMITS_NOT_ACKNOWLEDGED: correct the declared input.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: the three explicit scopes and an unrestricted same-organisation key are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "TAG_NOT_FOUND, TARGET_TAG_NOT_FOUND or COMMAND_NOT_FOUND: use an existing exact label or an authorised command UUID.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_STORED_TAG_REFERENCE, TAG_COMMAND_TOO_LARGE or IDEMPOTENCY_CONFLICT: no new owner invocation; review the source data, narrow the operation or use the original idempotency content.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: no private error details are exposed.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE: outcome admission could not be proved. Read the original command status; never invent a new key to retry an uncertain effect.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:manage-tags",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /contacts/tag-commands/{commandId}

Read the durable status of one organisation tag command

`get_contact_tag_command`

Requires explicitly granted contacts:manage-tags AND contacts:read AND contacts:write. No default grant. Rejects any campaign-restricted key with CAMPAIGN_RESTRICTED_KEY. This authorises organisation-wide tag administration, including archived/deleted records and legacy stored appointments; no appointments API is opened. Tags are exact stored labels, never UUIDs, list IDs, pole IDs or custom-field keys. All query parameters are forbidden. Read only by commandId UUID returned by apply. It rechecks all three scopes and the current organisation; references and old receipts grant no authority. No request body is accepted. Returns the last durable phase/state with no owner invocation, retry or lock recovery. ADMITTING/RUNNING may describe an in-flight or interrupted call; no age proves failure. PARTIAL and UNKNOWN retain the external lock pending authorised review and never authorise a new-key replay. A 404 proves only that no accessible receipt was read, not that another POST failed. canRetry:false in every state. Native CRM propagation covers contacts, legacy appointments, shared tag sets and pole restrictions; rename/merge also updates access category restrictions. REMOVE intentionally preserves access category restrictions but removes the label from pole restrictions: poleRestrictionsEmptied warns when a pole loses its last category filter, which can broaden that pole's access. Saved campaign audiences, saved searches and automatic system-tag generators are unchanged: system tags can reappear on a later business action. No contact is deleted. This is not a globally atomic snapshot: internal writers are not locked and organisation-wide intent can include records created during the command. Counts and the revision describe observed tag-bearing records only, with at most 5000 records per observation. No provider is called. 

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "contacts:manage-tags",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### פרמטרים

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Last durable command status; no replay.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTagCommandReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_COMMAND, INVALID_ACTION, INVALID_TAG, IDENTICAL_TAGS, UNEXPECTED_TARGET_TAG, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, INVALID_UUID or LIMITS_NOT_ACKNOWLEDGED: correct the declared input.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid authentication.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT or CAMPAIGN_RESTRICTED_KEY: the three explicit scopes and an unrestricted same-organisation key are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "TAG_NOT_FOUND, TARGET_TAG_NOT_FOUND or COMMAND_NOT_FOUND: use an existing exact label or an authorised command UUID.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_STORED_TAG_REFERENCE, TAG_COMMAND_TOO_LARGE or IDEMPOTENCY_CONFLICT: no new owner invocation; review the source data, narrow the operation or use the original idempotency content.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR: no private error details are exposed.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE: outcome admission could not be proved. Read the original command status; never invent a new key to retry an uncertain effect.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:manage-tags",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## סכמות

```json
{
  "components": {
    "schemas": {
      "Contact": {
        "type": "object",
        "description": "A contact (donor / member) of the org. Identity fields are flat; the multi-value sub-collections (secondary addresses / phones / emails, tags, custom fields, family links) are arrays. All `readOnly` fields are computed and are never accepted on write.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "readOnly": true,
            "description": "Server-generated UUID. Use it as `{id}` in every sub-resource path."
          },
          "firstName": {
            "type": "string",
            "description": "First name. Stored capitalised (« david » → « David »)."
          },
          "lastName": {
            "type": "string",
            "description": "Last name / family name. Stored UPPER-CASED (« levy » → « LEVY »)."
          },
          "gender": {
            "type": "string",
            "enum": [
              "M",
              "F"
            ],
            "nullable": true,
            "description": "Gender: \"M\" (male) or \"F\" (female), null = unknown. It is derived from civility on import — never guessed."
          },
          "email": {
            "type": "string",
            "description": "Primary email (lower-cased). Extra emails live in `secondaryEmails[]`."
          },
          "phone": {
            "type": "string",
            "description": "Primary phone in E.164 (`+33612345678`). Extra numbers live in `secondaryPhones[]`."
          },
          "birthDate": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "Date of birth, ISO `YYYY-MM-DD`."
          },
          "hebrewFirstName": {
            "type": "string",
            "description": "Hebrew first name (prénom hébraïque)."
          },
          "taxId": {
            "type": "string",
            "nullable": true,
            "description": "National / tax identifier (e.g. Israeli Teudat Zehut). Declarative — not validated against a registry."
          },
          "giftAid": {
            "type": "boolean",
            "description": "UK Gift Aid eligibility flag. Declarative."
          },
          "address": {
            "type": "string",
            "description": "Primary address — street line (flat, no id)."
          },
          "postalCode": {
            "type": "string",
            "description": "Primary address — postal / ZIP code."
          },
          "city": {
            "type": "string",
            "description": "Primary address — city."
          },
          "region": {
            "type": "string",
            "description": "Primary address — state / region / province."
          },
          "country": {
            "type": "string",
            "description": "Primary address — country."
          },
          "note": {
            "type": "string",
            "nullable": true,
            "description": "Free note on the primary address."
          },
          "addresses": {
            "type": "array",
            "description": "SECONDARY addresses (each with a stable `id` UUID — patchable via PATCH /contacts/{id}/addresses/{addressId}). The primary address is the flat `address`/`postalCode`/`city` above and has NO id.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid",
                  "readOnly": true
                },
                "label": {
                  "type": "string",
                  "description": "Free label of the address (e.g. « Bureau »)."
                },
                "type": {
                  "type": "string",
                  "nullable": true,
                  "description": "PRO | PERSO (free label)."
                },
                "address": {
                  "type": "string",
                  "description": "Street line."
                },
                "postalCode": {
                  "type": "string"
                },
                "city": {
                  "type": "string"
                },
                "region": {
                  "type": "string"
                },
                "country": {
                  "type": "string"
                },
                "companyId": {
                  "type": "string",
                  "nullable": true,
                  "description": "Company registration number (for a PRO address)."
                },
                "note": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "secondaryPhones": {
            "type": "array",
            "description": "Additional phones (E.164). The primary is `phone`.",
            "items": {
              "type": "object",
              "properties": {
                "phone": {
                  "type": "string"
                }
              }
            }
          },
          "secondaryEmails": {
            "type": "array",
            "description": "Additional emails. The primary is `email`.",
            "items": {
              "type": "object",
              "properties": {
                "email": {
                  "type": "string"
                }
              }
            }
          },
          "tags": {
            "type": "array",
            "description": "Category TAGS — boolean labels (upper-cased & de-accented, e.g. `DONATEUR`, `#FORM`). These are NOT key/value custom fields — see `customFields[]`.",
            "items": {
              "type": "string"
            }
          },
          "customFields": {
            "type": "array",
            "description": "Typed key/value custom fields. One entry per key (never duplicated). `type` is one of TEXT/DATE/BOOL only — NUMBER/SELECT are stored as TEXT. Distinct from `tags[]`.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "readOnly": true
                },
                "key": {
                  "type": "string"
                },
                "type": {
                  "type": "string",
                  "description": "TEXT | DATE | BOOL"
                },
                "value": {
                  "nullable": true,
                  "description": "Stored value (string, ISO date, or boolean)."
                }
              }
            }
          },
          "familyLinks": {
            "type": "array",
            "description": "Family relationships. `contactId` = the related contact, `relationship` = SPOUSE/PARENT/CHILD/SIBLING/GRANDPARENT/GRANDCHILD/IN_LAW/EX/COUSIN/FRIEND. Bidirectional (the reverse link is on the other contact).",
            "items": {
              "type": "object",
              "properties": {
                "relationship": {
                  "type": "string",
                  "enum": [
                    "SPOUSE",
                    "PARENT",
                    "CHILD",
                    "SIBLING",
                    "GRANDPARENT",
                    "GRANDCHILD",
                    "IN_LAW",
                    "EX",
                    "COUSIN",
                    "FRIEND"
                  ],
                  "nullable": true
                },
                "contactId": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "isLocal": {
            "type": "boolean",
            "readOnly": true,
            "description": "Whether the contact is a « local » proximity contact (lives in the org's action zone), set automatically or manually."
          },
          "isLocalSource": {
            "type": "string",
            "nullable": true,
            "readOnly": true,
            "description": "How `isLocal` was set: AUTO | MANUAL | null."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Creation date."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Last edit date."
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "hasMore": {
            "type": "boolean"
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "UnisoftRequest_e4688e4bc822e21f91a3": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "First name (stored capitalised)."
          },
          "lastName": {
            "type": "string",
            "description": "Last name / family name (stored UPPER-CASED)."
          },
          "gender": {
            "type": "string",
            "enum": [
              "M",
              "F",
              null
            ],
            "nullable": true,
            "description": "\"M\" (male), \"F\" (female) or null (unknown). Never a civility string like \"Mr\"/\"Mme\"."
          },
          "email": {
            "type": "string",
            "description": "Primary email. Invalid emails are dropped."
          },
          "phone": {
            "type": "string",
            "description": "Primary phone (any format; normalised to E.164). Provide `phoneCountry` for local numbers without a country code."
          },
          "phoneCountry": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code (e.g. \"FR\", \"IL\") used to normalise a local `phone`/`phones` without a `+` prefix."
          },
          "phones": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Additional (secondary) phones."
          },
          "emails": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Additional (secondary) emails."
          },
          "birthDate": {
            "type": "string",
            "format": "date",
            "description": "Date of birth, ISO `YYYY-MM-DD`. Fill-if-empty on upsert (never overwrites)."
          },
          "hebrewFirstName": {
            "type": "string",
            "description": "Hebrew first name."
          },
          "taxId": {
            "type": "string",
            "description": "National / tax identifier (e.g. Israeli Teudat Zehut). Declarative."
          },
          "giftAid": {
            "type": "boolean",
            "description": "UK Gift Aid flag. Declarative."
          },
          "address": {
            "type": "string",
            "description": "Primary street address. If the contact already has a main address, this is added as a secondary one."
          },
          "postalCode": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "region": {
            "type": "string",
            "description": "State / region / province."
          },
          "country": {
            "type": "string",
            "description": "Country (default \"France\")."
          },
          "note": {
            "type": "string",
            "description": "Free note on the primary address."
          },
          "addresses": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "type": {
                  "type": "string",
                  "description": "PRO | PERSO"
                },
                "address": {
                  "type": "string"
                },
                "postalCode": {
                  "type": "string"
                },
                "city": {
                  "type": "string"
                },
                "region": {
                  "type": "string"
                },
                "country": {
                  "type": "string"
                },
                "companyId": {
                  "type": "string",
                  "description": "Company registration number (for a PRO address)."
                },
                "note": {
                  "type": "string"
                }
              },
              "additionalProperties": false
            },
            "description": "Extra SECONDARY addresses to add."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Category tags to attach (each normalised UPPERCASE). On CREATE the first tag is the seed tag; with none, the source tag `#API` is set."
          },
          "customFields": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "description": "Field key (case-insensitive, `_`↔`-` equivalent). Upsert-by-key: writing the same key twice updates the single existing field, never duplicates it."
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "TEXT",
                    "NUMBER",
                    "DATE",
                    "DATETIME",
                    "BOOL"
                  ],
                  "description": "TEXT | NUMBER | DATE | DATETIME | BOOL. NUMBER/DATETIME are stored as TEXT.",
                  "default": "TEXT"
                },
                "value": {
                  "description": "Field value (string / number / ISO date / boolean)."
                }
              },
              "required": [
                "key"
              ],
              "additionalProperties": false,
              "description": "A typed custom field. `type` is reduced to TEXT/DATE/BOOL on storage — NUMBER/SELECT/etc. are stored as TEXT (the round-trip value stays a string)."
            },
            "description": "Typed key/value custom fields (upsert-by-key). On create/import these are fill-if-empty (append-only). Distinct from `tags[]`."
          }
        },
        "additionalProperties": false,
        "description": "Identity of a contact to CREATE or UPSERT. All fields optional — the smallest useful contact is a single `phone` or `email`. Formats: `gender` = \"M\" (male) or \"F\" (female) or null (unknown — NEVER \"Mr\"/\"Mme\"); `phone` accepts a dirty string (« 06 11 22 33 44 »), normalised to E.164; `birthDate` ISO `YYYY-MM-DD`; each `tags` entry is upper-cased/de-accented (« Donateur régulier » → « DONATEUR_REGULIER »). `tags` are boolean labels; `customFields` are typed key/value fields — do not confuse them."
      },
      "ContactImportSchema": {
        "type": "object",
        "description": "The self-describing import guide: the catalogue of importable fields (each with the aliases to match your spreadsheet columns) and the available import options. Call it FIRST, map your columns onto these field keys, then normalize → lookup → import dryRun → import.",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "fields": {
            "type": "array",
            "description": "Every importable public field.",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "description": "The public field key to use in normalize/import rows (e.g. \"firstName\", \"phone\", \"tags\")."
                },
                "label": {
                  "type": "string",
                  "description": "Human label."
                },
                "type": {
                  "type": "string",
                  "description": "string | enum | date | boolean | object[]."
                },
                "kind": {
                  "type": "string",
                  "enum": [
                    "identity",
                    "address",
                    "contact",
                    "tag",
                    "customField"
                  ],
                  "description": "Which part of the contact this field feeds."
                },
                "multi": {
                  "type": "boolean",
                  "description": "Whether the field accepts multiple values (e.g. tags, secondary phones)."
                },
                "example": {
                  "description": "A sample value."
                },
                "description": {
                  "type": "string"
                },
                "aliases": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "Common FR/EN spreadsheet column headers that map to this field — use them to auto-match your columns."
                }
              }
            }
          },
          "options": {
            "type": "object",
            "description": "Import option metadata from the owner. Only options declared by ContactImportInput are callable through this API; metadata alone does not admit additional arguments.",
            "additionalProperties": true
          }
        }
      },
      "UnisoftRequest_f3635fecc6f75b85ba0f": {
        "type": "object",
        "properties": {
          "rows": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "phone": {
                  "type": "string",
                  "description": "Raw phone, e.g. \"06 12 34 56 78\"."
                },
                "email": {
                  "type": "string",
                  "description": "Raw email, e.g. \"David.Levy@GMAIL.com \"."
                },
                "birthDate": {
                  "type": "string",
                  "description": "Raw date of birth, e.g. \"15/03/1990\" (DD/MM/YYYY by default)."
                },
                "lastName": {
                  "type": "string"
                },
                "firstName": {
                  "type": "string"
                },
                "gender": {
                  "type": "string",
                  "description": "Raw civility/gender, e.g. \"Mme\", \"Mr\", \"מר\", \"M\", \"F\" → gender \"M\"/\"F\"."
                },
                "category": {
                  "type": "string",
                  "description": "Raw category tag, e.g. \"Séder night\" → SEDER_NIGHT."
                }
              },
              "additionalProperties": false
            },
            "description": "Each object holds the raw cell values of one spreadsheet row."
          },
          "defaultPhoneCountry": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country (e.g. \"FR\") to normalise local phones without a country code. Default \"ZZ\" (none)."
          },
          "dateFormat": {
            "type": "string",
            "description": "Hint for ambiguous dates (e.g. \"M/D/YYYY\" for US files). Dates are parsed with a date-parser, NEVER new Date(). Day-first (DD/MM/YYYY) by default."
          }
        },
        "required": [
          "rows"
        ],
        "additionalProperties": false,
        "description": "Rows of raw (dirty Excel/CSV) columns to normalise per-column. PURE — no database, no org data touched. Use this FIRST when importing a spreadsheet: it cleans phone→E.164 (+ detected country), email, birthDate→ISO, and civility→gender \"M\"/\"F\", and flags per-row `issues`."
      },
      "NormalizeResult": {
        "type": "object",
        "description": "Per-row normalisation result. Read `valid`/`country` per column to decide what to fix before importing.",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "rows": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "phone": {
                  "type": "object",
                  "properties": {
                    "input": {
                      "type": "string"
                    },
                    "e164": {
                      "type": "string",
                      "nullable": true
                    },
                    "national": {
                      "type": "string",
                      "nullable": true
                    },
                    "country": {
                      "type": "string",
                      "nullable": true
                    },
                    "valid": {
                      "type": "boolean"
                    }
                  }
                },
                "email": {
                  "type": "object",
                  "properties": {
                    "input": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string",
                      "nullable": true
                    },
                    "valid": {
                      "type": "boolean"
                    }
                  }
                },
                "birthDate": {
                  "type": "object",
                  "properties": {
                    "input": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string",
                      "nullable": true,
                      "description": "ISO date."
                    },
                    "valid": {
                      "type": "boolean"
                    }
                  }
                },
                "lastName": {
                  "type": "string",
                  "nullable": true
                },
                "firstName": {
                  "type": "string",
                  "nullable": true
                },
                "gender": {
                  "type": "string",
                  "enum": [
                    "M",
                    "F"
                  ],
                  "nullable": true,
                  "description": "Derived from the raw civility/gender column. null if unrecognised."
                },
                "civilityMatched": {
                  "type": "boolean",
                  "description": "Whether the raw civility/gender string was recognised."
                },
                "tags": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "Normalised category tags derived from the row."
                },
                "issues": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "field": {
                        "type": "string"
                      },
                      "reason": {
                        "type": "string"
                      },
                      "severity": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "LookupResult": {
        "type": "object",
        "description": "Batch lookup result. Each item reports the matched contact (if any) without any write.",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "matchedContactId": {
                  "type": "string",
                  "nullable": true
                },
                "matchedOn": {
                  "type": "string",
                  "nullable": true,
                  "description": "\"phone\" or \"email\"."
                },
                "matchedName": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "summary": {
            "type": "object",
            "properties": {
              "matched": {
                "type": "integer"
              },
              "unmatched": {
                "type": "integer"
              }
            }
          }
        }
      },
      "UnisoftRequest_7ef2b58154210ab6fbbe": {
        "type": "object",
        "properties": {
          "contacts": {
            "type": "array",
            "maxItems": 500,
            "items": {
              "$ref": "#/components/schemas/UnisoftRequest_7e027332669117995c44"
            },
            "description": "The rows to import (≤ 500). Each row supports the same public identity fields as ContactCreateInput (firstName/lastName/gender/email/phone/birthDate/tags/customFields/address…), plus an optional `__row` (the source spreadsheet row number, echoed back in the report)."
          },
          "options": {
            "type": "object",
            "properties": {
              "dedupStrategy": {
                "type": "string",
                "enum": [
                  "skip",
                  "update",
                  "create"
                ],
                "description": "On a match: skip (leave untouched), update (fill-if-empty, default), or create (always insert a new doc).",
                "default": "update"
              },
              "applyTags": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Category tags added to EVERY imported contact (normalised UPPERCASE)."
              },
              "defaultPhoneCountry": {
                "type": "string",
                "description": "ISO country to normalise local phones. Default \"ZZ\"."
              },
              "dateFormat": {
                "type": "string",
                "description": "Hint for ambiguous dates (e.g. \"M/D/YYYY\")."
              }
            },
            "additionalProperties": false,
            "description": "Import options."
          },
          "dryRun": {
            "type": "boolean",
            "description": "true = validate + plan only, NO write. Counters are PROJECTED; `report.lines` shows the action per row.",
            "default": false
          }
        },
        "required": [
          "contacts"
        ],
        "additionalProperties": false,
        "description": "Bulk upsert of up to 500 contacts (500+ → 400 IMPORT_TOO_LARGE; paginate). Set `dryRun:true` to get the per-line PLAN (action + issues) WITHOUT writing anything. Each row is normalised & validated like create_contact; a row with a blocking error is skipped (action:\"error\"). Call get_contact_import_schema first to learn the importable field keys and their aliases."
      },
      "UnisoftRequest_7e027332669117995c44": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "First name (stored capitalised)."
          },
          "lastName": {
            "type": "string",
            "description": "Last name / family name (stored UPPER-CASED)."
          },
          "gender": {
            "type": "string",
            "enum": [
              "M",
              "F",
              null
            ],
            "nullable": true,
            "description": "\"M\" (male), \"F\" (female) or null (unknown). Never a civility string like \"Mr\"/\"Mme\"."
          },
          "email": {
            "type": "string",
            "description": "Primary email. Invalid emails are dropped."
          },
          "phone": {
            "type": "string",
            "description": "Primary phone (any format; normalised to E.164). Provide `phoneCountry` for local numbers without a country code."
          },
          "phoneCountry": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code (e.g. \"FR\", \"IL\") used to normalise a local `phone`/`phones` without a `+` prefix."
          },
          "phones": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Additional (secondary) phones."
          },
          "emails": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Additional (secondary) emails."
          },
          "birthDate": {
            "type": "string",
            "maxLength": 100,
            "nullable": true
          },
          "hebrewFirstName": {
            "type": "string",
            "description": "Hebrew first name."
          },
          "taxId": {
            "type": "string",
            "description": "National / tax identifier (e.g. Israeli Teudat Zehut). Declarative."
          },
          "giftAid": {
            "type": "boolean",
            "description": "UK Gift Aid flag. Declarative."
          },
          "address": {
            "type": "string",
            "description": "Primary address supplied to the bulk-import owner. For matched contacts it can replace the current primary address; compare it before dryRun and application. This differs from create_contact fill-if-empty behaviour."
          },
          "postalCode": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "region": {
            "type": "string",
            "description": "State / region / province."
          },
          "country": {
            "type": "string",
            "description": "Country (default \"France\")."
          },
          "note": {
            "type": "string",
            "description": "Free note on the primary address."
          },
          "addresses": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "type": {
                  "type": "string",
                  "description": "PRO | PERSO"
                },
                "address": {
                  "type": "string"
                },
                "postalCode": {
                  "type": "string"
                },
                "city": {
                  "type": "string"
                },
                "region": {
                  "type": "string"
                },
                "country": {
                  "type": "string"
                },
                "companyId": {
                  "type": "string",
                  "description": "Company registration number (for a PRO address)."
                },
                "note": {
                  "type": "string"
                }
              },
              "additionalProperties": false
            },
            "description": "Extra SECONDARY addresses to add."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Category tags to attach (each normalised UPPERCASE). On CREATE the first tag is the seed tag; with none, the source tag `#API` is set."
          },
          "customFields": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "description": "Field key (case-insensitive, `_`↔`-` equivalent). Upsert-by-key: writing the same key twice updates the single existing field, never duplicates it."
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "TEXT",
                    "NUMBER",
                    "DATE",
                    "DATETIME",
                    "BOOL"
                  ],
                  "description": "TEXT | NUMBER | DATE | DATETIME | BOOL. NUMBER/DATETIME are stored as TEXT.",
                  "default": "TEXT"
                },
                "value": {
                  "description": "Field value (string / number / ISO date / boolean)."
                }
              },
              "required": [
                "key"
              ],
              "additionalProperties": false,
              "description": "A typed custom field. `type` is reduced to TEXT/DATE/BOOL on storage — NUMBER/SELECT/etc. are stored as TEXT (the round-trip value stays a string)."
            },
            "description": "Typed key/value custom fields (upsert-by-key). On create/import these are fill-if-empty (append-only). Distinct from `tags[]`."
          },
          "__row": {
            "oneOf": [
              {
                "type": "integer",
                "minimum": 1
              },
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              }
            ]
          }
        },
        "additionalProperties": false,
        "description": "Identity of a contact to CREATE or UPSERT. All fields optional — the smallest useful contact is a single `phone` or `email`. Formats: `gender` = \"M\" (male) or \"F\" (female) or null (unknown — NEVER \"Mr\"/\"Mme\"); `phone` accepts a dirty string (« 06 11 22 33 44 »), normalised to E.164; `birthDate` ISO `YYYY-MM-DD`; each `tags` entry is upper-cased/de-accented (« Donateur régulier » → « DONATEUR_REGULIER »). `tags` are boolean labels; `customFields` are typed key/value fields — do not confuse them."
      },
      "ImportResult": {
        "type": "object",
        "description": "Import outcome. Same shape for dry-run and real: in dry-run the counters are PROJECTED and nothing is written; `report.lines` is always present (the per-row plan).",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "report": {
            "type": "object",
            "properties": {
              "created": {
                "type": "integer",
                "description": "Contacts created (projected in dry-run)."
              },
              "updated": {
                "type": "integer",
                "description": "Contacts updated (projected in dry-run)."
              },
              "skipped": {
                "type": "integer",
                "description": "Rows skipped (matched + dedupStrategy skip)."
              },
              "errors": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "row": {
                      "description": "__row or index."
                    },
                    "reason": {
                      "description": "The blocking issues of that row."
                    }
                  }
                }
              },
              "warnings": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "row": {},
                    "reason": {
                      "type": "string"
                    }
                  }
                }
              },
              "lines": {
                "type": "array",
                "description": "One entry per input row (dry-run AND real).",
                "items": {
                  "type": "object",
                  "properties": {
                    "row": {
                      "description": "__row (if provided) or the 0-based index."
                    },
                    "action": {
                      "type": "string",
                      "enum": [
                        "create",
                        "update",
                        "skip",
                        "error"
                      ],
                      "description": "The planned/performed action. \"error\" = a blocking issue → not written."
                    },
                    "matchedContactId": {
                      "type": "string",
                      "nullable": true,
                      "description": "The existing contact detected by dedup (null = new)."
                    },
                    "issues": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "description": "The PUBLIC field of the issue (e.g. \"phone\", \"email\", \"birthDate\")."
                          },
                          "reason": {
                            "type": "string",
                            "description": "MISSING_IDENTITY | INVALID_PHONE | INVALID_EMAIL | INVALID_DATE | INVALID_BOOL | DUPLICATE_IN_BATCH | UNKNOWN_RELATIONSHIP."
                          },
                          "severity": {
                            "type": "string",
                            "enum": [
                              "error",
                              "warning"
                            ],
                            "description": "error blocks the write; warning does not."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "UnisoftRequest_731434cf8427fd36cfcb": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "Overwrites the first name (capitalised). \"\" = leave untouched."
          },
          "lastName": {
            "type": "string",
            "description": "Overwrites the last name (upper-cased). \"\" = leave untouched."
          },
          "gender": {
            "type": "string",
            "enum": [
              "M",
              "F",
              null
            ],
            "nullable": true,
            "description": "\"M\" (male), \"F\" (female) or null (unknown)."
          },
          "email": {
            "type": "string",
            "description": "Overwrites the primary email (must be valid → 400 INVALID_EMAIL)."
          },
          "phone": {
            "type": "string",
            "description": "Overwrites the primary phone (E.164; 400 INVALID_PHONE if unparseable)."
          },
          "phoneCountry": {
            "type": "string",
            "description": "ISO country to normalise a local `phone`."
          },
          "birthDate": {
            "type": "string",
            "format": "date",
            "description": "Overwrites date of birth (ISO). 400 INVALID_DATE if unparseable."
          },
          "hebrewFirstName": {
            "type": "string",
            "description": "Overwrites the Hebrew first name."
          },
          "taxId": {
            "type": "string",
            "description": "Overwrites the national / tax identifier (Teudat Zehut)."
          },
          "giftAid": {
            "type": "boolean",
            "description": "Overwrites the UK Gift Aid flag."
          },
          "address": {
            "type": "string",
            "description": "Overwrites the PRIMARY address (street)."
          },
          "postalCode": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "region": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "note": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "description": "Identity fields to OVERRIDE on an existing contact (explicit edit — replaces the stored value, unlike the fill-if-empty create/upsert). Sub-collections (secondary phones / emails / addresses / tags / custom fields) are NOT touched here — use the dedicated sub-resource endpoints. An empty string (\"\") means « leave untouched » (append-only: identity is never erased). Same formats as ContactCreateInput."
      },
      "UnisoftRequest_b743641a58b8fd5cb226": {
        "type": "object",
        "properties": {
          "customFields": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "description": "Field key (case-insensitive, `_`↔`-` equivalent). Upsert-by-key: writing the same key twice updates the single existing field, never duplicates it."
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "TEXT",
                    "NUMBER",
                    "DATE",
                    "DATETIME",
                    "BOOL"
                  ],
                  "description": "TEXT | NUMBER | DATE | DATETIME | BOOL. NUMBER/DATETIME are stored as TEXT.",
                  "default": "TEXT"
                },
                "value": {
                  "description": "Field value (string / number / ISO date / boolean)."
                }
              },
              "required": [
                "key"
              ],
              "additionalProperties": false,
              "description": "A typed custom field. `type` is reduced to TEXT/DATE/BOOL on storage — NUMBER/SELECT/etc. are stored as TEXT (the round-trip value stays a string)."
            },
            "description": "The fields to set (upsert-by-key, never duplicated)."
          },
          "override": {
            "type": "boolean",
            "description": "true (default) overwrites an existing value; false only fills empty fields.",
            "default": true
          }
        },
        "required": [
          "customFields"
        ],
        "additionalProperties": false,
        "description": "Typed key/value custom fields to upsert-by-key. `override` (default true here — an explicit edit) overwrites the stored value; set it false to only fill empty fields. `type` reduced to TEXT/DATE/BOOL (NUMBER/DATETIME stored as TEXT). Distinct from category tags."
      },
      "ContactInteraction": {
        "type": "object",
        "description": "A logged touchpoint with the contact (a call, a visit, a note). Read projection of a `contact_activity` document.",
        "properties": {
          "id": {
            "type": "string",
            "readOnly": true
          },
          "type": {
            "type": "string",
            "description": "Kind of interaction, e.g. « Appel », « Visite »."
          },
          "content": {
            "type": "string",
            "description": "Free-text notes."
          },
          "actions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional string tags describing what was done."
          },
          "author": {
            "type": "string",
            "nullable": true,
            "readOnly": true,
            "description": "Name of the staff author when the entry came from the admin/copilot; null for API-created entries."
          },
          "datetime": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          }
        }
      },
      "ContactDocument": {
        "type": "object",
        "description": "A file attached to the contact (a receipt, an ID scan, a signed mandate…). Read projection of a `contact.docs[]` sub-document.",
        "properties": {
          "id": {
            "type": "string",
            "readOnly": true,
            "description": "Document id (UUID) — pass it to DELETE /contacts/{id}/documents/{docId}."
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Human label (defaults to the filename if none was given)."
          },
          "filename": {
            "type": "string",
            "nullable": true,
            "readOnly": true,
            "description": "Hosted filename (md5.ext). Reusable to attach the SAME file elsewhere without re-uploading."
          },
          "url": {
            "type": "string",
            "nullable": true,
            "readOnly": true,
            "description": "Absolute URL to download the file."
          },
          "uploadedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "readOnly": true
          }
        }
      },
      "ChlihoutSettingsResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ChlihoutSettings"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ChlihoutSettings": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "revision": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740990
          },
          "types": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 80,
                  "pattern": "^[A-Z][A-Z0-9_-]*$"
                },
                "label": {
                  "type": "string",
                  "maxLength": 100
                },
                "enabled": {
                  "type": "boolean"
                }
              },
              "required": [
                "id",
                "label",
                "enabled"
              ]
            }
          },
          "levels": {
            "type": "array",
            "minItems": 2,
            "maxItems": 30,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "value": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100
                },
                "label": {
                  "type": "string",
                  "maxLength": 100
                },
                "enabled": {
                  "type": "boolean"
                }
              },
              "required": [
                "value",
                "label",
                "enabled"
              ]
            }
          }
        },
        "required": [
          "revision",
          "types",
          "levels"
        ]
      },
      "ContactMergePreviewResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactMergePreview"
          }
        }
      },
      "ContactMergePreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "survivor",
          "absorbed",
          "merged",
          "revision",
          "effects",
          "physicalDeletionOfAbsorbed",
          "financialAmountsChanged",
          "historicalSnapshotsRewritten",
          "precedence",
          "effectsDeferred",
          "choicesAvailable",
          "atomicAcrossInternalWriters"
        ],
        "properties": {
          "survivor": {
            "$ref": "#/components/schemas/ContactMergeProfile"
          },
          "absorbed": {
            "$ref": "#/components/schemas/ContactMergeProfile"
          },
          "merged": {
            "$ref": "#/components/schemas/ContactMergeProfile"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "effects": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "domain",
                "records",
                "action"
              ],
              "properties": {
                "domain": {
                  "type": "string",
                  "enum": [
                    "paiements",
                    "dettes_v2",
                    "rappel",
                    "forms_submit"
                  ]
                },
                "records": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 2000
                },
                "action": {
                  "type": "string",
                  "enum": [
                    "REASSIGN_CONTACT"
                  ]
                }
              }
            }
          },
          "physicalDeletionOfAbsorbed": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "financialAmountsChanged": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "historicalSnapshotsRewritten": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "precedence": {
            "type": "string",
            "enum": [
              "SURVIVOR_PRESENT_SCALARS_SOURCE_OBJECT_OVERLAY_ARRAY_UNION_NATIVE"
            ]
          },
          "effectsDeferred": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "choicesAvailable": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "atomicAcrossInternalWriters": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "ContactMergeProfile": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactId",
          "firstName",
          "lastName",
          "email",
          "phone",
          "gender",
          "categories",
          "secondaryEmails",
          "secondaryPhones",
          "primaryAddress"
        ],
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "firstName": {
            "type": "string",
            "maxLength": 1000,
            "nullable": true
          },
          "lastName": {
            "type": "string",
            "maxLength": 1000,
            "nullable": true
          },
          "email": {
            "type": "string",
            "maxLength": 1000,
            "nullable": true
          },
          "phone": {
            "type": "string",
            "maxLength": 1000,
            "nullable": true
          },
          "gender": {
            "type": "string",
            "nullable": true,
            "enum": [
              "M",
              "F",
              null
            ]
          },
          "categories": {
            "type": "array",
            "maxItems": 2000,
            "items": {
              "type": "string",
              "maxLength": 1000
            }
          },
          "secondaryEmails": {
            "type": "array",
            "maxItems": 2000,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "value",
                "label"
              ],
              "properties": {
                "value": {
                  "type": "string",
                  "maxLength": 1000
                },
                "label": {
                  "type": "string",
                  "maxLength": 1000,
                  "nullable": true
                }
              }
            }
          },
          "secondaryPhones": {
            "type": "array",
            "maxItems": 2000,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "value",
                "label"
              ],
              "properties": {
                "value": {
                  "type": "string",
                  "maxLength": 1000
                },
                "label": {
                  "type": "string",
                  "maxLength": 1000,
                  "nullable": true
                }
              }
            }
          },
          "primaryAddress": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "line",
              "postalCode",
              "city",
              "state",
              "country"
            ],
            "properties": {
              "line": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              },
              "postalCode": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              },
              "city": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              },
              "state": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              },
              "country": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              }
            }
          }
        }
      },
      "ContactMergeError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      },
      "ContactMergeReceiptResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactMergeReceipt"
          }
        }
      },
      "ContactMergeReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "survivorId",
          "absorbedId",
          "nativeOperationId",
          "state",
          "effects",
          "effectsDeferred",
          "canRetry",
          "error",
          "lockCleanup",
          "atomicAcrossInternalWriters"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "survivorId": {
            "type": "string",
            "format": "uuid"
          },
          "absorbedId": {
            "type": "string",
            "format": "uuid"
          },
          "nativeOperationId": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "ADMITTING",
              "RUNNING",
              "APPLIED_PENDING_EFFECTS",
              "REJECTED",
              "UNKNOWN"
            ]
          },
          "effects": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "domain",
                "records",
                "action"
              ],
              "properties": {
                "domain": {
                  "type": "string",
                  "enum": [
                    "paiements",
                    "dettes_v2",
                    "rappel",
                    "forms_submit"
                  ]
                },
                "records": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 2000
                },
                "action": {
                  "type": "string",
                  "enum": [
                    "REASSIGN_CONTACT"
                  ]
                }
              }
            }
          },
          "effectsDeferred": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "canRetry": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "lockCleanup": {
            "type": "string",
            "enum": [
              "NOT_ATTEMPTED",
              "RELEASED",
              "RETAINED",
              "UNKNOWN"
            ]
          },
          "atomicAcrossInternalWriters": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "ContactNotesReadResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactNotesRead"
          }
        }
      },
      "ContactNotesRead": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactId",
          "revision",
          "content",
          "present"
        ],
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "content": {
            "type": "string",
            "nullable": true,
            "maxLength": 20000
          },
          "present": {
            "type": "boolean"
          }
        }
      },
      "ContactInteractionsError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      },
      "ContactInteractionCommandResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactInteractionCommandReceipt"
          }
        }
      },
      "ContactInteractionCommandReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "contactId",
          "kind",
          "resourceId",
          "state",
          "canRetry",
          "error",
          "revision",
          "startedAt",
          "finishedAt"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "NOTE",
              "INTERACTION",
              "ATTACHMENT"
            ]
          },
          "resourceId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "state": {
            "type": "string",
            "enum": [
              "ADMITTING",
              "RUNNING",
              "APPLIED",
              "NO_CHANGE",
              "REJECTED",
              "CONFLICT",
              "UNKNOWN"
            ]
          },
          "canRetry": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "nullable": true
          },
          "startedAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          },
          "finishedAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          }
        }
      },
      "ContactInteractionReadResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactInteractionRead"
          }
        }
      },
      "ContactInteractionRead": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactId",
          "id",
          "revision",
          "type",
          "content",
          "actions",
          "address",
          "time"
        ],
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "type": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "content": {
            "type": "string",
            "nullable": true,
            "maxLength": 20000
          },
          "actions": {
            "type": "array",
            "nullable": true,
            "maxItems": 50,
            "items": {
              "type": "string",
              "maxLength": 100
            }
          },
          "address": {
            "type": "string",
            "nullable": true,
            "maxLength": 2000
          },
          "time": {
            "$ref": "#/components/schemas/ContactInteractionTime"
          }
        }
      },
      "ContactInteractionTime": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "precision",
          "occurredOn",
          "datetime"
        ],
        "properties": {
          "precision": {
            "type": "string",
            "enum": [
              "DAY",
              "INSTANT",
              "UNKNOWN"
            ]
          },
          "occurredOn": {
            "type": "string",
            "nullable": true,
            "format": "date"
          },
          "datetime": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          }
        }
      },
      "UnisoftRequest_4b1a347f28ed132dbea4": {
        "type": "object",
        "properties": {
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$"
          },
          "changes": {
            "type": "object",
            "minProperties": 1,
            "properties": {
              "type": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "content": {
                "type": "string",
                "maxLength": 20000
              },
              "actions": {
                "type": "array",
                "maxItems": 50,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 100
                }
              },
              "address": {
                "type": "string",
                "maxLength": 2000
              },
              "occurredOn": {
                "type": "string",
                "pattern": "^(?!0000)\\d{4}-\\d{2}-\\d{2}$",
                "format": "date"
              },
              "datetime": {
                "type": "string",
                "pattern": "^(?!0000)\\d{4}-\\d{2}-\\d{2}T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?(?:Z|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$",
                "format": "date-time"
              }
            },
            "additionalProperties": false,
            "not": {
              "required": [
                "occurredOn",
                "datetime"
              ]
            }
          }
        },
        "required": [
          "expectedRevision",
          "idempotencyKey",
          "changes"
        ],
        "additionalProperties": false
      },
      "ContactAttachmentsReadResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactAttachmentList"
          }
        }
      },
      "ContactAttachmentList": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactId",
          "revision",
          "scope",
          "data"
        ],
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "scope": {
            "type": "string",
            "enum": [
              "CONTACT"
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactAttachmentRead"
            }
          }
        }
      },
      "ContactAttachmentRead": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "name",
          "filename",
          "recordedAt",
          "availability"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "maxLength": 200
          },
          "filename": {
            "type": "string",
            "nullable": true,
            "maxLength": 200
          },
          "recordedAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          },
          "availability": {
            "type": "string",
            "enum": [
              "AVAILABLE",
              "UNAVAILABLE"
            ]
          }
        }
      },
      "UnisoftRequest_891c98c82ce4abde0764": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "expectedRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "idempotencyKey": {
                "type": "string",
                "minLength": 8,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$"
              },
              "action": {
                "type": "string",
                "enum": [
                  "ADD"
                ]
              },
              "filename": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "pattern": "^(?!.*\\.\\.)[A-Za-z0-9][A-Za-z0-9._-]*\\.[A-Za-z0-9]+$"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              }
            },
            "required": [
              "expectedRevision",
              "idempotencyKey",
              "action",
              "filename"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "expectedRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "idempotencyKey": {
                "type": "string",
                "minLength": 8,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$"
              },
              "action": {
                "type": "string",
                "enum": [
                  "EDIT"
                ]
              },
              "documentId": {
                "type": "string",
                "format": "uuid"
              },
              "filename": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "pattern": "^(?!.*\\.\\.)[A-Za-z0-9][A-Za-z0-9._-]*\\.[A-Za-z0-9]+$"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              }
            },
            "required": [
              "expectedRevision",
              "idempotencyKey",
              "action",
              "documentId"
            ],
            "additionalProperties": false,
            "anyOf": [
              {
                "required": [
                  "filename"
                ]
              },
              {
                "required": [
                  "name"
                ]
              }
            ]
          },
          {
            "type": "object",
            "properties": {
              "expectedRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "idempotencyKey": {
                "type": "string",
                "minLength": 8,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$"
              },
              "action": {
                "type": "string",
                "enum": [
                  "DETACH"
                ]
              },
              "documentId": {
                "type": "string",
                "format": "uuid"
              }
            },
            "required": [
              "expectedRevision",
              "idempotencyKey",
              "action",
              "documentId"
            ],
            "additionalProperties": false
          }
        ]
      },
      "ContactSyncConnectionResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactSyncConnection"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactSyncMeta"
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ContactSyncConnection": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "CONNECTED",
              "NEEDS_REAUTH",
              "DISCONNECTED",
              null
            ],
            "nullable": true
          },
          "revision": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          },
          "configuration": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "fields": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "type": "string",
                  "enum": [
                    "name",
                    "email",
                    "phone",
                    "address",
                    "birthday",
                    "otherNames",
                    "company",
                    "jobTitle",
                    "department",
                    "occupation",
                    "websites",
                    "notes",
                    "photo",
                    "events",
                    "relations",
                    "labels",
                    "custom"
                  ]
                }
              },
              "groupIds": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "type": "string",
                  "pattern": "^contactGroups/[\\w-]+$"
                }
              },
              "coordinates": {
                "type": "string",
                "enum": [
                  "primary",
                  "all"
                ]
              },
              "policy": {
                "type": "string",
                "enum": [
                  "fill",
                  "replace"
                ]
              },
              "country": {
                "type": "string",
                "pattern": "^[A-Z]{2}$"
              },
              "fieldPolicies": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "field": {
                      "type": "string",
                      "enum": [
                        "name",
                        "email",
                        "phone",
                        "address",
                        "birthday",
                        "otherNames",
                        "company",
                        "jobTitle",
                        "department",
                        "occupation",
                        "websites",
                        "notes",
                        "photo",
                        "events",
                        "relations",
                        "labels",
                        "custom"
                      ]
                    },
                    "policy": {
                      "type": "string",
                      "enum": [
                        "fill",
                        "replace"
                      ]
                    }
                  },
                  "required": [
                    "field",
                    "policy"
                  ]
                }
              },
              "valueModes": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "field": {
                      "type": "string",
                      "enum": [
                        "email",
                        "phone",
                        "address"
                      ]
                    },
                    "mode": {
                      "type": "string",
                      "enum": [
                        "primary",
                        "all"
                      ]
                    }
                  },
                  "required": [
                    "field",
                    "mode"
                  ]
                }
              },
              "destinations": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "field": {
                      "type": "string"
                    },
                    "key": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 100
                    }
                  },
                  "required": [
                    "field",
                    "key"
                  ]
                }
              },
              "labels": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "groupId": {
                      "type": "string"
                    },
                    "tag": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 100
                    }
                  },
                  "required": [
                    "groupId",
                    "tag"
                  ]
                }
              },
              "customFields": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "source": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 100
                    },
                    "key": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 100
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "TEXT",
                        "NUMBER",
                        "BOOL",
                        "DATE"
                      ]
                    }
                  },
                  "required": [
                    "source",
                    "key",
                    "type"
                  ]
                }
              }
            },
            "required": [
              "fields",
              "groupIds",
              "coordinates",
              "policy",
              "country",
              "fieldPolicies",
              "valueModes",
              "destinations",
              "labels",
              "customFields"
            ],
            "nullable": true
          },
          "configurationState": {
            "type": "string",
            "enum": [
              "VALID_STORED_CONFIGURATION",
              "UNAVAILABLE_OR_INVALID"
            ]
          },
          "scheduleEnabled": {
            "type": "boolean",
            "nullable": true
          },
          "hasImported": {
            "type": "boolean",
            "nullable": true
          },
          "lastRunAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "lastRunState": {
            "type": "string",
            "enum": [
              "QUEUED",
              "PREPARING",
              "REVIEW_READY",
              "RUNNING",
              "SUCCEEDED",
              "PARTIAL",
              "FAILED",
              "STOPPED",
              null
            ],
            "nullable": true
          },
          "lastRunStats": {
            "$ref": "#/components/schemas/ContactSyncStats"
          }
        },
        "required": [
          "id",
          "status",
          "revision",
          "configuration",
          "configurationState",
          "scheduleEnabled",
          "hasImported",
          "lastRunAt",
          "lastRunState",
          "lastRunStats"
        ]
      },
      "ContactSyncStats": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "loaded": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          },
          "created": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          },
          "updated": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          },
          "skipped": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          },
          "review": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          },
          "failed": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          },
          "pending": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          }
        },
        "required": [
          "loaded",
          "created",
          "updated",
          "skipped",
          "review",
          "failed",
          "pending"
        ]
      },
      "ContactSyncMeta": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "maximum": 5000
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "readAt": {
            "type": "string",
            "format": "date-time"
          },
          "consistentSnapshot": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "providerChecked": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "workerReadiness": {
            "type": "boolean",
            "enum": [
              null
            ],
            "nullable": true
          },
          "completeHistory": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "order": {
            "type": "string",
            "enum": [
              "ID_ASC",
              "CREATED_AT_DESC_UNDATED_LAST_ID_ASC",
              "ROW_INDEX_ASC_ID_ASC"
            ]
          }
        },
        "required": [
          "count",
          "total",
          "hasMore",
          "nextCursor",
          "readAt",
          "consistentSnapshot",
          "providerChecked",
          "workerReadiness",
          "completeHistory",
          "order"
        ]
      },
      "ContactSyncError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactSyncRunResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactSyncRun"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactSyncMeta"
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ContactSyncRun": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "connectionId": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "PREVIEW",
              "IMPORT",
              null
            ],
            "nullable": true
          },
          "state": {
            "type": "string",
            "enum": [
              "QUEUED",
              "PREPARING",
              "REVIEW_READY",
              "RUNNING",
              "SUCCEEDED",
              "PARTIAL",
              "FAILED",
              "STOPPED",
              null
            ],
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "automatic": {
            "type": "boolean",
            "nullable": true
          },
          "revision": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          },
          "stats": {
            "$ref": "#/components/schemas/ContactSyncStats"
          },
          "errorCode": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "id",
          "connectionId",
          "kind",
          "state",
          "createdAt",
          "finishedAt",
          "automatic",
          "revision",
          "stats",
          "errorCode"
        ]
      },
      "ContactSyncConflictResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactSyncConflict"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactSyncMeta"
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ContactSyncConflict": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "rowId": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "index": {
            "type": "integer",
            "minimum": 0
          },
          "state": {
            "type": "string",
            "enum": [
              "PENDING",
              "REVIEW",
              "CREATED",
              "UPDATED",
              "SKIPPED",
              "FAILED",
              null
            ],
            "nullable": true
          },
          "resolutionKind": {
            "type": "string",
            "enum": [
              "CREATE",
              "LINK",
              "REVIEW",
              null
            ],
            "nullable": true
          },
          "reasonCode": {
            "type": "string",
            "nullable": true
          },
          "decisionAction": {
            "type": "string",
            "enum": [
              "CREATE",
              "LINK",
              "IGNORE",
              null
            ],
            "nullable": true
          },
          "errorCode": {
            "type": "string",
            "nullable": true
          },
          "requiresHumanReview": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "canDecide": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "rowId",
          "index",
          "state",
          "resolutionKind",
          "reasonCode",
          "decisionAction",
          "errorCode",
          "requiresHumanReview",
          "canDecide"
        ]
      },
      "ContactCommunicationPreferencesResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactCommunicationPreferences"
          }
        }
      },
      "ContactCommunicationPreferences": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactId",
          "revision",
          "observedAt",
          "snapshotGuaranteed",
          "email",
          "sms",
          "whatsapp",
          "optInAvailable"
        ],
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "observedAt": {
            "type": "string",
            "format": "date-time"
          },
          "snapshotGuaranteed": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "email": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "address",
              "optOut",
              "sharedPolicyOptOut",
              "historicalEmailRefusal",
              "legacyOptOut",
              "optOutAvailable",
              "affects"
            ],
            "properties": {
              "address": {
                "type": "string",
                "format": "email",
                "maxLength": 320,
                "nullable": true
              },
              "optOut": {
                "type": "string",
                "enum": [
                  "RECORDED",
                  "NOT_RECORDED",
                  "ADDRESS_UNAVAILABLE"
                ]
              },
              "sharedPolicyOptOut": {
                "type": "boolean",
                "nullable": true
              },
              "historicalEmailRefusal": {
                "type": "boolean",
                "nullable": true
              },
              "legacyOptOut": {
                "type": "boolean",
                "nullable": true
              },
              "optOutAvailable": {
                "type": "boolean"
              },
              "affects": {
                "type": "string",
                "enum": [
                  "ORGANISATION_EMAIL_ADDRESS"
                ]
              }
            }
          },
          "sms": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "optOut",
              "optOutAvailable",
              "reason"
            ],
            "properties": {
              "optOut": {
                "type": "string",
                "enum": [
                  "UNKNOWN"
                ]
              },
              "optOutAvailable": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "reason": {
                "type": "string",
                "enum": [
                  "NO_CANONICAL_OPTOUT_OWNER"
                ]
              }
            }
          },
          "whatsapp": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "optOut",
              "optOutAvailable",
              "reason"
            ],
            "properties": {
              "optOut": {
                "type": "string",
                "enum": [
                  "UNKNOWN"
                ]
              },
              "optOutAvailable": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "reason": {
                "type": "string",
                "enum": [
                  "NO_CANONICAL_OPTOUT_OWNER"
                ]
              }
            }
          },
          "optInAvailable": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "ContactCommunicationPreferenceReceiptResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactCommunicationPreferenceReceipt"
          }
        }
      },
      "ContactCommunicationPreferenceReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "contactId",
          "channel",
          "address",
          "state",
          "ownerInvocationPossible",
          "sharedPolicyVerified",
          "legacyVerified",
          "canRetry",
          "error",
          "startedAt",
          "finishedAt",
          "affects",
          "queuedMessagesCancelled",
          "providerChecked"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "channel": {
            "type": "string",
            "enum": [
              "EMAIL"
            ]
          },
          "address": {
            "type": "string",
            "format": "email",
            "maxLength": 320
          },
          "state": {
            "type": "string",
            "enum": [
              "ADMITTING",
              "RUNNING",
              "COMPLETED",
              "REJECTED",
              "PARTIAL",
              "UNKNOWN"
            ]
          },
          "ownerInvocationPossible": {
            "type": "boolean"
          },
          "sharedPolicyVerified": {
            "type": "boolean",
            "nullable": true
          },
          "legacyVerified": {
            "type": "boolean",
            "nullable": true
          },
          "canRetry": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "nullable": true,
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          },
          "startedAt": {
            "type": "string",
            "format": "date-time"
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "affects": {
            "type": "string",
            "enum": [
              "ORGANISATION_EMAIL_ADDRESS"
            ]
          },
          "queuedMessagesCancelled": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "providerChecked": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "ContactDiscoveryResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactDiscoveryContact"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactDiscoveryMeta"
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ContactDiscoveryContact": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "firstName": {
            "type": "string",
            "nullable": true
          },
          "lastName": {
            "type": "string",
            "nullable": true
          },
          "email": {
            "type": "string",
            "nullable": true
          },
          "phone": {
            "type": "string",
            "nullable": true
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 400,
              "pattern": "^[^\\u0000]+$"
            }
          },
          "archived": {
            "type": "boolean",
            "nullable": true
          },
          "deceased": {
            "type": "boolean",
            "nullable": true
          },
          "isNew": {
            "type": "boolean",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "id",
          "firstName",
          "lastName",
          "email",
          "phone",
          "tags",
          "archived",
          "deceased",
          "isNew",
          "updatedAt"
        ]
      },
      "ContactDiscoveryMeta": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "order": {
            "type": "string",
            "enum": [
              "ID_ASC"
            ]
          },
          "readAt": {
            "type": "string",
            "format": "date-time"
          },
          "listComputedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "consistentSnapshot": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "count",
          "hasMore",
          "nextCursor",
          "order",
          "readAt",
          "listComputedAt",
          "consistentSnapshot"
        ]
      },
      "ContactPoleRuleStateResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactPoleCategoryRules"
          }
        }
      },
      "ContactPoleCategoryRules": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "poleId",
          "label",
          "tags",
          "configured",
          "revision",
          "membershipMode",
          "manualMembershipEditable",
          "projectionRefreshed"
        ],
        "properties": {
          "poleId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "label": {
            "type": "string",
            "maxLength": 2000,
            "nullable": true
          },
          "tags": {
            "type": "array",
            "maxItems": 500,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          "configured": {
            "type": "boolean"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "membershipMode": {
            "type": "string",
            "enum": [
              "DERIVED_ANY_TAG_PLUS_BUSINESS_SOURCES"
            ]
          },
          "manualMembershipEditable": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "projectionRefreshed": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "ContactPoleRuleReceiptResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactPoleRuleReceipt"
          }
        }
      },
      "ContactPoleRuleReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "poleId",
          "state",
          "canRetry",
          "error",
          "appliedTags",
          "projectionRefreshed",
          "staffWhitelistChanged",
          "manualMembershipWritten",
          "startedAt",
          "finishedAt"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "poleId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "state": {
            "type": "string",
            "enum": [
              "ADMITTING",
              "RUNNING",
              "APPLIED",
              "NO_CHANGE",
              "REJECTED",
              "CONFLICT",
              "UNKNOWN"
            ]
          },
          "canRetry": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "appliedTags": {
            "type": "array",
            "maxItems": 500,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            },
            "nullable": true
          },
          "projectionRefreshed": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "staffWhitelistChanged": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "manualMembershipWritten": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "ContactHouseholdCapabilities": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "resource",
          "actions",
          "roles",
          "relationshipScope",
          "accountAccessGranted",
          "financialEffects"
        ],
        "properties": {
          "resource": {
            "type": "string",
            "enum": [
              "CRM_HOUSEHOLD"
            ]
          },
          "actions": {
            "type": "array",
            "minItems": 6,
            "maxItems": 6,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "ADD_MEMBER",
                "REMOVE_MEMBER",
                "SET_HEAD",
                "RENAME",
                "ADD_RELATION",
                "REMOVE_RELATION"
              ]
            }
          },
          "roles": {
            "type": "array",
            "minItems": 2,
            "maxItems": 2,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "HEAD",
                "MEMBER"
              ]
            }
          },
          "relationshipScope": {
            "type": "string",
            "enum": [
              "CURRENT_HOUSEHOLD_MEMBERS_ONLY"
            ]
          },
          "accountAccessGranted": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "financialEffects": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "ContactHouseholdSummary": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "ContactHousehold": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "name",
          "displayName",
          "revision",
          "recordedHeadContactId",
          "headContactId",
          "headState",
          "members",
          "relationshipScope",
          "relationships"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "displayName": {
            "type": "string"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "recordedHeadContactId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "headContactId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "headState": {
            "type": "string",
            "enum": [
              "UNASSIGNED",
              "MEMBER",
              "NOT_A_MEMBER"
            ]
          },
          "members": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/ContactHouseholdMember"
            }
          },
          "relationshipScope": {
            "type": "string",
            "enum": [
              "CURRENT_HOUSEHOLD_MEMBERS_ONLY"
            ]
          },
          "relationships": {
            "type": "array",
            "maxItems": 1000,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "sourceContactId",
                "relatedContactId",
                "relationship"
              ],
              "properties": {
                "sourceContactId": {
                  "type": "string",
                  "format": "uuid"
                },
                "relatedContactId": {
                  "type": "string",
                  "format": "uuid"
                },
                "relationship": {
                  "type": "string",
                  "enum": [
                    "SPOUSE",
                    "PARENT",
                    "CHILD",
                    "SIBLING",
                    "GRANDPARENT",
                    "GRANDCHILD",
                    "IN_LAW",
                    "EX",
                    "COUSIN",
                    "FRIEND"
                  ]
                }
              }
            }
          }
        }
      },
      "ContactHouseholdMember": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "firstName",
          "lastName",
          "revision",
          "isGlobalFamilyHead",
          "role",
          "legacyParentContactIds"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "firstName": {
            "type": "string",
            "nullable": true
          },
          "lastName": {
            "type": "string",
            "nullable": true
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "isGlobalFamilyHead": {
            "type": "boolean",
            "nullable": true
          },
          "role": {
            "type": "string",
            "enum": [
              "HEAD",
              "MEMBER"
            ]
          },
          "legacyParentContactIds": {
            "type": "array",
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          }
        }
      },
      "ContactHouseholdContactMemberships": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactId",
          "contactRevision",
          "households"
        ],
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "contactRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "households": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/ContactHouseholdSummary"
            }
          }
        }
      },
      "UnisoftRequest_f10a365c7bd580a11747": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "idempotencyKey": {
                "type": "string",
                "format": "uuid"
              },
              "expectedRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "action": {
                "type": "string",
                "enum": [
                  "ADD_MEMBER"
                ]
              },
              "contactId": {
                "type": "string",
                "format": "uuid"
              },
              "expectedContactRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              }
            },
            "required": [
              "idempotencyKey",
              "expectedRevision",
              "action",
              "contactId",
              "expectedContactRevision"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "idempotencyKey": {
                "type": "string",
                "format": "uuid"
              },
              "expectedRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "action": {
                "type": "string",
                "enum": [
                  "REMOVE_MEMBER"
                ]
              },
              "contactId": {
                "type": "string",
                "format": "uuid"
              },
              "expectedContactRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              }
            },
            "required": [
              "idempotencyKey",
              "expectedRevision",
              "action",
              "contactId",
              "expectedContactRevision"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "idempotencyKey": {
                "type": "string",
                "format": "uuid"
              },
              "expectedRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "action": {
                "type": "string",
                "enum": [
                  "SET_HEAD"
                ]
              },
              "contactId": {
                "type": "string",
                "format": "uuid",
                "nullable": true
              }
            },
            "required": [
              "idempotencyKey",
              "expectedRevision",
              "action",
              "contactId"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "idempotencyKey": {
                "type": "string",
                "format": "uuid"
              },
              "expectedRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "action": {
                "type": "string",
                "enum": [
                  "RENAME"
                ]
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 250
              }
            },
            "required": [
              "idempotencyKey",
              "expectedRevision",
              "action",
              "name"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "idempotencyKey": {
                "type": "string",
                "format": "uuid"
              },
              "expectedRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "action": {
                "type": "string",
                "enum": [
                  "ADD_RELATION"
                ]
              },
              "sourceContactId": {
                "type": "string",
                "format": "uuid"
              },
              "relatedContactId": {
                "type": "string",
                "format": "uuid"
              },
              "relationship": {
                "type": "string",
                "enum": [
                  "SPOUSE",
                  "PARENT",
                  "CHILD",
                  "SIBLING",
                  "GRANDPARENT",
                  "GRANDCHILD",
                  "IN_LAW",
                  "EX",
                  "COUSIN",
                  "FRIEND"
                ]
              }
            },
            "required": [
              "idempotencyKey",
              "expectedRevision",
              "action",
              "sourceContactId",
              "relatedContactId",
              "relationship"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "idempotencyKey": {
                "type": "string",
                "format": "uuid"
              },
              "expectedRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "action": {
                "type": "string",
                "enum": [
                  "REMOVE_RELATION"
                ]
              },
              "sourceContactId": {
                "type": "string",
                "format": "uuid"
              },
              "relatedContactId": {
                "type": "string",
                "format": "uuid"
              },
              "relationship": {
                "type": "string",
                "enum": [
                  "SPOUSE",
                  "PARENT",
                  "CHILD",
                  "SIBLING",
                  "GRANDPARENT",
                  "GRANDCHILD",
                  "IN_LAW",
                  "EX",
                  "COUSIN",
                  "FRIEND"
                ]
              }
            },
            "required": [
              "idempotencyKey",
              "expectedRevision",
              "action",
              "sourceContactId",
              "relatedContactId",
              "relationship"
            ],
            "additionalProperties": false
          }
        ]
      },
      "ContactHouseholdCommandResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "householdId",
          "action",
          "status",
          "reason",
          "resultRevision",
          "concurrentInternalChangesPossible",
          "nativeHouseholdIds",
          "household"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "householdId": {
            "type": "string",
            "format": "uuid"
          },
          "action": {
            "type": "string",
            "enum": [
              "ADD_MEMBER",
              "REMOVE_MEMBER",
              "SET_HEAD",
              "RENAME",
              "ADD_RELATION",
              "REMOVE_RELATION"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "APPLIED",
              "NOT_APPLIED",
              "UNKNOWN"
            ]
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "resultRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "nullable": true
          },
          "concurrentInternalChangesPossible": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "nativeHouseholdIds": {
            "type": "array",
            "maxItems": 2,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "household": {
            "$ref": "#/components/schemas/ContactHousehold"
          }
        }
      },
      "UnisoftRequest_16f9ab52d2cb23a5f8eb": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
          },
          "contacts": {
            "type": "array",
            "minItems": 1,
            "maxItems": 2000,
            "items": {
              "$ref": "#/components/schemas/UnisoftRequest_7e027332669117995c44"
            }
          },
          "options": {
            "type": "object",
            "properties": {
              "dedupStrategy": {
                "type": "string",
                "enum": [
                  "skip",
                  "update",
                  "create"
                ],
                "description": "On a match: skip (leave untouched), update (fill-if-empty, default), or create (always insert a new doc).",
                "default": "update"
              },
              "applyTags": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Category tags added to EVERY imported contact (normalised UPPERCASE)."
              },
              "defaultPhoneCountry": {
                "type": "string",
                "description": "ISO country to normalise local phones. Default \"ZZ\"."
              },
              "dateFormat": {
                "type": "string",
                "description": "Hint for ambiguous dates (e.g. \"M/D/YYYY\")."
              }
            },
            "additionalProperties": false,
            "description": "Import options."
          }
        },
        "required": [
          "idempotencyKey",
          "contacts"
        ],
        "additionalProperties": false
      },
      "ContactImportJobResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactImportJob"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactImportJob": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "DRAFT",
              "PREVIEWING",
              "READY",
              "RUNNING",
              "COMPLETED",
              "ATTENTION_REQUIRED"
            ]
          },
          "revision": {
            "type": "integer",
            "minimum": 1
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "previewFingerprint": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "nullable": true
          },
          "counts": {
            "$ref": "#/components/schemas/ContactImportJobCounts"
          },
          "rows": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactImportJobRow"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactImportJobMeta"
          }
        },
        "required": [
          "id",
          "state",
          "revision",
          "createdAt",
          "updatedAt",
          "previewFingerprint",
          "counts",
          "rows",
          "meta"
        ]
      },
      "ContactImportJobCounts": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "total": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000
          },
          "previewed": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000
          },
          "notStarted": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000
          },
          "running": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000
          },
          "succeeded": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000
          },
          "skipped": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000
          },
          "rejected": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000
          },
          "unknown": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000
          }
        },
        "required": [
          "total",
          "previewed",
          "notStarted",
          "running",
          "succeeded",
          "skipped",
          "rejected",
          "unknown"
        ]
      },
      "ContactImportJobRow": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "index": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1999
          },
          "sourceRow": {
            "oneOf": [
              {
                "type": "integer",
                "minimum": 1
              },
              {
                "type": "string",
                "nullable": true
              }
            ]
          },
          "preview": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "action": {
                "type": "string",
                "enum": [
                  "create",
                  "update",
                  "skip",
                  "error"
                ]
              },
              "matchedContactId": {
                "type": "string",
                "format": "uuid",
                "nullable": true
              },
              "matchedContactAvailable": {
                "type": "boolean",
                "nullable": true
              },
              "issues": {
                "type": "array",
                "maxItems": 10,
                "items": {
                  "$ref": "#/components/schemas/ContactImportJobIssue"
                }
              },
              "issueCount": {
                "type": "integer",
                "minimum": 0
              },
              "issuesTruncated": {
                "type": "boolean"
              }
            },
            "required": [
              "action",
              "matchedContactId",
              "matchedContactAvailable",
              "issues",
              "issueCount",
              "issuesTruncated"
            ],
            "nullable": true
          },
          "execution": {
            "$ref": "#/components/schemas/ContactImportJobExecution"
          }
        },
        "required": [
          "index",
          "sourceRow",
          "preview",
          "execution"
        ]
      },
      "ContactImportJobIssue": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "field": {
            "type": "string",
            "nullable": true
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "severity": {
            "type": "string",
            "enum": [
              "error",
              "warning",
              null
            ],
            "nullable": true
          }
        },
        "required": [
          "field",
          "reason",
          "severity"
        ]
      },
      "ContactImportJobExecution": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "NOT_STARTED",
              "RUNNING",
              "SUCCEEDED",
              "SKIPPED",
              "REJECTED",
              "UNKNOWN"
            ]
          },
          "action": {
            "type": "string",
            "enum": [
              "create",
              "update",
              "skip",
              null
            ],
            "nullable": true
          },
          "matchedContactId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "matchedContactAvailable": {
            "type": "boolean",
            "nullable": true
          },
          "reasonCode": {
            "type": "string",
            "nullable": true
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "state",
          "action",
          "matchedContactId",
          "matchedContactAvailable",
          "reasonCode",
          "startedAt",
          "finishedAt"
        ]
      },
      "ContactImportJobMeta": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "sourceRowsReturned": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "targetReferencesChecked": {
            "type": "boolean"
          },
          "consistentSnapshot": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "count",
          "hasMore",
          "nextCursor",
          "sourceRowsReturned",
          "targetReferencesChecked",
          "consistentSnapshot"
        ]
      },
      "ContactImportJobError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactTimelineResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactTimelineResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactTimelineResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "period": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time"
              },
              "to": {
                "type": "string",
                "format": "date-time"
              },
              "endExclusive": {
                "type": "boolean",
                "enum": [
                  true
                ]
              }
            },
            "required": [
              "from",
              "to",
              "endExclusive"
            ]
          },
          "items": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactTimelineItem"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactTimelineMeta"
          }
        },
        "required": [
          "contactId",
          "period",
          "items",
          "meta"
        ]
      },
      "ContactTimelineItem": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "INTERACTION",
              "REGISTRATION",
              "PAYMENT",
              "SUBSCRIPTION"
            ]
          },
          "recordId": {
            "type": "string",
            "format": "uuid"
          },
          "recordedAt": {
            "type": "string",
            "format": "date-time"
          },
          "datePrecision": {
            "type": "string",
            "enum": [
              "DAY",
              "RECORDED_TIMESTAMP",
              "UNKNOWN"
            ]
          },
          "occurredOn": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "relation": {
            "type": "string",
            "enum": [
              "CURRENT_CONTACT",
              "LEGACY_PAYLOAD_CONTACT"
            ]
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "state": {
            "type": "string",
            "nullable": true
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "nullable": true
          },
          "amountMeaning": {
            "type": "string",
            "enum": [
              "PAYMENT_ATTEMPT_NOMINAL",
              "SUBSCRIPTION_CONTRACT_NOMINAL",
              null
            ],
            "nullable": true
          },
          "currency": {
            "type": "string",
            "pattern": "^[a-z]{3}$",
            "nullable": true
          },
          "instrument": {
            "type": "string",
            "enum": [
              "MONETARY",
              "IN_KIND",
              "UNKNOWN",
              null
            ],
            "nullable": true
          },
          "imported": {
            "type": "boolean",
            "nullable": true
          },
          "paymentPhase": {
            "type": "string",
            "nullable": true
          },
          "active": {
            "type": "boolean",
            "nullable": true
          },
          "target": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "FORM",
                  "SUBMISSION",
                  "CAMPAIGN",
                  "PLEDGE",
                  "CAISSE"
                ]
              },
              "id": {
                "type": "string",
                "format": "uuid"
              }
            },
            "required": [
              "kind",
              "id"
            ],
            "nullable": true
          }
        },
        "required": [
          "source",
          "recordId",
          "recordedAt",
          "datePrecision",
          "occurredOn",
          "relation",
          "label",
          "state",
          "amountMinor",
          "amountMeaning",
          "currency",
          "instrument",
          "imported",
          "paymentPhase",
          "active",
          "target"
        ]
      },
      "ContactTimelineMeta": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "readAt": {
            "type": "string",
            "format": "date-time"
          },
          "sources": {
            "type": "array",
            "minItems": 1,
            "maxItems": 4,
            "items": {
              "$ref": "#/components/schemas/ContactTimelineSourceCoverage"
            }
          },
          "completeContactHistory": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "consistentSnapshot": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "sourceFailurePolicy": {
            "type": "string",
            "enum": [
              "FAIL_CLOSED"
            ]
          },
          "settlementVerification": {
            "type": "string",
            "enum": [
              "NOT_PERFORMED"
            ]
          }
        },
        "required": [
          "count",
          "hasMore",
          "nextCursor",
          "readAt",
          "sources",
          "completeContactHistory",
          "consistentSnapshot",
          "sourceFailurePolicy",
          "settlementVerification"
        ]
      },
      "ContactTimelineSourceCoverage": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "INTERACTION",
              "REGISTRATION",
              "PAYMENT",
              "SUBSCRIPTION"
            ]
          },
          "unsupportedDateCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "scope": {
            "type": "string",
            "enum": [
              "KEY_CAMPAIGNS_ONLY",
              "ORGANISATION_CONTACT"
            ]
          },
          "unsupportedFinancialTypesExcluded": {
            "type": "boolean"
          }
        },
        "required": [
          "source",
          "unsupportedDateCount",
          "scope",
          "unsupportedFinancialTypesExcluded"
        ]
      },
      "ContactTimelineError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactBulkPreviewResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactBulkPreview"
          }
        }
      },
      "ContactBulkPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactIds",
          "changes",
          "revision",
          "observedAt",
          "snapshotGuaranteed",
          "rows"
        ],
        "properties": {
          "contactIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "changes": {
            "type": "object",
            "additionalProperties": false,
            "minProperties": 1,
            "properties": {
              "addTags": {
                "type": "array",
                "minItems": 1,
                "maxItems": 50,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 500
                }
              },
              "removeTags": {
                "type": "array",
                "minItems": 1,
                "maxItems": 50,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 500
                }
              },
              "identity": {
                "type": "object",
                "additionalProperties": false,
                "minProperties": 1,
                "properties": {
                  "firstName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "lastName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "gender": {
                    "type": "string",
                    "nullable": true,
                    "enum": [
                      "M",
                      "F",
                      null
                    ]
                  },
                  "hebrewFirstName": {
                    "type": "string",
                    "maxLength": 200
                  }
                }
              }
            }
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "observedAt": {
            "type": "string",
            "format": "date-time"
          },
          "snapshotGuaranteed": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "rows": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "contactId",
                "state"
              ],
              "properties": {
                "contactId": {
                  "type": "string",
                  "format": "uuid"
                },
                "state": {
                  "type": "string",
                  "enum": [
                    "WILL_CHANGE",
                    "NO_CHANGE"
                  ]
                }
              }
            }
          }
        }
      },
      "UnisoftRequest_835aa2faff08c42df4c5": {
        "type": "object",
        "properties": {
          "contactIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "changes": {
            "type": "object",
            "minProperties": 1,
            "properties": {
              "addTags": {
                "type": "array",
                "minItems": 1,
                "maxItems": 50,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 500
                }
              },
              "removeTags": {
                "type": "array",
                "minItems": 1,
                "maxItems": 50,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 500
                }
              },
              "identity": {
                "type": "object",
                "minProperties": 1,
                "properties": {
                  "firstName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "lastName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "gender": {
                    "type": "string",
                    "enum": [
                      "M",
                      "F",
                      null
                    ],
                    "nullable": true
                  },
                  "hebrewFirstName": {
                    "type": "string",
                    "maxLength": 200
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[a-zA-Z0-9._:-]{8,128}$"
          }
        },
        "required": [
          "contactIds",
          "changes",
          "revision",
          "idempotencyKey"
        ],
        "additionalProperties": false
      },
      "ContactBulkReceiptResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactBulkReceipt"
          }
        }
      },
      "ContactBulkReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "state",
          "canRetry",
          "error",
          "rows",
          "startedAt",
          "finishedAt"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "ADMITTING",
              "RUNNING",
              "COMPLETED",
              "REJECTED",
              "PARTIAL",
              "UNKNOWN"
            ]
          },
          "canRetry": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "rows": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "contactId",
                "state"
              ],
              "properties": {
                "contactId": {
                  "type": "string",
                  "format": "uuid"
                },
                "state": {
                  "type": "string",
                  "enum": [
                    "PENDING",
                    "RUNNING",
                    "APPLIED",
                    "NO_CHANGE",
                    "CONFLICT",
                    "BLOCKED",
                    "UNKNOWN",
                    "NOT_ATTEMPTED"
                  ]
                }
              }
            }
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "ContactCoordinateStateResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactCoordinates"
          }
        }
      },
      "ContactCoordinates": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactId",
          "revision",
          "primary",
          "secondaryEmails",
          "secondaryPhones",
          "secondaryAddresses",
          "geographyRecomputed"
        ],
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "primary": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "email",
              "phone",
              "address"
            ],
            "properties": {
              "email": {
                "type": "string",
                "nullable": true,
                "maxLength": 2000
              },
              "phone": {
                "type": "string",
                "nullable": true,
                "maxLength": 2000
              },
              "address": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "address",
                  "postalCode",
                  "city",
                  "region",
                  "country",
                  "note"
                ],
                "properties": {
                  "address": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 2000
                  },
                  "postalCode": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 2000
                  },
                  "city": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 2000
                  },
                  "region": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 2000
                  },
                  "country": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 2000
                  },
                  "note": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 2000
                  }
                }
              }
            }
          },
          "secondaryEmails": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "email",
                "label"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "email": {
                  "type": "string",
                  "maxLength": 2000
                },
                "label": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 200
                }
              }
            }
          },
          "secondaryPhones": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "phone",
                "label"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "phone": {
                  "type": "string",
                  "maxLength": 2000
                },
                "label": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 200
                }
              }
            }
          },
          "secondaryAddresses": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "address",
                "postalCode",
                "city",
                "region",
                "country",
                "note",
                "label",
                "type",
                "companyId"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "address": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 2000
                },
                "postalCode": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 2000
                },
                "city": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 2000
                },
                "region": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 2000
                },
                "country": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 2000
                },
                "note": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 2000
                },
                "label": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 2000
                },
                "type": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 2000
                },
                "companyId": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 2000
                }
              }
            }
          },
          "geographyRecomputed": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "UnisoftRequest_3eb894b2a1f27c208752": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "EMAIL",
              "PHONE",
              "ADDRESS"
            ]
          },
          "action": {
            "type": "string",
            "enum": [
              "EDIT",
              "REMOVE",
              "MAKE_PRIMARY"
            ]
          },
          "coordinateId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "value": {
            "type": "string",
            "minLength": 1,
            "maxLength": 320
          },
          "phoneCountry": {
            "type": "string",
            "pattern": "^[A-Z]{2}$"
          },
          "label": {
            "type": "string",
            "maxLength": 200
          },
          "address": {
            "type": "object",
            "minProperties": 1,
            "properties": {
              "address": {
                "type": "string",
                "maxLength": 2000
              },
              "postalCode": {
                "type": "string",
                "maxLength": 2000
              },
              "city": {
                "type": "string",
                "maxLength": 2000
              },
              "region": {
                "type": "string",
                "maxLength": 2000
              },
              "country": {
                "type": "string",
                "maxLength": 2000
              },
              "note": {
                "type": "string",
                "maxLength": 2000
              },
              "label": {
                "type": "string",
                "maxLength": 2000
              },
              "type": {
                "type": "string",
                "maxLength": 2000
              },
              "companyId": {
                "type": "string",
                "maxLength": 2000
              }
            },
            "additionalProperties": false
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[a-zA-Z0-9._:-]{8,128}$"
          }
        },
        "required": [
          "kind",
          "action",
          "coordinateId",
          "revision",
          "idempotencyKey"
        ],
        "additionalProperties": false
      },
      "ContactCoordinateReceiptResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactCoordinateReceipt"
          }
        }
      },
      "ContactCoordinateReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "contactId",
          "state",
          "canRetry",
          "error",
          "geographyRecomputed",
          "consentChanged",
          "fiscalHistoryChanged",
          "startedAt",
          "finishedAt"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "ADMITTING",
              "RUNNING",
              "APPLIED",
              "NO_CHANGE",
              "REJECTED",
              "CONFLICT",
              "UNKNOWN"
            ]
          },
          "canRetry": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "geographyRecomputed": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "consentChanged": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "fiscalHistoryChanged": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "ContactLifecycleStateResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactLifecycle"
          }
        }
      },
      "ContactLifecycle": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactId",
          "state",
          "archived",
          "trashed",
          "deceased",
          "isNew",
          "mergedIntoContactId",
          "revision",
          "permanentDeletionAvailable"
        ],
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "ARCHIVED",
              "TRASHED",
              "MERGED"
            ]
          },
          "archived": {
            "type": "boolean"
          },
          "trashed": {
            "type": "boolean"
          },
          "deceased": {
            "type": "boolean",
            "nullable": true
          },
          "isNew": {
            "type": "boolean",
            "nullable": true
          },
          "mergedIntoContactId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "permanentDeletionAvailable": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "ContactLifecycleReceiptResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactLifecycleReceipt"
          }
        }
      },
      "ContactLifecycleReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "contactId",
          "action",
          "state",
          "lifecycleState",
          "canRetry",
          "error",
          "linkedRecordsDeleted",
          "fiscalHistoryChanged",
          "startedAt",
          "finishedAt"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "action": {
            "type": "string",
            "enum": [
              "ARCHIVE",
              "UNARCHIVE",
              "TRASH",
              "RESTORE"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "ADMITTING",
              "RUNNING",
              "APPLIED",
              "NO_CHANGE",
              "REJECTED",
              "CONFLICT",
              "UNKNOWN"
            ]
          },
          "lifecycleState": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "ARCHIVED",
              "TRASHED",
              "MERGED",
              null
            ],
            "nullable": true
          },
          "canRetry": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "linkedRecordsDeleted": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "fiscalHistoryChanged": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "ContactPostalExportResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactPostalExportResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactPostalExportResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "rows": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactPostalExportRow"
            }
          },
          "meta": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "selectedCount": {
                "type": "integer",
                "minimum": 1,
                "maximum": 2000
              },
              "totalRows": {
                "type": "integer",
                "minimum": 0,
                "maximum": 5000
              },
              "count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "hasMore": {
                "type": "boolean"
              },
              "nextCursor": {
                "type": "string",
                "nullable": true
              },
              "readAt": {
                "type": "string",
                "format": "date-time"
              },
              "consistentSnapshot": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "skippedNoAddress": {
                "type": "integer",
                "minimum": 0,
                "maximum": 5000
              },
              "householdContextUsed": {
                "type": "boolean"
              },
              "genderInferencePublished": {
                "type": "boolean",
                "enum": [
                  false
                ]
              }
            },
            "required": [
              "selectedCount",
              "totalRows",
              "count",
              "hasMore",
              "nextCursor",
              "readAt",
              "consistentSnapshot",
              "skippedNoAddress",
              "householdContextUsed",
              "genderInferencePublished"
            ]
          }
        },
        "required": [
          "rows",
          "meta"
        ]
      },
      "ContactPostalExportRow": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "rowId": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "representativeContactId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "formattedRecipient": {
            "type": "string",
            "nullable": true
          },
          "familyLabel": {
            "type": "string",
            "nullable": true
          },
          "address": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          },
          "postalCode": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "region": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "grouping": {
            "type": "string",
            "enum": [
              "CONTACT",
              "HOUSEHOLD"
            ]
          },
          "recipientFormat": {
            "type": "string",
            "enum": [
              "NAME_ONLY"
            ]
          },
          "addressSource": {
            "type": "string",
            "enum": [
              "PRIMARY"
            ]
          }
        },
        "required": [
          "rowId",
          "representativeContactId",
          "formattedRecipient",
          "familyLabel",
          "address",
          "postalCode",
          "city",
          "region",
          "country",
          "grouping",
          "recipientFormat",
          "addressSource"
        ]
      },
      "ContactPostalExportError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactMapExportResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactMapExportResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactMapExportResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "rows": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactMapExportRow"
            }
          },
          "meta": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "selectedCount": {
                "type": "integer",
                "minimum": 1,
                "maximum": 2000
              },
              "totalRows": {
                "type": "integer",
                "minimum": 0,
                "maximum": 5000
              },
              "count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "hasMore": {
                "type": "boolean"
              },
              "nextCursor": {
                "type": "string",
                "nullable": true
              },
              "readAt": {
                "type": "string",
                "format": "date-time"
              },
              "consistentSnapshot": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "contactsWithoutAddress": {
                "type": "integer",
                "minimum": 0,
                "maximum": 2000
              },
              "geocodingPerformed": {
                "type": "boolean",
                "enum": [
                  false
                ]
              }
            },
            "required": [
              "selectedCount",
              "totalRows",
              "count",
              "hasMore",
              "nextCursor",
              "readAt",
              "consistentSnapshot",
              "contactsWithoutAddress",
              "geocodingPerformed"
            ]
          }
        },
        "required": [
          "rows",
          "meta"
        ]
      },
      "ContactMapExportRow": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "addressId": {
            "oneOf": [
              {
                "type": "string",
                "enum": [
                  "MAIN"
                ]
              },
              {
                "type": "string",
                "format": "uuid"
              }
            ]
          },
          "displayName": {
            "type": "string",
            "nullable": true
          },
          "address": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          },
          "postalCode": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "region": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "latitude": {
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "nullable": true
          },
          "longitude": {
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "nullable": true
          },
          "coordinateStatus": {
            "type": "string",
            "enum": [
              "STORED_CURRENT_ADDRESS_MATCH",
              "NO_VERIFIED_STORED_COORDINATE"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "STORED_ONLY_NO_GEOCODER"
            ]
          }
        },
        "required": [
          "contactId",
          "addressId",
          "displayName",
          "address",
          "postalCode",
          "city",
          "region",
          "country",
          "latitude",
          "longitude",
          "coordinateStatus",
          "source"
        ]
      },
      "ContactReconciliationResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactReconciliationResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactReconciliationResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "protocol": {
            "type": "integer",
            "enum": [
              1
            ]
          },
          "mode": {
            "type": "string",
            "enum": [
              "RECONCILE"
            ]
          },
          "scope": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "reset": {
            "type": "boolean"
          },
          "manifest": {
            "type": "array",
            "maxItems": 10000,
            "items": {
              "$ref": "#/components/schemas/ContactReconciliationManifestEntry"
            }
          },
          "upserts": {
            "type": "array",
            "maxItems": 10000,
            "items": {
              "$ref": "#/components/schemas/ContactReconciliationContact"
            }
          },
          "removed": {
            "type": "array",
            "maxItems": 10000,
            "items": {
              "$ref": "#/components/schemas/ContactReconciliationRemoved"
            }
          },
          "observedAt": {
            "type": "string",
            "format": "date-time"
          },
          "coverage": {
            "$ref": "#/components/schemas/ContactReconciliationCoverage"
          }
        },
        "required": [
          "protocol",
          "mode",
          "scope",
          "reset",
          "manifest",
          "upserts",
          "removed",
          "observedAt",
          "coverage"
        ]
      },
      "ContactReconciliationManifestEntry": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "version": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        },
        "required": [
          "id",
          "version"
        ]
      },
      "ContactReconciliationContact": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "firstName": {
            "type": "string",
            "nullable": true
          },
          "lastName": {
            "type": "string",
            "nullable": true
          },
          "email": {
            "type": "string",
            "nullable": true
          },
          "phone": {
            "type": "string",
            "nullable": true
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 400,
              "pattern": "^[^\\u0000]+$"
            }
          },
          "archived": {
            "type": "boolean",
            "nullable": true
          },
          "deceased": {
            "type": "boolean",
            "nullable": true
          },
          "isNew": {
            "type": "boolean",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "id",
          "firstName",
          "lastName",
          "email",
          "phone",
          "tags",
          "archived",
          "deceased",
          "isNew",
          "updatedAt",
          "createdAt"
        ]
      },
      "ContactReconciliationRemoved": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "reason": {
            "type": "string",
            "enum": [
              "UNKNOWN"
            ]
          }
        },
        "required": [
          "id",
          "reason"
        ]
      },
      "ContactReconciliationCoverage": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "fields": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "id",
                "firstName",
                "lastName",
                "email",
                "phone",
                "tags",
                "archived",
                "deceased",
                "isNew",
                "createdAt",
                "updatedAt"
              ]
            }
          },
          "selection": {
            "type": "string",
            "enum": [
              "EXPLICIT_IDS",
              "ORGANISATION"
            ]
          },
          "completeChangeJournal": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "archiveCurrentStateIncluded": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "mergeHistoryAvailable": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "hardDeleteReasonAvailable": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "consistentSnapshot": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "fields",
          "selection",
          "completeChangeJournal",
          "archiveCurrentStateIncluded",
          "mergeHistoryAvailable",
          "hardDeleteReasonAvailable",
          "consistentSnapshot"
        ]
      },
      "ContactReconciliationError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactQualityReadResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactQualityReadResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactQualityReadResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "findings": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactQualityReadFinding"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactQualityReadMeta"
          }
        },
        "required": [
          "findings",
          "meta"
        ]
      },
      "ContactQualityReadFinding": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "method": {
            "type": "string"
          },
          "reasonCode": {
            "type": "string"
          },
          "contactIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "severity": {
            "type": "string",
            "enum": [
              "info",
              "warning",
              "error",
              "critical",
              null
            ],
            "nullable": true
          },
          "proposedDuplicate": {
            "type": "boolean"
          },
          "requiresHumanReview": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "canApply": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "id",
          "method",
          "reasonCode",
          "contactIds",
          "severity",
          "proposedDuplicate",
          "requiresHumanReview",
          "canApply"
        ]
      },
      "ContactQualityReadMeta": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "selectedCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200
          },
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "readAt": {
            "type": "string",
            "format": "date-time"
          },
          "coverage": {
            "type": "string",
            "enum": [
              "SELECTED_CURRENT_CONTACTS_ONLY"
            ]
          },
          "storedAnalysisRead": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "completeOrganisationScan": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "sourceHistoryIncluded": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "familyContextComplete": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "duplicateCandidatesRequireReview": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "selectedCount",
          "count",
          "hasMore",
          "nextCursor",
          "readAt",
          "coverage",
          "storedAnalysisRead",
          "completeOrganisationScan",
          "sourceHistoryIncluded",
          "familyContextComplete",
          "duplicateCandidatesRequireReview"
        ]
      },
      "ContactQualityReadError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactQualityReportResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactQualityReport"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactQualityReport": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9_.:-]{1,200}$",
            "nullable": true
          },
          "measuredAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "timeZone": {
            "type": "string",
            "nullable": true,
            "minLength": 1,
            "maxLength": 100,
            "description": "Recorded organisation time zone for civil dates and 12/24 calendar-month criteria; null when not recorded. New reports use organisation timeZone or timezone, defaulting to Europe/Paris. The AI night admission window separately stays in Europe/Paris. No request override is accepted."
          },
          "status": {
            "type": "string",
            "enum": [
              "ready",
              "scope_changed",
              "not_prepared",
              "pending",
              "failed"
            ]
          },
          "stale": {
            "type": "boolean"
          },
          "view": {
            "$ref": "#/components/schemas/ContactQualityReportView"
          },
          "versions": {
            "$ref": "#/components/schemas/ContactQualityReportVersions"
          },
          "observation": {
            "$ref": "#/components/schemas/ContactQualityReportObservation"
          },
          "metrics": {
            "$ref": "#/components/schemas/ContactQualityReportMetrics"
          },
          "ai": {
            "$ref": "#/components/schemas/ContactQualityReportAi"
          },
          "warning": {
            "type": "string",
            "enum": [
              "calculation_failed"
            ]
          }
        },
        "required": [
          "id",
          "measuredAt",
          "timeZone",
          "status",
          "stale",
          "view",
          "versions",
          "observation",
          "metrics",
          "ai"
        ]
      },
      "ContactQualityReportView": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "scope": {
            "type": "string",
            "enum": [
              "global",
              "local"
            ],
            "default": "global"
          },
          "population": {
            "type": "string",
            "enum": [
              "all",
              "active"
            ],
            "default": "all"
          }
        },
        "required": [
          "scope",
          "population"
        ]
      },
      "ContactQualityReportVersions": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "criteria": {
            "type": "string",
            "maxLength": 100
          },
          "activity": {
            "type": "string",
            "maxLength": 100
          }
        },
        "required": [
          "criteria",
          "activity"
        ],
        "nullable": true
      },
      "ContactQualityReportObservation": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "startedAt": {
            "type": "string",
            "format": "date-time"
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time"
          },
          "transactional": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "startedAt",
          "finishedAt",
          "transactional"
        ],
        "nullable": true
      },
      "ContactQualityReportMetrics": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "total": {
            "type": "integer",
            "minimum": 0
          },
          "evaluable": {
            "type": "integer",
            "minimum": 0
          },
          "clean": {
            "type": "integer",
            "minimum": 0
          },
          "affected": {
            "type": "integer",
            "minimum": 0
          },
          "unknown": {
            "type": "integer",
            "minimum": 0
          },
          "score": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "nullable": true
          },
          "coverage": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "nullable": true
          },
          "activitySelectionUnknown": {
            "type": "integer",
            "minimum": 0
          },
          "kpis": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactQualityReportKpi"
            }
          }
        },
        "required": [
          "total",
          "evaluable",
          "clean",
          "affected",
          "unknown",
          "score",
          "coverage",
          "activitySelectionUnknown",
          "kpis"
        ],
        "nullable": true
      },
      "ContactQualityReportKpi": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "count": {
            "type": "integer",
            "minimum": 0
          },
          "penalizes": {
            "type": "boolean"
          }
        },
        "required": [
          "code",
          "count",
          "penalizes"
        ]
      },
      "ContactQualityReportAi": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "not_requested",
              "pending",
              "running",
              "partial",
              "complete",
              "interrupted",
              "superseded",
              "failed",
              "unavailable",
              "scope_unavailable"
            ]
          },
          "covered": {
            "type": "integer",
            "minimum": 0
          },
          "total": {
            "type": "integer",
            "minimum": 0
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "sections": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactQualityReportSection"
            }
          }
        },
        "required": [
          "status",
          "covered",
          "total",
          "generatedAt",
          "sections"
        ]
      },
      "ContactQualityReportSection": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "kind": {
            "type": "string",
            "enum": [
              "priority",
              "coincidence",
              "coverage"
            ]
          },
          "code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "relatedCode": {
            "type": "string",
            "nullable": true,
            "maxLength": 100
          },
          "count": {
            "type": "integer",
            "minimum": 0
          },
          "denominator": {
            "type": "integer",
            "minimum": 0
          },
          "scope": {
            "type": "string",
            "enum": [
              "global",
              "local"
            ],
            "default": "global"
          },
          "population": {
            "type": "string",
            "enum": [
              "all",
              "active"
            ],
            "default": "all"
          },
          "action": {
            "type": "string",
            "enum": [
              "review",
              "improve"
            ]
          }
        },
        "required": [
          "id",
          "kind",
          "code",
          "relatedCode",
          "count",
          "denominator",
          "scope",
          "population",
          "action"
        ]
      },
      "ContactQualityReportError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactQualityReportHistoryResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactQualityReportHistory"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactQualityReportHistory": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "items": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactQualityReportSummary"
            }
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "items",
          "nextCursor"
        ]
      },
      "ContactQualityReportSummary": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9_.:-]{1,200}$",
            "nullable": true
          },
          "measuredAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "timeZone": {
            "type": "string",
            "nullable": true,
            "minLength": 1,
            "maxLength": 100,
            "description": "Recorded organisation time zone for civil dates and 12/24 calendar-month criteria; null when not recorded. New reports use organisation timeZone or timezone, defaulting to Europe/Paris. The AI night admission window separately stays in Europe/Paris. No request override is accepted."
          },
          "status": {
            "type": "string",
            "enum": [
              "ready",
              "scope_changed",
              "not_prepared",
              "pending",
              "failed"
            ]
          },
          "stale": {
            "type": "boolean"
          },
          "view": {
            "$ref": "#/components/schemas/ContactQualityReportView"
          },
          "versions": {
            "$ref": "#/components/schemas/ContactQualityReportVersions"
          },
          "observation": {
            "$ref": "#/components/schemas/ContactQualityReportObservation"
          },
          "metrics": {
            "$ref": "#/components/schemas/ContactQualityReportMetrics"
          },
          "warning": {
            "type": "string",
            "enum": [
              "calculation_failed"
            ]
          }
        },
        "required": [
          "id",
          "measuredAt",
          "timeZone",
          "status",
          "stale",
          "view",
          "versions",
          "observation",
          "metrics"
        ]
      },
      "ContactQualityReportContactsResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactQualityReportContacts"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactQualityReportContacts": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "items": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactQualityReportContact"
            }
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Currently displayable contacts matching the optional current-name search."
          },
          "measuredTotal": {
            "type": "integer",
            "minimum": 0,
            "description": "Dated KPI membership authorised for the reader, before current availability and name search."
          },
          "unavailable": {
            "type": "integer",
            "minimum": 0,
            "description": "Dated authorised members no longer currently displayable, counted before name search."
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "items",
          "total",
          "measuredTotal",
          "unavailable",
          "nextCursor"
        ]
      },
      "ContactQualityReportContact": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9_.:-]{1,200}$"
          },
          "firstName": {
            "type": "string",
            "nullable": true,
            "maxLength": 2000
          },
          "lastName": {
            "type": "string",
            "nullable": true,
            "maxLength": 2000
          },
          "name": {
            "type": "string",
            "nullable": true,
            "maxLength": 2000
          }
        },
        "required": [
          "id"
        ]
      },
      "ContactSuggestionListResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactSuggestionList"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactSuggestionList": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "items": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ContactSuggestionMotif"
                },
                {
                  "$ref": "#/components/schemas/ContactSuggestionGroup"
                },
                {
                  "$ref": "#/components/schemas/ContactSuggestionPaused"
                }
              ]
            }
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000
          },
          "size": {
            "type": "integer",
            "enum": [
              3,
              20,
              50
            ]
          },
          "population": {
            "type": "string",
            "enum": [
              "local",
              "global"
            ],
            "description": "local means contacts marked local (starred), not people nearby. global means all contacts allowed in the current organisation, never other organisations."
          },
          "timeZone": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "coverage": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "partial",
                  "calculated",
                  "pause_configuration"
                ]
              },
              "checked": {
                "type": "integer",
                "minimum": 0,
                "maximum": 10000000,
                "nullable": true
              },
              "uncalculated": {
                "type": "integer",
                "minimum": 0,
                "maximum": 10000000,
                "nullable": true
              },
              "limits": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 256
                }
              },
              "population": {
                "type": "string",
                "enum": [
                  "local",
                  "global"
                ],
                "description": "local means contacts marked local (starred), not people nearby. global means all contacts allowed in the current organisation, never other organisations."
              }
            },
            "required": [
              "status",
              "checked",
              "uncalculated",
              "limits",
              "population"
            ]
          },
          "job": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "kind": {
                "type": "string",
                "enum": [
                  "analysis"
                ]
              },
              "state": {
                "type": "string",
                "enum": [
                  "queued",
                  "running",
                  "completed",
                  "partial",
                  "failed",
                  "canceled"
                ]
              },
              "population": {
                "type": "string",
                "enum": [
                  "local",
                  "global"
                ],
                "description": "local means contacts marked local (starred), not people nearby. global means all contacts allowed in the current organisation, never other organisations."
              },
              "volet": {
                "type": "string",
                "enum": [
                  "finance",
                  "social",
                  "both"
                ]
              },
              "contact": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160,
                "nullable": true
              },
              "processed": {
                "type": "integer",
                "minimum": 0,
                "maximum": 10000000
              },
              "failed": {
                "type": "integer",
                "minimum": 0,
                "maximum": 10000000
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "completedAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "code": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160,
                "nullable": true
              },
              "throttled": {
                "type": "boolean"
              }
            },
            "required": [
              "id",
              "kind",
              "state",
              "population",
              "volet",
              "contact",
              "processed",
              "failed",
              "createdAt",
              "completedAt",
              "code",
              "throttled"
            ],
            "nullable": true
          }
        },
        "required": [
          "items",
          "total",
          "page",
          "size",
          "population",
          "timeZone",
          "coverage",
          "job"
        ]
      },
      "ContactSuggestionMotif": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "motif"
            ]
          },
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "contact": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "identity": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "firstName": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              },
              "lastName": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              }
            },
            "required": [
              "id",
              "firstName",
              "lastName"
            ]
          },
          "volet": {
            "type": "string",
            "enum": [
              "finance",
              "social"
            ],
            "description": "Finance and Social classify the purpose of a conversation. A person may have reasons in both sections."
          },
          "family": {
            "type": "string",
            "enum": [
              "recognition",
              "restart_support",
              "relevant_project",
              "lasting_support",
              "commitment",
              "obstacle",
              "welcome",
              "develop_link",
              "reconnect",
              "life_event",
              "support",
              "followup",
              "involvement",
              "acknowledge_help"
            ]
          },
          "scope": {
            "type": "string",
            "enum": [
              "common",
              "personal"
            ],
            "description": "common means team instructions or pauses; personal means private to the consenting user. A common-labelled result may still use private adjustments and must not be redistributed as a public team result."
          },
          "state": {
            "type": "string",
            "enum": [
              "active",
              "review",
              "paused",
              "expired",
              "unavailable",
              "resolved"
            ]
          },
          "priority": {
            "$ref": "#/components/schemas/ContactSuggestionPriority"
          },
          "reason": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "evidence": {
            "type": "array",
            "maxItems": 250,
            "items": {
              "$ref": "#/components/schemas/ContactSuggestionEvidence"
            }
          },
          "firstDetectedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "analyzedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "nextReviewAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "dueAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "partial": {
            "type": "boolean"
          },
          "pauses": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 160
                },
                "until": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true
                },
                "scope": {
                  "type": "string",
                  "enum": [
                    "common",
                    "personal"
                  ],
                  "description": "common means team instructions or pauses; personal means private to the consenting user. A common-labelled result may still use private adjustments and must not be redistributed as a public team result."
                },
                "volet": {
                  "type": "string",
                  "enum": [
                    "finance",
                    "social"
                  ],
                  "description": "Finance and Social classify the purpose of a conversation. A person may have reasons in both sections."
                },
                "motif": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 160,
                  "nullable": true
                }
              },
              "required": [
                "id",
                "until",
                "scope",
                "volet",
                "motif"
              ]
            }
          }
        },
        "required": [
          "kind",
          "id",
          "contact",
          "identity",
          "volet",
          "family",
          "scope",
          "state",
          "priority",
          "reason",
          "evidence",
          "firstDetectedAt",
          "analyzedAt",
          "nextReviewAt",
          "dueAt",
          "partial",
          "pauses"
        ]
      },
      "ContactSuggestionPriority": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "value": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "nullable": true,
            "description": "Action priority, not a probability or a judgement about a person. Four rounded contributions (35/30/20/15), an instruction adjustment and a possible review cap explain the returned value. For example, 66 raw points can become 49 because current relevance needs checking. Use the returned score/version; do not recompute a future version."
          },
          "cap": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "criteria": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "P": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "T": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "A": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "E": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              }
            },
            "required": [
              "P",
              "T",
              "A",
              "E"
            ]
          },
          "contributions": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "P": {
                "type": "integer",
                "minimum": 0,
                "maximum": 35
              },
              "T": {
                "type": "integer",
                "minimum": 0,
                "maximum": 35
              },
              "A": {
                "type": "integer",
                "minimum": 0,
                "maximum": 35
              },
              "E": {
                "type": "integer",
                "minimum": 0,
                "maximum": 35
              }
            },
            "required": [
              "P",
              "T",
              "A",
              "E"
            ]
          },
          "adjustment": {
            "type": "integer",
            "minimum": -20,
            "maximum": 20
          },
          "version": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          }
        },
        "required": [
          "value",
          "cap",
          "criteria",
          "contributions",
          "adjustment",
          "version"
        ]
      },
      "ContactSuggestionEvidence": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "collection": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "quote": {
            "type": "string",
            "maxLength": 10000,
            "nullable": true
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "occurredOn": {
            "type": "string",
            "format": "date",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "nullable": true
          },
          "datePrecision": {
            "type": "string",
            "enum": [
              "instant",
              "day",
              null
            ],
            "nullable": true
          }
        },
        "required": [
          "collection",
          "id",
          "quote",
          "at",
          "occurredOn",
          "datePrecision"
        ]
      },
      "ContactSuggestionGroup": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "contact"
            ]
          },
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "contact": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "identity": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "firstName": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              },
              "lastName": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              }
            },
            "required": [
              "id",
              "firstName",
              "lastName"
            ]
          },
          "priority": {
            "$ref": "#/components/schemas/ContactSuggestionPriority"
          },
          "mainId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "motifs": {
            "type": "array",
            "maxItems": 1000,
            "items": {
              "$ref": "#/components/schemas/ContactSuggestionMotif"
            }
          }
        },
        "required": [
          "kind",
          "id",
          "contact",
          "identity",
          "priority",
          "mainId",
          "motifs"
        ]
      },
      "ContactSuggestionPaused": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "pause"
            ]
          },
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "until": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "scope": {
            "type": "string",
            "enum": [
              "common",
              "personal"
            ],
            "description": "common means team instructions or pauses; personal means private to the consenting user. A common-labelled result may still use private adjustments and must not be redistributed as a public team result."
          },
          "volet": {
            "type": "string",
            "enum": [
              "finance",
              "social"
            ],
            "description": "Finance and Social classify the purpose of a conversation. A person may have reasons in both sections."
          },
          "motif": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160,
            "nullable": true
          },
          "contact": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "identity": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "firstName": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              },
              "lastName": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              }
            },
            "required": [
              "id",
              "firstName",
              "lastName"
            ]
          }
        },
        "required": [
          "kind",
          "id",
          "until",
          "scope",
          "volet",
          "motif",
          "contact",
          "identity"
        ]
      },
      "ContactSuggestionError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "required": {
            "type": "array",
            "minItems": 1,
            "maxItems": 16,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "location": {
                "type": "string",
                "enum": [
                  "query",
                  "path",
                  "body"
                ]
              }
            },
            "required": [
              "code"
            ]
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactSuggestionSettingsResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactSuggestionSettings"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactSuggestionSettings": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "population": {
            "type": "string",
            "enum": [
              "local",
              "global"
            ],
            "description": "local means contacts marked local (starred), not people nearby. global means all contacts allowed in the current organisation, never other organisations."
          },
          "modes": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "finance": {
                "type": "string",
                "enum": [
                  "combined",
                  "common",
                  "personal"
                ]
              },
              "social": {
                "type": "string",
                "enum": [
                  "combined",
                  "common",
                  "personal"
                ]
              }
            },
            "required": [
              "finance",
              "social"
            ]
          },
          "isAdmin": {
            "type": "boolean"
          },
          "entries": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "$ref": "#/components/schemas/ContactSuggestionSetting"
            }
          }
        },
        "required": [
          "population",
          "modes",
          "isAdmin",
          "entries"
        ]
      },
      "ContactSuggestionSetting": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "volet": {
            "type": "string",
            "enum": [
              "finance",
              "social"
            ],
            "description": "Finance and Social classify the purpose of a conversation. A person may have reasons in both sections."
          },
          "scope": {
            "type": "string",
            "enum": [
              "common",
              "personal"
            ],
            "description": "common means team instructions or pauses; personal means private to the consenting user. A common-labelled result may still use private adjustments and must not be redistributed as a public team result."
          },
          "revision": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000
          },
          "draft": {
            "type": "string",
            "maxLength": 10000
          },
          "status": {
            "type": "string",
            "enum": [
              "interpreting",
              "active",
              "review",
              "error"
            ]
          },
          "active": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "version": {
                "type": "integer",
                "minimum": 0,
                "maximum": 10000000
              },
              "text": {
                "type": "string",
                "maxLength": 10000
              }
            },
            "required": [
              "version",
              "text"
            ],
            "nullable": true
          },
          "code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160,
            "nullable": true
          }
        },
        "required": [
          "volet",
          "scope",
          "revision",
          "draft",
          "status",
          "active",
          "code"
        ]
      },
      "UnisoftRequest_0c53887249a3fdc8ad93": {
        "type": "object",
        "properties": {
          "population": {
            "type": "string",
            "enum": [
              "local",
              "global"
            ],
            "description": "local means contacts marked local (starred), not people nearby. global means all contacts allowed in the current organisation, never other organisations."
          },
          "volet": {
            "type": "string",
            "enum": [
              "finance",
              "social"
            ],
            "description": "Finance and Social classify the purpose of a conversation. A person may have reasons in both sections."
          },
          "mode": {
            "type": "string",
            "enum": [
              "combined",
              "common",
              "personal"
            ],
            "description": "combined combines team and private instructions; common uses team instructions only; personal uses private instructions only. Standard criteria remain active in all three modes. Private instructions take precedence on conflicts in the combined view and never become team text."
          }
        },
        "additionalProperties": false,
        "allOf": [
          {
            "anyOf": [
              {
                "not": {
                  "required": [
                    "mode"
                  ]
                }
              },
              {
                "required": [
                  "volet"
                ]
              }
            ]
          },
          {
            "anyOf": [
              {
                "not": {
                  "required": [
                    "volet"
                  ]
                }
              },
              {
                "required": [
                  "mode"
                ]
              }
            ]
          }
        ],
        "anyOf": [
          {
            "required": [
              "population"
            ]
          },
          {
            "required": [
              "volet",
              "mode"
            ]
          }
        ]
      },
      "ContactSuggestionJobResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactSuggestionJob"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactSuggestionJob": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "kind": {
            "type": "string",
            "enum": [
              "analysis"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "partial",
              "failed",
              "canceled"
            ]
          },
          "population": {
            "type": "string",
            "enum": [
              "local",
              "global"
            ],
            "description": "local means contacts marked local (starred), not people nearby. global means all contacts allowed in the current organisation, never other organisations."
          },
          "volet": {
            "type": "string",
            "enum": [
              "finance",
              "social",
              "both"
            ]
          },
          "contact": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160,
            "nullable": true
          },
          "processed": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000
          },
          "failed": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "completedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160,
            "nullable": true
          },
          "throttled": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "kind",
          "state",
          "population",
          "volet",
          "contact",
          "processed",
          "failed",
          "createdAt",
          "completedAt",
          "code",
          "throttled"
        ]
      },
      "ContactSuggestionSourceResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactSuggestionSource"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactSuggestionSource": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "contact": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "collection": {
            "type": "string",
            "enum": [
              "contact",
              "contact_activity",
              "paiements",
              "abonnements",
              "dettes_v2",
              "forms_submit",
              "rappel",
              "custom_rappels",
              "forms",
              "caisses",
              "campagnes"
            ]
          },
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "title": {
            "type": "string",
            "maxLength": 10000,
            "nullable": true
          },
          "text": {
            "type": "string",
            "maxLength": 10000,
            "nullable": true
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "occurredOn": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "datePrecision": {
            "type": "string",
            "enum": [
              "instant",
              "day",
              null
            ],
            "nullable": true
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "amount": {
                "type": "number",
                "nullable": true
              },
              "currency": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160,
                "nullable": true
              },
              "state": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160,
                "nullable": true
              },
              "type": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160,
                "nullable": true
              },
              "dueAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "dueOn": {
                "type": "string",
                "format": "date",
                "nullable": true
              }
            },
            "required": [
              "amount",
              "currency",
              "state",
              "type",
              "dueAt",
              "dueOn"
            ]
          }
        },
        "required": [
          "contact",
          "collection",
          "id",
          "title",
          "text",
          "at",
          "occurredOn",
          "datePrecision",
          "details"
        ]
      },
      "ContactSuggestionPauseResultResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactSuggestionPauseResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactSuggestionPauseResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "until": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "timeZone": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "partial": {
            "type": "boolean"
          },
          "results": {
            "type": "array",
            "maxItems": 400,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "scope": {
                  "type": "string",
                  "enum": [
                    "common",
                    "personal"
                  ],
                  "description": "common means team instructions or pauses; personal means private to the consenting user. A common-labelled result may still use private adjustments and must not be redistributed as a public team result."
                },
                "volet": {
                  "type": "string",
                  "enum": [
                    "finance",
                    "social"
                  ],
                  "description": "Finance and Social classify the purpose of a conversation. A person may have reasons in both sections."
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "saved",
                    "failed"
                  ]
                }
              },
              "required": [
                "scope",
                "volet",
                "status"
              ]
            }
          }
        },
        "required": [
          "until",
          "timeZone",
          "partial",
          "results"
        ]
      },
      "ContactSuggestionResumeResultResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactSuggestionResumeResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactSuggestionResumeResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "resumed": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "resumed"
        ]
      },
      "ContactSuggestionInteractionResultResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactSuggestionInteractionResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactSuggestionInteractionResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "recorded": {
            "type": "boolean"
          },
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "nullable": true
          }
        },
        "required": [
          "recorded",
          "id"
        ]
      },
      "ContactExternalIdAttachResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactExternalIdMapping"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactExternalIdMapping": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "system": {
            "type": "string",
            "minLength": 2,
            "maxLength": 64,
            "pattern": "^[a-z][a-z0-9._-]{1,63}$"
          },
          "externalId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
          },
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "created": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "provenance": {
            "type": "string",
            "enum": [
              "INTEGRATIONS_API"
            ]
          },
          "canonicalContactField": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "system",
          "externalId",
          "contactId",
          "created",
          "createdAt",
          "provenance",
          "canonicalContactField"
        ]
      },
      "ContactExternalIdError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactExternalIdLookupResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactExternalIdLookup"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactExternalIdLookup": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "system": {
            "type": "string",
            "minLength": 2,
            "maxLength": 64,
            "pattern": "^[a-z][a-z0-9._-]{1,63}$"
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/ContactExternalIdLookupItem"
            }
          },
          "provenance": {
            "type": "string",
            "enum": [
              "INTEGRATIONS_API"
            ]
          },
          "canonicalContactField": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "readAt": {
            "type": "string",
            "format": "date-time"
          },
          "consistentSnapshot": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "system",
          "items",
          "provenance",
          "canonicalContactField",
          "readAt",
          "consistentSnapshot"
        ]
      },
      "ContactExternalIdLookupItem": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "externalId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
          },
          "state": {
            "type": "string",
            "enum": [
              "RESOLVED",
              "UNRESOLVED"
            ]
          },
          "contactId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "externalId",
          "state",
          "contactId",
          "createdAt"
        ]
      },
      "UnisoftRequest_4f53ab7a631d002ee822": {
        "type": "object",
        "properties": {
          "contactIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 2000,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "fields": {
            "type": "array",
            "minItems": 1,
            "maxItems": 40,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "firstName",
                "lastName",
                "gender",
                "birthDate",
                "email",
                "phone",
                "secondaryEmails",
                "secondaryPhones",
                "tags",
                "address",
                "postalCode",
                "city",
                "region",
                "country",
                "archived",
                "deceased",
                "isNew",
                "createdAt",
                "updatedAt"
              ]
            }
          },
          "customFields": {
            "type": "array",
            "maxItems": 40,
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 120
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "TEXT",
                    "NUMBER",
                    "DATE",
                    "DATETIME",
                    "BOOL"
                  ]
                }
              },
              "required": [
                "key",
                "type"
              ],
              "additionalProperties": false
            }
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          }
        },
        "required": [
          "contactIds",
          "fields"
        ],
        "additionalProperties": false
      },
      "ContactExportResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactExportResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactExportResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "columns": {
            "type": "array",
            "minItems": 1,
            "maxItems": 40,
            "items": {
              "$ref": "#/components/schemas/ContactExportColumn"
            }
          },
          "rows": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactExportRow"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactExportMeta"
          }
        },
        "required": [
          "columns",
          "rows",
          "meta"
        ]
      },
      "ContactExportColumn": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "TEXT",
              "GENDER",
              "DATE",
              "EMAILS",
              "PHONES",
              "TEXT_ARRAY",
              "BOOL",
              "DATETIME",
              "NUMBER"
            ]
          }
        },
        "required": [
          "id",
          "type"
        ]
      },
      "ContactExportRow": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "cells": {
            "type": "array",
            "minItems": 1,
            "maxItems": 40,
            "items": {
              "$ref": "#/components/schemas/ContactExportCell"
            }
          }
        },
        "required": [
          "contactId",
          "cells"
        ]
      },
      "ContactExportCell": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "columnId": {
            "type": "string"
          },
          "value": {
            "oneOf": [
              {
                "oneOf": [
                  {
                    "type": "string",
                    "nullable": true
                  },
                  {
                    "type": "number"
                  },
                  {
                    "type": "boolean"
                  }
                ]
              },
              {
                "type": "array",
                "items": {
                  "oneOf": [
                    {
                      "type": "string",
                      "nullable": true
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "boolean"
                    }
                  ]
                }
              }
            ]
          }
        },
        "required": [
          "columnId",
          "value"
        ]
      },
      "ContactExportMeta": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "selectedCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2000
          },
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "order": {
            "type": "string",
            "enum": [
              "ID_ASC"
            ]
          },
          "readAt": {
            "type": "string",
            "format": "date-time"
          },
          "consistentSnapshot": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "selectedCount",
          "count",
          "hasMore",
          "nextCursor",
          "order",
          "readAt",
          "consistentSnapshot"
        ]
      },
      "ContactExportError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "UnisoftRequest_169b8464c56f9629f796": {
        "type": "object",
        "properties": {
          "tags": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 400,
              "pattern": "^[^\\u0000]+$"
            },
            "description": "Exact observed category strings, including a leading # when present. These are labels, never category UUIDs."
          },
          "tagMode": {
            "type": "string",
            "enum": [
              "any",
              "all",
              "none"
            ]
          },
          "listIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 400,
              "pattern": "^[^\\u0000]+$"
            },
            "description": "Exact current calculated-list IDs: form:<UUID>, product:<formUUID>:<productUUID>, cagnotte:<UUID>, event:<UUID>, fundraising:<UUID>. An object UUID alone is not a list ID."
          },
          "listMode": {
            "type": "string",
            "enum": [
              "any",
              "all",
              "none"
            ]
          },
          "poleIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid",
              "nullable": true
            },
            "description": "Current pole UUIDs; null identifies the organisation main pole. Matches any selected current live pole membership, never a stored projection used as an access grant."
          },
          "customFields": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/UnisoftRequest_302e8df769b310d93b74"
            }
          },
          "archived": {
            "type": "boolean",
            "description": "Omitted or false selects contacts not marked archived; true selects archived contacts. This is independent from deceased/isNew. Missing source flags stay null in results."
          },
          "deceased": {
            "type": "boolean",
            "description": "true selects marked deceased; false selects not marked deceased, including an absent legacy flag. Omission imposes no deceased filter."
          },
          "isNew": {
            "type": "boolean",
            "description": "true selects marked new; false selects not marked new, including an absent legacy flag. This is not a creation-date or membership-status filter."
          }
        },
        "additionalProperties": false
      },
      "UnisoftRequest_302e8df769b310d93b74": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120,
                "pattern": "^[^\\u0000]+$",
                "description": "Exact observed custom-field key, paired with its stored type. Copy it from the authorised contact catalogue; no normalisation, database path or expression is accepted."
              },
              "type": {
                "type": "string",
                "enum": [
                  "TEXT"
                ]
              },
              "values": {
                "type": "array",
                "minItems": 1,
                "maxItems": 20,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 400,
                  "pattern": "^[^\\u0000]+$"
                }
              },
              "mode": {
                "type": "string",
                "enum": [
                  "any",
                  "all",
                  "none"
                ]
              }
            },
            "required": [
              "key",
              "type",
              "values"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120,
                "pattern": "^[^\\u0000]+$",
                "description": "Exact observed custom-field key, paired with its stored type. Copy it from the authorised contact catalogue; no normalisation, database path or expression is accepted."
              },
              "type": {
                "type": "string",
                "enum": [
                  "BOOL"
                ]
              },
              "value": {
                "type": "boolean"
              }
            },
            "required": [
              "key",
              "type",
              "value"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120,
                "pattern": "^[^\\u0000]+$",
                "description": "Exact observed custom-field key, paired with its stored type. Copy it from the authorised contact catalogue; no normalisation, database path or expression is accepted."
              },
              "type": {
                "type": "string",
                "enum": [
                  "NUMBER"
                ]
              },
              "min": {
                "type": "number",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "max": {
                "type": "number",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              }
            },
            "required": [
              "key",
              "type"
            ],
            "additionalProperties": false,
            "anyOf": [
              {
                "required": [
                  "min"
                ]
              },
              {
                "required": [
                  "max"
                ]
              }
            ]
          },
          {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120,
                "pattern": "^[^\\u0000]+$",
                "description": "Exact observed custom-field key, paired with its stored type. Copy it from the authorised contact catalogue; no normalisation, database path or expression is accepted."
              },
              "type": {
                "type": "string",
                "enum": [
                  "DATE"
                ]
              },
              "from": {
                "type": "string",
                "format": "date"
              },
              "to": {
                "type": "string",
                "format": "date"
              }
            },
            "required": [
              "key",
              "type"
            ],
            "additionalProperties": false,
            "anyOf": [
              {
                "required": [
                  "from"
                ]
              },
              {
                "required": [
                  "to"
                ]
              }
            ]
          },
          {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120,
                "pattern": "^[^\\u0000]+$",
                "description": "Exact observed custom-field key, paired with its stored type. Copy it from the authorised contact catalogue; no normalisation, database path or expression is accepted."
              },
              "type": {
                "type": "string",
                "enum": [
                  "DATETIME"
                ]
              },
              "from": {
                "type": "string",
                "format": "date-time"
              },
              "to": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "key",
              "type"
            ],
            "additionalProperties": false,
            "anyOf": [
              {
                "required": [
                  "from"
                ]
              },
              {
                "required": [
                  "to"
                ]
              }
            ]
          }
        ]
      },
      "ContactDiscoveryError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "field": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactCatalogTagResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactCatalogTag"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactCatalogMeta"
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ContactCatalogTag": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "tag": {
            "type": "string",
            "minLength": 1,
            "maxLength": 400
          }
        },
        "required": [
          "tag"
        ]
      },
      "ContactCatalogMeta": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "readAt": {
            "type": "string",
            "format": "date-time"
          },
          "generation": {
            "type": "string",
            "nullable": true
          },
          "computedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "meaning": {
            "type": "string",
            "enum": [
              "VALID_OBSERVED_VALUES_NOT_VALIDATION_RULES",
              "CURRENT_AUTHORISED_CALCULATED_LISTS",
              "CURRENT_POLE_IDENTIFIERS"
            ]
          }
        },
        "required": [
          "count",
          "hasMore",
          "nextCursor",
          "readAt",
          "generation",
          "computedAt",
          "meaning"
        ]
      },
      "ContactCatalogError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactCatalogFieldResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactCatalogField"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactCatalogMeta"
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ContactCatalogField": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "key": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "type": {
            "type": "string",
            "enum": [
              "TEXT",
              "NUMBER",
              "DATE",
              "DATETIME",
              "BOOL"
            ]
          },
          "operators": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "hasObservedValues": {
            "type": "boolean"
          },
          "unit": {
            "type": "string",
            "enum": [
              "NATIVE_UNSPECIFIED",
              null
            ],
            "nullable": true
          }
        },
        "required": [
          "key",
          "type",
          "operators",
          "hasObservedValues",
          "unit"
        ]
      },
      "ContactCatalogValueResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactCatalogValue"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactCatalogMeta"
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ContactCatalogValue": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "key": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "type": {
            "type": "string",
            "enum": [
              "TEXT"
            ]
          },
          "value": {
            "type": "string",
            "minLength": 1,
            "maxLength": 400
          }
        },
        "required": [
          "key",
          "type",
          "value"
        ]
      },
      "ContactCatalogListResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactCatalogList"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactCatalogMeta"
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ContactCatalogList": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "form",
              "product",
              "cagnotte",
              "event",
              "fundraising"
            ]
          },
          "sourceId": {
            "type": "string",
            "format": "uuid"
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "historyIncomplete": {
            "type": "boolean"
          },
          "availableForSearch": {
            "type": "boolean"
          },
          "requiredScopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "id",
          "kind",
          "sourceId",
          "label",
          "historyIncomplete",
          "availableForSearch",
          "requiredScopes"
        ]
      },
      "ContactCatalogPoleResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactCatalogPole"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactCatalogMeta"
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ContactCatalogPole": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "main": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "label",
          "main"
        ]
      },
      "ContactTagCommandCapabilitiesResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactTagCommandCapabilities"
          }
        }
      },
      "ContactTagCommandCapabilities": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "resource",
          "identity",
          "supported",
          "actions",
          "previewAvailable",
          "applyAvailable",
          "maximumObservedRecords"
        ],
        "properties": {
          "resource": {
            "type": "string",
            "enum": [
              "ORGANISATION_TAG"
            ]
          },
          "identity": {
            "type": "string",
            "enum": [
              "EXACT_LABEL"
            ]
          },
          "supported": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "actions": {
            "type": "array",
            "minItems": 3,
            "maxItems": 3,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "RENAME",
                "MERGE",
                "REMOVE"
              ]
            }
          },
          "previewAvailable": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "applyAvailable": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "maximumObservedRecords": {
            "type": "integer",
            "enum": [
              5000
            ]
          }
        }
      },
      "ContactTagCommandPreviewResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactTagCommandPreview"
          }
        }
      },
      "ContactTagCommandPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "command",
          "revision",
          "observedAt",
          "counts",
          "affectedRecords",
          "savedAudiencesUpdated",
          "accessRestrictionsPreservedOnRemoval",
          "snapshotGuaranteed",
          "poleRestrictionsEmptied"
        ],
        "properties": {
          "command": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "action",
              "sourceTag",
              "targetTag"
            ],
            "properties": {
              "action": {
                "type": "string",
                "enum": [
                  "RENAME",
                  "MERGE",
                  "REMOVE"
                ]
              },
              "sourceTag": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              },
              "targetTag": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500,
                "nullable": true
              }
            }
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "observedAt": {
            "type": "string",
            "format": "date-time"
          },
          "counts": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "contacts",
              "legacyAppointments",
              "sharedTagSets",
              "accessRestrictions",
              "poleRestrictions"
            ],
            "properties": {
              "contacts": {
                "type": "object",
                "nullable": true,
                "additionalProperties": false,
                "required": [
                  "sourceRecords",
                  "targetRecords"
                ],
                "properties": {
                  "sourceRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  },
                  "targetRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  }
                }
              },
              "legacyAppointments": {
                "type": "object",
                "nullable": true,
                "additionalProperties": false,
                "required": [
                  "sourceRecords",
                  "targetRecords"
                ],
                "properties": {
                  "sourceRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  },
                  "targetRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  }
                }
              },
              "sharedTagSets": {
                "type": "object",
                "nullable": true,
                "additionalProperties": false,
                "required": [
                  "sourceRecords",
                  "targetRecords"
                ],
                "properties": {
                  "sourceRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  },
                  "targetRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  }
                }
              },
              "accessRestrictions": {
                "type": "object",
                "nullable": true,
                "additionalProperties": false,
                "required": [
                  "sourceRecords",
                  "targetRecords"
                ],
                "properties": {
                  "sourceRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  },
                  "targetRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  }
                }
              },
              "poleRestrictions": {
                "type": "object",
                "nullable": true,
                "additionalProperties": false,
                "required": [
                  "sourceRecords",
                  "targetRecords"
                ],
                "properties": {
                  "sourceRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  },
                  "targetRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  }
                }
              }
            }
          },
          "affectedRecords": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5000
          },
          "savedAudiencesUpdated": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "accessRestrictionsPreservedOnRemoval": {
            "type": "boolean"
          },
          "snapshotGuaranteed": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "poleRestrictionsEmptied": {
            "type": "integer",
            "minimum": 0,
            "maximum": 5000
          }
        }
      },
      "ContactTagCommandReceiptResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactTagCommandReceipt"
          }
        }
      },
      "ContactTagCommandReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "command",
          "state",
          "phase",
          "canRetry",
          "error",
          "remainingSourceRecords",
          "verifiedRecords",
          "startedAt",
          "finishedAt"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "command": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "action",
              "sourceTag",
              "targetTag"
            ],
            "properties": {
              "action": {
                "type": "string",
                "enum": [
                  "RENAME",
                  "MERGE",
                  "REMOVE"
                ]
              },
              "sourceTag": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              },
              "targetTag": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500,
                "nullable": true
              }
            }
          },
          "state": {
            "type": "string",
            "enum": [
              "ADMITTING",
              "RUNNING",
              "COMPLETED",
              "REJECTED",
              "PARTIAL",
              "UNKNOWN"
            ]
          },
          "phase": {
            "type": "string"
          },
          "canRetry": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "remainingSourceRecords": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 5000
          },
          "verifiedRecords": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 5000
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format: `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
