ZippedScript Reference Checks API

openapi: 3.2.0
info:
  title: ZippedScript Reference Checks API
  description: ZippedScript's enterprise education verification API
  termsOfService: https://zippedscript.com/privacy
  contact:
    email: support@zippedscript.com
  version: v1
servers:
- url: http://app.zippedscript.com/api/v1
security:
- apiKeyAuth: []
tags:
- name: reference_checks
paths:
  /reference_checks/:
    parameters: []
    get:
      operationId: reference_checks_list
      summary: List Reference Check Records
      description: Retrieve a paginated list of reference check records which can be optionally filtered by candidate and reference names. Ordered by creation time (most recent first) by default; pass ordering=last_activity to instead order by the latest status change (e.g. a status update triggered by a response).
      parameters:
      - name: candidate_name
        in: query
        description: Filter by candidate name
        schema:
          type: string
      - name: reference_name
        in: query
        description: Filter by reference name
        schema:
          type: string
      - name: reference_email
        in: query
        description: Filter by reference email
        schema:
          type: string
      - name: request_id
        in: query
        description: Filter by request ID
        schema:
          type: string
      - name: status
        in: query
        description: Filter by status
        schema:
          type: string
      - name: page
        in: query
        description: Page number
        schema:
          type: integer
      - name: page_size
        in: query
        description: Page size
        schema:
          type: integer
      - name: ordering
        in: query
        description: Set to 'last_activity' to order by the most recent status change instead of creation time
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedReadReferenceCheckSerializer'
      tags:
      - reference_checks
    post:
      operationId: reference_checks_create
      summary: Create Reference Check Record
      description: Create one or more reference check records. The record's company is automatically set to the authenticated user's company. The body may be a single object or an array of objects; a single object is treated as an array of one, and the response is always an array.
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReadReferenceCheck'
      tags:
      - reference_checks
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateReferenceCheck'
        required: true
  /reference_checks/check_request_id/{request_id}:
    parameters:
    - name: request_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: reference_checks_check_request_id_read
      summary: Check Request ID
      description: Check if a request ID is already used for the company.
      responses:
        '200':
          description: Existence status of the request ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  exists:
                    type: boolean
      tags:
      - reference_checks
  /reference_checks/token/{token}:
    parameters:
    - name: token
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: reference_checks_token_read
      summary: Retrieve Reference Checks by Token
      description: Retrieve the pending reference checks sent to the email address associated with the token. Used by the public-facing reference forms.
      parameters:
      - name: token
        in: path
        description: The unique token associated with an email address
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReadReferenceCheck'
        '404':
          description: Token not found
      tags:
      - reference_checks
  /reference_checks/{reference_check_id}:
    parameters:
    - name: reference_check_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: reference_checks_read
      summary: Retrieve reference check details
      description: Retrieve a single reference check record belonging to the authenticated user's company.
      parameters:
      - name: reference_check_id
        in: path
        description: The unique identifier of the reference check record
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadReferenceCheck'
        '404':
          description: Reference check not found
      tags:
      - reference_checks
    put:
      operationId: reference_checks_update
      summary: Update reference check details
      description: 'Partially update a reference check record: only the fields sent are changed, and none are required. Restricted to administrative users.'
      parameters:
      - name: reference_check_id
        in: path
        description: The unique identifier of the reference check record
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadReferenceCheck'
        '400':
          description: Invalid input data
        '403':
          description: Permission denied
        '404':
          description: Reference check not found
      tags:
      - reference_checks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateReferenceCheck'
        required: true
    delete:
      operationId: reference_checks_delete
      summary: Delete reference check record
      description: ''
      parameters:
      - name: reference_check_id
        in: path
        description: The unique identifier of the reference check record
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '404':
          description: Reference check not found
      tags:
      - reference_checks
  /reference_checks/{reference_check_id}/cancel:
    parameters:
    - name: reference_check_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: reference_checks_cancel_create
      summary: Cancel reference check request
      description: Cancel a reference check request that is in progress. Completed or already cancelled checks cannot be cancelled.
      parameters:
      - name: reference_check_id
        in: path
        description: The unique identifier of the reference check record
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferenceStatus'
        '400':
          description: Reference check is already completed or cancelled
        '404':
          description: Reference check not found
      tags:
      - reference_checks
  /reference_checks/{reference_check_id}/consent:
    parameters:
    - name: reference_check_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: reference_checks_consent_create
      summary: Upload end-user consent file(s)
      description: Upload one or more PDF files containing the candidate's consent for the reference check. You can upload multiple files using any field name in the multipart form.
      parameters:
      - name: reference_check_id
        in: path
        description: The unique identifier of the reference check record
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Consent file(s) uploaded successfully
        '400':
          description: Invalid file or request
        '404':
          description: Reference check not found
      tags:
      - reference_checks
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  description: One or more PDF files to upload
                  format: binary
              required:
              - file
  /reference_checks/{reference_check_id}/verify:
    parameters:
    - name: reference_check_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: reference_checks_verify_create
      summary: Submit reference check verification
      description: Submit the reference's response for the given reference check. Marks the check as completed unless it has been cancelled.
      parameters:
      - name: reference_check_id
        in: path
        description: The unique identifier of the reference check record
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Reference check verification submitted successfully
        '400':
          description: Invalid input data
        '404':
          description: Reference check not found
      tags:
      - reference_checks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReferenceCheckVerification'
        required: true
