Certn Reports API

openapi: 3.0.3
info:
  title: Certn 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: Applications
    description: Invite or instantly screen applicants and list applications (HR and PM surfaces).
  - name: Checks
    description: Individual check types requested and returned within an application.
  - name: Reports
    description: Consolidated applicant screening reports and results.
  - name: Packages
    description: Predefined bundles of checks and application upgrades.
  - name: Webhooks
    description: Signed server-to-server callbacks for screening status updates.
  - name: Teams and Users
    description: Organizational hierarchy - Superteams, Teams, Users, reference templates.
paths:
  /api/v1/hr/applications/invite/:
    post:
      operationId: inviteHrApplicant
      tags:
        - Applications
      summary: Invite an HR applicant to complete a screen
      description: >-
        Invite an applicant to complete a screen via email. The applicant fills in
        their own information and consent, then the requested checks run.
        (Deprecated in the v1 API; use the CertnCentric equivalent.)
      deprecated: true
      x-endpoint-status: confirmed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationInvite'
      responses:
        '201':
          description: Application created and invitation sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/hr/applications/quick/:
    post:
      operationId: quickScreenHrApplicant
      tags:
        - Applications
      summary: Screen an HR applicant instantly
      description: >-
        Screen an applicant using only the information supplied in the body of the
        request, without sending an invitation email.
        (Deprecated in the v1 API.)
      deprecated: true
      x-endpoint-status: confirmed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuickScreen'
      responses:
        '201':
          description: Application created and screening started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/hr/applicants/:
    get:
      operationId: listHrApplicants
      tags:
        - Applications
      summary: List HR applications
      description: >-
        Retrieve a paginated list of all applications, in chronological order,
        with filtering by team or owner.
      x-endpoint-status: confirmed
      parameters:
        - $ref: '#/components/parameters/Team'
        - $ref: '#/components/parameters/Owner'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of applications.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /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/pm/applications/invite/:
    post:
      operationId: invitePmApplicant
      tags:
        - Applications
      summary: Invite a property-management applicant to complete a screen
      description: >-
        Invite one or more applicants to complete a property-management screening
        form; supports batch invitations. (Deprecated in the v1 API.)
      deprecated: true
      x-endpoint-status: confirmed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationInvite'
      responses:
        '201':
          description: Application(s) created and invitation(s) sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/pm/applications/quick/:
    post:
      operationId: quickScreenPmApplicant
      tags:
        - Applications
      summary: Screen a property-management applicant instantly
      description: >-
        Screen an applicant using only the information in the body of the request.
        (Deprecated in the v1 API.)
      deprecated: true
      x-endpoint-status: confirmed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuickScreen'
      responses:
        '201':
          description: Application created and screening started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/pm/applicants/:
    get:
      operationId: listPmApplicants
      tags:
        - Applications
      summary: List property-management applications
      description: View details of all applications, paginated in chronological order.
      x-endpoint-status: confirmed
      parameters:
        - $ref: '#/components/parameters/Team'
        - $ref: '#/components/parameters/Owner'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of applications.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/reports/{applicant_id}/:
    get:
      operationId: getApplicantReport
      tags:
        - Reports
      summary: Retrieve an applicant's consolidated report
      description: >-
        Retrieve the consolidated screening report for an applicant, including each
        requested check's status and findings, verified identity and financial
        data, and an overall risk assessment. MODELED: the report payload is
        returned within the applicant object on the confirmed v1 list endpoints;
        this dedicated path mirrors the CertnCentric reports resource and should be
        confirmed against the live docs.
      x-endpoint-status: modeled
      parameters:
        - $ref: '#/components/parameters/ApplicantId'
      responses:
        '200':
          description: The applicant's consolidated report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/checks/:
    get:
      operationId: listAvailableChecks
      tags:
        - Checks
      summary: List available check types
      description: >-
        List the check types available to the account (criminal, identity/OneID,
        credit, public records, employment, education, credential, professional
        reference, driver's abstract, working-with-children, social media, and
        international variants). MODELED from the published check catalog; confirm
        the exact path and schema against the CertnCentric docs.
      x-endpoint-status: modeled
      responses:
        '200':
          description: A list of available check types.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Check'
        '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'
  /api/v1/users/:
    get:
      operationId: listUsers
      tags:
        - Teams and Users
      summary: List users in the account
      description: >-
        Retrieve a list of users in your organizational account. Each user is
        returned with a UUID id and profile fields.
      x-endpoint-status: confirmed
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/teams/:
    get:
      operationId: listTeams
      tags:
        - Teams and Users
      summary: Retrieve all teams
      description: >-
        Retrieve all teams in the account. Superteams contain Teams which contain
        Users. (Deprecated in the v1/v2 API.)
      deprecated: true
      x-endpoint-status: confirmed
      responses:
        '200':
          description: A list of teams.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/teams/{team_id}/address/reference_templates/:
    get:
      operationId: getAddressReferenceTemplates
      tags:
        - Teams and Users
      summary: Retrieve address reference templates
      description: >-
        Retrieve the templated address-reference questionnaires configured for a
        team, including question types (TRUE_FALSE, MULTIPLE_CHOICE, NUMERIC_RANGE,
        LONG_ANSWER) and variable substitution. (Deprecated in the v2 API.)
      deprecated: true
      x-endpoint-status: confirmed
      parameters:
        - $ref: '#/components/parameters/TeamId'
      responses:
        '200':
          description: A list of address reference templates.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReferenceTemplate'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhooks/receiver:
    post:
      operationId: receiveWebhook
      tags:
        - Webhooks
      summary: Webhook receiver (implemented on your side)
      description: >-
        Documentation of the callback contract. Certn POSTs screening status
        updates to the endpoint URL you register in the Partner dashboard as
        results become available. Each request carries a Certn-Signature header
        (an HMAC-SHA256 over "{timestamp}.{json_body}" with a t= timestamp and a
        v1= signature) so you can verify authenticity and guard against replay.
        Certn retries up to three additional times on 408/500/502/503/504.
        There is no public REST endpoint to register webhooks - configuration is
        done in the Partner dashboard. This path documents the payload you
        receive, not a Certn-hosted endpoint.
      x-endpoint-status: modeled
      parameters:
        - name: Certn-Signature
          in: header
          required: true
          description: HMAC-SHA256 signature "t={timestamp},v1={signature}".
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEvent'
      responses:
        '200':
          description: Acknowledge receipt (your endpoint should return 2xx).
