📄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.

put

/services/documents/{documentId}

Path parameters

documentIdstring uuidrequired

The id of the document.

Body

signeeSignatureTypeenumrequired

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

Options: ADVANCED, QUALIFIED, EASY

titlestring

Document name

Example: title

skipAccountCreationboolean

Skipping account creation for EASY signature. Defaults to false

Example: false

graphicalRepresentationTypeenum

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

Example: LAST_PAGE

Options: NONE, LAST_PAGE, FIRST_PAGE, CUSTOM

signeesUsersobject[]required

A list of document signees

Responses

*/*

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url 'https://professional.signius.eu:8970/services/documents/{documentId}' \
  --header 'Content-Type: application/json' \
  --data '{"signeeSignatureType":"EASY","title":"title","skipAccountCreation":false,"graphicalRepresentationType":"LAST_PAGE","signeesUsers":[{"signeeEmail":"[e-mail]","signeePhone":"+48XXXXXXXXX","signingOrder":1,"name":"Imię","surname":"Nazwisko","skipAccountCreation":false}]}'

200

400

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "title": "text",
  "createDate": "2025-02-18T22:47:58.810Z",
  "status": "UPLOADED",
  "signees": [
    {
      "signingOrder": 1,
      "rejectMessage": "text",
      "user": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "email": "text",
        "terms": true
      },
      "signedDate": "2025-02-18T22:47:58.810Z",
      "status": "AWAITING"
    }
  ]
}

OK

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

get

/services/documents/{documentId}/link

Path parameters

documentIdstring uuidrequired

Id of the document

Query parameters

userIdstring uuidrequired

Id of the signee for whom the link is retrieved.

Responses

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://professional.signius.eu:8970/services/documents/{documentId}/link?userId=123e4567-e89b-12d3-a456-426614174000'

200

200

{
  "documentLink": "text"
}

OK

Download original document

Download original document

Enables downloading originally uploaded document (unless previously removed)

get

/services/documents/{documentId}/file

Path parameters

documentIdstring uuidrequired

The id of the document.

Responses

application/octet-stream

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://professional.signius.eu:8970/services/documents/{documentId}/file'

200

200

[
  "text"
]

OK

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

get

/services/documents/{documentId}/signed

Path parameters

documentIdstring uuidrequired

The id of the document.

Responses

application/octet-stream

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://professional.signius.eu:8970/services/documents/{documentId}/signed'

200

200

[
  "text"
]

OK

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.

get

/services/documents/document-folders/{documentFolderId}

Path parameters

documentFolderIdstring uuidrequired

The id of the folder.

Responses

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://professional.signius.eu:8970/services/documents/document-folders/{documentFolderId}'

200

200

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "title": "text",
    "createDate": "2025-02-18T22:47:58.810Z",
    "status": "UPLOADED",
    "signees": [
      {
        "signingOrder": 1,
        "rejectMessage": "text",
        "user": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "email": "text",
          "terms": true
        },
        "signedDate": "2025-02-18T22:47:58.810Z",
        "status": "AWAITING"
      }
    ]
  }
]

OK

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.

delete

/services/documents/{documentId}//

Path parameters

documentIdstring uuidrequired

The id of the document.

Responses

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://professional.signius.eu:8970/services/documents/{documentId}/'

200

200

{}

OK