openapi: 3.0.3
info:
  title: VerifyRef API
  version: "2025-05-19"
  description: REST API for automated reference checks and ATS integrations.
servers:
  - url: https://verifyref.com/api/v1
    description: Production
paths:
  /account:
    get:
      summary: Team account and credits
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Account details
  /checks:
    get:
      summary: List reference checks
      security:
        - bearerAuth: []
      parameters:
        - name: externalId
          in: query
          schema: { type: string }
        - name: externalSource
          in: query
          schema:
            type: string
            enum: [bullhorn, zoho_recruit, sap_successfactors, workday, greenhouse, lever, other]
        - name: status
          in: query
          schema:
            type: string
            enum: [PENDING, AWAITING_CONSENT, SENT, IN_PROGRESS, COMPLETED, EXPIRED]
        - name: jobId
          in: query
          schema: { type: string }
        - name: createdAfter
          in: query
          schema: { type: string, format: date-time }
        - name: page
          in: query
          schema: { type: integer, default: 1 }
        - name: limit
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
      responses:
        "200":
          description: Paginated checks
    post:
      summary: Create a reference check
      security:
        - bearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          schema: { type: string }
          description: Replay-safe key for ATS automations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCheckRequest"
      responses:
        "201":
          description: Check created
        "409":
          description: Duplicate externalId
  /checks/{id}:
    get:
      summary: Get check with references and responses
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Check detail
    patch:
      summary: Update check metadata or cancel
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata: { type: object, additionalProperties: true }
                status: { type: string, enum: [EXPIRED] }
                emailRemindersEnabled: { type: boolean }
      responses:
        "200":
          description: Updated check
  /webhooks:
    get:
      summary: List webhook endpoints
      security:
        - bearerAuth: []
    post:
      summary: Create webhook endpoint
      security:
        - bearerAuth: []
  /webhooks/{id}/test:
    post:
      summary: Send test webhook payload
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key (rc_live_ or rc_test_)
  schemas:
    CreateCheckRequest:
      type: object
      required: [candidateName, candidateEmail]
      properties:
        candidateName: { type: string }
        candidateEmail: { type: string, format: email }
        candidateProvidedReferences: { type: boolean, default: false }
        externalId: { type: string, maxLength: 255 }
        externalSource:
          type: string
          enum: [bullhorn, zoho_recruit, sap_successfactors, workday, greenhouse, lever, other]
        metadata: { type: object, additionalProperties: true }
        jobId: { type: string }
        questionnaireId: { type: string }
        references:
          type: array
          items:
            type: object
            required: [name, email, relationship]
            properties:
              name: { type: string }
              email: { type: string }
              relationship: { type: string }