GoodHire

GoodHire Reports API

Order and track background check reports.

Documentation GitHub OpenAPI

OpenAPI Specification

openapi: 3.0.3
info:
  title: GoodHire Packages Reports 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.
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'
components:
  schemas:
    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
    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
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    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.
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    RequestorId:
      name: requestor_id
      in: path
      required: true
      schema:
        type: string
    CompanyId:
      name: company_id
      in: path
      required: true
      schema:
        type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key sent as: Authorization: ApiKey <API_KEY>. Request keys from api@goodhire.com.'

Where this information came from

This is an independent, third-party profile of GoodHire Reports API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.

The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.

Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.

info@apievangelist.com · Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.

GoodHire Reports API

Documentation

Specifications

Other Resources

OpenAPI Specification