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

> **גרסה זו של ה־API מיושנת.** לחיבורים חדשים יש להשתמש בגרסה העדכנית ביותר. [לתיעוד העדכני](/integrations/v2/docs?lang=he)

# Contacts

OpenAPI 3.0.3 · API 1.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v1",
    "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/ContactCreateInput"
      },
      "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)."
}
```

### תגובות

#### 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/ContactNormalizeInput"
      },
      "example": {
        "rows": [
          {
            "phone": "06 12 34 56 78",
            "birthDate": "15/03/1990",
            "gender": "Mme",
            "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": {
        "$ref": "#/components/schemas/ContactLookupInput"
      },
      "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/ContactImportInput"
      },
      "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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### תגובות

#### 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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactUpdateInput"
      },
      "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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactAddressInput"
      },
      "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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

```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": {
        "$ref": "#/components/schemas/ContactAddressPatchInput"
      }
    }
  }
}
```

### תגובות

#### 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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPhoneInput"
      },
      "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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactEmailInput"
      },
      "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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTagsInput"
      },
      "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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

```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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCustomFieldsInput"
      },
      "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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

```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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactFamilyLinkInput"
      },
      "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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

```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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactChildInput"
      },
      "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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

```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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionInput"
      },
      "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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### תגובות

#### 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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### תגובות

#### 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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDocumentInput"
      },
      "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",
    "format": "uuid",
    "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}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

```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
  }
}
```

## סכמות

```json
{
  "components": {
    "parameters": {
      "LimitParam": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 50
        },
        "description": "Number of results per page"
      },
      "CursorParam": {
        "name": "cursor",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "Opaque cursor returned by the previous request"
      },
      "CreatedAfterParam": {
        "name": "createdAfter",
        "in": "query",
        "schema": {
          "type": "string",
          "format": "date-time"
        },
        "description": "Filter: created after this date (ISO 8601)"
      },
      "IdParam": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid",
          "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}$"
        },
        "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
      }
    },
    "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"
          }
        }
      },
      "ContactCreateInput": {
        "type": "object",
        "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.",
        "required": [],
        "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"
            ],
            "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",
            "description": "Extra SECONDARY addresses to add.",
            "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"
                }
              }
            }
          },
          "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": {
              "$ref": "#/components/schemas/ContactFieldEntry"
            },
            "description": "Typed key/value custom fields (upsert-by-key). On create/import these are fill-if-empty (append-only). Distinct from `tags[]`."
          }
        }
      },
      "ContactFieldEntry": {
        "type": "object",
        "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).",
        "required": [
          "key"
        ],
        "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)."
          }
        }
      },
      "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": "The import options (dedupStrategy, defaultPhoneCountry, dateFormat, requireContact, applyTags) with their allowed values and defaults, mirroring the import step of the admin ImportPage.",
            "additionalProperties": true
          }
        }
      },
      "ContactNormalizeInput": {
        "type": "object",
        "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`.",
        "required": [
          "rows"
        ],
        "properties": {
          "rows": {
            "type": "array",
            "description": "Each object holds the raw cell values of one spreadsheet row.",
            "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."
                }
              }
            }
          },
          "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."
          }
        }
      },
      "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"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ContactLookupInput": {
        "type": "object",
        "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).",
        "required": [
          "items"
        ],
        "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)."
                }
              }
            }
          },
          "defaultPhoneCountry": {
            "type": "string",
            "description": "ISO country to normalise local phones. Default \"ZZ\"."
          }
        }
      },
      "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"
              }
            }
          }
        }
      },
      "ContactImportInput": {
        "type": "object",
        "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.",
        "required": [
          "contacts"
        ],
        "properties": {
          "contacts": {
            "type": "array",
            "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).",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/ContactCreateInput"
                },
                {
                  "type": "object",
                  "properties": {
                    "__row": {
                      "description": "Original spreadsheet row number, echoed as `report.lines[].row`."
                    }
                  }
                }
              ]
            }
          },
          "options": {
            "type": "object",
            "description": "Import options.",
            "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\")."
              }
            }
          },
          "dryRun": {
            "type": "boolean",
            "description": "true = validate + plan only, NO write. Counters are PROJECTED; `report.lines` shows the action per row.",
            "default": false
          }
        }
      },
      "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."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ContactUpdateInput": {
        "type": "object",
        "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.",
        "required": [],
        "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"
            ],
            "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"
          }
        }
      },
      "ContactAddressInput": {
        "type": "object",
        "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.",
        "required": [
          "address"
        ],
        "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"
          }
        }
      },
      "ContactAddressPatchInput": {
        "type": "object",
        "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).",
        "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"
          }
        }
      },
      "ContactPhoneInput": {
        "type": "object",
        "description": "A SECONDARY phone to append (deduped). The primary phone is set via POST/PATCH /contacts.",
        "required": [
          "phone"
        ],
        "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."
          }
        }
      },
      "ContactEmailInput": {
        "type": "object",
        "description": "A SECONDARY email to append (deduped). The primary email is set via POST/PATCH /contacts.",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "description": "Email (lower-cased; 400 INVALID_EMAIL if invalid)."
          }
        }
      },
      "ContactTagsInput": {
        "type": "object",
        "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).",
        "required": [
          "tags"
        ],
        "properties": {
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Tags, e.g. [\"Donateur\", \"Séder night\"] → stored DONATEUR, SEDER_NIGHT."
          }
        }
      },
      "ContactCustomFieldsInput": {
        "type": "object",
        "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.",
        "required": [
          "customFields"
        ],
        "properties": {
          "customFields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactFieldEntry"
            },
            "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
          }
        }
      },
      "ContactFamilyLinkInput": {
        "type": "object",
        "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).",
        "required": [
          "relationship",
          "relatedContactId"
        ],
        "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)."
          }
        }
      },
      "ContactChildInput": {
        "type": "object",
        "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.",
        "required": [
          "firstName"
        ],
        "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)."
          }
        }
      },
      "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
          }
        }
      },
      "ContactInteractionInput": {
        "type": "object",
        "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.",
        "required": [
          "type"
        ],
        "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 »]."
          }
        }
      },
      "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
          }
        }
      },
      "ContactDocumentInput": {
        "type": "object",
        "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.",
        "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)."
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format: `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
