---
title: "Invite a teammate"
method: POST
path: "/team/invitations"
tags: ["Team & settings", "Human only"]
---

# Invite a teammate

`POST /team/invitations`

## Request

- Base URL: `https://gtmswag.com/api/v1`
- URL: `https://gtmswag.com/api/v1/team/invitations`
- Auth: API key in cookie `gtm_session`

Human only: A signed-in owner or admin does this in the browser at gtmswag.com. API keys and OAuth connections receive 403 HUMAN_APPROVAL_REQUIRED with a `url` to hand to that person. Only the owner may invite admins. Returns a private `inviteUrl` (valid 7 days).

## Request body

- object
  - `email` string, email, required: Recipient or teammate email address.
  - `role` 'admin' | 'member', required: Workspace role; only owners may grant admin access.

## Response `201`

Success: `{"data": TeamInvitationCreated}`.

- TeamInvitationCreatedResponse: The success body: `{"data": TeamInvitationCreated}`.
  - `data` TeamInvitationCreated, required: The new invitation and its private `inviteUrl` (valid 7 days).
    - `invitation` TeamInvitation, required: An invitation to join the workspace.
      - `id` string, required
      - `email` string, required
      - `status` 'pending' | 'accepted' | 'revoked' | 'expired', required
    - `inviteUrl` string, required
    - `emailQueued` boolean, required

## Other responses

- `400`: Bad request: `VALIDATION_ERROR`, `INVALID_JSON`. Each example says when.
- `401`: Not authenticated: `AUTH_REQUIRED`. no credentials, or an OAuth token on a route that only takes workspace keys; the key is malformed, unknown or revoked.
- `403`: Forbidden: `HUMAN_APPROVAL_REQUIRED`, `TEAM_MANAGER_REQUIRED`, `ACCOUNT_REQUIRED`, `TEAM_OWNER_REQUIRED`. Each example says when.
- `409`: Conflict: `ALREADY_MEMBER`, `TEAM_CHANGED`. Each example says when.
- `413`: Request too large: `INVALID_REQUEST`. the body exceeds 1 MiB.
- `415`: Unsupported media type: `INVALID_REQUEST`. a write with a body that is not `Content-Type: application/json` (a key request with no body needs no Content-Type).
- `429`: Too many requests: `RATE_LIMIT`. Each example says when.
- `default`: Any other refusal or failure, such as 403 CSRF (a cross-origin `Origin` header), 403 HTTPS_REQUIRED or 500 INTERNAL_ERROR, with what to do next.

---

[API](https://skmtc.dev/gtmswag/apis/gtm-swag-api.md) · [All operations](https://skmtc.dev/gtmswag/apis/gtm-swag-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gtmswag/apis/gtm-swag-api/revisions/9ff86fa99afe?raw)