Sterling Screenings API

openapi: 3.2.0
info:
  title: Sterling Authentication Screenings API
  description: 'The Sterling API integrates background and identity screening into your platform and manages the process end to end. It is a RESTful, OAuth2-secured API: you exchange a Client ID and Client Secret for an access token, then create candidates, look up the screening packages available to your account, initiate screenings (orders), invite candidates by email or hosted link, retrieve results/reports (PDF or HTML), and receive real-time status updates via webhook callbacks.


    ACCESS IS GATED. Credentials are provisioned per screening region (US, EMEA, Canada, or APAC) by request through Sterling; there is a separate set of credentials for the sandbox/integration environment and for production.


    GROUNDING AND MODELING NOTE: The documented, confirmed operations are the OAuth token exchange, GET /packages, POST /candidates, POST /screenings (including the invite object and the callbackUri for webhooks), and the availability of results/reports with per-item statuses. The remaining operations in this document (list/retrieve/cancel screenings, retrieve/update candidates, retrieve a package, report retrieval paths, recurring screening management, and standalone webhook subscription management) are HONESTLY MODELED on Sterling''s documented order lifecycle and are marked in each operation description with "[MODELED]". The API request host is also modeled: exact hosts are provisioned with your credentials. The OAuth host auth.sterlingcheck.app and the documentation host apidocs.sterlingcheck.app are confirmed; api.sterlingcheck.app is a representative modeled base.


    Sterling is a First Advantage company (First Advantage completed its $2.2B acquisition of Sterling Check Corp on October 31, 2024).'
  version: '2.0'
  contact:
    name: Sterling (a First Advantage company)
    url: https://www.sterlingcheck.com/services/api/
  x-documentation: https://apidocs.sterlingcheck.app/
  x-developer-portal: https://developer.sterlingcheck.app/
  x-acquisition: First Advantage completed acquisition of Sterling Check Corp on 2024-10-31 ($2.2B).
servers:
- url: https://api.sterlingcheck.app/v2
  description: Production (MODELED representative host - exact host provisioned with production credentials)
- url: https://api-sandbox.sterlingcheck.app/v2
  description: Sandbox / Integration (MODELED representative host - exact host provisioned with sandbox credentials)
security:
- oAuth2ClientCredentials: []
- bearerAuth: []
tags:
- name: Screenings
  description: Screening orders and their lifecycle, including recurring/continuous screening.
paths:
  /screenings:
    get:
      operationId: listScreenings
      tags:
      - Screenings
      summary: List screenings
      description: '[MODELED] List the screenings (orders) in your account, filterable by status.'
      parameters:
      - name: status
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ScreeningStatus'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 25
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: A list of screenings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Screening'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createScreening
      tags:
      - Screenings
      summary: Initiate a screening
      description: '[CONFIRMED] Initiate a background screening (order) for a candidate against a package. Three initiation workflows are supported via the invite object: set invite.method to "email" so Sterling emails the candidate an invite; set invite.method to "link" to receive a hosted form URL in the response for embedding in your own flow; or omit the invite to initiate directly when candidate data is already complete. Provide a callbackUri to receive real-time webhook status updates. Set the recurring object to schedule continuous/recurring screening.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScreeningCreate'
      responses:
        '201':
          description: The created screening. If invite.method is "link", the response includes the hosted form URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Screening'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /screenings/{screeningId}:
    get:
      operationId: getScreening
      tags:
      - Screenings
      summary: Retrieve a screening
      description: '[MODELED] Retrieve a screening (order) by ID, including its current status and rolled-up report item statuses.'
      parameters:
      - $ref: '#/components/parameters/ScreeningId'
      responses:
        '200':
          description: A screening.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Screening'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /screenings/{screeningId}/cancel:
    post:
      operationId: cancelScreening
      tags:
      - Screenings
      summary: Cancel a screening
      description: '[MODELED] Cancel an in-progress screening where allowed by product and compliance rules.'
      parameters:
      - $ref: '#/components/parameters/ScreeningId'
      responses:
        '200':
          description: The cancelled screening.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Screening'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    ScreeningId:
      name: screeningId
      in: path
      required: true
      schema:
        type: string
  schemas:
    ReportItem:
      type: object
      description: An individual product result within a screening report, each with its own status.
      properties:
        product:
          type: string
        status:
          type: string
          description: Common report item status values (e.g., pending, clear, consider, review).
        summary:
          type: string
    RecurringConfig:
      type: object
      description: '[MODELED] Configure continuous/recurring screening to monitor a candidate over time.'
      properties:
        enabled:
          type: boolean
        interval:
          type: string
          enum:
          - monthly
          - quarterly
          - annually
    InviteRequest:
      type: object
      properties:
        method:
          type: string
          enum:
          - email
          - link
          description: '"email" sends the candidate an invitation email; "link" returns a hosted form URL in the response for you to embed.'
    Screening:
      type: object
      properties:
        id:
          type: string
        candidateId:
          type: string
        packageId:
          type: string
        clientReferenceId:
          type: string
        status:
          $ref: '#/components/schemas/ScreeningStatus'
        inviteUrl:
          type: string
          format: uri
          description: Present when invite.method was "link".
        callbackUri:
          type: string
          format: uri
        reportItems:
          type: array
          items:
            $ref: '#/components/schemas/ReportItem'
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    ScreeningCreate:
      type: object
      required:
      - candidateId
      - packageId
      properties:
        candidateId:
          type: string
        packageId:
          type: string
        clientReferenceId:
          type: string
        callbackUri:
          type: string
          format: uri
          description: URL Sterling posts real-time status-change webhook events to.
        invite:
          $ref: '#/components/schemas/InviteRequest'
        recurring:
          $ref: '#/components/schemas/RecurringConfig'
    ScreeningStatus:
      type: string
      description: Rolled-up screening status. Individual report items carry their own statuses.
      enum:
      - pending
      - awaiting_candidate
      - in_progress
      - completed
      - cancelled
      - review
  responses:
    BadRequest:
      description: The request was malformed or missing required fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid access 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'
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      description: OAuth2 client credentials grant using your Client ID and Client Secret.
      flows:
        clientCredentials:
          tokenUrl: https://auth.sterlingcheck.app/oauth/token
          scopes: {}
    bearerAuth:
      type: http
      scheme: bearer
      description: The access token returned from the OAuth token exchange, sent as a Bearer token.