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

# Update candidate reference

> Updates the fields that the request contains: the referrer, the referred candidate or the comments. A pair of candidates can have only one reference.



## OpenAPI

````yaml /api-reference/openapi.json patch /candidates/references/{referenceId}
openapi: 3.1.0
info:
  title: Spott API Reference
  version: '0.1'
servers:
  - url: https://api.gospott.com
security: []
tags: []
paths:
  /candidates/references/{referenceId}:
    patch:
      tags:
        - Candidates
      summary: Update candidate reference
      description: >-
        Updates the fields that the request contains: the referrer, the referred
        candidate or the comments. A pair of candidates can have only one
        reference.
      operationId: updateCandidateReference
      parameters:
        - name: referenceId
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCandidateReferenceDto'
      responses:
        '204':
          description: Reference updated successfully.
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          description: Bad request - invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseDto'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '401':
          description: Unauthorized - invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseDto'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '404':
          description: The reference, or a candidate in the request, was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseDto'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '409':
          description: A reference already exists for this referrer and referred candidate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseDto'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '429':
          description: >-
            Too Many Requests. The published limit for this endpoint is 600
            requests per minute per workspace. The limit in force for your
            workspace can differ from it in either direction — a workspace on a
            free trial can be capped lower, and a higher limit can be arranged
            through support — so the headers, not this number, are
            authoritative. Read the RateLimit-Policy response header for the
            quota actually in force and RateLimit for what is left of the
            current window; on a 429, Retry-After gives the seconds to wait.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseDto'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
        '500':
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorDto'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
      security:
        - x-api-key: []
components:
  schemas:
    UpdateCandidateReferenceDto:
      type: object
      properties:
        referrerId:
          description: The ID of the new candidate that gave the reference.
          type: string
          minLength: 1
        referredId:
          description: The ID of the new candidate that received the reference.
          type: string
          minLength: 1
        comments:
          description: The new comments. Send null to remove the comments.
          type:
            - string
            - 'null'
    ExceptionBaseDto:
      type: object
      properties:
        status:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        category:
          $ref: '#/components/schemas/ApiErrorCategoryDto'
        message:
          type: string
        requestId:
          type: string
      required:
        - status
        - message
        - requestId
    InternalServerErrorDto:
      type: object
      properties:
        status:
          type: number
          const: 500
        category:
          type: string
          enum:
            - INTERNAL_ERROR
        message:
          type: string
          enum:
            - Internal server error
        requestId:
          type: string
      required:
        - status
        - category
        - message
        - requestId
    ApiErrorCategoryDto:
      type: string
      enum:
        - MALFORMED_REQUEST
        - SCHEMA_VALIDATION_FAILED
        - DOMAIN_VALIDATION_FAILED
        - OPERATION_LIMIT_EXCEEDED
        - AUTHENTICATION_REQUIRED
        - AUTHENTICATION_FAILED
        - SECURITY_CHALLENGE_REQUIRED
        - SECURITY_CHALLENGE_FAILED
        - PERMISSION_DENIED
        - ENTITLEMENT_REQUIRED
        - PROVIDER_AUTHENTICATION_REQUIRED
        - PROVIDER_AUTHENTICATION_FAILED
        - CONFIGURATION_REQUIRED
        - RESOURCE_NOT_FOUND
        - RESOURCE_ALREADY_EXISTS
        - RESOURCE_EXPIRED
        - RESOURCE_BUSY
        - RESOURCE_STATE_CONFLICT
        - QUOTA_EXCEEDED
        - RATE_LIMITED
        - UNSUPPORTED_OPERATION
        - UPSTREAM_REJECTED
        - TIMEOUT
        - TEMPORARILY_UNAVAILABLE
        - INTERNAL_ERROR
  headers:
    RateLimit:
      description: >-
        Quota state for this endpoint, as an RFC 8941 structured field
        (draft-ietf-httpapi-ratelimit-headers). The quoted value names the
        policy — the operationId of the endpoint the counters belong to. `r` is
        how many requests are left in the current window, `t` how many seconds
        remain before it resets.
      schema:
        type: string
      example: '"getCandidates";r=417;t=23'
    RateLimit-Policy:
      description: >-
        The policy the RateLimit header reports against, as an RFC 8941
        structured field. `q` is the quota — the requests allowed per window —
        and `w` the window length in seconds. Limits are per endpoint, so the
        quota differs between operations. This is the quota in force for the
        calling workspace, which can be lower or higher than the default
        published on the operation; treat it as authoritative.
      schema:
        type: string
      example: '"getCandidates";q=600;w=60'
    Retry-After:
      description: >-
        Seconds to wait before retrying. Sent on 429 responses; it matches the
        `t` parameter of the RateLimit header.
      schema:
        type: integer
      example: 23
  securitySchemes:
    x-api-key:
      type: apiKey
      name: x-api-key
      in: header
      description: >-
        API key for authentication. Get your API key from Settings → API Keys in
        your Spott dashboard.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.