---
post:

  summary: Set the signatory authentication-to-sign method

  tags:
    - Modify

  description: |
    Set the signatory authentication-to-sign method after the document has been
    started.

    *Side effects of this operation may include adding or modifying fields for the signatory.*

    For example, if the signatory does not have a field for mobile number, then
    setting the authentication method to SMS PIN will necessitate adding a
    mobile number field to the signatory and setting it as obligatory.

    *OAuth Privileges required: `DOC_SEND`*

  parameters:
    - $ref: ../../../../extras/parameters.yaml#/DocumentID
    - $ref: ../../../../extras/parameters.yaml#/SignatoryID
    - name: authentication_type
      in: formData
      type: string
      enum:
        - standard
        - sms_pin
        - se_bankid
        - no_bankid
        - dk_nemid
        - fi_tupas
        - onfido_document_check
        - onfido_document_and_photo_check
      required: true
      description: |
        The type of authentication-to-sign method to set for the signatory.
    - name: personal_number
      in: formData
      type: string
      # TODO format?
      required: false
      # default not valid here
      description: |
        If provided, it must be valid for the chosen authentication-to-sign
        method.

        If it is not used by the chosen authentication-to-sign method, the
        parameter will be ignored and will have no effect.

        If not provided, any existing `personal_number` field value set for the
        signatory will not be changed.
        However, if a `personal_number` _SignatoryField_ does not yet exist,
        one will be added to the signatory (with empty string as `value`).
    - name: mobile_number
      in: formData
      type: string
      # TODO format?
      required: false
      # default not valid here
      description: |
        If provided, it must be valid for the chosen authentication-to-sign
        method.

        If it is not used by the chosen authentication-to-sign method, the
        parameter will be ignored and will have no effect.

        If not provided, any existing `mobile` field value set for the
        signatory will not be changed.
        However, if a `mobile` _SignatoryField_ does not yet exist, one will be
        added to the signatory (with empty string as `value`).
    - $ref: ../../../../extras/parameters.yaml#/ObjectVersion

  responses:
    200:
      $ref: ../../../../extras/responses.yaml#/Document
    409:
      description: |
        Possible error responses:

        * `document_state_error`: The document status should be 'Pending'.
        * `signatory_state_error`: The signatory has already signed.
        * `signatory_state_error`: You can’t mix different e-legitimation
           providers (one for viewing and another for signing) for the same
           signatory.