components:
  schemas:
    Candidate:
      required:
      - candidate_name
      type: object
      properties:
        candidate_id:
          title: Candidate id
          type: string
          readOnly: true
          minLength: 1
        candidate_name:
          title: Candidate name
          type: string
          maxLength: 255
          minLength: 1
        created_at:
          title: Created at
          type: string
          format: date-time
          readOnly: true
    UpdateReferenceCheck:
      type: object
      properties:
        candidate:
          title: Candidate
          type: string
        request_id:
          title: Request id
          type: string
          maxLength: 256
          minLength: 1
        reference_name:
          title: Reference name
          type: string
          maxLength: 255
          minLength: 1
        reference_email:
          title: Reference email
          description: The email of the reference to send the check request to.
          type: string
          format: email
          maxLength: 254
          minLength: 1
        relationship:
          title: Relationship
          description: Relationship to the candidate
          type:
          - string
          - 'null'
          maxLength: 255
        additional_details:
          title: Additional details
          type:
          - object
          - 'null'
        end_user_consent_files:
          title: End user consent files
          type:
          - object
          - 'null'
        lang:
          title: Lang
          type: string
          maxLength: 10
        initial_email_sent:
          title: Initial email sent
          type: boolean
        cadence_emails_sent:
          title: Cadence emails sent
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        last_cadence_email_sent:
          title: Last cadence email sent
          type:
          - string
          - 'null'
          format: date-time
        company:
          title: Company
          type: integer
        initiator:
          title: Initiator
          description: The user who created the reference check request
          type:
          - integer
          - 'null'
    CreateReferenceCheckVerification:
      required:
      - reference_check
      type: object
      properties:
        reference_check:
          title: Reference check
          type: string
        reference_name:
          title: Reference name
          type:
          - string
          - 'null'
          maxLength: 255
        relationship:
          title: Relationship
          type:
          - string
          - 'null'
          maxLength: 255
        reference_response:
          title: Reference response
          description: The feedback provided by the reference
          type:
          - string
          - 'null'
        additional_details:
          title: Additional details
          type:
          - object
          - 'null'
        ip:
          title: Ip
          description: The IP address the verification was submitted from. Never returned by the API
          type:
          - string
          - 'null'
          minLength: 1
    PaginatedReadReferenceCheckSerializer:
      required:
      - count
      - next
      - previous
      - results
      type: object
      properties:
        count:
          title: Count
          description: Total number of records able to be retrieved
          type: integer
        next:
          title: Next
          description: A link to the next page of records
          type:
          - string
          - 'null'
        previous:
          title: Previous
          description: A link to the previous page of records
          type:
          - string
          - 'null'
        results:
          description: A list of the returned records
          type: array
          items:
            $ref: '#/components/schemas/ReadReferenceCheck'
    ReferenceStatus:
      required:
      - status
      type: object
      properties:
        status:
          title: Status
          description: The current status of the reference check
          type: string
          enum:
          - Awaiting results
          - Completed
          - Stale
          - Not delivered
          - Cancelled
        created_at:
          title: Created at
          type: string
          format: date-time
          readOnly: true
    CreateReferenceCheck:
      required:
      - request_id
      - candidate
      - reference_name
      - reference_email
      type: object
      properties:
        request_id:
          title: Request id
          type: string
          maxLength: 256
          minLength: 1
        candidate:
          title: Candidate
          type: string
        reference_name:
          title: Reference name
          type: string
          maxLength: 255
          minLength: 1
        reference_email:
          title: Reference email
          description: The email of the reference to send the check request to.
          type: string
          format: email
          maxLength: 254
          minLength: 1
        relationship:
          title: Relationship
          description: Relationship to the candidate
          type:
          - string
          - 'null'
          maxLength: 255
        additional_details:
          title: Additional details
          type:
          - object
          - 'null'
        lang:
          title: Lang
          type: string
          maxLength: 10
    ReadReferenceCheck:
      description: A list of the returned records
      required:
      - request_id
      - reference_name
      - reference_email
      - company
      type: object
      properties:
        candidate:
          $ref: '#/components/schemas/Candidate'
        verified:
          title: Verified
          type: string
          readOnly: true
        current_status:
          title: Current status
          description: The most recent status of the reference check
          type: string
          readOnly: true
        end_user_consent_file_download_urls:
          title: End user consent file download urls
          description: URLs to download all end-user consent files
          type: string
          readOnly: true
        email_sent_times:
          title: Email sent times
          description: The times that emails were sent out for this record
          type: string
          readOnly: true
        created_at:
          title: Created at
          type: string
          format: date-time
          readOnly: true
        request_id:
          title: Request id
          type: string
          maxLength: 256
          minLength: 1
        reference_check_id:
          title: Reference check id
          type: string
          readOnly: true
          minLength: 1
        reference_name:
          title: Reference name
          type: string
          maxLength: 255
          minLength: 1
        reference_email:
          title: Reference email
          description: The email of the reference to send the check request to.
          type: string
          format: email
          maxLength: 254
          minLength: 1
        relationship:
          title: Relationship
          description: Relationship to the candidate
          type:
          - string
          - 'null'
          maxLength: 255
        additional_details:
          title: Additional details
          type:
          - object
          - 'null'
        end_user_consent_files:
          title: End user consent files
          type:
          - object
          - 'null'
        lang:
          title: Lang
          type: string
          maxLength: 10
        initial_email_sent:
          title: Initial email sent
          type: boolean
        cadence_emails_sent:
          title: Cadence emails sent
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        last_cadence_email_sent:
          title: Last cadence email sent
          type:
          - string
          - 'null'
          format: date-time
        company:
          title: Company
          type: integer
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: Authorization
      in: header
      description: 'Enter the full header value, including the prefix: `Token <api_key>` for an API key from `GET /user/api-key`, or `Bearer <access>` for a JWT from `POST /user/login`. A bare key without the prefix is rejected with 403.'