JobMojito Reasons API

openapi: 3.2.0
info:
  title: JobMojito Reasons 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: Reasons
paths:
  /merchant-reason-list:
    get:
      tags:
      - Reasons
      summary: List the company's reasons
      description: 'The company''s decision reasons (why a candidate was rejected or withdrew; the decision_reasons feature) and position status reasons (why a position went on hold, was cancelled, closed or filled: the reason_id job-interview-set-state takes; the position_lifecycle feature). The first read of position status reasons gives the company the six defaults, as the admin''s Taxonomy page does. Every staff role may read. 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
          enum:
          - decision
          - position_status
          description: 'Only one type: decision (reject / withdraw reasons) or position_status (the reason_id of a position lifecycle change). Left out: both, without a type the company has switched off.'
        required: false
        name: type
        in: query
      - schema:
          type: string
          enum:
          - reject
          - withdraw
          description: 'Decision reasons only: reject or withdraw.'
        required: false
        name: kind
        in: query
      - schema:
          type: string
          enum:
          - 'true'
          - 'false'
          default: 'false'
          description: 'true: also the archived reasons, which past decisions keep but are no longer offered.'
          example: 'false'
        required: false
        name: include_archived
        in: query
      - schema:
          type: string
          pattern: ^[a-z]{2}$
          default: en
          description: Language of a decision reason's display_label (default en).
          example: en
        required: false
        name: language
        in: query
      responses:
        '200':
          description: The reasons.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReasonList'
        '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 type asked for is switched off for the company (the message names the switch).
          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_reasons
  /merchant-reason-get:
    get:
      tags:
      - Reasons
      summary: Get one of the company's reasons
      description: One decision or position status reason of the company by id, archived ones included. Every staff role may read. 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: The reason (an id from merchant-reason-list, a decision or a position lifecycle change).
        required: true
        name: reason_id
        in: query
      - schema:
          type: string
          enum:
          - decision
          - position_status
          description: Its type, when known (decision or position_status); left out, both are searched.
        required: false
        name: type
        in: query
      responses:
        '200':
          description: The reason.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reason'
        '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 type asked for is switched off for the company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No reason with this id in this company.
          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: get_reason
  /merchant-reason-save:
    post:
      tags:
      - Reasons
      summary: Create, change or archive a reason
      description: 'Creates a decision or position status reason of the company, or changes, archives or restores one (fields left out keep their value). A reason is company-wide: renaming one renames it on every past decision or lifecycle change that uses it. Owners only (and JobMojito admins), as on the admin''s Taxonomy page. Sends nothing to candidates.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReasonSave'
      responses:
        '200':
          description: The reason after the change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReasonSaveResult'
        '401':
          description: Missing, expired or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Not an owner of the company, another company, or the type is switched off for the company (the message names the switch).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No reason with this id in this company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: The company already has an active reason with this label (name label).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'A field that does not fit: a field of the other type, a missing kind, label or applies_to on a new reason, a changed kind, or restoring a position status reason (name says which).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: save_reason
components:
  schemas:
    Reason:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: 'Reason id: reason_id of merchant-reason-save, of a decision and of job-interview-set-state.'
        type:
          type: string
          enum:
          - decision
          - position_status
          description: 'decision: why a candidate was rejected or withdrew. position_status: why a position went on hold, was cancelled, closed or filled.'
        kind:
          type: string
          enum:
          - reject
          - withdraw
          description: 'Decision reasons: reject (the company turned the candidate down) or withdraw (the candidate pulled out).'
        applies_to:
          type: array
          items:
            type: string
            enum:
            - on_hold
            - cancelled
            - closed
            - filled
          description: 'Position status reasons: the lifecycles it can be given for.'
        label:
          type: string
          description: The reason as the company wrote it.
        display_label:
          type: string
          description: 'Decision reasons: the label in the requested language (its translation, else the label).'
        translations:
          type: object
          additionalProperties:
            type: string
          description: 'Decision reasons: the label per two-letter language code.'
        default_key:
          type: string
          description: 'Position status reasons: set on the six defaults while their label is unchanged (budget_freeze, priorities_changed, internal_candidate, role_redefined, filled_outside, other).'
        sort_order:
          type: integer
          description: Position in the list (lower first).
        status:
          type: string
          enum:
          - active
          - archived
          description: 'active: offered when deciding or changing a lifecycle. archived: kept on past decisions, no longer offered.'
        use_count:
          type: integer
          description: 'Decision reasons: how many decisions use it.'
      required:
      - id
      - type
      - label
      - sort_order
      - status
    ReasonSaveResult:
      allOf:
      - $ref: '#/components/schemas/Reason'
      - type: object
        properties:
          created:
            type: boolean
            description: True when a new reason was created.
        required:
        - created
    ReasonSave:
      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.
        type:
          type: string
          enum:
          - decision
          - position_status
          description: decision (why a candidate was rejected or withdrew) or position_status (why a position went on hold, was cancelled, closed or filled).
        reason_id:
          type: string
          format: uuid
          description: 'The reason to change (from merchant-reason-list). Left out: a new reason is created.'
        kind:
          type: string
          enum:
          - reject
          - withdraw
          description: 'Decision reasons: reject or withdraw. Required for a new one; it cannot change later.'
        label:
          type: string
          maxLength: 120
          description: The reason, 1 to 120 characters. Required for a new one; left out on a change, it stays.
        translations:
          type: object
          additionalProperties:
            type: string
          description: 'Decision reasons: the label per two-letter language code, e.g. {"de": "Zu wenig Erfahrung"}. Replaces the stored translations; left out on a change, they stay.'
        applies_to:
          type: array
          items:
            type: string
            enum:
            - on_hold
            - cancelled
            - closed
            - filled
          minItems: 1
          description: 'Position status reasons: the lifecycles it can be given for (on_hold, cancelled, closed, filled). Required for a new one; left out on a change, it stays.'
        sort_order:
          type: integer
          minimum: 0
          maximum: 100000
          description: 'Position in the list (lower first). Left out: the end of the list for a new reason, unchanged otherwise.'
        status:
          type: string
          enum:
          - active
          - archived
          description: 'archived: no longer offered; past decisions and lifecycle changes keep it. active: offered again (decision reasons only: an archived position status reason cannot be restored).'
      required:
      - type
    Error:
      type: object
      properties:
        error:
          type: string
          example: Field is required.
        name:
          type: string
          example: interview_result_id
      required:
      - error
    ReasonList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Reason'
          description: Decision reasons by kind, then position status reasons, each in the company's order.
      required:
      - data
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Supabase JWT — `Authorization: Bearer <token>`.'