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

# Invite a candidate to assessments

> POST /v1/invite



## OpenAPI

````yaml POST /v1/invite
openapi: 3.0.1
info:
  title: Connect Api
  version: '1.0'
servers:
  - url: https://api.hiringbranch.com/connect
security:
  - ApiKey: []
paths:
  /v1/invite:
    post:
      tags:
        - Invite
      summary: Invite a new or existing candidate to one or more assessments
      description: POST /v1/invite
      parameters:
        - name: instance
          in: header
          description: Name of the instance
          required: true
          schema:
            type: string
        - name: sendInvite
          in: query
          description: Determines if the invite should be sent by us
          schema:
            type: boolean
            default: false
      requestBody:
        description: Information about the candidate and the assessments for the invite
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InviteDto'
          text/json:
            schema:
              $ref: '#/components/schemas/InviteDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/InviteDto'
        required: true
      responses:
        '200':
          description: List of links and invitation status
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InviteResponseDto'
        '400':
          description: Validation failed
components:
  schemas:
    InviteDto:
      required:
        - assessments
        - email
        - firstName
        - lastName
      type: object
      properties:
        email:
          minLength: 1
          type: string
          description: Candidate's email
          example: candidate@enterprise.com
        firstName:
          minLength: 1
          type: string
          description: Candidate's first name
          example: John
        lastName:
          minLength: 1
          type: string
          description: Candidate's last name
          example: Doe
        assessments:
          type: array
          items:
            type: string
          description: Assessment ids separated by comma to invite the candidate to
          example:
            - 59bc377497c7ac0cbc1b69c7
            - 59bc377497c7ac0cbc1b69c8
            - 59bc377497c7ac0cbc1b69c9
      additionalProperties: false
    InviteResponseDto:
      required:
        - candidateId
        - link
      type: object
      properties:
        link:
          minLength: 1
          type: string
          description: SSO link for the candidate to connect to the assessment(s)
          example: >-
            https://portal.hiringbranch.com/abc/#?sessionToken=123456789123456789
        invitationStatus:
          $ref: '#/components/schemas/InvitationStatus'
        candidateId:
          minLength: 1
          type: string
          description: Candidate Id
          example: 59bc377497c7ac0cbc1b69c8
      additionalProperties: false
    InvitationStatus:
      enum:
        - SENT
        - FAILED
      description: Invitation status of the invite to the candidate when sendEmail is true
      type: string
      format: ''
  securitySchemes:
    ApiKey:
      type: apiKey
      description: Api key given by Hiringbranch
      name: X-API-Key
      in: header

````