How to retrieve files

This section covers the signature API file types: which files are supported and how to download the signed files. We only store signed files for a limited time. Therefore, you have to make sure to download them as soon as they are signed.

Supported file types

All the different file types can be a bit confusing at first, so it's a good idea to start by reviewing the list of supported file types.

When is the file ready?

The recommended approach

Use our notification API to be notified with webhooks or service bus messages when the document is ready.

Note

If you are a new customer or have recently migrated to our new Digital Trust Platform (DTP), events such as webhooks are now self-serviceable through our Dashboard. See our new Events and webhooks documentation (opens new window) for information on setting up and managing events.

Differences between our old and new platforms

The names and content of the events have changed in our new platform. Additionally, events in our new platform contain no personally identifiable information, only IDs.

The table below shows the differences in event names between our old and new platforms.

Old event name	New event name
DocumentBeforeDeletedEvent	signature-api:order.tobedeleted
DocumentCanceledEvent	Not yet available.
DocumentCreatedEvent	signature-api:order.created
DocumentDeletedEvent	signature-api:order.deleted
DocumentExpiredEvent	signature-api:order.expired
DocumentEmailOpenedEvent	communication-api:email.opened
DocumentLinkOpenedEvent	Not yet available.
DocumentPackagedEvent / DocumentSignedEvent	signature-api:order.completed
DocumentPartiallySignedEvent	signature-api:recipient.completed
DocumentReadEvent	Not yet available.

If you can't subscribe to webhooks

Alternative 1

The following will only work if you have a single signer per document:

Let the signer wait for all files to be ready. The files can then be downloaded directly after the signer is redirected, or after you receive the sign success web message. Contact us at support@signicat.com to enable this feature.

Alternative 2

Check if the document is ready by calling the document status endpoint. In the response you will see all the completed packages and if the document is signed.

GET /documents/{documentId}/status

Response sample

{
  "documentStatus": "signed",
  "completedPackages": [
    "standard_packaging",
    "pades"
  ],
  "attachmentPackages": {}
}

Retrieve file

Main document

This endpoint delivers the main document file containing all the signatures. You can retrieve a file by specifying its document ID and which file type you want.

Example: A signature job is completed, the file to be signed was a PDF, so we want to fetch the PAdES file.

GET /documents/{documentId}/files

Signer document

This endpoint can return the signed file for each signer (native or packaged) before they are merged together in one file.

GET /documents/{documentId}/files/signers/{signerId}

Attachment documents

You can download the files for each of the signable attachments too.

Document

GET /documents/{documentId}/files/attachments/{attachmentId}

Signer

GET /documents/{documentId}/files/attachments/{attachmentId}/signers/{signerId}