openapi: 3.0.3
info:
  title: GoodHire API
  version: '1.0'
  x-endpointsModeled: true
  description: >-
    RESTful, FCRA-compliant employment background check API for GoodHire (a Checkr
    company). Background checks are ordered by creating a report object tied to a
    candidate and a screening package (product bundle); status changes are delivered
    via outbound webhooks. The API is split into a Customer API (a single company
    ordering its own reports) and a Partner API (HR platforms ordering on behalf of
    embedded employer requestors).


    Access is gated - request an API key from api@goodhire.com and build against the
    sandbox (https://api-sandbox.goodhire.com), which returns dummy report data,
    before moving to production.


    NOTE: This document mixes endpoints confirmed from GoodHire's public docs with
    endpoints and schemas honestly modeled from documented resource patterns
    (x-endpointsModeled: true). It is a discovery aid, not a byte-for-byte mirror of
    GoodHire's official reference.
  contact:
    name: GoodHire API Team
    email: api@goodhire.com
    url: https://www.goodhire.com/api/
servers:
  - url: https://api.goodhire.com
    description: Production
  - url: https://api-sandbox.goodhire.com
    description: Sandbox (returns dummy report data)
security:
  - ApiKeyAuth: []
tags:
  - name: Reports
    description: Order and track background check reports.
  - name: Requestors
    description: Manage the users who order and are associated with reports.
  - name: Packages
    description: List available screening packages (product bundles) and prices.
  - name: Partner
    description: Partner API app-access flow for embedded HR platforms.
paths:
  /company/{company_id}/requestor/{requestor_id}/report/queue:
    post:
      tags:
        - Reports
      summary: Queue a background report
      description: >-
        Create and queue a new background check report for a candidate under a
        given company and requestor, selecting the screening package and passing
        candidate details plus request options (e.g. mark all info as submitted,
        add billing codes, suppress the receipt email). Confirmed endpoint.
      operationId: queueReport
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - $ref: '#/components/parameters/RequestorId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportOrder'
      responses:
        '200':
          description: Report queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /company/{company_id}/requestor/{requestor_id}/report/{report_id}:
    get:
      tags:
        - Reports
      summary: Get report status
      description: Retrieve the status and available results of a report by ID. Confirmed endpoint.
      operationId: getReport
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - $ref: '#/components/parameters/RequestorId'
        - name: report_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Report not found
  /company/{company_id}/requestor/{requestor_id}/report:
    get:
      tags:
        - Reports
      summary: List reports
      description: List reports for a requestor. Endpoint modeled from documented resource patterns (x-endpointsModeled).
      operationId: listReports
      x-endpointModeled: true
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - $ref: '#/components/parameters/RequestorId'
      responses:
        '200':
          description: A page of reports
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Report'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /company/{company_id}/requestor/{requestor_id}/productbundles:
    get:
      tags:
        - Packages
      summary: List product bundles (packages)
      description: >-
        Retrieve all screening packages (product bundles) available to the account
        along with their prices. Confirmed endpoint.
      operationId: listProductBundles
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - $ref: '#/components/parameters/RequestorId'
      responses:
        '200':
          description: Available packages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductBundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /company/{company_id}/requestors:
    get:
      tags:
        - Requestors
      summary: List requestors
      description: List requestors for a company. Endpoint modeled from documented resource patterns (x-endpointsModeled).
      operationId: listRequestors
      x-endpointModeled: true
      parameters:
        - $ref: '#/components/parameters/CompanyId'
      responses:
        '200':
          description: A page of requestors
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Requestor'
    post:
      tags:
        - Requestors
      summary: Create a requestor
      description: Provision a new requestor. Endpoint modeled from documented resource patterns (x-endpointsModeled).
      operationId: createRequestor
      x-endpointModeled: true
      parameters:
        - $ref: '#/components/parameters/CompanyId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Requestor'
      responses:
        '200':
          description: Requestor created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Requestor'
  /company/{company_id}/requestor/{requestor_id}:
    get:
      tags:
        - Requestors
      summary: Get a requestor
      description: Retrieve a single requestor. Endpoint modeled from documented resource patterns (x-endpointsModeled).
      operationId: getRequestor
      x-endpointModeled: true
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - $ref: '#/components/parameters/RequestorId'
      responses:
        '200':
          description: Requestor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Requestor'
  /company/{company_id}/requestor/{requestor_id}/partnerappaccess/stepselectreport:
    post:
      tags:
        - Partner
      summary: Partner app access - select report step
      description: >-
        Partner API flow step used by an embedded HR platform to select and
        configure the report to be ordered on behalf of a requestor, with request
        options customizing portions of the request. Confirmed endpoint.
      operationId: partnerSelectReport
      parameters:
        - $ref: '#/components/parameters/CompanyId'
        - $ref: '#/components/parameters/RequestorId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerReportSelection'
      responses:
        '200':
          description: Report selection accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key sent as: Authorization: ApiKey <API_KEY>. Request keys from api@goodhire.com.'
  parameters:
    CompanyId:
      name: company_id
      in: path
      required: true
      schema:
        type: string
    RequestorId:
      name: requestor_id
      in: path
      required: true
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Candidate:
      type: object
      description: The person being screened. Schema modeled from documented fields.
      properties:
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        ssn:
          type: string
          description: Provided when the requestor submits candidate info directly rather than via candidate self-consent.
    ReportOrder:
      type: object
      description: Request body for queuing a report. Schema modeled from documented fields.
      required:
        - candidate
        - productBundleId
      properties:
        candidate:
          $ref: '#/components/schemas/Candidate'
        productBundleId:
          type: string
          description: Identifier of the screening package to run.
        requestOptions:
          type: object
          description: Options such as allInfoSubmitted, billingCode, or suppressReceiptEmail.
          additionalProperties: true
    Report:
      type: object
      description: A background check report. Schema modeled from documented fields.
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - queued
            - pending_candidate
            - in_progress
            - complete
            - action_required
            - canceled
        result:
          type: string
          description: Overall outcome once complete (e.g. clear or needs review).
        candidate:
          $ref: '#/components/schemas/Candidate'
        productBundleId:
          type: string
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
    ProductBundle:
      type: object
      description: A screening package available to the account, with price.
      properties:
        id:
          type: string
        name:
          type: string
        price:
          type: number
          description: Per-check price in USD.
        screenings:
          type: array
          items:
            type: string
    Requestor:
      type: object
      description: A user who orders and is associated with reports.
      properties:
        id:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
    PartnerReportSelection:
      type: object
      description: Partner API report selection payload. Schema modeled from documented fields.
      properties:
        productBundleId:
          type: string
        requestOptions:
          type: object
          additionalProperties: true
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
webhooks:
  reportStatusChanged:
    post:
      summary: Report status changed
      description: >-
        Outbound HTTP callback GoodHire POSTs to the subscriber-configured URL when
        a report changes status. Payload shape modeled from documented behavior
        (x-endpointsModeled). This is a one-way HTTP webhook, not a WebSocket.
      x-endpointModeled: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                event:
                  type: string
                  example: report.status_changed
                report:
                  $ref: '#/components/schemas/Report'
      responses:
        '200':
          description: Acknowledged by the subscriber