---
description: Walk-through
---

# Integration Example

### Push PDF document from external application to SimpleSIgn

In this walk-through example, we guide you through the following use case:

From an external web application, ask a user to digitally sign a PDF document using his local SimpleSign application. Once the PDF document has been locally signed by the user, the external application will receive the document using a callback URL.

### Prepare to use SimpleSign API

### Health check for the SimpleSign module

Verify the SimpleSign CMS module is enabled:

```bash
curl --location 'https://t1c.t1t.io:51984/v3/modules/simplesign' `
--header 'Origin: localhost'
```

Response:

{% code overflow="wrap" %}
```json
{
    "success": true,
    "data": {
        "version": "0.2.11",
        "localFolder": "/Users/gilles/Desktop/_lsa"
    }
}
```
{% endcode %}

The response contains the SimpleSign version installed on your system, and the SimpleSign application folder selected by the user upon startup.&#x20;

When no SimpleSign has been detected, you will not be able to continue from here.



### Push PDf document

The external application can push a new PDF document in 2 steps:

* upload PDF file
* request digital signature - including metadata -&#x20;

See the [sequence diagram](integration-api)

To upload a PDF file, you can use the download function

```sh
curl --location 'https://t1c.t1t.io:51984/v3/modules/fileexchange/apps/file/download' `
--form 'file=@"..."' `
--form 'fileName="somedocument.pdf"'
```

The result of the file upload, is that the file will be uploaded (from the application point of view) to the SimpleSign exchange folder.&#x20;

{% hint style="info" %}
The request above is sent to 'download' as the naming is done from a user perspective. Don't be confused, when an application pushes a new PDF document, 'download' endpoint is the correct one :thumbsup:
{% endhint %}

The response will return the information of the file uploaded. This is important as you will need to use the `name` in the request for adding context information.

{% hint style="warning" %}
When you try to upload a file which already exists in the SimpleSign folders or Database it will automatically rename the file for you. The response will contain the new name in the `name` property and the full path to the file in the `path` property.
{% endhint %}

After the preceding request, nothing will happen, until the external application pushed the context information as well.&#x20;

This can be done by sending a request to the SimpleSign CMS module:

```bash
curl --location 'https://t1c.t1t.io:51984/v3/modules/simplesign' `
--header 'Content-Type: application/json' `
--data '{
    "filename": "somedocument_1729680589.pdf",
    "callback": "https://some_url/hook",
    "sendFile": true,
    "externalId": "123456"
}'
```

After a successful request of the latter, the PDF document will be picked up by SimpleSign and will be available in the user's Inbox folder :clap:.

{% hint style="info" %}
You can choose to not receive the actual file in the callback by adding the `sendFile` property and setting it to false.

This will send the callback not in Multipart form-data but as JSON, the name can then be used with the Download function to get the actual PDF document.
{% endhint %}

An example json with `sendFile` propety being false (not returning with Multipart form-data);

```json
{
    "filename": "app_pdf_to_sign.pdf",
    "callback": "https://some_url/hook",
    "sendFile": false,
    "externalId": "some_uuid_or_opaque_id"
}
```

### Receive Signed PDF document

When the document has been signed, the SimpleSign CMS module will send the document information to the defined callback.

Depending on the `sendFile` property this will be in either `application/json` or in `form-data`

The response as Multipart;

```
"fileName": String("T1T_test_green copy3_1729680589_signed.pdf"),
"file": Bytes(),
"createdAt": String("2024-10-23T10:49:56.104047+00:00"),
"updatedAt": String("2024-10-23T10:50:18.265913+00:00"),
"status": String("SIGNED"),
"externalId": String("123456")
```

The response as JSON;

```
{
    "fileName": "T1T_test_green copy3_1729680589_signed.pdf",
    "createdAt": "2024-10-23T10:49:56.104047+00:00",
    "updatedAt": "2024-10-23T10:50:18.265913+00:00",
    "status": "SIGNED",
    "externalId": "123456"
}
```

If you have chosen to get the signed document information as JSON you will need to retrieve the file via the SimpleSign CMS API.

This can be done with the download endpoint. The `filename` property will be the file received in the callback

```bash
curl --location 'https://t1c.t1t.io:51984/v3/modules/fileexchange/apps/file/upload' `
--header 'Content-Type: application/json' `
--data '{
    "filename": "T1T_test_green copy3_1729680589_signed.pdf"
}'
```

The response will be a streamed file.

Below an image on how this looks like in postman

<figure><img src="https://2664935600-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSIjEwGgewVPDRmhYUhdu%2Fuploads%2FJngpiHndYzceMuKoMVxM%2Fimage.png?alt=media&#x26;token=6d3f3944-7730-4964-8fec-d4bd3c6daf6c" alt=""><figcaption></figcaption></figure>
