# team.invite

Invite a new team member by email with a role (admin, finance or contributor), an optional message and an idempotency key. Oatmilk emails them a private link when email is enabled; the result always includes a link to share and a delivery status. The link works for 14 days. Only organization administrators can manage the team. MCP calls also require the accounting:admin scope; the direct API cannot send team invitations or remove members.

`POST /api/v1/accounting/team.invite`

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

MCP tool: `accounting_team_invite`

## Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `email` | string (email) | Yes | An email address. at most 320 characters. |
| `role` | enum | Yes | A person's access level in the company. One of: `admin`, `finance`, `contributor`. |
| `message` | string |  | at most 1000 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/team.invite \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "email": "finance@example.com",
  "role": "admin"
}'
```

Reference page: https://app.getoatmilk.com/docs/api/team.invite