openapi: 3.0.3
info:
  title: Checkmate REST API
  description: >
    Checkmate API for launching background checks from your side using
    Checkmate.


    **Contact**

    - Questions or feedback:
    [development@checkmate.tech](mailto:development@checkmate.tech)

    - Become a partner: [team@checkmate.tech](mailto:team@checkmate.tech)
  version: 1.0.0
servers:
  - url: https://staging-api.checkmate.tech/partners/v1
    description: Staging
  - url: https://api.checkmate.tech/partners/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: OAuth
    description: |
      OAuth token authorization 

      {% admonition type="info" name="Basic Authorization" %}
        If you are not planning to build a multi-tenant integration then, we encorauge you to skip OAuth authentication and use your Checkmate account token instead. You can grab it from your [Partner's page](https://app.checkmate.tech/company/integrations) under "Account API"
        
        Remember to store it safely!
      {% /admonition %}


      {% admonition type="info" name="Basic Authorization" %}
        placeholder
      {% /admonition %}
  - name: Brands
    description: Company branding
  - name: Check Types
    description: Available check types
  - name: Bundles
    description: Pre-configured check bundles
  - name: Candidates
    description: Candidate management
  - name: Checks
    description: Candidate checks
  - name: Sub-checks
    description: Sub-check results
  - name: Referees
    description: Reference check referees
  - name: Companies
    description: Company details
  - name: Company Checks
    description: Company-enabled checks
  - name: Forms
    description: Forms (reference, questionnaire, etc.)
  - name: Uploads
    description: File uploads
  - name: Webhooks
    description: >
      {% admonition type="info" name="Webhooks are unique per partner and
      company!" %}
        Only one webhook can exists for a partner and company. You will only get updates notifications on candidates created under this context.

        E.g. If you subscribe to a webhook using your __Account API token__ you won't be get notified about updates on candidates created directly on the web application or other partners.
      {% /admonition %}


      {% admonition type="info" name=":global parameter" %}
        `:global` parameter is the only exception to the above. If `global=true` you will get notifications on all candidates created through the API. 
        You still won't get notifications on candidates created from the web application as they don't belog to the API.
      {% /admonition %}
paths:
  /branding:
    get:
      tags:
        - Brands
      summary: Get brands
      description: Retrieves all available brands for company.
      operationId: getBranding
      responses:
        '200':
          description: List of brands
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseBrands'
  /checks:
    get:
      tags:
        - Check Types
      summary: Get check types
      description: Retrieves all available check types.
      operationId: getCheckTypes
      responses:
        '200':
          description: List of check types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseChecks'
  /checks/{type}:
    get:
      tags:
        - Check Types
      summary: Get check type details
      description: Retrieves the details for a specific check type.
      operationId: getCheckTypeDetails
      parameters:
        - name: type
          in: path
          required: true
          description: Code of a check type
          schema:
            type: string
      responses:
        '200':
          description: Check type details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseCheckDetails'
  /bundles:
    get:
      tags:
        - Bundles
      summary: Get bundles
      description: Retrieves company bundles.
      operationId: getBundles
      responses:
        '200':
          description: List of bundles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseBundles'
    post:
      tags:
        - Bundles
      summary: Create bundle
      description: Creates a Checks Bundle with checks data.
      operationId: createBundle
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBundleRequest'
      responses:
        '200':
          description: Created bundle
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseChecksBundle'
  /candidates:
    post:
      tags:
        - Candidates
      summary: Create candidate
      description: Creates a Candidate with associated checks.
      operationId: createCandidate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCandidateRequest'
      responses:
        '200':
          description: Created candidate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseCandidate'
    get:
      tags:
        - Candidates
      summary: Get candidates
      description: Creates list of Candidate with associated checks.
      operationId: getCandidates
      responses:
        '200':
          description: Created candidate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseCandidates'
  /candidates/{partner_application_id}:
    get:
      tags:
        - Candidates
      summary: Get candidate
      description: Retrieves a Candidate by partner_application_id.
      operationId: getCandidate
      parameters:
        - $ref: '#/components/parameters/PartnerApplicationId'
      responses:
        '200':
          description: Candidate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseCandidate'
    put:
      tags:
        - Candidates
      summary: Update candidate
      description: Updates a Candidate.
      operationId: updateCandidate
      parameters:
        - $ref: '#/components/parameters/PartnerApplicationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - candidate
              properties:
                candidate:
                  $ref: '#/components/schemas/CandidateInput'
      responses:
        '200':
          description: Updated candidate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseCandidate'
    delete:
      tags:
        - Candidates
      summary: Delete candidate
      description: Deletes a candidate.
      operationId: deleteCandidate
      parameters:
        - $ref: '#/components/parameters/PartnerApplicationId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseNull'
  /candidates/{partner_application_id}/files:
    post:
      tags:
        - Candidates
      summary: Add files to candidate
      description: >-
        Adds a file (e.g. ID, signature) to candidate. If is_signature is true,
        candidate is submitted (consent implied).
      operationId: addCandidateFiles
      parameters:
        - $ref: '#/components/parameters/PartnerApplicationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - data
                - id_type
              properties:
                data:
                  type: string
                  description: Base64 encoded file (e.g. data:image/jpeg;base64,...)
                  example: data:image/jpeg;base64,....
                id_type:
                  $ref: '#/components/schemas/FileTypeEnum'
                is_signature:
                  type: boolean
                  default: false
                  description: >-
                    If true, file contains candidate signature and candidate is
                    submitted.
                  example: false
      responses:
        '200':
          description: Upload details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseUpload'
  /candidates/{partner_application_id}/history:
    get:
      tags:
        - Candidates
      summary: Get candidate history
      description: Retrieves Candidate history events.
      operationId: getCandidateHistory
      parameters:
        - $ref: '#/components/parameters/PartnerApplicationId'
      responses:
        '200':
          description: List of history events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseHistoryEvents'
  /candidates/{partner_application_id}/start:
    post:
      tags:
        - Candidates
      summary: Set as started
      description: >-
        Marks the candidate as started. Use only if you have a webhook
        configured for status updates.
      operationId: setCandidateStarted
      parameters:
        - $ref: '#/components/parameters/PartnerApplicationId'
      responses:
        '200':
          description: Updated candidate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseCandidate'
  /candidates/{partner_application_id}/checks:
    post:
      tags:
        - Checks
      summary: Add checks
      description: Adds checks to an existing candidate.
      operationId: addChecks
      parameters:
        - $ref: '#/components/parameters/PartnerApplicationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - checks
              properties:
                checks:
                  type: array
                  items:
                    $ref: '#/components/schemas/CheckData'
      responses:
        '200':
          description: Updated candidate with new checks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseCandidate'
  /candidates/{partner_application_id}/checks/{candidate_check_id}/result:
    get:
      tags:
        - Checks
      summary: Get check result file
      description: Retrieves result file or null if not present.
      operationId: getCheckResultFile
      parameters:
        - $ref: '#/components/parameters/PartnerApplicationId'
        - name: candidate_check_id
          in: path
          required: true
          schema:
            type: integer
          description: ID of candidate check
      responses:
        '200':
          description: Result file (binary) or null
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /candidates/{partner_application_id}/checks/{candidate_check_id}/result/base_64:
    get:
      tags:
        - Checks
      summary: Get check base64 result file
      description: Retrieves result file data base64 encoded or null if not present.
      operationId: getCheckResultBase64
      parameters:
        - $ref: '#/components/parameters/PartnerApplicationId'
        - name: candidate_check_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Base64 encoded result or null
          content:
            application/json:
              schema:
                type: string
  /candidates/{partner_application_id}/sub_checks/{sub_check_id}/result:
    get:
      tags:
        - Sub-checks
      summary: Get sub-check result file
      description: Retrieves result file or null if not present.
      operationId: getSubCheckResultFile
      parameters:
        - $ref: '#/components/parameters/PartnerApplicationId'
        - name: sub_check_id
          in: path
          required: true
          schema:
            type: integer
          description: ID of candidate sub check
      responses:
        '200':
          description: Result file (binary) or null
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /candidates/{partner_application_id}/sub_checks/{sub_check_id}/result/base_64:
    get:
      tags:
        - Sub-checks
      summary: Get sub-check base64 result file
      description: Retrieves result file data base64 encoded or null if not present.
      operationId: getSubCheckResultBase64
      parameters:
        - $ref: '#/components/parameters/PartnerApplicationId'
        - name: sub_check_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Base64 encoded result or null
          content:
            application/json:
              schema:
                type: string
  /candidates/{partner_application_id}/checks/{candidate_check_id}/referees:
    get:
      tags:
        - Referees
      summary: Get referees
      description: >-
        Gets a list of referees for a Reference Check Plus / Custom Reference
        Check.
      operationId: getReferees
      parameters:
        - $ref: '#/components/parameters/PartnerApplicationId'
        - name: candidate_check_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: List of referees
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseReferees'
    post:
      tags:
        - Referees
      summary: Create referee
      description: Creates a referee on a Reference Check Plus.
      operationId: createReferee
      parameters:
        - $ref: '#/components/parameters/PartnerApplicationId'
        - name: candidate_check_id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - candidate_form_id
                - form_id
              properties:
                candidate_form_id:
                  type: integer
                  description: Form ID for Candidate
                  example: 12
                form_id:
                  type: integer
                  description: Form ID for Referee
                  example: 24
                manual:
                  type: boolean
                  description: >-
                    If true, details are provided on this call; communications
                    to candidate won't be sent
                  example: false
                answers:
                  type: object
                  additionalProperties: true
                  description: Keys are form field IDs, values are answers
      responses:
        '200':
          description: Created referee
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseReferee'
  /candidates/{partner_application_id}/checks/{candidate_check_id}/referees/{referee_id}:
    delete:
      tags:
        - Referees
      summary: Delete referee
      description: Deletes a referee.
      operationId: deleteReferee
      parameters:
        - $ref: '#/components/parameters/PartnerApplicationId'
        - name: candidate_check_id
          in: path
          required: true
          schema:
            type: integer
        - name: referee_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseNull'
  /candidates/{partner_application_id}/checks/{candidate_check_id}/referees/{referee_id}/request:
    post:
      tags:
        - Referees
      summary: Send request to referee
      description: >-
        Sends email/SMS to the referee requesting completion of the reference
        form.
      operationId: sendRefereeRequest
      parameters:
        - $ref: '#/components/parameters/PartnerApplicationId'
        - name: candidate_check_id
          in: path
          required: true
          schema:
            type: integer
        - name: referee_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseNull'
  /company:
    get:
      tags:
        - Companies
      summary: Get company
      description: Retrieves company details.
      operationId: getCompany
      responses:
        '200':
          description: Company details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseCompany'
  /company/checks:
    get:
      tags:
        - Company Checks
      summary: Get company checks
      description: Retrieves enabled check types for company.
      operationId: getCompanyChecks
      responses:
        '200':
          description: List of company checks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseCompanyChecks'
  /forms:
    get:
      tags:
        - Forms
      summary: Get forms
      description: Retrieves all available forms for company.
      operationId: getForms
      responses:
        '200':
          description: List of forms
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseForms'
  /forms/types:
    get:
      tags:
        - Forms
      summary: Get forms by types
      description: >-
        Retrieves all available forms grouped by form type (library, customs,
        intelligent, questionnaires, candidates, referees).
      operationId: getFormsByTypes
      responses:
        '200':
          description: Forms grouped by type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseFormsByTypes'
  /uploads/{upload_id}:
    get:
      tags:
        - Uploads
      summary: Get upload
      description: Retrieves upload object.
      operationId: getUpload
      parameters:
        - name: upload_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Upload details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseUpload'
    delete:
      tags:
        - Uploads
      summary: Delete upload
      description: Deletes an upload.
      operationId: deleteUpload
      parameters:
        - name: upload_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Boolean success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseBoolean'
  /webhooks:
    post:
      tags:
        - Webhooks
      summary: Create or update webhook
      description: >
        Creates or updates the Webhook for the company. Only one webhook per
        company and partner.

        The Webhook will POST to the provided URL whenever a candidate check
        created using the same partner (unless global) changes status.
      operationId: createOrUpdateWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Webhook'
      responses:
        '200':
          description: Webhook configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseWebhook'
  /oauth/token:
    post:
      tags:
        - OAuth
      summary: Oauth token
      description: >
        - **Authorization code**: Exchange `code` for access_token and
        refresh_token.

        - **Refresh**: Use refresh_token to get a new access_token (access
        tokens expire after 5 minutes).

        Send body as application/x-www-form-urlencoded.
      operationId: oauthToken
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - client_id
                - client_secret
                - grant_type
              properties:
                client_id:
                  type: string
                  example: 3468d2767c98565c
                client_secret:
                  type: string
                  example: aee0fc19fhgxf37ccfa853dd93b134836
                grant_type:
                  type: string
                  enum:
                    - authorization_code
                    - refresh_token
                  example: authorization_code
                redirect_uri:
                  type: string
                  description: Required for authorization_code
                  example: https://myloginpage.domain.com
                code:
                  type: string
                  description: Required for authorization_code
                  example: aee0fc19fhgxf37ccskfdn9af238bnqwe8w03n93r8bb98r23b
                refresh_token:
                  type: string
                  description: Required for refresh_token
                  example: >-
                    eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJkYXRhIjp7InVzZXJfaWQiOjY5NywiY29tcGFueV9pZCI6MTI0MywicGFydG5lciI6MTAsInZlcnNpb24iOjN9fQ.3I0rhYhH7Wyfw-_HodPByRFdmVZygg8VB_77X7JCw
      responses:
        '200':
          description: Token response
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    example: >-
                      eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJkYXRhIjp7InVzZXJfaWQiOjY5NywiY29tcGFueV9pZCI6MTI0MywicGFydG5lciI6MTAsInZlcnNpb24iOjN9fQ.3I0rhYhH7Wyfw-_HodPByRFdmVZygg8VB_77X7JCw
                  refresh_token:
                    type: string
                    example: >-
                      eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlJqaEROemRDUlVKRVEwTTVSVFE0TmtZME9UZzVNVEpDTlVJNFJqRTBPREExTmpZMk1qazFPQSJ9.eyJodHRwOi8vbWF0dHIvdGVuYW50LWlkIjoiNTcwYTcyOGEt
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        API token from Integrations or OAuth 2.0 access token. Use header
        Authorization: Bearer {token}
  parameters:
    PartnerApplicationId:
      name: partner_application_id
      in: path
      required: true
      description: value of candidate.partner_application_id
      schema:
        type: string
  schemas:
    ApiResponseBrands:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/Brand'
        status:
          type: integer
          example: 200
        error:
          type: object
          nullable: true
    ApiResponseCandidates:
      type: object
      properties:
        result:
          type: object
          properties:
            candidates:
              type: array
              items:
                $ref: '#/components/schemas/Candidate'
            pagination:
              type: object
              properties:
                page:
                  type: integer
                  example: 1
                records_per_page:
                  type: integer
                  example: 15
                total_records:
                  type: integer
                  example: 30
                total_pages:
                  type: integer
                  example: 2
        status:
          type: integer
          example: 200
        error:
          type: object
          nullable: true
    ApiResponseChecks:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/Check'
        status:
          type: integer
          example: 200
        error:
          type: object
          nullable: true
    ApiResponseCheckDetails:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/CheckDetails'
        status:
          type: integer
          example: 200
        error:
          type: object
          nullable: true
    ApiResponseBundles:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/ChecksBundle'
        status:
          type: integer
          example: 200
        error:
          type: object
          nullable: true
    ApiResponseChecksBundle:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/ChecksBundle'
        status:
          type: integer
          example: 200
        error:
          type: object
          nullable: true
    ApiResponseCandidate:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/Candidate'
        status:
          type: integer
          example: 200
        error:
          type: object
          nullable: true
    ApiResponseNull:
      type: object
      properties:
        result:
          type: object
          nullable: true
        status:
          type: integer
          example: 200
        error:
          type: object
          nullable: true
    ApiResponseUpload:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/Upload'
        status:
          type: integer
          example: 200
        error:
          type: object
          nullable: true
    ApiResponseHistoryEvents:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/HistoryEvent'
        status:
          type: integer
          example: 200
        error:
          type: object
          nullable: true
    ApiResponseReferees:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/Referee'
        status:
          type: integer
          example: 200
        error:
          type: object
          nullable: true
    ApiResponseReferee:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/Referee'
        status:
          type: integer
          example: 200
        error:
          type: object
          nullable: true
    ApiResponseCompany:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/Company'
        status:
          type: integer
          example: 200
        error:
          type: object
          nullable: true
    ApiResponseCompanyChecks:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/CompanyCheck'
        status:
          type: integer
          example: 200
        error:
          type: object
          nullable: true
    ApiResponseForms:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/Form'
        status:
          type: integer
          example: 200
        error:
          type: object
          nullable: true
    ApiResponseFormsByTypes:
      type: object
      properties:
        result:
          type: object
          properties:
            library:
              type: array
              items:
                $ref: '#/components/schemas/Form'
            customs:
              type: array
              items:
                $ref: '#/components/schemas/Form'
            intelligent:
              type: array
              items:
                $ref: '#/components/schemas/Form'
            questionnaires:
              type: array
              items:
                $ref: '#/components/schemas/Form'
            candidates:
              type: array
              items:
                $ref: '#/components/schemas/Form'
            referees:
              type: array
              items:
                $ref: '#/components/schemas/Form'
        status:
          type: integer
          example: 200
        error:
          type: object
          nullable: true
    ApiResponseBoolean:
      type: object
      properties:
        result:
          type: boolean
          example: true
        status:
          type: integer
          example: 200
        error:
          type: object
          nullable: true
    ApiResponseWebhook:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/Webhook'
        status:
          type: integer
          example: 200
        error:
          type: object
          nullable: true
    ApiError:
      type: object
      properties:
        result:
          type: object
          nullable: true
        status:
          type: integer
          example: 401
        error:
          type: object
          properties:
            message:
              type: string
              example: Unauthorized
            log:
              type: string
              example: Unauthorized
    Brand:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier
          example: '1'
        name:
          type: string
          description: Brand name
          example: Custom Brand
    Check:
      type: object
      properties:
        code:
          type: string
          example: moj
        title:
          type: string
          example: Ministry of Justice Check
    CheckDetails:
      type: object
      properties:
        code:
          type: string
          example: moj
        title:
          type: string
          example: Ministry of Justice Check
        fields:
          type: array
          items:
            $ref: '#/components/schemas/Field'
        id_types:
          type: array
          items:
            type: array
            items:
              type: string
              example: nz_passport
    Field:
      type: object
      properties:
        code:
          type: string
          example: first_name
        title:
          type: string
          example: First Name
        type:
          type: string
          enum:
            - text
            - date
            - select
            - checkbox
            - country
            - address
          example: text
        options:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
                example: Male
              value:
                type: string
                example: male
    CheckData:
      type: object
      properties:
        type:
          type: string
          description: Check code
          example: reference
        details:
          type: object
          description: Details from Get Check Type Details
        renewal:
          type: boolean
          example: true
    ChecksBundle:
      type: object
      properties:
        id:
          type: integer
          example: 156
        name:
          type: string
          example: Sales
        checks_data:
          type: array
          items:
            $ref: '#/components/schemas/CheckData'
    CreateBundleRequest:
      type: object
      required:
        - name
        - checks_data
      properties:
        name:
          type: string
          example: Sales
        checks_data:
          type: array
          items:
            $ref: '#/components/schemas/CheckData'
    Candidate:
      type: object
      properties:
        id:
          type: integer
          example: 1
        reference_code:
          type: string
          example: whatever
        first_name:
          type: string
          example: Luke
        last_name:
          type: string
          example: Skywalker
        name:
          type: string
          example: Luke Skywalker
        email:
          type: string
          example: luke.skywalker@email.com
        contact_number:
          type: string
          example: '+6493614595'
        job_role:
          type: string
          example: Padawan
        department:
          type: string
          example: Jedis
        ip:
          type: string
          nullable: true
          example: null
        status:
          $ref: '#/components/schemas/StatusEnum'
        token:
          type: string
          example: >-
            https://app.checkmate.tech/assessments/details/12/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1N...
        created_at:
          type: string
          format: date-time
          example: '2021-06-27T10:05:13+02:00'
        submitted_at:
          type: string
          format: date-time
          nullable: true
          example: null
        completed_at:
          type: string
          format: date-time
          nullable: true
          example: null
        accepted_terms_and_conditions:
          type: boolean
          example: false
        partner_application_id:
          type: string
          example: your_unique_id
        partner_application_started:
          type: boolean
          example: true
        cc_notification_emails:
          type: string
          example: ''
        partner_link:
          type: string
          example: >-
            https://app.checkmate.tech/assessments/details/12/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1N...
        candidate_checks:
          type: array
          items:
            $ref: '#/components/schemas/CandidateCheck'
        candidate_checks_values:
          $ref: '#/components/schemas/CandidateChecksValues'
    CandidateInput:
      type: object
      properties:
        first_name:
          type: string
          example: Luke
        last_name:
          type: string
          example: Skywalker
        email:
          type: string
          example: luke.skywalker@email.com
        contact_number:
          type: string
          example: '+6493614595'
        job_role:
          type: string
          example: Padawan
        department:
          type: string
          example: Jedis
        partner_application_id:
          type: string
          example: your_unique_id
        partner_application_started:
          type: boolean
          example: true
    CandidateCheck:
      type: object
      properties:
        id:
          type: integer
          example: 1
        type:
          type: string
          example: acc
        created_at:
          type: string
          format: date-time
          example: '2021-06-27T10:05:13+02:00'
        submitted_at:
          type: string
          nullable: true
          example: null
        job_at:
          type: string
          nullable: true
          example: null
        details:
          type: object
          nullable: true
        completed_at:
          type: string
          nullable: true
          example: null
        accepted_terms:
          type: boolean
          example: false
        result_flag:
          type: boolean
          example: false
        renewal:
          type: boolean
          example: false
        status:
          type: string
          example: candidate
        user_agent:
          type: string
          nullable: true
          example: null
        upload:
          $ref: '#/components/schemas/Upload'
        expiration_date:
          type: string
          nullable: true
          example: '2024-10-23'
    CandidateChecksValues:
      type: object
      properties:
        id:
          type: integer
          example: 1
        values:
          type: object
    CreateCandidateRequest:
      type: object
      required:
        - candidate
      properties:
        candidate:
          $ref: '#/components/schemas/CandidateInput'
        checks:
          type: array
          items:
            $ref: '#/components/schemas/CheckData'
        bundle_id:
          type: integer
          nullable: true
          description: If given, checks value will be ignored
          example: null
        bypass:
          type: boolean
          default: false
          description: If true, candidate won't be contacted
          example: false
        user_email:
          type: string
          description: Match with existing company user as owner
          example: user@company.com
    HistoryEvent:
      type: object
      properties:
        id:
          type: integer
          example: 125
        user_name:
          type: string
          nullable: true
          example: Luke Skywalker
        date:
          type: string
          format: date-time
          example: '2021-06-04T10:14:28+02:00'
        type:
          type: integer
          example: 14
        country:
          type: string
          nullable: true
          example: null
        check_type:
          type: string
          nullable: true
          example: moj
        message:
          type: string
          nullable: true
          example: null
        referee:
          type: object
          nullable: true
    Referee:
      type: object
      properties:
        id:
          type: integer
          example: 6153
        first_name:
          type: string
          example: Jar Jar
        last_name:
          type: string
          example: Binks
        name:
          type: string
          example: Jar Jar Binks
        email:
          type: string
          example: jarjar.binks@gmail.com
        contact_number:
          type: string
          example: '+123456789'
        created_at:
          type: string
          format: date-time
          example: '2025-08-15T20:38:03+00:00'
        submitted_at:
          type: string
          nullable: true
          example: '2025-08-15T20:38:03+00:00'
        completed_at:
          type: string
          nullable: true
          example: null
        ip:
          type: string
          nullable: true
          example: null
        linkedin_profile:
          type: string
          nullable: true
          example: null
        backup:
          type: boolean
          example: false
        overdue:
          type: boolean
          example: false
        replaced_by:
          type: integer
          nullable: true
          example: 2
        manual:
          type: boolean
          example: true
        canceled:
          type: boolean
          example: false
        user_agent:
          type: string
          nullable: true
          example: null
        ip_country:
          type: string
          nullable: true
          example: null
        candidate_form_id:
          type: integer
          example: 896
        form_id:
          type: integer
          example: 891
        warning_flag:
          type: boolean
          example: false
        approved_by_client:
          type: boolean
          example: false
        status:
          type: string
          enum:
            - canceled
            - completed
            - overdue
            - in-progress
            - candidate
          example: in-progress
    Company:
      type: object
      properties:
        id:
          type: integer
          example: 1
        uuid:
          type: string
          example: 9aazd3f9-39d9
        contact_number:
          type: string
          example: +64 021 0000 0000
        name:
          type: string
          example: Checkmate
    CompanyCheck:
      type: object
      properties:
        type:
          type: string
          example: acc
        credits:
          type: integer
          example: -1
        code:
          type: string
          example: acc
        title:
          type: string
          nullable: true
          example: null
        check_type:
          $ref: '#/components/schemas/CheckType'
    CheckType:
      type: object
      properties:
        title:
          type: string
          example: Reference Check
        slug:
          type: string
          example: reference
        icon:
          type: string
          example: user
        logo:
          type: string
          example: >-
            https://checkmate-prod.s3.ap-southeast-2.amazonaws.com/assets/checkmate_check_logo.svg
        signature_required:
          type: boolean
          example: false
        result_type:
          type: string
          enum:
            - link
            - file
          example: file
        client_fields:
          type: array
        client_required_fields:
          type: array
        candidate_fields:
          type: array
          nullable: true
        candidate_required_fields:
          type: array
          nullable: true
        has_expiration_date:
          type: boolean
          example: false
        id_types:
          type: array
          nullable: true
    Form:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Essential
        public:
          type: boolean
          example: false
        type:
          type: string
          example: type:standard
        typeform_id:
          type: string
          nullable: true
          example: bMEvs6FR
        created_at:
          type: string
          format: date-time
          example: '2019-01-15T10:02:31+01:00'
    Upload:
      type: object
      properties:
        id:
          type: integer
          example: 2589
        file_name:
          type: string
          example: dummy_result.pdf
        file_type:
          type: string
          example: application/pdf
        created_at:
          type: string
          format: date-time
          example: '2021-07-03T16:44:56+02:00'
        url:
          type: string
          description: Expires after 20 minutes; refreshes on each request
          example: https://checkmate-staging.s3.ap-southeast-2.amazonaws.com/backg...
    Webhook:
      type: object
      required:
        - uri
      properties:
        uri:
          type: string
          format: uri
          example: https://your_webhook_uri/endpoint
        id_in_path:
          type: boolean
          description: Send partner_application_id in path
          example: true
        global:
          type: boolean
          description: >-
            Set it to true if you want to receive notifications indistinctly the
            partner it was created from
          example: false
        authorization:
          type: string
          description: Value for Authorization header
          example: Bearer your_authorization_token
        headers:
          type: object
          additionalProperties:
            type: string
            example: custom_auth_value
    StatusEnum:
      type: string
      enum:
        - candidate
        - submitted
        - in-progress
        - completed
        - overdue
        - canceled
      example: submitted
    FileTypeEnum:
      type: string
      enum:
        - drivers_license
        - passport
        - nz_passport
        - firearm_license
        - card_18
        - birth_certificate
        - citizenship_certificate
        - centrelink_card
        - id
      example: passport
