JobMojito Document requests API

openapi: 3.2.0
info:
  title: JobMojito Document requests API
  version: 1.0.0
  description: Public API for JobMojito, served by Supabase Edge Functions. Authenticate with a Supabase JWT access token via the Authorization header.
servers:
- url: https://cool.jobmojito.com/functions/v1
  description: Production
tags:
- name: Document requests
  description: Ask candidates for documents (certificates, IDs, references), follow them up and mark them reviewed.
paths:
  /merchant-document-request-list:
    get:
      tags:
      - Document requests
      summary: List document requests
      description: 'Documents the company asked candidates for after they applied (the document_requests feature): company-wide, or of one candidate (candidate_id), optionally of one status, with each requested document and whether it was uploaded. attention=true lists instead the requests you made that need you: received (completed, not yet reviewed) and overdue (open past the due date), at most 50. Position access applies: requests of candidates you may not see, or made for an application on a position you may not see, are never listed. An audited read of candidate data. Read only.'
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          format: uuid
          description: Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant.
          example: 28106cba-1c27-4e53-b149-32113e5e8e31
        required: false
        name: merchant_id
        in: query
      - schema:
          type: string
          format: uuid
          description: Only the requests of this candidate (profile_interview.id).
        required: false
        name: candidate_id
        in: query
      - schema:
          type: string
          enum:
          - open
          - completed
          - cancelled
          description: Only open, completed or cancelled requests.
        required: false
        name: status
        in: query
      - schema:
          type: string
          enum:
          - 'true'
          - 'false'
          default: 'false'
          description: 'true: only your own requests that need you (received or overdue), as To do > Today shows them.'
          example: 'false'
        required: false
        name: attention
        in: query
      - schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
          description: Requests per page (1 to 200, default 50).
          example: 50
        required: false
        name: limit
        in: query
      - schema:
          type: integer
          nullable: true
          minimum: 0
          default: 0
          description: Number of records to skip from the start of the result set.
          example: 0
        required: false
        name: offset
        in: query
      responses:
        '200':
          description: One page of document requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtsDocumentRequestList'
        '401':
          description: Missing, expired or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Not company staff, another company, or the document_requests feature is off.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error; the message (and name, when given) says which field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: list_document_requests
  /merchant-document-request-create:
    post:
      tags:
      - Document requests
      summary: Ask a candidate for documents
      description: 'Asks a candidate to upload documents after applying (the document_requests feature): 1 to 10 documents, an optional message and due date, optionally for one of their applications. The candidate uploads them on their application page; you see them in list_document_requests. E-mail: with notify true (the default) the candidate gets "Documents requested" (the documents, your message, the due date, the position), and once more "Some documents are still missing" after the due date; nothing else is sent. Use dry_run first to check the input and see who would be e-mailed. Recorded on the candidate history. Position access applies (a candidate you may not see answers 404). Hiring managers are read only.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtsDocumentRequestCreate'
      responses:
        '200':
          description: The request (or, on a dry run, what it would be) and the e-mail outcome.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtsDocumentRequestCreateResult'
        '401':
          description: Missing, expired or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Not company staff, a hiring manager (read only), another company, or the document_requests feature is off.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such candidate or application in this company, or not visible to you (name says which).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error; the message (and name, when given) says which field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: request_candidate_documents
  /merchant-document-request-update:
    post:
      tags:
      - Document requests
      summary: Cancel a document request or mark it reviewed
      description: cancel withdraws an open request; reviewed marks a completed one reviewed (the document_requests feature). Neither sends an e-mail; a cancel is recorded on the candidate history. Position access applies (a request of a candidate or position you may not see answers 404). Hiring managers are read only.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtsDocumentRequestUpdate'
      responses:
        '200':
          description: The request after the call.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtsDocumentRequestUpdateResult'
        '401':
          description: Missing, expired or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Not company staff, a hiring manager (read only), another company, or the document_requests feature is off.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such request in this company, or not visible to you.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'cancel: the request is no longer open (completed or cancelled). reviewed: the request is not completed.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error; the message (and name, when given) says which field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: update_document_request
