# personalTax.shareholder.addPerson

As a freshly verified company administrator, save a known verified associated person's real shareholder details in this exact company without switching workspaces. Requires ownerUserId, real holder fields, optional explicit existingHolderId, current register and target association fingerprints. Notifies the selected person and responsible company administrators through the verified notice and email queue. Preserves all other people, classes, holdings and officers. Never invent ownership, submit a tax number, create a setup request or approve personal sharing. Use the native reviewed person form.

`POST /api/v1/accounting/personalTax.shareholder.addPerson`

Permissions: `accounting:read`, `accounting:write`, `accounting:admin` · Roles: admin, finance, contributor, accountant · Idempotency key required · Reaches outside Oatmilk (email or a provider)

Not available over MCP: Saving another verified person's shareholder details requires fresh administrator access in the explicitly selected company and accounting:admin OAuth consent. A broad personal-action role policy never grants that company permission.

## Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `organizationId` | string | Yes | The company to work in, for people who belong to more than one. API keys belong to one company. 1–200 characters. |
| `ownerUserId` | string | Yes | 1–200 characters. |
| `existingHolderId` | string |  | Matches ^[a-z0-9][a-z0-9-]{7,39}$. |
| `holder` | object | Yes | No other fields. |
| `holder.legalName` | string | Yes | 1–200 characters. |
| `holder.email` | string (email) | Yes | An email address. at most 254 characters. |
| `holder.residency` | enum | Yes | One of: `canada`, `other`. |
| `holder.address` | object | Yes | No other fields. |
| `holder.address.line1` | string | Yes | at most 120 characters. |
| `holder.address.line2` | string | Yes | at most 120 characters. |
| `holder.address.city` | string | Yes | at most 80 characters. |
| `holder.address.region` | string | Yes | at most 80 characters. |
| `holder.address.postalCode` | string | Yes | at most 20 characters. |
| `holder.address.country` | string | Yes | exactly 2 characters. |
| `holder.note` | string |  | A short note, kept with the record. at most 500 characters. |
| `expectedRegisterRevision` | integer | Yes | The related record's current revision, from the last time you read it. 0 to 1000000000. |
| `expectedAssociationFingerprint` | string | Yes | SHA-256 hash as 64 lowercase hex characters. |
| `idempotencyKey` | string | Yes | Any unique text you generate once per intended change, so a retried request only happens once. Send it as the Idempotency-Key header instead if you prefer; if you send both they must match. 8–200 characters. |

## Example request

```bash
curl https://app.getoatmilk.com/api/v1/accounting/personalTax.shareholder.addPerson \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "organizationId": "example",
  "ownerUserId": "example",
  "holder": {
    "legalName": "Synthetic Ventures Inc.",
    "email": "finance@example.com",
    "residency": "canada",
    "address": {
      "line1": "example",
      "line2": "example",
      "city": "example",
      "region": "example",
      "postalCode": "example",
      "country": "CA"
    }
  },
  "expectedRegisterRevision": 3,
  "expectedAssociationFingerprint": "9f2b5c1d7e3a4b6c8d0e2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a2b4c"
}'
```

Reference page: https://app.getoatmilk.com/docs/api/personalTax.shareholder.addPerson