Backend for frontend

The following endpoints are utilized by the SWF frontend. Endpoints under the /admin category require administrative authorization, while /auth endpoints are designated for user authentication. All remaining endpoints are secured with user-specific authorization.

Available endpoints

/api/document_signing*

Method Path Body type Description
GET /   Task count
GET /tasks   Fetch all tasks with a specific status. Example: /tasks?status=PENDING
GET /tasks/:taskId   Fetch a specific task
POST /tasks JSON Create task
PUT /tasks/:taskId JSON Update task
DELETE /tasks/:taskId   Delete task
PUT /task/:taskId/remind   Send reminders to all pending signers
POST /files Form data Create file
PUT /files/:fileId/convert Form data Convert file
PUT /files/:fileId/convert/approve Form data Approve conversion
GET /validate/:taskId   Validate files for a specific task
PUT /tasks/:taskId/cancel Plain text Cancel task. Returns a text "Cancelled" if succeeded
POST /tasks/:taskId/rejections   Reject signature. Returns a text "rejected" if succeeded
POST /tasks/:taskId/signatures   Begin signature. This endpoint will be used for the frontend and will be used to upload files to the signing server and to redirect to the signing server
GET /tasks/:taskId/signatures   Begin signature. Just like the above endpoint, but will be used by email invitations to redirect users to the signing server
PUT /tasks/:taskId/signatures/:signatureId   End signature. Stores the signed document and redirects the user to the correct URL
POST /tasks/:taskId/signatures/:signatureId   End signature. Just like the above endpoint, but will be used by email invitations to redirect users to the signing
GET /tasks/:taskId/files   Download files. If one, the file will be downloaded, if many, the files will be bundled into a zip file
GET /tasks/:taskId/files/:fileId   Download specific file
GET /orders/:taskId/signatures   Backwards compatibility endpoint for users with an email from SWF 2.x

/api/document_signing/admin*

Method Path Body type Description
GET /   Task count
GET /tasks   Fetch all tasks with a specific status. Example: /tasks?status=PENDING
GET /tasks/:taskId   Fetch a specific task
PUT /tasks/:taskId   Update task
GET /tasks/:taskId/files   Download files. If one, the file will be downloaded, if many, the files will be bundled into a zip file
GET /tasks/:taskId/files/:fileId   Download specific file
PUT /tasks/:taskId/remind   Send reminders to all pending signers
POST /tasks/:taskId/cancel   Cancel task

/finalize

Method Path Body type Description
GET /task/:taskId/signature/:signatureId/:status   Route for redirecting the user to their designated final page after signing
POST /task/:taskId/signature/:signatureId/:status   Same as above, but for POST requests

/landing

Method Path Body type Description
GET /   Endpoint for loading landing page configurations and showing spinner
POST /   Same as above, but for POST requests

/auth

Method Path Body type Description
GET /   Get user information for current user
POST /saml   SAML redirect
POST /logout   Logout + redirect if logoutUrl is configured
GET /jwtAuth   Login endpoint for email invitations

/lang

Method Path Body type Description
GET /   Fetch locale. Example: /lang/en will fetch english locale

/users

Method Path Body type Description
GET /employees   Search for employees
GET /citizens   Search for citizens

Bodies

Get tasks

Response body - PENDING 

{
  "tasks": [
    {
      "id": string,
      "title": string,
      "containsEmailSigner": boolean,
      "creator": string,
      "created": number,
      "dueDate": number,
      "signedBy": string
    }
  ]
}
Click to copy

Response body - ACCEPTED 

{
  "tasks": [
    {
      "id": string,
      "title": string,
      "containsEmailSigner": boolean,
      "creator": string,
      "created": number,
      "finalizedDate": number,
      "availableUntil": number
    }
  ]
}
Click to copy

Response body - REJECTED 

{
  "tasks": [
    {
      "id": string,
      "title": string,
      "containsEmailSigner": boolean,
      "creator": string,
      "rejectedBy": string,
      "rejectedDate": number,
      "created": number
    }
  ]
}
Click to copy

Response body - CANCELLED 

{
  "tasks": [
    {
      "id": string,
      "title": string,
      "containsEmailSigner": boolean,
      "creator": string,
      "signedBy": string,
      "cancelDate": number,
      "cancelledBy": string
    }
  ]
}
Click to copy

