---
title: "Create organization invitation"
method: POST
path: "/internal/v1/orgs/{org_id}/invites"
tags: ["Users"]
---

# Create organization invitation

`POST /internal/v1/orgs/{org_id}/invites`

Invite a user to the organization by email. Requires org admin. Behavior:
- If the email maps to an already-confirmed User, attach them as an
  OrgUser (and to any teamIds) immediately. The response includes a
  compact invite summary with status `accepted` and orgId set to the
  attached org; no invite row is inserted.

- If the email maps to an unconfirmed User with a live pending invite for
  this org, return the existing invite with status `sent`. If the
  existing invite is canceled or expired, reactivate it with status
  `sent`.

- Otherwise create the User row (with `email_confirmed=false` if missing),
  create a UserInvite row, send the invitation email, and return it with
  status `sent`.

Subject to a per-inviter cap of 10 pending invites. Every non-accepted invite within the invite TTL counts toward the cap.

## Path parameters

- `org_id` integer, required

## Request body

- UserInviteCreateRequest
  - `email` string, required — Email address of the invitee. Required; trimmed and lowercased server-side.
  - `role` 'owner' | 'admin' | 'member' | 'viewer' | 'billing_manager' | 'collaborator' — A user's role within an organization.
  - `teamIds` integer[] — Teams to add the invitee to on acceptance. Each team must belong to the URL org.

## Response `200`

Invitation created (email sent) or immediately accepted.

- UserInviteResponse — Response from creating or processing an invitation. `user` is a public invitee summary. `invite` is a compact invite summary; `invite.status` is `sent` for pending invitations and `accepted` when the email already maps to a confirmed user. `invite.id` is the persisted invite ID for pending invites and a response-only random ID for already-confirmed users. `invite.orgId` is present for org-scoped actions; when `invite.status` is `accepted` and `invite.orgId` is present, the confirmed user was attached to that org.
  - `user` PublicUser, required — Safe user summary for UI display.
    - `id` integer, required
    - `name` string, required
    - `avatar` string, required — URL to the user's avatar image.
  - `invite` InviteSummary, required — Compact invite summary returned from create-invite endpoints.
    - `id` string, required — 32-character hex trace ID.
    - `status` 'sent' | 'accepted' | 'canceled' | 'expired', required — Lifecycle status of an organization invitation.
    - `orgId` integer — Present for org-scoped invite actions.

## Other responses

- `400` — Invalid request
- `401` — Authentication required
- `403` — Insufficient permissions
- `500` — Internal server error

---

[API](https://skmtc.net/uptrace/apis/uptrace-json-api.md) · [All operations](https://skmtc.net/uptrace/apis/uptrace-json-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/uptrace/uptrace-json-api/versions/550c8881ab9a/schema)