# Invite Member

> Invite someone to the workspace by email.

Requires an API key with the `write` scope.

N e

**Sends a real email** from FoxReach to the address, naming the user who created the key. Inviting an address again resets its link and role. The invite link is never returned by the API. The call writes an `audit.workspace_member.invited` entry in the event log.

## Body Parameters

<ParamField body="email" type="string" required>
  The address to invite.
</ParamField>

<ParamField body="role" type="string">
  `member` (default) or `admin`. `owner` is not accepted.
</ParamField>

## Response

Returns the invitation in `data`. Your plan's team member limit applies.

<RequestExample>
```bash cURL
curl -X POST "https://api.foxreach.io/api/v1/workspace/members/invite" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "sam@example.com", "role": "member"}'
```

```python Python SDK
from foxreach import FoxReach

client = FoxReach(api_key="otr_your_key")
invite = client.workspace.invite("sam@example.com")
```

```typescript TypeScript SDK
import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });
const invite = await client.workspace.invite("sam@example.com");
```

</RequestExample>

<ResponseExample>
```json
{ "data": { "id": "wsi_abc123", "email": "sam@example.com", "role": "member", "invitedBy": "usr_1", "expiresAt": "2026-11-11T09:30:00+00:00", "acceptedAt": null, "createdAt": "2026-11-04T09:30:00+00:00", "workspaceId": "ws_abc123", "workspaceName": "Acme", "invitedByName": "Alex Doe" } }
```
</ResponseExample>

## Errors

| Status | Description |
|--------|-------------|
| `401` | Missing, invalid, revoked or expired API key |
| `403` | The key lacks the `admin` or `write` scope, or its creator lacks the required role |
| `400` | The person is already a member |
| `403` | Plan team member limit reached (`upgrade_required`) |
| `422` | Invalid email, or a role other than `admin` or `member` |

## Rate Limit

- **100 requests per minute, shared by every `expensive` call in your workspace.** Fixed 60-second window.
- Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (unix epoch seconds) and `X-RateLimit-Bucket` (`expensive`).
- A `429` response includes a `Retry-After` header (seconds until the bucket resets).

For client-side patterns, see [Rate Limiting](/rate-limiting).