---
post:

  summary: Set a signatory attachment

  tags:
    - Sign
    - Internal

  description: |
    Set a signatory attachment that was requested by the document author.

    There can be multiple signatory attachments with different names,
    though at most one of a particular name for a signatory of a document.

    Also, as opposed to author attachments, signatory attachments are set one by
    one and are explicitly named.

  parameters:
    - $ref: ../../../../extras/parameters.yaml#/DocumentID
    - $ref: ../../../../extras/parameters.yaml#/SignatoryID
    - name: name
      in: formData
      type: string
      required: true
      description: |
        The name of the attachment.

        Must match an attachment name as requested by the document author.
    - name: attachment
      in: formData
      type: file
      format: application/pdf
      required: false
      # default not valid here
      description: |
        Set / Unset a named signatory attachment for a signatory of a document.

        If provided, this is the file to set as the attachment.

        If not provided, this will remove the existing attachment.
    - $ref: ../../../../extras/parameters.yaml#/ObjectVersion

  responses:
    200:
      $ref: ../../../../extras/responses.yaml#/Document
    400:
      description: The PDF provided is invalid.
      # FIXME It is possible to add a schema here, although APIError is too general
    409:
      description: TODO
      # TODO
      # document_state_error; The document is not pending.
      # signatory_state_error; The signatory has already signed.
      # request_parameters_invalid; There is no attachment with that name for the signatory.
      # signatory_state_error; (If attachment is included) An attachment of this name for this signatory and document is already set, remove it first.
      # signatory_state_error; (If `attachment` is omitted) There is no attachment to remove of this name for this signatory and document.
      # FIXME It is possible to add a schema here, although APIError is too general