components:
  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}".
  parameters:
    ApplicantId:
      name: applicant_id
      in: path
      required: true
      description: The UUID of the applicant / application.
      schema:
        type: string
        format: uuid
    TeamId:
      name: team_id
      in: path
      required: true
      description: The UUID of the team.
      schema:
        type: string
        format: uuid
    Team:
      name: team
      in: query
      required: false
      description: Filter results by team ID.
      schema:
        type: string
    Owner:
      name: owner
      in: query
      required: false
      description: Filter results by owner (user) ID.
      schema:
        type: string
    Offset:
      name: offset
      in: query
      required: false
      description: Number of records to skip for pagination.
      schema:
        type: integer
        minimum: 0
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of records to return.
      schema:
        type: integer
        minimum: 1
        maximum: 100
  responses:
    Unauthorized:
      description: Missing or invalid Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    ApplicationInvite:
      type: object
      description: Request to invite an applicant to complete a screen.
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: Applicant email to send the invitation to.
        first_name:
          type: string
        last_name:
          type: string
        package:
          type: string
          description: ID of the screening package to apply.
        team:
          type: string
          description: Team ID that owns the application.
        request_criminal_record_check:
          type: boolean
        request_identity_verification:
          type: boolean
        request_credit_check:
          type: boolean
        request_employment_verification:
          type: boolean
        request_education_verification:
          type: boolean
        request_reference_check:
          type: boolean
    QuickScreen:
      type: object
      description: Instant screen using information supplied directly in the request.
      required:
        - email
      properties:
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        date_of_birth:
          type: string
          format: date
        package:
          type: string
        checks:
          type: array
          items:
            type: string
          description: Check type identifiers to run.
    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.
    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
    ApplicationList:
      type: object
      properties:
        count:
          type: integer
        next:
          type: string
          nullable: true
        previous:
          type: string
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/Application'
    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.
    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
    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
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
    Team:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        superteam:
          type: string
          format: uuid
    ReferenceTemplate:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        questions:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
              type:
                type: string
                enum:
                  - TRUE_FALSE
                  - MULTIPLE_CHOICE
                  - NUMERIC_RANGE
                  - LONG_ANSWER
              required:
                type: boolean
              verifiable:
                type: boolean
    WebhookEvent:
      type: object
      description: Payload Certn POSTs to your registered webhook endpoint.
      properties:
        event:
          type: string
          description: Event type (e.g. application.updated, check.completed, report.completed).
        applicant_id:
          type: string
          format: uuid
        status:
          type: string
        timestamp:
          type: string
          format: date-time
        data:
          type: object
          description: The updated application / check / report object.
    Error:
      type: object
      properties:
        detail:
          type: string
        code:
          type: string