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

# Get candidate for invitation

> Retrieves the candidate information associated with an invitation.



## OpenAPI

````yaml /background-check-api/api-reference/openapi.json get /candidate/invitation/token/{invitationToken}
openapi: 3.1.0
info:
  title: KarmaCheck API
  description: >-
    All requests to the KarmaCheck API require a JSON Web Token (JWT) in the
    Authorization header. For an overview of the API and its authentication
    method, refer to the following topics:


    - [API basics](docs/overview/apis/api-overview.md)

    - [Authentication](docs/overview/apis/authentication.md)

    - [Environments](docs/overview/apis/environments.md)

    - [Status codes and errors](docs/overview/apis/errors.md)
  version: '1.0'
  contact:
    name: KarmaCheck
    email: customersuccess@karmacheck.com
servers:
  - description: Stage
    url: https://api-stage.karmacheck.io
  - description: Prod
    url: https://api.karmacheck.io
security:
  - JWT: []
tags:
  - name: Authentication
  - name: Cases
  - name: Candidate onboarding
  - name: Secure documents
  - name: Packages
  - name: Services
  - name: Users
  - name: Companies
  - name: Partner integrations
paths:
  /candidate/invitation/token/{invitationToken}:
    parameters:
      - schema:
          type: string
          example: 84729060-f3f3-42fc-88fe-c5ac3da46d41
        name: invitationToken
        in: path
        required: true
        description: >-
          The token used for the invitation. This can be retrieved from [Get
          invitation for case
          ID](karma-api-openapi.yaml/paths/~1invitation~1case~1{caseId}/get).
    get:
      tags:
        - Candidate onboarding
      summary: Get candidate for invitation
      description: Retrieves the candidate information associated with an invitation.
      operationId: get-candidate-invitation-token-invitationToken
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - caseId
                  - candidateId
                  - legalStarted
                properties:
                  caseId:
                    type: string
                    description: >-
                      The ID of the case associated with the candidate and
                      invitation.
                  candidateId:
                    type: string
                    description: The ID of the candidate associated with the invitation.
                  legalStarted:
                    type: boolean
                    description: >-
                      True if the candidate began authorization of legal checks
                      (for example, acknowledged a disclosure); false otherwise.
              examples:
                Example 1:
                  value:
                    caseId: 6f84bc4b-9206-49e4-92b2-529c3d5990b3
                    candidateId: 56730732-b977-4e1f-b6d4-ffd96c51ff5b
                    legalStarted: false
        '403':
          description: Forbidden
        '422':
          description: >
            The invitation is no longer valid due to one of the following:

            - The invitation expired.

            - The invitation was canceled and deleted.

            - The invitation was completed. In other words, a candidate
            acknowledged the invitation and completed the onboarding process.
          content:
            application/json:
              schema:
                type: string
              examples:
                Example 1:
                  value: Token is not valid
        '500':
          description: >-
            An error occurred on KarmaCheck's end.


            **Known issue:** The API returns this error instead of a 4xx
            response when either of the following occurs:

            - The invited candidate hasn't initiated the onboarding process.

            - The invitation token provided is invalid.
          content:
            application/json:
              schema:
                type: string
              examples:
                Example 1:
                  value: Server Error
components:
  securitySchemes:
    JWT:
      type: http
      scheme: bearer

````