Response body - EXPIRED 

{
  "tasks": [
    {
      "id": string,
      "title": string,
      "containsEmailSigner": boolean,
      "dueDate": number,
      "creator": string,
      "signedBy": string,
      "created": number
    }
  ]
}
Click to copy

Create file

Response body 

[
  {
    "fileName": string,
    "validationResult": {
      "id": string,
      "status": number
    }
  }
]
Click to copy

Convert file

Response body

Same as create file

Approve conversion

Response body 

{
  "fileName": string,
  "validationResult": {
    "id": string,
    "status": number
  },
  "file": string // Base 64 encoded file content
}
Click to copy

Validate signatures 

{
  "taskId": string,
  "files": [
    {
      "documentId": string,
      "title": string,
      "changedAfterSigning": boolean,
      "signatures": [
        {
          "intact": boolean,
          "trusted": boolean,
          "when": string,
          "who": string
        }
      ]
    }
  ]
}
Click to copy

Fetch task

Response body 

{
  "task": {
    "id": string,
    "title": string,
    "description": string,
    "inviteUrlTarget": "SWF | SIGN_SERVICE",
    "dueDate": number,
    "created": number,
    "finalizedDate": number,
    "status": "PENDING | ACCEPTED | REJECTED | CANCELLED | EXPIRED",
    "signedBy": string,
    "tags": [
      {
        "displayText": string,
        "name": string,
        "type": "enum | boolean",
        "value": string | boolean
      }
    ],
    "files": [
      {
        "id": string,
        "fileName": string,
        "toBeSigned": boolean,
        "availableUntil": number,
        "isDeleted": boolean
      }
    ],
    "creator": {
      "id": string,
      "firstName": string,
      "lastName": string,
      "mail": string,
      "mobile": string,
      "source": "INTERNAL | EXTERNAL"
    },
    "signers": [
      {
        "id": string,
        "firstName": string,
        "lastName": string,
        "mail": string,
        "mobile": string,
        "source": "INTERNAL | EXTERNAL | EMAIL",
        "priority": number | null,
        "signerStatus": "QUEUED | PENDING | SIGNED | REJECTED",
        "signerTaskRole": ["CREATOR | DOWNLOADER | SIGNER"]
      }
    ],
    "rejected": {
      "rejectedBy": {
        "id": string,
        "firstName": string,
        "lastName": string,
        "mail": string,
        "mobile": string,
        "source": "INTERNAL | EXTERNAL"
      },
      "rejectMessage": string
    }
  }
}
Click to copy

Create task

Request body 

{
  "files": [
    {
      "fileId": string,
      "toBeSigned": boolean
    }
  ],
  "title": string,
  "description": string,
  "dueDate": number,
  "signers": [
    {
      "identifier": string,
      "source": "INTERNAL | INTERNAL | EMAIL",
      "firstName": string,
      "lastName": string,
      "mail": string,
      "mobile": string,
      "priority": null | number
    }
  ],
  "options": {
    "notifyAllSigners": boolean,
    "inviteUrlTarget": "SWF | SIGN_SERVICE"
  },
  "tags": [
    {
      "name": string,
      "type": "boolean | enum",
      "value": boolean
    }
  ]
}
Click to copy

Response body

Same as response body for fetch task

Update task

Request body

Body for updating a task

{
  "title": string,
  "description": string,
  "dueDate": number,
  "signers": [
    {
      "id | identifier": string,
      "firstName": string,
      "lastName": string,
      "mail": string,
      "mobile": string,
      "source": "INTERNAL | EXTERNAL | EMAIL",
      "priority": number 
    }
  ]
}
Click to copy

Response body

Same as response body for fetch task

Query INTERNAL users

Response body 

[
  {
    "source": "INTERNAL | EXTERNAL",
    "identifier": string,
    "externalIds": string[],
    "attributes": {
      "organization": string,
      "userId": string,
      "mail": string,
      "firstName": string,
      "lastName": string,
      "mobile": string,
      "department": string,
    },
    "key": string
  }
]
Click to copy

Query EXTERNAL users

Response body

Same as for querying INTERNAL users

Error response 

{
  "error": {
    "localizationKey": string
  }
}
Click to copy