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

# Create Invitation

> Create a new invitation.

Creates an invitation for a user to join the current user's account.
Sends an invitation email with a secure token.

Flow:
1. Validate email format (handled by Pydantic)
2. Check if user already exists in account
3. Check if pending invitation exists
4. Generate secure token
5. Create invitation record
6. Send invitation email
7. Return invitation details (excluding token)



## OpenAPI

````yaml post /api/v1/invitations
openapi: 3.1.0
info:
  title: SnackBase
  description: Open-source Backend-as-a-Service (BaaS)
  version: 0.1.0
servers: []
security: []
paths:
  /api/v1/invitations:
    post:
      tags:
        - invitations
      summary: Create Invitation
      description: |-
        Create a new invitation.

        Creates an invitation for a user to join the current user's account.
        Sends an invitation email with a secure token.

        Flow:
        1. Validate email format (handled by Pydantic)
        2. Check if user already exists in account
        3. Check if pending invitation exists
        4. Generate secure token
        5. Create invitation record
        6. Send invitation email
        7. Return invitation details (excluding token)
      operationId: create_invitation_api_v1_invitations_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvitationCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitationResponse'
        '400':
          description: Validation error or user already in account
        '409':
          description: Pending invitation already exists
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    InvitationCreateRequest:
      properties:
        email:
          type: string
          format: email
          title: Email
          description: Email address of the user to invite
        role_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Role Id
          description: Optional role ID to assign to the user
        groups:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Groups
          description: Optional list of group IDs to add the user to
        account_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Account Id
          description: Optional account ID (Superadmin only)
      type: object
      required:
        - email
      title: InvitationCreateRequest
      description: Request schema for creating an invitation.
    InvitationResponse:
      properties:
        id:
          type: string
          title: Id
          description: Invitation ID
        account_id:
          type: string
          title: Account Id
          description: Account ID (UUID)
        account_code:
          type: string
          title: Account Code
          description: Human-readable account code in XX#### format (e.g., AB1234)
        email:
          type: string
          title: Email
          description: Email address of the invited user
        invited_by:
          type: string
          title: Invited By
          description: User ID of the inviter
        expires_at:
          type: string
          format: date-time
          title: Expires At
          description: Expiration timestamp
        accepted_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Accepted At
          description: Acceptance timestamp (if accepted)
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Creation timestamp
        email_sent:
          type: boolean
          title: Email Sent
          description: Whether the invitation email has been sent
          default: false
        email_sent_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Email Sent At
          description: Timestamp when the email was sent
        status:
          $ref: '#/components/schemas/InvitationStatus'
          description: Current invitation status
        token:
          type: string
          title: Token
          description: Invitation token for constructing acceptance URL
      type: object
      required:
        - id
        - account_id
        - account_code
        - email
        - invited_by
        - expires_at
        - created_at
        - status
        - token
      title: InvitationResponse
      description: Response schema for invitation details.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    InvitationStatus:
      type: string
      enum:
        - pending
        - accepted
        - expired
        - cancelled
      title: InvitationStatus
      description: Invitation status enum.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````