> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vort-sourcing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Report recruiter decisions and the notices shown

> Mandatory under the partnership. Each (run_id, candidate_id, decision) is stored
once; repeats are counted in `duplicates`. Safe to retry. Treat a 422 as
"nothing stored" and resend the corrected batch.




## OpenAPI

````yaml /api-reference/openapi.yaml post /runs/{run_id}/decisions
openapi: 3.1.0
info:
  title: Vort Partner API
  version: 1.0.0
  summary: Server-to-server API for ATS vendors embedding Vort candidate matching.
  description: >
    Guides: [Integration flow](/integration-flow). UI rules: [UI
    specification](/ui-specification). Notices: [Notices](/notices).


    - Every call is server-to-server. `vpk_` keys and `vot_` org tokens MUST NOT
    reach a browser.

    - Clients MUST ignore unknown response fields; additive changes within v1
    are non-breaking.

    - Notices with an unknown `code` MUST be rendered generically from `title` +
    `body`,
      styled by `severity`, placed by `slot`.
    - Rate limits are per partner (default 120/minute, 20,000/day); `429`
    carries `Retry-After`.

    - Sandbox ([Sandbox guide](/sandbox)): every sandbox response carries
    `x-vort-environment: sandbox`;
      names are masked, reveals are synthetic and free, `target_count` <= 20, 20 real runs
      per organization per 24 h, `cert-*` jobs run certification fixtures, and the
      sandbox-only headers `x-vort-sandbox-simulate` / `x-vort-sandbox-reveal-price` and
      route `POST /sandbox/webhooks/test` exist. None of these exist in production.
  contact:
    name: Vort partner support (always include the run_id)
  license:
    name: Proprietary
    identifier: LicenseRef-Vort-Proprietary
servers:
  - url: https://vort-partner-api.vercel.app/sandbox/v1
    description: Sandbox
security:
  - partnerKey: []
    orgToken: []
tags:
  - name: Activation
    description: Connect a customer organization by redeeming its one-time activation code.
  - name: Users
    description: Register the recruiters who act on runs (a field, never a credential).
  - name: Jobs
    description: Jobs the runs search for.
  - name: Runs
    description: Start runs and read their progress, notices and candidates.
  - name: Candidates
    description: Reveal candidate contact details (charges credits).
  - name: Decisions
    description: Report recruiter decisions and the notices shown (mandatory).
  - name: Sandbox
    description: >-
      Sandbox-only helpers (see the [Sandbox guide](/sandbox)). Not present in
      production (404).
  - name: Webhooks
    description: >-
      Events Vort posts to your registered HTTPS endpoint, signed with
      `x-vort-signature`.
