> For the complete documentation index, see [llms.txt](https://docs.signius.eu/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.signius.eu/api/document-handling.md).
# Document handling
### Submit a document for signing
{% openapi src="/files/LD3nN0wzqyFuu1SiGnQN" path="/services/documents/{documentId}" method="put" expanded="true" %}
[swagger\_23.11.2023.json](https://4027982074-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAYbulpdLC0WzUkMqXPkv%2Fuploads%2FXm92q8RMAmJZS9ZgCzDm%2Fswagger_23.11.2023.json?alt=media\&token=874423cd-a149-4d34-80b0-67440ecdfeef)
{% endopenapi %}
### 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.
{% code title="Example request body." lineNumbers="true" %}
```json
{
"signeesUsers": [
{
"signeeEmail": "example@example.com",
"signeePhone": "+48XXXXXXXXX",
"signingOrder": 1,
"name": "First name",
"surname": "Last name",
"skipAccountCreation": false,
"signature": {
"top": 100,
"left": 100,
"page": 2
}
}
],
"title": "title",
"signeeSignatureType": "EASY",
"graphicalRepresentationType": "CUSTOM",
"skipAccountCreation": false
}
```
{% endcode %}
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 callback URL can be preconfigured in the customer account by the SIGNIUS team, or you can declare it yourself in the PUT method.
```
"callbackUrl": "https://URL.site",
```
{% code title="Example request body." lineNumbers="true" %}
```json
{
"signeesUsers": [
{
"signeeEmail": "example@example.com",
"signeePhone": "+48XXXXXXXXX",
"signingOrder": 1,
"name": "First name",
"surname": "Last name",
"skipAccountCreation": false
}
],
"title": "title",
"signeeSignatureType": "EASY",
"graphicalRepresentationType": "NONE",
"callbackUrl": "https://URL.site",
"skipAccountCreation": false
}
```
{% endcode %}
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. Please report this setting to the Signius team.
The callback notification can be secured using OAuth or another authentication method (Please report this setting to the Signius team)
#### Request Body
| Name | Type | Description |
| -------------- | ---------------------- | ------------------------------------------------------ |
| documentId | string \ | |
| presentSignee | string \ | |
| nextSignee | string or null \ | |
| documentStatus | string | The value should be "SIGNED" or "SIGNING\_IN\_PROGESS" |
{% tabs %}
{% tab title="200: OK Return this code if the callback was received and processed successfully." %}
{% endtab %}
{% tab title="500: Internal Server Error default The callback will be repeated 5 times - each retry after an hour." %}
{% endtab %}
{% endtabs %}
### Get a document link
{% openapi src="/files/HW6pLkNMKNxZSAtlto1u" path="/services/documents/{documentId}/link?userId={userId}" method="get" %}
[MKrawczyk-28-03-2025-swagger\_23.11.2023.json](https://4027982074-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAYbulpdLC0WzUkMqXPkv%2Fuploads%2FELeukV91f1fMM6fBIuht%2FMKrawczyk-28-03-2025-swagger_23.11.2023.json?alt=media\&token=240e6cf2-edaa-4b38-9bbe-0d16ebb76cb3)
{% endopenapi %}
### Download original document
{% openapi src="/files/LD3nN0wzqyFuu1SiGnQN" path="/services/documents/{documentId}/file" method="get" expanded="true" %}
[swagger\_23.11.2023.json](https://4027982074-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAYbulpdLC0WzUkMqXPkv%2Fuploads%2FXm92q8RMAmJZS9ZgCzDm%2Fswagger_23.11.2023.json?alt=media\&token=874423cd-a149-4d34-80b0-67440ecdfeef)
{% endopenapi %}
### Download signed document
{% openapi src="/files/LD3nN0wzqyFuu1SiGnQN" path="/services/documents/{documentId}/signed" method="get" expanded="true" %}
[swagger\_23.11.2023.json](https://4027982074-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAYbulpdLC0WzUkMqXPkv%2Fuploads%2FXm92q8RMAmJZS9ZgCzDm%2Fswagger_23.11.2023.json?alt=media\&token=874423cd-a149-4d34-80b0-67440ecdfeef)
{% endopenapi %}
### List all documents in the folder
{% openapi src="/files/LD3nN0wzqyFuu1SiGnQN" path="/services/documents/document-folders/{documentFolderId}" method="get" expanded="true" %}
[swagger\_23.11.2023.json](https://4027982074-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAYbulpdLC0WzUkMqXPkv%2Fuploads%2FXm92q8RMAmJZS9ZgCzDm%2Fswagger_23.11.2023.json?alt=media\&token=874423cd-a149-4d34-80b0-67440ecdfeef)
{% endopenapi %}
### Delete a document
{% openapi src="/files/LD3nN0wzqyFuu1SiGnQN" path="/services/documents/{documentId}/" method="delete" expanded="true" %}
[swagger\_23.11.2023.json](https://4027982074-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAYbulpdLC0WzUkMqXPkv%2Fuploads%2FXm92q8RMAmJZS9ZgCzDm%2Fswagger_23.11.2023.json?alt=media\&token=874423cd-a149-4d34-80b0-67440ecdfeef)
{% endopenapi %}