# contractorOps.titleChange.propose

Create a title-change amendment tied to an active organization job role with a different title, copying every other current agreement term and all required signer roles. The contractor uses their current email; company signers must be active finance or admin members. Optional companySigner and signerReplacements select current recipients before send. The title stays pending until every signer signs and its effective date arrives. Requires contractorId, roleId, effectiveFrom, send and idempotencyKey.

`POST /api/v1/accounting/contractorOps.titleChange.propose`

Permissions: `accounting:read`, `accounting:write` · Roles: admin, finance · Idempotency key required

MCP tool: `accounting_contractor_ops_title_change_propose`

## Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `contractorId` | string (ID) | Yes | The ID of a contractor, from contractors.list. |
| `roleId` | string (ID) | Yes | The ID of the related record. |
| `effectiveFrom` | string (date) | Yes |  |
| `send` | boolean |  | Default `true`. |
| `companySigner` | object |  | No other fields. |
| `companySigner.userId` | string |  | The ID of a person in your company. 1–200 characters. |
| `companySigner.name` | string | Yes | A display name. 1–200 characters. |
| `companySigner.email` | string (email) | Yes | An email address. at most 320 characters. |
| `companySigner.title` | string or null |  | A short title. |
| `signerReplacements` | array of objects |  | at most 25 items. |
| `signerReplacements[].recipientId` | string (ID) | Yes | The ID of one signer on a document. |
| `signerReplacements[].name` | string | Yes | A display name. 1–200 characters. |
| `signerReplacements[].email` | string (email) | Yes | An email address. at most 320 characters. |
| `message` | string or null |  |  |
| `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/contractorOps.titleChange.propose \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "contractorId": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
  "roleId": "7f0f6c1e-1c1f-4b5e-9c8d-2f5e8e3c1a10",
  "effectiveFrom": "2026-09-01"
}'
```

Reference page: https://app.getoatmilk.com/docs/api/contractorOps.titleChange.propose