> ## Documentation Index
> Fetch the complete documentation index at: https://opentrain.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Invite Team Member

> Invite a human to the workspace team by email — sends the same invitation as the in-app flow.

Invites a human to the employer team by email, giving them shared access to the account's jobs and team inbox once they accept. This sends the same invitation email as the in-app flow.

The outcome depends on the email:

| `status`         | What happened                                                                                                         |
| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| `invite_created` | An invitation email was sent; the invite appears in [`GET /team`](/docs/developers/api-reference/team/list) until accepted |
| `member_added`   | The email belongs to an existing OpenTrain account — they were added to the team directly, no email round-trip        |
| `already_member` | Already on the team; nothing changed                                                                                  |

**Requirements:** `team:write` scope + the `public_api_team` feature + a **claimed** account (unclaimed accounts get `403` with `details.reason: "account_claim_required"` and a `claimUrl`).

## Request

<ParamField body="email" type="string" required>
  Email address to invite. Must be a valid email.
</ParamField>

## Response

<ResponseField name="ok" type="boolean">
  `true` on success.
</ResponseField>

<ResponseField name="status" type="string">
  `invite_created`, `member_added`, or `already_member` (see the table above).
</ResponseField>

<ResponseField name="email" type="string">
  The email that was invited.
</ResponseField>

<ResponseField name="team" type="object">
  The refreshed team record — same shape as [`GET /team`](/docs/developers/api-reference/team/list) — so you can confirm the new member or pending invite without a second call.
</ResponseField>

## Errors

| Status | `code`         | Meaning                                                                                                                                                                                                       |
| ------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `BAD_REQUEST`  | Body missing/not valid JSON, `email` invalid (`details.issues`), or the invite was rejected by validation (`details.email`)                                                                                   |
| `401`  | `UNAUTHORIZED` | Missing or invalid token                                                                                                                                                                                      |
| `403`  | `FORBIDDEN`    | Missing `team:write`, `public_api_team` disabled, employer teams not enabled (`details.reason: "teams_not_enabled"`), or account not claimed (`details.reason: "account_claim_required"`, `details.claimUrl`) |
| `409`  | `CONFLICT`     | The invitation email could not be sent (`details.reason: "invite_email_send_failed"`) — retry later                                                                                                           |

<RequestExample>
  ```bash curl theme={null}
  curl -sS -X POST https://app.opentrain.ai/api/public/v1/team/invites \
    -H "Authorization: Bearer $OT_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"email": "newhire@example.com"}'
  ```

  ```bash CLI theme={null}
  opentrain team invite --email newhire@example.com --json
  ```

  ```json MCP: opentrain_invite_team_member theme={null}
  {
    "email": "newhire@example.com"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 (invite created) theme={null}
  {
    "ok": true,
    "status": "invite_created",
    "email": "newhire@example.com",
    "team": {
      "organization": {
        "id": "<ORGANIZATION_ID>",
        "name": "Acme Research",
        "ownerUserId": "<OWNER_USER_ID>",
        "ownerName": "Dana Owner"
      },
      "members": [
        {
          "userId": "<OWNER_USER_ID>",
          "role": "OWNER",
          "name": "Dana Owner",
          "email": "dana@example.com",
          "joinedAt": "2026-05-01T09:00:00.000Z"
        }
      ],
      "invites": [
        {
          "id": "<INVITE_ID>",
          "email": "newhire@example.com",
          "createdAt": "2026-06-12T10:00:00.000Z",
          "expiresAt": "2026-06-19T10:00:00.000Z"
        }
      ]
    }
  }
  ```

  ```json 403 (unclaimed account) theme={null}
  {
    "error": "A human must claim this agent account before it can invite team members.",
    "code": "FORBIDDEN",
    "requestId": "<REQUEST_ID>",
    "details": {
      "reason": "account_claim_required",
      "action": "invite team members",
      "claimUrl": "https://app.opentrain.ai/claim"
    }
  }
  ```
</ResponseExample>