paths:
  /runs/{run_id}/decisions:
    post:
      tags:
        - Decisions
      summary: Report recruiter decisions and the notices shown
      description: >
        Mandatory under the partnership. Each (run_id, candidate_id, decision)
        is stored

        once; repeats are counted in `duplicates`. Safe to retry. Treat a 422 as

        "nothing stored" and resend the corrected batch.
      operationId: reportDecisions
      parameters:
        - $ref: '#/components/parameters/RunId'
        - $ref: '#/components/parameters/Lang'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecisionsRequest'
            example:
              acting_user_external_id: u-88121
              decisions:
                - candidate_id: 48213377
                  decision: shortlisted
                  occurred_at: '2026-10-04T09:15:02Z'
                - candidate_id: 50119020
                  decision: rejected
                  reject_reason: location
                  note: Lives in Haifa, will not commute.
                  occurred_at: '2026-10-04T09:15:40Z'
              notices_shown:
                - location_relaxed
                - requirement_attribution
                - run_progress
      responses:
        '200':
          description: Stored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionsResponse'
              example:
                accepted: 2
                duplicates: 0
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: '`run_not_found` or `user_not_found`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: '`unknown_reject_reason` (with `allowed[]`) or `invalid_decision`'
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/UnknownRejectReasonError'
                  - $ref: '#/components/schemas/Error'
              examples:
                unknownRejectReason:
                  value:
                    error: unknown_reject_reason
                    message: 'Unknown reject reason: too_expensive'
                    allowed:
                      - cv_irrelevant
                      - overqualified
                      - location
                      - insufficient_experience
                      - declined
                      - candidate_withdrew
                      - known
                invalidDecision:
                  value:
                    error: invalid_decision
                    message: reject_reason is only allowed with decision "rejected".
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    RunId:
      name: run_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    Lang:
      name: x-vort-lang
      in: header
      required: false
      description: Language of notices and messages. Defaults to the partner default.
      schema:
        type: string
        enum:
          - he
          - en
  schemas:
    DecisionsRequest:
      type: object
      required:
        - acting_user_external_id
        - decisions
      properties:
        acting_user_external_id:
          type: string
        decisions:
          type: array
          description: May be empty when only reporting notices_shown.
          items:
            $ref: '#/components/schemas/Decision'
        notices_shown:
          type: array
          description: >-
            Codes of notices rendered to a recruiter for this run, including
            unknown codes.
          items:
            type: string
    DecisionsResponse:
      type: object
      required:
        - accepted
        - duplicates
      properties:
        accepted:
          type: integer
          minimum: 0
        duplicates:
          type: integer
          minimum: 0
    Error:
      type: object
      description: >-
        Error envelope. Branch on `error`; unknown codes are handled by HTTP
        status.
      required:
        - error
        - message
      properties:
        error:
          type: string
          examples:
            - invalid_partner_key
            - invalid_org_token
            - partner_disabled
            - organization_disabled
            - rate_limited
            - rate_limit_unavailable
            - code_not_found
            - code_expired
            - external_id_taken
            - invalid_user
            - job_not_found
            - user_not_found
            - run_not_found
            - candidate_not_in_run
            - invalid_decision
        message:
          type: string
      additionalProperties: true
    UnknownRejectReasonError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          required:
            - allowed
          properties:
            error:
              const: unknown_reject_reason
            allowed:
              type: array
              items:
                type: string
    Decision:
      type: object
      required:
        - candidate_id
        - decision
        - occurred_at
      properties:
        candidate_id:
          type: integer
          format: int64
        decision:
          $ref: '#/components/schemas/DecisionValue'
        reject_reason:
          description: >-
            Only with decision `rejected`. null when the recruiter picked no
            reason.
          oneOf:
            - $ref: '#/components/schemas/RejectReason'
            - type: 'null'
        note:
          type:
            - string
            - 'null'
        occurred_at:
          type: string
          format: date-time
    DecisionValue:
      type: string
      enum:
        - shortlisted
        - rejected
        - contacted
        - interviewing
        - hired
    RejectReason:
      type: string
      enum:
        - cv_irrelevant
        - overqualified
        - location
        - insufficient_experience
        - declined
        - candidate_withdrew
        - known
  responses:
    Unauthorized:
      description: '`invalid_partner_key` or `invalid_org_token`'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: invalid_org_token
            message: The organization token is not valid.
    Forbidden:
      description: '`partner_disabled` or `organization_disabled`'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: organization_disabled
            message: This organization's Vort connection is disabled.
    RateLimited:
      description: '`rate_limited`'
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: rate_limited
            message: Too many requests.
    ServiceUnavailable:
      description: >-
        `rate_limit_unavailable` — the rate limiter could not be checked, so the
        request was refused rather than let through unmetered. Retry with
        backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: rate_limit_unavailable
            message: Rate limiting is temporarily unavailable. Retry shortly.
  headers:
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        minimum: 0
  securitySchemes:
    partnerKey:
      type: apiKey
      in: header
      name: x-partner-key
      description: 'Partner API key: `vpk_live_` + 48 lowercase hex. Server-side only.'
    orgToken:
      type: apiKey
      in: header
      name: x-vort-org
      description: >-
        Customer org token: `vot_` + 48 lowercase hex, from /activations/redeem.
        Server-side only.

````