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

# Add an invite recipient

> Adds a new recipient to an existing invite. An invite can be amended as long as it hasn't been canceled, expired, or converted into an application.



## OpenAPI

````yaml /openapi/application-api.json post /v1/invites/{id}/invite-recipients
openapi: 3.1.0
info:
  description: >-
    Partner API for creating invites, tracking applications, and retrieving
    bonds.
  title: TheGuarantors Application API
  contact: {}
  version: '1.0'
servers:
  - url: https://api.theguarantors.com
security: []
paths:
  /v1/invites/{id}/invite-recipients:
    post:
      tags:
        - Invites
      summary: Add an invite recipient
      description: >-
        Adds a new recipient to an existing invite. An invite can be amended as
        long as it hasn't been canceled, expired, or converted into an
        application.
      parameters:
        - description: Invite ID
          name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddRecipientRequest'
            example:
              first_name: Jordan
              last_name: Lee
              email: jordan.lee@example.com
              phone_number: '+12125551236'
              metadata:
                pms_reference: occupant-3
        description: Recipient to add
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteRecipient'
              example:
                id: ivre_m2kd8xq4hz7tw1pa
                link: >-
                  https://qualify.sandbox.theguarantors.com/invite/sign-up/ivre_m2kd8xq4hz7tw1pa
                first_name: Jordan
                last_name: Lee
                email: jordan.lee@example.com
                phone_number: '+12125551236'
                metadata:
                  pms_reference: occupant-3
                object: invite_recipient
        '400':
          description: >-
            Bad Request


            | `error_code` | When |

            | --- | --- |

            | `invalid_request` | The body is not valid JSON, or a field has the
            wrong type |

            | `validation_error` | The request failed validation; see
            field_errors |
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - object
                  - error_code
                properties:
                  error_code:
                    type: string
                    enum:
                      - invalid_request
                      - validation_error
                  field_errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/FieldError'
                  message:
                    type: string
                  object:
                    type: string
                    example: error
              example:
                message: 'validation error: email: must be a valid email address.'
                error_code: validation_error
                field_errors:
                  - field: email
                    code: invalid_format
                    message: must be a valid email address
                object: error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Missing authorization header
                object: error
        '403':
          description: >-
            Forbidden


            | `error_code` | When |

            | --- | --- |

            | `invite_property_inactive` | The invite's own property is inactive
            |
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - object
                  - error_code
                properties:
                  error_code:
                    type: string
                    enum:
                      - invite_property_inactive
                  message:
                    type: string
                  object:
                    type: string
                    example: error
              example:
                message: cannot amend invite, property is inactive
                error_code: invite_property_inactive
                object: error
        '404':
          description: |-
            Not Found

            | `error_code` | When |
            | --- | --- |
            | `invite_not_found` | The invite was not found |
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - object
                  - error_code
                properties:
                  error_code:
                    type: string
                    enum:
                      - invite_not_found
                  message:
                    type: string
                  object:
                    type: string
                    example: error
              example:
                message: invite not found
                error_code: invite_not_found
                object: error
        '409':
          description: >-
            Conflict


            | `error_code` | When |

            | --- | --- |

            | `invite_accepted` | A recipient has already accepted the invite |

            | `invite_application_started` | The invite is in the process of
            being converted into an application |

            | `invite_canceled` | The invite has been canceled |

            | `invite_expired` | The invite has expired |

            | `duplicate_email_conflict` | The email is already used by another
            recipient on the invite |
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - object
                  - error_code
                properties:
                  error_code:
                    type: string
                    enum:
                      - invite_accepted
                      - invite_application_started
                      - invite_canceled
                      - invite_expired
                      - duplicate_email_conflict
                  message:
                    type: string
                  object:
                    type: string
                    example: error
              example:
                message: email is already used by another recipient on this invite
                error_code: duplicate_email_conflict
                object: error
        '422':
          description: >-
            Unprocessable Entity


            | `error_code` | When |

            | --- | --- |

            | `recipient_limit_exceeded` | The invite would have more than 6
            recipients |
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - object
                  - error_code
                properties:
                  error_code:
                    type: string
                    enum:
                      - recipient_limit_exceeded
                  message:
                    type: string
                  object:
                    type: string
                    example: error
              example:
                message: cannot add recipient, total would exceed maximum of 6
                error_code: recipient_limit_exceeded
                object: error
        '429':
          description: Rate limit exceeded
        '500':
          description: |-
            Internal Server Error

            | `error_code` | When |
            | --- | --- |
            | `internal_error` | An unexpected server error occurred |
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - object
                  - error_code
                properties:
                  error_code:
                    type: string
                    enum:
                      - internal_error
                  message:
                    type: string
                  object:
                    type: string
                    example: error
              example:
                message: unable to add invite recipient
                error_code: internal_error
                object: error
      security:
        - BasicAuth: []
