> ## 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 one-time token link

> Retrieves a one-time token (OTT) URL to give to a candidate so that they can complete onboarding for a case.
The returned URL contains a token, ensuring that the candidate secures their account before proceeding with onboarding.

This endpoint is typically called when a candidate has been newly integrated into KarmaCheck by a partner. This is so that testimony can be presented on behalf of the candidate for a case before onboarding begins. The URL is designed to ensure that the onboarding process includes a step where the candidate can secure their account before continuing.

**Note:** To properly redirect the candidate to the provided invitation context to commence their background check, append the full invitation link to the end of the returned OTT URL as a `redirect_url` query parameter. For example:
- `https://my.karmacheck.com/ott/{ott}?redirect_url=/invite/{invitationToken}`
- `https://my.karmacheck.com/ott/{ott}?redirect_url=https://my.karmacheck.com/invite/{invitationToken}`



## OpenAPI

````yaml /background-check-api/api-reference/openapi.json get /case/id/{caseId}/candidate/id/{candidateId}/url
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:
  /case/id/{caseId}/candidate/id/{candidateId}/url:
    parameters:
      - schema:
          type: string
        name: caseId
        in: path
        required: true
      - name: candidateId
        in: path
        required: true
        description: The ID of the candidate for the case.
        schema:
          type: string
    get:
      tags:
        - Candidate onboarding
      summary: Get one-time token link
      description: >-
        Retrieves a one-time token (OTT) URL to give to a candidate so that they
        can complete onboarding for a case.

        The returned URL contains a token, ensuring that the candidate secures
        their account before proceeding with onboarding.


        This endpoint is typically called when a candidate has been newly
        integrated into KarmaCheck by a partner. This is so that testimony can
        be presented on behalf of the candidate for a case before onboarding
        begins. The URL is designed to ensure that the onboarding process
        includes a step where the candidate can secure their account before
        continuing.


        **Note:** To properly redirect the candidate to the provided invitation
        context to commence their background check, append the full invitation
        link to the end of the returned OTT URL as a `redirect_url` query
        parameter. For example:

        -
        `https://my.karmacheck.com/ott/{ott}?redirect_url=/invite/{invitationToken}`

        -
        `https://my.karmacheck.com/ott/{ott}?redirect_url=https://my.karmacheck.com/invite/{invitationToken}`
      operationId: get-case-id-caseid-candidate-id-candidateId-url
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - ottUrl
                properties:
                  ottUrl:
                    type: string
                    description: >-
                      The URL in the format
                      `https://my{-env}.karmacheck.com/ott/{ott}`, with `{ott}`
                      as the token.
                    example: >-
                      https://my.karmacheck.com/ott/a1bc234-56de-7891-234a-b5c6d7c8e901
        '403':
          description: 'Forbidden: No access to the candidate or the case.'
        '422':
          description: >-
            Unprocessable Entity: Candidate account is already secured, or bad
            credentials.
        '500':
          description: Internal Server Error
components:
  securitySchemes:
    JWT:
      type: http
      scheme: bearer

````