📄Document handling

Submit a document for signing

Submit a document for signing

Start document signing by defining all attributes. After the request is processed, the document becomes availble in the portal. If the automatic email sending is enabled, users are being notified about a document delegated to sign.

PUThttps://professional.signius.eu:8970/services/documents/{documentId}

Path parameters

documentId*string (uuid)

The id of the document.

Body

application/json

signeesUsers*array of SigneeUser (object)

A list of document signees

titlestring

Document name

Example: "title"

signeeSignatureType*SignatureType (enum)

Type of signature. Only signatures of the same type ("EASY", or "ADVANCED", or "QUALIFIED") can be stored in one folder. Adding another document of different signature type to the same folder will result in an error.

Example: "EASY"

ADVANCEDQUALIFIEDEASY

graphicalRepresentationTypeenum

Type of graphical representation. Defaults to LAST_PAGE. CUSTOM to set custom location.

Example: "LAST_PAGE"

NONELAST_PAGEFIRST_PAGECUSTOM

skipAccountCreationboolean

Skipping account creation for EASY signature. Defaults to false

Example: false

Response

200400

OK

Body

*/*

idstring (uuid)

namestring

statusenum

UPLOADEDASSIGNEDSENTSIGNING_IN_PROGRESSSIGNEDREMOVED

titlestring

createDatestring (date-time)

signeesarray of Sign (object)

Request

JavaScriptCurlPython

const response = await fetch('https://professional.signius.eu:8970/services/documents/{documentId}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "signeeSignatureType": "EASY",
      "signeesUsers": [
        {
          "signeeEmail": "[e-mail]",
          "signeePhone": "+48XXXXXXXXX"
        }
      ]
    }),
});
const data = await response.json();

Response

200400

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "status": "UPLOADED",
  "title": "text",
  "createDate": "2024-11-21T17:14:55.877Z",
  "signees": [
    {
      "status": "AWAITING",
      "rejectMessage": "text",
      "user": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "email": "text",
        "terms": false
      },
      "signedDate": "2024-11-21T17:14:55.877Z"
    }
  ]
}

Submit a document for signing with specifing location of graphical representation of signarure

If you want to specify locatation of graphical representation of signature you have to set graphicalRepresentationType to CUSTOM. And specify values of top, left, page. You can see example on image below.

Example request body.

{
  "signeesUsers": [
    {
      "signeeEmail": "[e-mail]",
      "signeePhone": "+48XXXXXXXXX",
      "signingOrder": 1,
      "name": "Imię",
      "surname": "Nazwisko",
      "skipAccountCreation": false,
      "signature": {
        "top": 100,  
        "left": 100, 
        "page": 2 
      }
    }
  ],
  "title": "title",
  "signeeSignatureType": "EASY",
  "graphicalRepresentationType": "CUSTOM",
  "skipAccountCreation": false
}

A single „rectangle” with a signature measures Width: 160px Height: 36px

Maximum position of A4 signature placement vertically: Max top = 807px Max left = 435px

Maximum position of A4 signature placement horizontal: Max top = 560px Max left = 682px

WARNING!! On one vertical A4 sheet you can fit 3 signatures (on one level). To center them perfectly, set the coordinates according to image below.

Callbacks

Document signing status change notification

POST http://yourserver.com/

Successfully implementing signing process with Signius requires client to take care of document status change notifications. The url for callback notification has to be configured beforehand on the client’s account. Depending on the configuration the callback notification can be sent either after placing last signature on a document (a good time to download fully signed file), or after every signature placed on the document (when you may want to notify next signee about awaiting signature

Request Body

Name	Type	Description
documentId	string <uuid>
presentSignee	string <uuid>
nextSignee	string or null <uuid>
documentStatus	string	The value should be "SIGNED" or "SIGNING_IN_PROGESS"

200: OK Return this code if the callback was received and processed successfully.

500: Internal Server Error default The callback will be repeated 5 times - each retry after an hour.

Get a document link

Get a document link

Retrieves an individual link to the document for defined signee. For the signing flow without registration - the link is valid for 30 days since retrieval

GEThttps://professional.signius.eu:8970/services/documents/{documentId}/link

Path parameters

documentId*string (uuid)

Id of the document

Query parameters

Response

200

OK

Body

*/*

documentLinkstring

Request

JavaScriptCurlPython

const response = await fetch('https://professional.signius.eu:8970/services/documents/{documentId}/link?userId=123e4567-e89b-12d3-a456-426614174000', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "documentLink": "text"
}

Download original document

Download original document

Enables downloading originally uploaded document (unless previously removed)

GEThttps://professional.signius.eu:8970/services/documents/{documentId}/file

Path parameters

documentId*string (uuid)

The id of the document.

Response

200

OK

Body

application/octet-stream

itemsstring (byte)

Request

JavaScriptCurlPython

const response = await fetch('https://professional.signius.eu:8970/services/documents/{documentId}/file', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

[
  "Ynl0ZXM="
]

Download signed document

Download signed document

Enables downloading signed document (unless previously removed). In case document was not yet signed the 404 code is returned

GEThttps://professional.signius.eu:8970/services/documents/{documentId}/signed

Path parameters

documentId*string (uuid)

The id of the document.

Response

200

OK

Body

application/octet-stream

itemsstring (byte)

Request

JavaScriptCurlPython

const response = await fetch('https://professional.signius.eu:8970/services/documents/{documentId}/signed', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

[
  "Ynl0ZXM="
]

List all documents in the folder

List all documents in the folder

Enables to check the signing status (signed or unsigned) of all documents uploaded in one folder.

GEThttps://professional.signius.eu:8970/services/documents/document-folders/{documentFolderId}

Path parameters

documentFolderId*string (uuid)

The id of the folder.

Response

200

OK

Body

*/*

idstring (uuid)

namestring

statusenum

UPLOADEDASSIGNEDSENTSIGNING_IN_PROGRESSSIGNEDREMOVED

titlestring

createDatestring (date-time)

signeesarray of Sign (object)

Request

JavaScriptCurlPython

const response = await fetch('https://professional.signius.eu:8970/services/documents/document-folders/{documentFolderId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "status": "UPLOADED",
    "title": "text",
    "createDate": "2024-11-21T17:14:55.877Z",
    "signees": [
      {
        "status": "AWAITING",
        "rejectMessage": "text",
        "user": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "email": "text",
          "terms": false
        },
        "signedDate": "2024-11-21T17:14:55.877Z"
      }
    ]
  }
]

Delete a document

Delete a document

Removes document the system. By default SIGNIUS removes all data older than 30 days. Only audit logs are retained.

DELETEhttps://professional.signius.eu:8970/services/documents/{documentId}/

Path parameters

documentId*string (uuid)

The id of the document.

Response

200

OK

Body

*/*

object

Request

JavaScriptCurlPython

const response = await fetch('https://professional.signius.eu:8970/services/documents/{documentId}/', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();