# contractorOps.agreements.linkContractor

File a signed agreement or NDA that has no contractor with an existing contractor (envelopeId, contractorId, idempotencyKey). An agreement newer than their terms is read for its terms to check and replaces them once confirmed (a draft read from an older agreement is replaced; while an update is out for signature it waits); an older or undated one is kept as history and never changes newer terms. An NDA stays apart from the agreement.

`POST /api/v1/accounting/contractorOps.agreements.linkContractor`

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

MCP tool: `accounting_contractor_ops_agreements_link_contractor`

## Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `envelopeId` | string (ID) | Yes | The ID of a document sent for signature, from signing.envelopes.list. |
| `contractorId` | string (ID) | Yes | The ID of a contractor, from contractors.list. |
| `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.agreements.linkContractor \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "envelopeId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "contractorId": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a"
}'
```

Reference page: https://app.getoatmilk.com/docs/api/contractorOps.agreements.linkContractor