SWswisscom
Process: manage

Replace a signer

Replaces an existing signer with a new one. The replaced signer gets the status REPLACED and loses access to the process; the new signer references it via replaces. The new signer always inherits the signing index and the signature positions of the replaced signer, they cannot be set in the request. The externalIdentifier is not inherited. To keep your reference, pass the same externalIdentifier again. It must not be used by another current signer of the process. If the replaced signer had the status PENDING, the new signer is invited immediately, otherwise as soon as it is their turn.

Preconditions:

  • The process must have the status PENDING.
  • The signer must have the status WAITING or PENDING.
  • The signer must not be required to complete an online identification (ident.required is true).
post/api/process/{processId}/signer/{personId}/replace

Request

Path parameters

processIdstring uuid required

Unique identifier of the process.

personIdstring required

The system-assigned identifier or the external reference from your system can be used to identify the signer. If several signers share the same external reference (e.g. after a replacement), the signer with status WAITING or PENDING is used.

Request body

externalIdentifierstring

External reference from your system. It is not inherited from the replaced signer, pass the same value again to keep your reference. Must not be used by another current signer (status WAITING, PENDING or SIGNED) of the process.

firstNamestring required

First name.

lastNamestring required

Last name.

emailstring email

Email address (RFC 5322).

mobilestring

Mobile number in international format (+ or 00 prefix, no spaces or dashes). Swiss numbers (+41) must be mobile numbers (+4175 to +4179), numbers of other countries are only checked for the format.

  • Authorization behavior: If a mobile number is provided, the fallback code authorization uses an SMS code.
  • Signing behavior: If the number is a Swiss mobile (+41…), it will be preselected for ADVANCED signatures and cannot be changed in the UI.
rolestring

Role or function of the signer.

Example request

{
  "externalIdentifier": "crm-4712",
  "firstName": "Jane",
  "lastName": "Roe",
  "email": "jane.roe@example.com",
  "mobile": "+41791234567",
  "role": "Chief Signing Officer (CSO)"
}

Response

The signer has been replaced. The modified process is returned.

idstring uuid

System-assigned process identifier.

status'CREATED' | 'PENDING' | 'COMPLETED' | 'EXPIRED'

Current lifecycle state of the process.

signatureLevel'SIMPLE' | 'ADVANCED' | 'ADVANCED_EU' | 'QUALIFIED' | 'QUALIFIED_EU'

Legal quality of the signature(s).

teamIdstring uuid nullable

Optional identifier of an existing team to which the process will be assigned. The team must be created in the cockpit beforehand and the teamId can be retrieved there. If provided, the process will be visible to all members of the specified team. The team assignment cannot be modified after the process is created.

payloadstring

Optional opaque application payload for correlation/auditing. May contain a JSON string.

validUntilstring date-time

Expiration timestamp of the process. After this point in time, the system automatically transitions the process status to EXPIRED.

createdDatestring date-time

Creation timestamp (UTC).

lastModifiedDatestring date-time

Last modification timestamp (UTC).

archiveOnstring date-time

Scheduled archival time, if any (UTC).

archivedOnstring date-time

Actual time when archival happened, if archived (UTC).

partnerIdstring nullable

Optional partner identifier. If provided, it must reference an existing partner.

authorization'CODE' | 'ACCOUNT'

Authorization requirements for accessing the process.

signingOrder'PARALLEL' | 'SERIAL' nullable

Signing order of the process.

  • PARALLEL – All signers may sign in any order. Default value, including before the process has been released.
  • SERIAL – Signers sign one after another, per each signer's signingIndex. Only takes effect once the process has been released with signingOrder: SERIAL.

Example response

{
  "signatureLevel": "QUALIFIED",
  "initiator": {
    "type": "NON_PERSON",
    "externalIdentifier": "ext-systems_oms-42",
    "name": "Swisscom Sign Orchestrator"
  },
  "invitees": {
    "personalMessage": "Hello, please sign. Thank you!",
    "signers": [
      {
        "type": "SIGNER",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "status": "PENDING"
      }
    ]
  },
  "properties": [
    {
      "key": "contractType",
      "value": "NDA"
    },
    {
      "key": "department",
      "value": "Legal"
    }
  ],
  "payload": "{ \"caseId\": \"ABC-42\", \"priority\": \"HIGH\" }",
  "validUntil": "2025-12-31T23:59:59Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.