> ## 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.

# Create candidate by proxy for invitation

> Creates the candidate object in KarmaCheck on behalf of the candidate so that there can be pre-population of PII before the candidate accepts an invitation and enters the system.
The candidate will be directed to onboard the associated case via the one-time token link that will be provided by the API partner.

This API marks the candidate object as not secured in the KarmaCheck system, which results in the candidate being prompted to set a password when the onboarding of the case begins.
After this call is complete, the candidate will be associated with the specific `caseId` that was attached to the invitation. The `caseId` will be used for saving all further case data, such as authorizations and acknowledgements. This assumes that a candidate will need to sign up with KarmaCheck before being able to continue to accept the invitation.




## OpenAPI

````yaml /background-check-api/api-reference/openapi.json post /invitation/candidate/create
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:
  /invitation/candidate/create:
    post:
      tags:
        - Candidate onboarding
      summary: Create candidate by proxy for invitation
      description: >
        Creates the candidate object in KarmaCheck on behalf of the candidate so
        that there can be pre-population of PII before the candidate accepts an
        invitation and enters the system.

        The candidate will be directed to onboard the associated case via the
        one-time token link that will be provided by the API partner.


        This API marks the candidate object as not secured in the KarmaCheck
        system, which results in the candidate being prompted to set a password
        when the onboarding of the case begins.

        After this call is complete, the candidate will be associated with the
        specific `caseId` that was attached to the invitation. The `caseId` will
        be used for saving all further case data, such as authorizations and
        acknowledgements. This assumes that a candidate will need to sign up
        with KarmaCheck before being able to continue to accept the invitation.
      operationId: post-invitation-candidate-create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - caseInvitationId
                - email
                - password
              properties:
                caseInvitationId:
                  type: string
                email:
                  type: string
                  description: The candidate's email address.
                password:
                  type: string
                  description: >-
                    The password for the candidate's account. The supplied
                    password must be at least eight characters long and must
                    contain a lowercase letter, an uppercase letter, a number,
                    and a special character.
                givenName:
                  type: string
                middleName:
                  type: string
                familyName:
                  type: string
                dob:
                  type: string
                  description: The candidate's birthdate in the format *YYYY*-*MM*-*DD*.
                  format: date
                phone:
                  type: string
                govtId:
                  type: string
            examples:
              Example 1:
                value:
                  caseInvitationId: e1f27fde-8ec3-4fa2-abfe-43b7c9f43084
                  email: john.lee@example.com
                  password: Password!1
                  givenName: John
                  middleName: Michael
                  familyName: Lee
                  dob: '1980-09-19'
                  phone: 800-555-0142
                  govtId: 111-11-1111
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  caseId:
                    type: string
                  candidateId:
                    type: string
              examples:
                Example 1:
                  value:
                    caseId: af51d69f-996a-4891-a745-aadfcdec225a
                    candidateId: 10f4deb6-fd4e-4907-a47e-355caf6e449d
        '400':
          description: An invalid `email`, `password`, or `dob` format was passed.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '404':
          description: An invalid `caseInvitationId` was passed.
        '422':
          description: |-
            The candidate cannot be created due to one of the following:

            - The invitation expired.
            - The invitation was deleted.
            - The invitation was completed.
            - The invitation is already associated with another candidate.
            - An account already exists for the candidate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  caseId:
                    type: string
                  candidateId:
                    type: string
        '500':
          description: Internal Server Error
      security:
        - JWT: []
components:
  securitySchemes:
    JWT:
      type: http
      scheme: bearer

````