Source: https://datafa.st/docs/api/account/team/invite
Markdown source: https://datafa.st/docs/api/account/team/invite.md
Description: Invite a team member by email.

# Invite team member

`POST https://datafa.st/api/v1/admin/websites/{websiteId}/team`

Invite someone to the website by email. They receive an invitation link to accept and join with the specified role.

**Owner only.** Website API keys cannot invite team members.

> **Related:** [Team member roles](/changelog/team-member-roles)

## Request

#### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `websiteId` | string | — | Website ObjectId. From [List websites](/docs/api/account/websites/list) (`_id` field). Example: `665f0b3c4d2e1a0012345678`. |

#### Body parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | Yes | Email to invite. Example: `"colleague@example.com"`. Lowercased before storage. |
| `role` | `viewer` or `member` | No | `"viewer"` (read-only, default) or `"member"` (can manage settings). Cannot invite as `owner`. |

#### Example request body

```json
{
  "email": "colleague@example.com",
  "role": "viewer"
}
```

## Response

Returns a JSON object with `status: "success"` and endpoint-specific fields in `data`.

#### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `data[].message` | string | Human-readable confirmation or status message for the operation. |
| `data[].invitationId` | string | Invitation ObjectId. |
| `data[].email` | string | Invited email address. |
| `data[].role` | string | Role assigned by the invite. |

### Authentication

Use a `dft_` account token with `team:write + owner role`.

A `df_` website API key for the same website can also call this route when the path `websiteId` matches the key's website. Write access with a `df_` key is capped at **member** level — owner-only actions such as [team management](/docs/api/account/team) require a `dft_` token and owner role.

**Owner only:** Inviting and removing team members requires website **owner** role, even with a `dft_` token that has `team:write`.

### Errors

**400** — Invalid email or self-invite.

**403** — Caller is not the website owner, or billing seat limit reached.

**409** — Email is already a member or has a pending invite.

See [API errors](/docs/api#errors) for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

## Code examples

### Example request

```bash
curl -X POST "https://datafa.st/api/v1/admin/websites/{websiteId}/team" \
  -H "Authorization: Bearer dft_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"member@example.com","role":"viewer"}'
```

### Success response

```json
{
  "status": "success",
  "data": [{
    "message": "Invitation created. Send the invite link to the user.",
    "invitationId": "665f0b3c4d2e1a0012345678",
    "email": "member@example.com",
    "role": "viewer"
  }]
}
```