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

# Invite a person to join the firm

> Invites a person who has no login yet to the firm associated with the authenticated client;
accepting the invitation creates their login. The invitation is recorded asynchronously, so
the returned link answers 404 for a few seconds. Set `sendEmail` to false to deliver it yourself.



## OpenAPI

````yaml /openapi.json post /invitations
openapi: 3.0.1
info:
  title: API
  version: '1.0'
servers:
  - url: https://api.smokeball.com
  - url: https://api.smokeball.com.au
  - url: https://api.smokeball.co.uk
  - url: https://stagingapi.smokeball.com
  - url: https://stagingapi.smokeball.com.au
  - url: https://stagingapi.smokeball.co.uk
security:
  - api-key: []
    token: []
paths:
  /invitations:
    post:
      tags:
        - Invitations
      summary: Invite a person to join the firm
      description: "Invites a person who has no login yet to the firm associated with the authenticated client;\r\naccepting the invitation creates their login. The invitation is recorded asynchronously, so\r\nthe returned link answers 404 for a few seconds. Set `sendEmail` to false to deliver it yourself."
      operationId: CreateInvitationAsync
      requestBody:
        description: The person to invite.
        content:
          application/json-patch+json:
            schema:
              allOf:
                - $ref: '#/components/schemas/InvitationDto'
              description: An invitation to create.
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/InvitationDto'
              description: An invitation to create.
          application/*+json:
            schema:
              allOf:
                - $ref: '#/components/schemas/InvitationDto'
              description: An invitation to create.
      responses:
        '202':
          description: >-
            When the request is accepted. Returns a hypermedia 'Link' object of
            the invitation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: >-
            When the email address is invalid, the authenticated client carries
            no user id ('Inviting user is required'), a login for the email
            address already belongs to this firm ('Already registered with this
            firm') or to another firm ('Registered with another firm'), or an
            invitation for it has not expired yet ('An unexpired invitation
            already exists for this email address').
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: >-
            When the inviting user is not a member of the firm ('User is not
            associated to the specified account'), or the authenticated client
            carries no firm account (bodyless).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    InvitationDto:
      required:
        - email
      type: object
      properties:
        email:
          minLength: 1
          type: string
          description: Email address of the person being invited to join the firm.
          format: email
          example: jane.doe@example.com
        sendEmail:
          type: boolean
          description: >-
            Whether the platform emails the invitation (default true); false to
            deliver it yourself.
          example: true
      additionalProperties: false
      description: An invitation to create.
    Link:
      type: object
      properties:
        id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
  securitySchemes:
    api-key:
      type: apiKey
      name: x-api-key
      in: header
    token:
      type: apiKey
      name: Authorization
      in: header
      x-amazon-apigateway-authtype: cognito_user_pools

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.