components:
  schemas:
    Pagination:
      type: object
      properties:
        total:
          type: integer
          description: Total matching records across all pages.
          example: 137
        limit:
          type: integer
          description: Page size used for this response.
          example: 50
        offset:
          type: integer
          description: Offset used for this response.
          example: 0
        has_more:
          type: boolean
          description: True when more records exist beyond this page (offset + returned < total).
          example: true
      required:
      - total
      - limit
      - offset
      - has_more
    AtsDocumentRequest:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Document request id (profile_interview_document_request.id).
        status:
          type: string
          enum:
          - open
          - completed
          - cancelled
          description: open (waiting for the candidate), completed (every required document uploaded) or cancelled.
        candidate_id:
          type: string
          format: uuid
          description: Candidate asked (profile_interview.id).
        candidate_name:
          type: string
          description: Candidate's name, or e-mail when the name is empty.
        application_id:
          type: string
          format: uuid
          description: Application the request was made for (position_result.id).
        position_id:
          type: string
          format: uuid
          description: That application's position (position_def_set.id).
        position_name:
          type: string
          description: That position's name.
        message:
          type: string
          description: Message to the candidate.
        due_date:
          type: string
          description: Due date (YYYY-MM-DD).
        notify:
          type: boolean
          description: The candidate was e-mailed when the request was made (and is reminded once after the due date).
        created_at:
          type: string
          description: When the request was made (ISO 8601).
        created_by_name:
          type: string
          description: Who made it.
        completed_at:
          type: string
          description: When the last required document arrived (ISO 8601).
        cancelled_at:
          type: string
          description: When it was cancelled (ISO 8601).
        reviewed_at:
          type: string
          description: When a recruiter marked the completed request reviewed (ISO 8601).
        reviewed_by_name:
          type: string
          description: Who marked it reviewed.
        overdue_reminded_at:
          type: string
          description: When the candidate got the one reminder after the due date (ISO 8601).
        attention:
          type: string
          enum:
          - received
          - overdue
          description: 'Only with attention=true: received (completed, not yet reviewed) or overdue (open past the due date).'
        documents:
          type: array
          items:
            $ref: '#/components/schemas/AtsRequestedDocument'
          description: The requested documents, in order.
      required:
      - id
      - status
      - notify
      - created_at
      - documents
    AtsDocumentRequestCreate:
      type: object
      properties:
        merchant_id:
          type: string
          format: uuid
          description: Optional company to act on. Admins and sub-merchant operators only; other callers always use their token's company.
        candidate_id:
          type: string
          format: uuid
          description: The candidate to ask (profile_interview.id).
        application_id:
          type: string
          format: uuid
          description: 'Optional: the candidate''s application this is for (position_result.id); the e-mail then names its position.'
        documents:
          type: array
          items:
            $ref: '#/components/schemas/AtsRequestedDocumentInput'
          minItems: 1
          maxItems: 10
          description: The documents to ask for, 1 to 10.
        message:
          type: string
          maxLength: 2000
          description: Message to the candidate, at most 2000 characters.
        due_date:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Due date (YYYY-MM-DD), today or later. After it the candidate is reminded once by e-mail (when notify is true).
        notify:
          type: boolean
          default: true
          description: 'Default true: e-mail the candidate "Documents requested" now (and the one reminder after the due date). false: the request only shows on their application page.'
        dry_run:
          type: boolean
          default: false
          description: 'true: check everything and answer who would be e-mailed, without creating the request or sending anything.'
      required:
      - candidate_id
      - documents
    AtsRequestedDocumentInput:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 120
          description: What you ask for, as the candidate sees it (1 to 120 characters), e.g. "Signed reference letter".
        description:
          type: string
          maxLength: 500
          description: Explanation shown to the candidate, at most 500 characters.
        required:
          type: boolean
          default: true
          description: Default true. The request completes when every required document is uploaded.
        source_field_id:
          type: string
          pattern: ^(form_cover_letter|form_national_id|custom_[A-Za-z0-9_]{1,60})$
          description: 'Optional: the position''s own file question this replaces, as its form names it (form_cover_letter, a custom_<name> question or another of the form''s file questions).'
      required:
      - title
    AtsDocumentRequestUpdate:
      type: object
      properties:
        merchant_id:
          type: string
          format: uuid
          description: Optional company to act on. Admins and sub-merchant operators only; other callers always use their token's company.
        request_id:
          type: string
          format: uuid
          description: The document request (profile_interview_document_request.id, from list_document_requests).
        action:
          type: string
          enum:
          - cancel
          - reviewed
          description: 'What to do with the request. Options — `cancel`: withdraw an open request; the candidate can no longer upload to it. | `reviewed`: mark a completed request as reviewed; it leaves To do > Today, and marking it again changes nothing.'
      required:
      - request_id
      - action
    Error:
      type: object
      properties:
        error:
          type: string
          example: Field is required.
        name:
          type: string
          example: interview_result_id
      required:
      - error
    AtsDocumentRequestList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AtsDocumentRequest'
          description: 'Document requests of this page, newest first (attention: most recent event first).'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
      - data
      - pagination
    AtsDocumentRequestCreateResult:
      type: object
      properties:
        dry_run:
          type: boolean
          description: true when nothing was created or sent.
        request_id:
          type: string
          format: uuid
          description: The new request (profile_interview_document_request.id). Left out on a dry run.
        candidate_id:
          type: string
          format: uuid
          description: The candidate (profile_interview.id).
        candidate_name:
          type: string
          description: Candidate's name, or e-mail when the name is empty.
        candidate_email:
          type: string
          description: The candidate's e-mail address, where the e-mail goes.
        application_id:
          type: string
          format: uuid
          description: The application (position_result.id).
        position_id:
          type: string
          format: uuid
          description: The application's position (position_def_set.id).
        position_name:
          type: string
          description: The position's name, as the e-mail shows it.
        message:
          type: string
          description: The message, trimmed.
        due_date:
          type: string
          description: The due date (YYYY-MM-DD).
        notify:
          type: boolean
          description: Whether the candidate is to be e-mailed.
        email:
          type: string
          enum:
          - will_send
          - not_requested
          - no_valid_email
          - suppressed
          description: 'The "Documents requested" e-mail: will_send (sent now, or at the time the company scheduled), not_requested (notify false), no_valid_email (the candidate has no usable address), suppressed (the company set this e-mail to Do not send).'
        documents:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
                description: Title, trimmed.
              description:
                type: string
                description: Explanation.
              required:
                type: boolean
                description: Required.
              source_field_id:
                type: string
                description: File question it replaces.
              sequence_no:
                type: integer
                description: Order, from 1.
            required:
            - title
            - required
            - sequence_no
          description: The documents as they are (or would be) stored.
      required:
      - dry_run
      - candidate_id
      - notify
      - email
      - documents
    AtsRequestedDocument:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Requested document id (profile_interview_document_request_item.id).
        title:
          type: string
          description: What was asked for.
        description:
          type: string
          description: Explanation shown to the candidate.
        required:
          type: boolean
          description: The request completes when every required document is uploaded.
        source_field_id:
          type: string
          description: The position's own file question it came from, as its form names it (form_cover_letter, a custom_<name> question or another of the form's file questions).
        sequence_no:
          type: integer
          description: Order in the request, from 1.
        uploaded_at:
          type: string
          description: When the candidate uploaded it (ISO 8601). Left out while missing.
        file_id:
          type: string
          format: uuid
          description: The uploaded file (interview_file.id).
        file_name:
          type: string
          description: Name of the uploaded file.
      required:
      - id
      - title
      - required
      - sequence_no
    AtsDocumentRequestUpdateResult:
      type: object
      properties:
        request_id:
          type: string
          format: uuid
          description: The document request (profile_interview_document_request.id).
        action:
          type: string
          enum:
          - cancel
          - reviewed
          description: What was done.
        status:
          type: string
          enum:
          - cancelled
          - completed
          description: The request status after the call.
        reviewed_at:
          type: string
          description: 'reviewed: when the request was (first) marked reviewed (ISO 8601).'
      required:
      - request_id
      - action
      - status
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Supabase JWT — `Authorization: Bearer <token>`.'