components:
  schemas:
    AddRecipientRequest:
      type: object
      required:
        - email
        - first_name
        - last_name
      properties:
        email:
          description: >-
            Must be unique among the invite's recipients. It's trimmed and
            lowercased before it's saved.
          type: string
          format: email
          example: jordan.lee@example.com
        first_name:
          type: string
          maxLength: 100
          minLength: 1
          example: Jordan
        last_name:
          type: string
          maxLength: 100
          minLength: 1
          example: Lee
        metadata:
          description: >-
            Key-value object. Each key must be a string, and values can be
            strings, numbers, booleans, or null.
          type: object
          nullable: true
        phone_number:
          description: >-
            Phone number in E.164 format, for example `+12125551234`. Spaces and
            formatting characters such as parentheses, dashes and dots are
            removed. A 10-digit number without a country code is treated as a US
            number and gets `+1` added. Include the `+` and country code for any
            other number.
          type: string
          format: e164
          example: '+12125551236'
          nullable: true
    InviteRecipient:
      type: object
      required:
        - email
        - first_name
        - id
        - last_name
        - link
        - object
      properties:
        email:
          type: string
          format: email
          example: dana.whitfield@example.com
        first_name:
          type: string
          example: Dana
        id:
          type: string
          example: ivre_01HQ8Y
        last_name:
          type: string
          example: Whitfield
        link:
          description: >-
            URL that links the prospective renter to their prefilled
            TheGuarantors application.
          type: string
          format: uri
          example: https://qualify.theguarantors.com/invite/sign-up/k3v9q2m7x1p4r8tz
        metadata:
          type: object
          nullable: true
        object:
          type: string
          example: invite_recipient
        phone_number:
          description: >-
            Phone number in E.164 format, for example `+12125551234`. Spaces and
            formatting characters such as parentheses, dashes and dots are
            removed. A 10-digit number without a country code is treated as a US
            number and gets `+1` added. Include the `+` and country code for any
            other number.
          type: string
          example: '+15551234567'
          nullable: true
    FieldError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/FieldErrorCode'
        field:
          type: string
          example: lease.start_date
        message:
          type: string
          example: must be in YYYY-MM-DD format
    ErrorResponse:
      type: object
      required:
        - message
        - object
      properties:
        message:
          type: string
          example: invite not found
        object:
          type: string
          example: error
    FieldErrorCode:
      type: string
      enum:
        - required
        - invalid_format
        - invalid_value
        - out_of_range
        - invalid_length
        - invalid_date_range
        - unknown_field
        - null_not_allowed
        - unsupported_field_edit
        - ambiguous_edit
        - incomplete_edit
        - invalid
      x-enum-comments:
        FieldCodeAmbiguousEdit: The field conflicts with another field in the same request
        FieldCodeIncompleteEdit: The field requires another field in the same request
        FieldCodeInvalid: The value is invalid for any other reason
        FieldCodeInvalidDateRange: end_date is not after start_date
        FieldCodeInvalidFormat: The value is not in the expected format (email, phone, date, id)
        FieldCodeInvalidLength: The value is too short or too long
        FieldCodeInvalidValue: The value is not one of the allowed values
        FieldCodeNullNotAllowed: null is not accepted at this path
        FieldCodeOutOfRange: The number is outside the allowed range
        FieldCodeRequired: The field is missing or blank
        FieldCodeUnknownField: The field is not recognized
        FieldCodeUnsupportedFieldEdit: The field cannot be edited on this invite or recipient entry
      x-enum-descriptions:
        - The field is missing or blank
        - The value is not in the expected format (email, phone, date, id)
        - The value is not one of the allowed values
        - The number is outside the allowed range
        - The value is too short or too long
        - end_date is not after start_date
        - The field is not recognized
        - null is not accepted at this path
        - The field cannot be edited on this invite or recipient entry
        - The field conflicts with another field in the same request
        - The field requires another field in the same request
        - The value is invalid for any other reason
      x-enum-varnames:
        - FieldCodeRequired
        - FieldCodeInvalidFormat
        - FieldCodeInvalidValue
        - FieldCodeOutOfRange
        - FieldCodeInvalidLength
        - FieldCodeInvalidDateRange
        - FieldCodeUnknownField
        - FieldCodeNullNotAllowed
        - FieldCodeUnsupportedFieldEdit
        - FieldCodeAmbiguousEdit
        - FieldCodeIncompleteEdit
        - FieldCodeInvalid
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic

````