openapi: 3.0.3
info:
  title: Certn Applications Packages API
  description: 'Certn is a background check and identity verification platform. This API lets partner platforms (HR, property management, gig/marketplace) order background screening for applicants, retrieve consolidated reports, manage the checks and packages that make up a screen, and receive status updates via signed webhooks. Certn screens candidates across 200+ countries and territories.


    Authentication uses OAuth 2.0 client credentials: a Client ID and Client Secret (created in the Partner tab under API Keys) are exchanged for a Bearer access token that is sent on every request.


    Base URL is https://api.certn.co for production and https://demo-api.certn.co for the demo/testing environment.


    IMPORTANT - endpoint provenance: The original api.certn.co v1 REST endpoints (under /api/v1/hr, /api/v1/pm, /api/v1/users, /api/v2/teams) are documented and CONFIRMED against the public reference, but Certn deprecated them on 2026-04-13 with discontinuation on 2026-08-05 in favor of the newer CertnCentric APIs. The CertnCentric documentation portal (centric-api-docs.certn.co) is a client-rendered SPA whose exact endpoint paths could not be scraped; its resource groupings (cases, checks, reports, packages, webhooks) are MODELED here honestly and marked with x-endpoint-status. Confirm all shapes against the live docs before use.'
  version: '1.0'
  contact:
    name: Certn
    url: https://certn.co
  license:
    name: Proprietary
    url: https://certn.co/terms/
servers:
- url: https://api.certn.co
  description: Production
- url: https://demo-api.certn.co
  description: Demo / testing
security:
- bearerAuth: []
tags:
- name: Packages
  description: Predefined bundles of checks and application upgrades.
paths:
  /api/v1/hr/applicants/{applicant_id}/packages/:
    put:
      operationId: upgradeHrApplication
      tags:
      - Packages
      summary: Add screening requests to an existing application
      description: Upgrade an application by adding further screening requests (checks or a package) to an existing applicant after the initial report returns. (Deprecated in the v1 API.)
      deprecated: true
      x-endpoint-status: confirmed
      parameters:
      - $ref: '#/components/parameters/ApplicantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PackageUpgrade'
      responses:
        '200':
          description: Application upgraded with the added requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/packages/:
    get:
      operationId: listPackages
      tags:
      - Packages
      summary: List screening packages
      description: List the predefined screening packages configured for the account or team (for example the CertnCentric Essential, Pro, and Elite tiers), each a named bundle of checks. MODELED from the general-resources docs; confirm the exact path against the CertnCentric docs.
      x-endpoint-status: modeled
      parameters:
      - $ref: '#/components/parameters/Team'
      responses:
        '200':
          description: A list of packages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Package'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Applicant:
      type: object
      properties:
        id:
          type: string
          format: uuid
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        date_of_birth:
          type: string
          format: date
    Check:
      type: object
      description: An individual check within an application, or an available check type.
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          description: Check type - e.g. CRIMINAL_RECORD_CHECK, ENHANCED_CRIMINAL_RECORD_CHECK, INTERNATIONAL_CRIMINAL_RECORD_CHECK, IDENTITY_VERIFICATION, CREDIT_CHECK, PUBLIC_RECORDS, EMPLOYMENT_VERIFICATION, EDUCATION_VERIFICATION, CREDENTIAL_VERIFICATION, REFERENCE_CHECK, DRIVERS_ABSTRACT, WORKING_WITH_CHILDREN, SOCIAL_MEDIA.
        status:
          type: string
          description: Check status (e.g. PENDING, ANALYZING, COMPLETE, CANCELLED).
        result:
          type: string
          description: Adjudicated result (e.g. CLEAR, CONSIDER, IN_DISPUTE).
        country:
          type: string
          description: ISO country code the check was run in.
    PackageUpgrade:
      type: object
      description: Additional screening requests to add to an existing application.
      properties:
        package:
          type: string
          description: ID of a package to add.
        checks:
          type: array
          items:
            type: string
          description: Additional check type identifiers to add.
    Package:
      type: object
      description: A named bundle of checks.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        checks:
          type: array
          items:
            type: string
        team:
          type: string
    Report:
      type: object
      description: Consolidated report across all checks in an application.
      properties:
        id:
          type: string
          format: uuid
        applicant_id:
          type: string
          format: uuid
        overall_result:
          type: string
          description: Overall adjudicated outcome / risk assessment.
        risk_assessment:
          type: string
        checks:
          type: array
          items:
            $ref: '#/components/schemas/Check'
        report_url:
          type: string
          format: uri
          description: Link to the rendered PDF/HTML report.
        completed:
          type: string
          format: date-time
    Application:
      type: object
      description: A screening application for an applicant.
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          description: Overall application status (e.g. PENDING, ANALYZING, COMPLETE).
        applicant:
          $ref: '#/components/schemas/Applicant'
        checks:
          type: array
          items:
            $ref: '#/components/schemas/Check'
        report:
          $ref: '#/components/schemas/Report'
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        detail:
          type: string
        code:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    ApplicantId:
      name: applicant_id
      in: path
      required: true
      description: The UUID of the applicant / application.
      schema:
        type: string
        format: uuid
    Team:
      name: team
      in: query
      required: false
      description: Filter results by team ID.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'OAuth 2.0 client credentials. Exchange your Client ID and Client Secret for an access token, then send it as "Authorization: Bearer {token}".'