Introduction

Example Request for Access Token

curl -X POST --location "https://deepcloud.swiss/auth/realms/sso/protocol/openid-connect/token" \
        -H "Content-Type: application/x-www-form-urlencoded" \
        --data-urlencode "grant_type=password" \
        --data-urlencode "username=[service_account_username]" \
        --data-urlencode "password=[service_account_password]" \
        --data-urlencode "client_id=[Partner-Service-Client-ID]" \
        --data-urlencode "client_secret=[Partner-Service-Client-Secret]"

POST /auth/realms/sso/protocol/openid-connect/token HTTP/1.1
Host: deepcloud.swiss
Content-Type: application/x-www-form-urlencoded

grant_type=password&
username=[service_account_username]&
password=[service_account_password]&
client_id=[Partner-Service-Client-ID]&
client_secret=[Partner-Service-Client-Secret]

The HTTP POST call does not contain line breaks or whitespaces. It has been shown with line breaks for clarity. The "&" is the parameter separator.

Version:
v1

Schemes
https

Host & base path
https://api.sign.deepbox.swiss/api/v1

API Swagger docs
https://api.sign.deepbox.swiss/swagger-ui/index.html

Terms of Service
In using this API you agree to be bound by the DeepCloud Terms of Service, available at DeepCloud

Welcome to the DeepSign API !

Before you can access the DeepSign API, you need to complete an onboarding process.

Essentially, the process is divided into the following 3 steps :

The steps 1 and 2 establish the necessary configuration and service user for accessing the DeepCloud access. Step 3 enables access to the DeepCloud API functionality.

Please contact DeepSign (deepsign@deepcloud.swiss) development personnel to determine the best way to integrate the partner access for an integration. Additional Information is also available in the Deep Sign Partner Setup.

Authentication

Authentication uses standard OAuth technologies to access the DeepCloud API's. An access token is used in the "Authorization" HTTP header to validate the access to the API's. Please see Deep Cloud Partner Setup for the details how to setup the DeepCloud access and obtain the access tokens to use the API's.

The "access_token" retrieved from the OAuth authentication is used to validate the requests for DeepSign. The access_token is used in the Authorization HTTP Header as shown below.

class Example {
  public void main(String[] args) {
     // The Authorization header is set for each request - see further examples for completed code
      HttpRequest request = HttpRequest.newBuilder()
        .PUT(HttpRequest.BodyPublishers.ofString())
        .uri(URI.create("api_endpoint_here"))
        .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
        .build();
        // ....
        // ....
  }
}

public async void simplePutRequestExample()
{
    String requestUrl = "api_endpoint_here";

    HttpClient httpClient = new HttpClient();

    // The Authorization header is added to each request - see further examples for completed code
    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");
    ....
    ....
}

# With shell, the Authorization header is sent with every request
curl "api_endpoint_here" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ"

GET /api/v1/[api_endpoint_here] HTTP/1.1
Accept-Charset: UTF-8
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ

All DeepSign API calls require the "Authorization" header to be included in requests as shown below:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ

Make sure to replace eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ with the current DeepSign API access token.

Getting Started

The simplest usage flow generally starts with the following steps :

Uploading a Document file
(Optional additional configuration calls e.g. configuration of Signees and Observers)
Starting the Sign Process

The above steps can be done entirely via the API, or can be combined with manual steps via the DeepSign Application

DeepSign Process Flow

Lifecyle of DeepSign Documents

The following outlines some lifecycle details when documents in DeepSign are deleted, or the status is automatically changed.

Document Status	DeepSign Lifecycle
"draft"	Documents with "draft" status will be deleted after 7 days
"in-progress"	Unsigned documents with "in-progress" status will be automatically set to status "withdrawn" after 30 days
"signed" "withdrawn" "rejected"	Documents with "signed", "withdrawn" or "rejected" status will be deleted after 14 days

The start time for the period when the document will be deleted, is determined from the last status change. For example, when the sign process is started for a document that was in "draft" status, the 30 days period starts from when the status changed to "in-progress".

Rate Limiting

GET requests to any specific URL cannot be called more than once every 15 minutes. For example, obtaining the status of a specific document can be done once every 20 minutes, but not once every 10 minutes.

Document

Upload Document

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      String mimeBoundary = "-----" + UUID.randomUUID().toString().replace("-", "");

      MultipartEntityBuilder multipartEntitybuilder = MultipartEntityBuilder.create();
      multipartEntitybuilder.setMode(HttpMultipartMode.STRICT);
      multipartEntitybuilder.setBoundary(mimeBoundary);

      // Only ContentType with "application/pdf" is accepted
      File uploadFile = new File("testupload.pdf");
      FileBody fileBody = new FileBody(uploadFile, ContentType.create("application/pdf"));
      multipartEntitybuilder.addTextBody("data", "{\"initiatorAliasName\": \"Mr. Tester\",\"sendMail\": \"all\",\"comment\":\"PDF file for testing\"," + 
                  "\"signatureMode\":\"timestamp\",\"jurisdiction\":\"zertes\",\"scanPredefined\":false}", ContentType.APPLICATION_JSON);
      multipartEntitybuilder.addPart("file", fileBody);

      HttpEntity entity = multipartEntitybuilder.build();

      final ByteArrayOutputStream os = new ByteArrayOutputStream();
      entity.writeTo(os);
      os.flush();

      HttpClient httpClient = getHttpClient();

      // Example code for POST https://api.sign.deepbox.swiss/api/v1/documents/file
      HttpRequest request = HttpRequest.newBuilder()
        .POST(HttpRequest.BodyPublishers.ofByteArray(os.toByteArray()))
        .uri(URI.create("https://api.sign.deepbox.swiss/api/v1/documents/file"))
        .setHeader("Accept-Charset", "UTF-8")
        .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
        .setHeader("Content-Type", "multipart/form-data; boundary=" + mimeBoundary)
        .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
      ge.printStackTrace();
    }
  }
}

public async void simplePostMutlipartMimeRequestExample()
{
    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/documents/file";
    String requestContent = "{\"initiatorAliasName\": \"Mr. Tester\",\"sendMail\": \"all\",\"comment\":\"PDF file for testing\"," + 
            "\"signatureMode\":\"timestamp\",\"jurisdiction\":\"zertes\",\"scanPredefined\":false}";

    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");
    requestHttpHeaders.Add("Accept-Charset", "UTF-8");

    // Example code for POST file upload with "multi-part" https://api.sign.deepbox.swiss/api/v1/documents/file
    String uploadLocalFilePath = "c:\\temp\\example.pdf";
    String shortFileName = uploadLocalFilePath;
    int ipos = shortFileName.LastIndexOf("\\");
    if (ipos > 0)
    {
        shortFileName = shortFileName.Substring(ipos + 1);
    }
    StringContent scDataPart = new StringContent(requestContent, Encoding.UTF8, "application/json");

    FileStream fileStream = new FileStream(uploadLocalFilePath, FileMode.Open);
    StreamContent fileDataPart = new StreamContent(fileStream);
    fileDataPart.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");

    MultipartFormDataContent multiPartData = new MultipartFormDataContent();
    multiPartData.Add(scDataPart, "data");
    multiPartData.Add(fileDataPart, "file", shortFileName);

    HttpResponseMessage response = await httpClient.PostAsync(requestUrl, multiPartData, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -X POST --location "https://api.sign.deepbox.swiss/api/v1/documents/file" \
                -H 'Authorization: Bearer ...' -H 'Content-Type: multipart/form-data' \ 
                -F 'file=@/path/to/example.pdf;type=application/pdf' \
                -F 'data={"initiatorAliasName":"Mr. Tester","sendMail":"all","comment":"PDF file for testing", "signatureMode":"timestamp", \
                    "jurisdiction":"zertes","scanPredefined":false};type=application/json'

POST /api/v1/documents/file HTTP/1.1
Accept-Charset: UTF-8
Content-Type: multipart/form-data; boundary=---------9B82F53A7B2247AB8B5B9707CBB0DFD2
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ
Content-Length: 27896

-----------9B82F53A7B2247AB8B5B9707CBB0DFD2
Content-Disposition: form-data; name="data"
Content-Type: application/json; charset=UTF-8
Content-Transfer-Encoding: 8bit

{
  "initiatorAliasName":"Mr. Tester",
  "sendMail": "all",
  "comment":"PDF file for testing",
  "signatureMode":"timestamp",
  "jurisdiction":"zertes",
  "scanPredefined":false
}
-----------9B82F53A7B2247AB8B5B9707CBB0DFD2
Content-Disposition: form-data; name="file"; filename="example.pdf"
Content-Type: application/pdf
Content-Transfer-Encoding: binary

%PDF-1.4
%äüöß
2 0 obj
&lt;&lt;/Length 3 0 R/Filter/FlateDecode&gt;&gt;
stream
   ...[abbreviated for display]...
trailer
&lt;&lt;/Size 14/Root 12 0 R
/Info 13 0 R
/ID [ &lt;853D3233C8F28B5C661255FC0C316B56&gt;
&lt;853D3233C8F28B5C661255FC0C316B56&gt; ]
/DocChecksum /0F3E7CFA8C22C3D6D3FF7F1AD91C10B8
&gt;&gt;
startxref
26698
%%EOF

-----------9B82F53A7B2247AB8B5B9707CBB0DFD2--

The above request returns JSON structured like this:

{
  "documentId":"bb602c43-caae-4656-a447-233b2317b14a",
  "documentName":"example.pdf",
  "documentMimeType":"application/pdf",
  "documentUrl":"https://bb.storage.deepbox.swiss/deepsign/data/bb/60/2c/43-caae...[abbreviated for display]...a2d873ba6e0c2583dd8a",
  "thumbnailUrl":null,
  "companyId":"09795a43-baaf-48ae-91a6-a533168f803a",
  "creationTime":"2022-12-13T12:10:16.650+00:00",
  "startTime":null,
  "completionTime":null,
  "documentStatus":"draft",
  "signatureMode":"timestamp",
  "jurisdiction":"zertes",
  "comment":"PDF file for testing",
  "initiatorCompanyDisplayName":"Abacus Software AG",
  "initiatorCompanyIsVerified":true,
  "initiatorCompanyVerificationType":"strong",
  "initiatorDisplayName":"Mr. Tester",
  "initiatorDisplayEmail":null,
  "initiatorSignKey":null,
  "signees":[],
  "signeesOrdered":[],
  "attachmentsAllowed":false
}

This endpoint uploads a document file to DeepSign.

HTTP Request

POST https://api.sign.deepbox.swiss/api/v1/documents/file

Swagger Reference

POST/api/v1/documents/file

Message Structure

The document upload is a 2 part, multipart mime POST request. The first part contains the JSON information for the document being uploaded and the second part contains the binary encoded document (e.g. pdf file). The following headers must be present in the Request when uploading document files :

Content-Type: multipart/form-data; boundary=-----<unique-boundary-id-to-separate-message-parts>;

Typical examples for the boundary parameter are shown in the HTTP Requests.
For example :
Content-Type: multipart/form-data; boundary=---------9B82F53A7B2247AB8B5B9707CBB0DFD2

Note: Each multipart mime part must contain the "Content-Type" header and the "Content-Disposition" header specifying the "name" for each section.
For example :

Part	Required Headers
data	Content-Disposition: form-data; name="data" Content-Type: application/json; charset=UTF-8
file	Content-Disposition: form-data; name="file"; filename="example.pdf" Content-Type: application/pdf

as shown in the "http" example (on the right hand side).

As a minimum, the data structure should contain the "initiatorAliasName" which defines the name of the person displayed in the invitation emails.

The following information can also be defined when uploading the document file :

Parameter	Possible values	Default value
"sendMail"	"all" - emails sent to all participants "others" - emails sent to signees "none" - no emails sent by DeepSign	"others"
"signatureMode"	"timestamp" - SES - simple timestamp "advanced" - AES - advanced signature with 2FA "qualified" - QES - statutory EU and Swiss signature	"timestamp"
"jurisdiction"	"zertes" - Swiss defined legal jurisdiction "eidas" - European defined legal jurisdiction	"zertes"
"scanPredefined"	false - Predefine signatures in the document file will not be scanned true - document file is scanned for predefined signatures	false

For more details about the signature modes, see the DeepSign Homepage

Note: Additional parameters are available in the JSON structure to configure callbacks for signing event notifications. Please see the section on Webhooks Callbacks for more information how these events can be configured.

The following Content-Type / Mime Type are supported for uploading documents to the DeepSign platform.

File type	Content-Type
*.pdf	application/pdf
*.docx	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
*.xlsx	application/vnd.openxmlformats-officedocument.wordprocessingml.document

Start Sign Process

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();

      // Example code for PUT https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/start
      HttpRequest request = HttpRequest.newBuilder()
          .PUT(HttpRequest.BodyPublishers.ofString())
          .uri(URI.create("https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/start"))
          .setHeader("Accept-Charset", "UTF-8")
          .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
          .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
      ge.printStackTrace();
    }
  }
}

public async void simplePutRequestExample()
{
    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/start";

    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");
    requestHttpHeaders.Add("Accept-Charset", "UTF-8");

    // Example code for PUT https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/start
    StringContent scData = new StringContent("", Encoding.UTF8, "application/json");
    HttpResponseMessage response = await httpClient.PutAsync(requestUrl, scData, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -X PUT --location "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/start" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \
  -H "Accept-Charset: UTF-8"

PUT /api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/start HTTP/1.1
Accept-Charset: UTF-8
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ

The above request returns and empty response with HTTP 204 No Content
HTTP/1.1 204 No Content

After all the signees have been added to a DeepSign document, the sign process can be started.

HTTP Request

PUT https://api.sign.deepbox.swiss/api/v1/documents/{documentId}/start

Swagger Reference

PUT/api/v1/documents/{documentId}/start

Details

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();

      // Example code for GET https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a
      HttpRequest request = HttpRequest.newBuilder()
        .GET()
        .uri(URI.create("https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a"))
        .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
        .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
      ge.printStackTrace();
    }
  }
}

public async void simpleGetRequestExample()
{
    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a";
    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");

    // Example code for GET https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a
    HttpResponseMessage response = await httpClient.GetAsync(requestUrl, HttpCompletionOption.ResponseContentRead, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \ 
       "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a"

GET /api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a HTTP/1.1
Accept-Charset: UTF-8
Accept: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ

The above request returns JSON structured like this:

{
  "documentId":"bb602c43-caae-4656-a447-233b2317b14a",
  "documentName":"example.pdf",
  "documentMimeType":"application/pdf",
  "documentUrl":"https://bb.storage.deepbox.swiss/deepsign/data/bb/60/2c/43-caae...[abbreviated for display]...a2d873ba6e0c2583dd8a",
  "thumbnailUrl":null,
  "companyId":"09795a43-baaf-48ae-91a6-a533168f803a",
  "creationTime":"2022-12-13T12:10:16.650+00:00",
  "startTime":null,
  "completionTime":null,
  "documentStatus":"draft",
  "signatureMode":"timestamp",
  "jurisdiction":"zertes",
  "comment":"PDF file for testing",
  "initiatorCompanyDisplayName":"Abacus Software AG",
  "initiatorCompanyIsVerified":true,
  "initiatorCompanyVerificationType":"strong",
  "initiatorDisplayName":"Mr. Tester",
  "initiatorDisplayEmail":null,
  "initiatorSignKey":null,
  "signees":[],
  "signeesOrdered":[],
  "attachmentsAllowed":false
}

Retrieves the Document details. The PDF document can be downloaded using the "documentUrl" link.

HTTP Request

GET https://api.sign.deepbox.swiss/api/v1/documents/{documentId}

Swagger Reference

GET/api/v1/documents/{documentId}

The most interesting properties for the document are :

"documentId" - uniquely defines the document and can be used for other API calls to reference the document
"documentStatus" - is defined by the DeepSign and can be one of the following : "draft", "in-progress", "signed", "withdrawn", "rejected"
"signStatus" - is defined by the DeepSign and can be one of the following : "on-hold", "pending", "in-progress", "signed", "rejected"

The following values are possible for a "documentStatus" :

"draft" - the document is in draft mode and document properties and signees can be added or changed
"in-progress" - the document sign process has been started and at least one signee has signed the document
"signed" - the document has been successfully signed by all signees
"withdrawn" - the document has been withdrwan from the signing process. It cannot be reactivated for the signing process.
"rejected" - at least one signee has rejected the signing of the document

The following values are possible for the "signStatus" :

"on-hold" - the sign process is waiting for signees in a specified order
"pending" - the sign process has been started, but not signed by any signee
"in-progress" - the sign process has been started and at least one signee has signed the document
"signed" - all signees have successfully signed the document
"rejected" - at least one signee has rejected the signing of the document

Update

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();

      // Example code for PUT https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a
      HttpRequest request = HttpRequest.newBuilder()
          .PUT(HttpRequest.BodyPublishers.ofString("{\"initiatorAliasName\": \"Mr. Tester\",\"comment\": \"Please sign the PDF file\"}"))
          .uri(URI.create("https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a"))
          .setHeader("Accept-Charset", "UTF-8")
          .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
          .setHeader("Content-Type", "application/json")
          .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
        ge.printStackTrace();
    }
  }
}

public async void simplePutRequestExample()
{
    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees";
    String requestContent = "{\"initiatorAliasName\":\"Mr. Tester\",\"comment\":\"Please sign the PDF file\"}";

    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");
    requestHttpHeaders.Add("Accept", "application/json");
    requestHttpHeaders.Add("Accept-Charset", "UTF-8");

    // Example code for PUT https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a
    StringContent scData = new StringContent(requestContent, Encoding.UTF8, "application/json");
    HttpResponseMessage response = await httpClient.PutAsync(requestUrl, scData, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -X PUT --location "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \
  -H "Content-Type: application/json" \
  -d '{"initiatorAliasName":"Mr. Tester","comment":"Please sign the PDF file"}'

PUT /api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a HTTP/1.1
Content-Length: 72
Host: api.sign.deepbox.swiss
User-Agent: Java-http-client/11.0.14.1
Accept-Charset: UTF-8
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ
Content-Type: application/json

{
  "initiatorAliasName": "Mr. Tester",
  "comment": "Please sign the PDF file"
}

The above request returns and empty response with HTTP 204 No Content
HTTP/1.1 204 No Content

Update the information for an existing DeepSign document.

HTTP Request

PUT https://api.sign.deepbox.swiss/api/v1/documents/{documentId}

Swagger Reference

PUT/api/v1/documents/{documentId}

Download

// No java example currently available (see shell examples)

// No csharp example currently available (see shell examples)

curl "https://bb.storage.deepbox.swiss/deepsign/data/bb/...[abbreviated for display]...583dd8a"

// No http example currently available (see shell examples)

The document file can be downloaded using the "documentUrl" link from the Document Details.

HTTP Request

GET https://bb.storage.deepbox.swiss/deepsign/data/bb/...[abbreviated for display]...583dd8a

The GET request is a standard GET request using the "documentUrl" URL, without the Authorization header.

Withdraw

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();

      // Example code for PUT https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/withdraw
      HttpRequest request = HttpRequest.newBuilder()
          .PUT(HttpRequest.BodyPublishers.ofString())
          .uri(URI.create("https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/withdraw"))
          .setHeader("Accept-Charset", "UTF-8")
          .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
          .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
      ge.printStackTrace();
    }
  }
}

public async void simplePutRequestExample()
{
    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/withdraw";

    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");
    requestHttpHeaders.Add("Accept-Charset", "UTF-8");

    // Example code for PUT https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/withdraw
    StringContent scData = new StringContent("", Encoding.UTF8, "application/json");
    HttpResponseMessage response = await httpClient.PutAsync(requestUrl, scData, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -X PUT --location "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/withdraw" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \
  -H "Accept-Charset: UTF-8"

PUT /api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/withdraw HTTP/1.1
Accept-Charset: UTF-8
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ

The above request returns and empty response with HTTP 204 No Content
HTTP/1.1 204 No Content

Withdraws a Document from signing process, after the signing process has been started.

HTTP Request

PUT https://api.sign.deepbox.swiss/api/v1/documents/{documentId}/withdraw

Swagger Reference

PUT/api/v1/documents/{documentId}/withdraw

Delete

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();

      // Example code for DELETE https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a
      HttpRequest request = HttpRequest.newBuilder()
          .DELETE(HttpRequest.BodyPublishers.ofString())
          .uri(URI.create("https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a"))
          .setHeader("Accept-Charset", "UTF-8")
          .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
          .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
      ge.printStackTrace();
    }
  }
}

public async void simpleDeleteRequestExample()
{
    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a";

    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");
    requestHttpHeaders.Add("Accept-Charset", "UTF-8");

    // Example code for DELETE https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a
    StringContent scData = new StringContent("", Encoding.UTF8, "application/json");
    HttpResponseMessage response = await httpClient.DeleteAsync(requestUrl, scData, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -X DELETE --location "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \
  -H "Accept-Charset: UTF-8"

DELETE /api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a HTTP/1.1
Accept-Charset: UTF-8
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ

The above request returns and empty response with HTTP 204 No Content
HTTP/1.1 204 No Content

Deletes a Document from DeepCloud. Only documents in "draft" or "withdrawn" mode can be deleted.

HTTP Request

DELETE https://api.sign.deepbox.swiss/api/v1/documents/{documentId}

Swagger Reference

DELETE/api/v1/documents/{documentId}

Scan Predefined

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      String mimeBoundary = "-----" + UUID.randomUUID().toString().replace("-", "");

      MultipartEntityBuilder multipartEntitybuilder = MultipartEntityBuilder.create();
      multipartEntitybuilder.setMode(HttpMultipartMode.STRICT);
      multipartEntitybuilder.setBoundary(mimeBoundary);

      // Only ContentType with "application/pdf" is accepted
      File uploadFile = new File("testupload.pdf");
      FileBody fileBody = new FileBody(uploadFile, ContentType.create("application/pdf"));
      multipartEntitybuilder.addPart("file", fileBody);

      HttpEntity entity = multipartEntitybuilder.build();

      final ByteArrayOutputStream os = new ByteArrayOutputStream();
      entity.writeTo(os);
      os.flush();

      HttpClient httpClient = getHttpClient();

      // Example code for POST https://api.sign.deepbox.swiss/api/v1/documents/file/scan-predefined
      HttpRequest request = HttpRequest.newBuilder()
        .POST(HttpRequest.BodyPublishers.ofByteArray(os.toByteArray()))
        .uri(URI.create("https://api.sign.deepbox.swiss/api/v1/documents/file/scan-predefined"))
        .setHeader("Accept-Charset", "UTF-8")
        .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
        .setHeader("Content-Type", "multipart/form-data; boundary=" + mimeBoundary)
        .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
      ge.printStackTrace();
    }
  }
}

public async void simplePostMutlipartMimeRequestExample()
{
    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/documents/file/scan-predefined";

    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");
    requestHttpHeaders.Add("Accept-Charset", "UTF-8");

    // Example code for POST file upload with "multi-part" https://api.sign.deepbox.swiss/api/v1/documents/file/scan-predefined
    String uploadLocalFilePath = "c:\\temp\\example.pdf";
    String shortFileName = uploadLocalFilePath;
    int ipos = shortFileName.LastIndexOf("\\");
    if (ipos > 0)
    {
        shortFileName = shortFileName.Substring(ipos + 1);
    }

    FileStream fileStream = new FileStream(uploadLocalFilePath, FileMode.Open);
    StreamContent fileDataPart = new StreamContent(fileStream);
    fileDataPart.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");

    MultipartFormDataContent multiPartData = new MultipartFormDataContent();
    multiPartData.Add(fileDataPart, "file", shortFileName);

    HttpResponseMessage response = await httpClient.PostAsync(requestUrl, multiPartData, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -X POST --location "https://api.sign.deepbox.swiss/api/v1/documents/file/scan-predefined" \
                -H 'Authorization: Bearer ...' -H 'Content-Type: multipart/form-data' \ 
                -F 'file=@/path/to/example.pdf;type=application/pdf'

POST /api/v1/documents/file/scan-predefined HTTP/1.1
Accept-Charset: UTF-8
Content-Type: multipart/form-data; boundary=---------9B82F53A7B2247AB8B5B9707CBB0DFD2
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ
Content-Length: 15842

-----------9B82F53A7B2247AB8B5B9707CBB0DFD2
Content-Disposition: form-data; name="file"; filename="example.pdf"
Content-Type: application/pdf
Content-Transfer-Encoding: binary

%PDF-1.4
%äüöß
2 0 obj
&lt;&lt;/Length 3 0 R/Filter/FlateDecode&gt;&gt;
stream
   ...[abbreviated for display]...
trailer
&lt;&lt;/Size 14/Root 12 0 R
/Info 13 0 R
/ID [ &lt;853D3233C8F28B5C661255FC0C316B56&gt;
&lt;853D3233C8F28B5C661255FC0C316B56&gt; ]
/DocChecksum /0F3E7CFA8C22C3D6D3FF7F1AD91C10B8
&gt;&gt;
startxref
26698
%%EOF

-----------9B82F53A7B2247AB8B5B9707CBB0DFD2--

The above request returns JSON structured like this:

{
  "signatureMode":"timestamp",
  "jurisdiction":"zertes",
  "authorityService":"ras",
  "attachments":false,
  "signWithin":null,
  "reminder":null,
  "signatureFields":[
    {
      "signFieldName":"Test Person",
      "signatureType":"signature",
      "sealKey":null,
      "email":"test.person@abacus.ch",
      "signOrder":0,
      "autographPosition":
      {
        "pageNumber":1,
        "x":75.3,
        "y":88.789,
        "width":159.0,
        "height":84.0
      }
    },
    {
      "signFieldName":"Test2 Person",
      "signatureType":"signature",
      "sealKey":null,
      "email":"test2.person@abacus.ch",
      "signOrder":1,
      "autographPosition":
      {
        "pageNumber":1,
        "x":323.4,
        "y":88.789,
        "width":159.0,
        "height":84.0
      }
    }],
  "observers":[]
}

This endpoint scans the predefined embedded field information of a document and return information without saving the document in DeepCloud.

The endpoint returns the information found for all embedded field information for the document signing, including signees and obeservers. It can be used to decide if a document contains the required pre-defined embedded fields to start a signing process, before uploading the document and starting the signing process.

HTTP Request

POST https://api.sign.deepbox.swiss/api/v1/documents/file/scan-predefined

Swagger Reference

POST/api/v1/documents/file/scan-predefined

Message Structure

The document upload is a multipart mime POST request. The document being uploaded contains the binary encoded document (e.g. pdf file). The following headers must be present in the Request when uploading document files :

Content-Type: multipart/form-data; boundary=-----<unique-boundary-id-to-separate-message-parts>;

Typical examples for the boundary parameter are shown in the HTTP Requests.
For example :
Content-Type: multipart/form-data; boundary=---------9B82F53A7B2247AB8B5B9707CBB0DFD2

Overview

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();

      // Example code for GET https://api.sign.deepbox.swiss/api/v1/overview?offset=0&limit=50
      HttpRequest request = HttpRequest.newBuilder()
        .GET()
        .uri(URI.create("https://api.sign.deepbox.swiss/api/v1/overview?offset=0&limit=50"))
        .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
        .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
      ge.printStackTrace();
    }
  }
}

public async void simpleGetRequestExample()
{
    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/overview?offset=0&limit=50";
    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");

    // Example code for GET https://api.sign.deepbox.swiss/api/v1/overview?offset=0&limit=50
    HttpResponseMessage response = await httpClient.GetAsync(requestUrl, HttpCompletionOption.ResponseContentRead, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \  
     "https://api.sign.deepbox.swiss/api/v1/overview?offset=0&limit=50"

GET /api/v1/overview?offset=0&limit=50 HTTP/1.1
Accept-Charset: UTF-8
Accept: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ

The above request returns JSON structured like this:

{
  "documents":[
    {
      "documentId":"bb602c43-caae-4656-a447-233b2317b14a",
      "documentName":"example.pdf",
      "documentMimeType":"application/pdf",
      "thumbnailUrl":null,
      "documentStatus":"draft",
      "signStatus":null,
      "signKey":null,
      "policy":{
        "canWithdraw":false,
        "canDelete":true
      }
    }
  ],
  "pagination":{
    "offset":0,
    "limit":50
  },
  "size":1
}

This endpoint retrieves the overview of all available documents, including the status, on the DeepSign server, for the current user. Only the documents belonging to the specific user can be retrieved. The document and sign status can be filtered by including the URL parameters "filterDocumentStatus" and "filterSignStatus".

HTTP Request

GET https://api.sign.deepbox.swiss/api/v1/overview?offset=0&limit=50

URL Parameters

Parameter	Description
offset	The offset of the starting document to retrieve
limit	The maximum number of documents that should be retrieved for the request
order	Defines the order based on creation time (e.g. "creationTime desc")
filterDocumentStatus	Filter by documentStatus (values : draft, in-progress, signed, withdrawn, rejected)
filterSignStatus	Filter by signStatus (values : on-hold, pending, in-progress, signed, rejected)

The URL Parameters are optional

Swagger Reference

GET/api/v1/overview

The Document Overview returns a list of summary information and status about each document. The information is equivalent to the information displayed in the DeepSign Application overview page. More detailed information about a document can be retrieved with the GET Request using the Document ID

The most interesting properties of the overview are :

"documentId" - uniquely defines the document and can be used for other API calls to reference the document
"documentStatus" - is defined by the DeepSign and can be one of the following : "draft", "in-progress", "signed", "withdrawn", "rejected"
"signStatus" - is defined by the DeepSign and can be one of the following : "on-hold", "pending", "in-progress", "signed", "rejected"

The following values are possible for a "documentStatus" :

"draft" - the document is in draft mode and document properties and signees can be added or changed
"in-progress" - the document sign process has been started and at least one signee has signed the document
"signed" - the document has been successfully signed by all signees
"withdrawn" - the document has been withdrwan from the signing process. It cannot be reactivated for the signing process.
"rejected" - at least one signee has rejected the signing of the document

The following values are possible for the "signStatus" :

"on-hold" - the sign process is waiting for signees in a specified order
"pending" - the sign process has been started, but not signed by any signee
"in-progress" - the sign process has been started and at least one signee has signed the document
"signed" - all signees have successfully signed the document
"rejected" - at least one signee has rejected the signing of the document

Available modes

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();

      // Example code for GET https://api.sign.deepbox.swiss/api/v1/available-modes
      HttpRequest request = HttpRequest.newBuilder()
        .GET()
        .uri(URI.create("https://api.sign.deepbox.swiss/api/v1/available-modes"))
        .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
        .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
      ge.printStackTrace();
    }
  }
}

public async void simpleGetRequestExample()
{
    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/available-modes";
    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");

    // Example code for GET https://api.sign.deepbox.swiss/api/v1/available-modes
    HttpResponseMessage response = await httpClient.GetAsync(requestUrl, HttpCompletionOption.ResponseContentRead, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \  
     "https://api.sign.deepbox.swiss/api/v1/available-modes"

GET /api/v1/available-modes HTTP/1.1
Accept-Charset: UTF-8
Accept: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ

The above request returns JSON structured like this:

{
  "timestamp":{},
  "advanced":{
    "zertes":["ras","did"],
    "eidas":["did"]
  },
  "qualified":{
    "zertes":["ras","did"],
    "eidas":["ras","did"]
  }
}

This endpoint retrieves available signature modes that can be used in each particular jurisdiction for signing documents.

HTTP Request

GET https://api.sign.deepbox.swiss/api/v1/available-modes

Swagger Reference

GET/api/v1/available-modes

Mode	Description
did	DeepID
ras	MobileID
zertes	Swiss defined legal jurisdiction
eidas	European defined legal jurisdiction

Signees

Add signee

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();

      // Example code for POST https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees
      HttpRequest request = HttpRequest.newBuilder()
          .POST(HttpRequest.BodyPublishers.ofString("{\"email\": \"test.person@abacus.ch\",\"comment\": \"Please sign the PDF file\",\"signOrder\":0}"))
          .uri(URI.create("https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees"))
          .setHeader("Accept-Charset", "UTF-8")
          .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
          .setHeader("Content-Type", "application/json")
          .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
        ge.printStackTrace();
    }
  }
}

public async void simplePostRequestExample()
{
    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees";
    String requestContent = "{\"email\": \"test.person@abacus.ch\",\"comment\": \"Please sign the PDF file\",\"signOrder\":0}";

    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");
    requestHttpHeaders.Add("Accept", "application/json");
    requestHttpHeaders.Add("Accept-Charset", "UTF-8");

    // Example code for POST https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees
    StringContent scData = new StringContent(requestContent, Encoding.UTF8, "application/json");
    HttpResponseMessage response = await httpClient.PostAsync(requestUrl, scData, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -X POST --location "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \
  -H "Content-Type: application/json" \
  -d '{"email":"test.person@abacus.ch","comment":"Please sign the PDF file","signOrder":0}'

POST /api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees HTTP/1.1
Accept-Charset: UTF-8
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ
Content-Length: 68

{
  "email": "test.person@abacus.ch",
  "comment": "Please sign the PDF file",
  "signOrder": 0
}

The above request returns JSON structured like this:

{
  "signeeId":"56f16b80-0058-44d8-bf33-2847612b24b1",
  "email":"test.person@abacus.ch",
  "signUrl":null,
  "documentId":"bb602c43-caae-4656-a447-233b2317b14a",
  "viewedTime":null,
  "signedTime":null,
  "completionTime":null,
  "signStatus":"on-hold",
  "initiatorComment":"PDF file for testing",
  "signeeComment":null,
  "language":null,
  "autographPosition":null,
  "signOrder":0,
  "policy":
  {
    "canModifyAutographPosition":true
  }
}

This endpoint adds a specified signee to a DeepSign document

HTTP Request

POST https://api.sign.deepbox.swiss/api/v1/documents/{documentId}/signees

URL Parameters

Parameter	Description
documentId	The ID of the document where the signee is added

Swagger Reference

POST/api/v1/documents/{documentId}/signees

Get signee

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();

      // Example code for GET https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1
      HttpRequest request = HttpRequest.newBuilder()
        .GET()
        .uri(URI.create("https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1"))
        .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
        .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
      ge.printStackTrace();
    }
  }
}

public async void simpleGetRequestExample()
{
    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1";
    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");

    // Example code for GET https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1
    HttpResponseMessage response = await httpClient.GetAsync(requestUrl, HttpCompletionOption.ResponseContentRead, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \  
     "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1"

GET /api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1 HTTP/1.1
Accept-Charset: UTF-8
Accept: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ

The above request returns JSON structured like this:

{
  "signeeId":"56f16b80-0058-44d8-bf33-2847612b24b1",
  "email":"test.person@abacus.ch",
  "signUrl":null,
  "documentId":"bb602c43-caae-4656-a447-233b2317b14a",
  "viewedTime":null,
  "signedTime":null,
  "completionTime":null,
  "signStatus":"on-hold",
  "initiatorComment":"PDF file for testing",
  "signeeComment":null,
  "language":null,
  "autographPosition":null,
  "signOrder":0,
  "policy":
  {
    "canModifyAutographPosition":true
  }
}

This endpoint retrieves an existing signee for a specified to a DeepSign document

HTTP Request

GET https://api.sign.deepbox.swiss/api/v1/documents/{documentId}/signees/{signeeId}

URL Parameters

Parameter	Description
documentId	The ID of the document where the signee is defined
signeeId	The ID of signee in the specified document

Swagger Reference

GET/api/v1/documents/{documentId}/signees/{signeeId}

Update signee

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();
      String requestContent = "{\"email\":\"test.person@abacus.ch\",\"comment\":\"Please sign the PDF file\"," +
                    "\"autographPosition\":{\"pageNumber\":0,\"x\":100,\"y\":400,\"width\":0,\"height\":50 },\"signOrder\":0}";

      // Example code for PUT https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1
      HttpRequest request = HttpRequest.newBuilder()
          .PUT(HttpRequest.BodyPublishers.ofString(requestContent))
          .uri(URI.create("https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1"))
          .setHeader("Accept-Charset", "UTF-8")
          .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
          .setHeader("Content-Type", "application/json")
          .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
        ge.printStackTrace();
    }
  }
}

public async void simplePutRequestExample()
{
    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1";
    String requestContent = "{\"email\":\"test.person@abacus.ch\",\"comment\":\"Please sign the PDF file\"," +
                 "\"autographPosition\":{\"pageNumber\":0,\"x\":100,\"y\":400,\"width\":0,\"height\":50 },\"signOrder\":0}";

    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");
    requestHttpHeaders.Add("Accept", "application/json");
    requestHttpHeaders.Add("Accept-Charset", "UTF-8");

    // Example code for PUT https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1
    StringContent scData = new StringContent(requestContent, Encoding.UTF8, "application/json");
    HttpResponseMessage response = await httpClient.PutAsync(requestUrl, scData, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -X PUT --location "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \
  -H "Content-Type: application/json" \
  -d '{"email":"test.person@abacus.ch","comment":"Please sign the PDF file", \
       "autographPosition":{"pageNumber":0,"x":100,"y":400,"width":0,"height":50 },"signOrder":0}'

PUT /api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1 HTTP/1.1
Content-Length: 72
Host: api.sign.deepbox.swiss
User-Agent: Java-http-client/11.0.14.1
Accept-Charset: UTF-8
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ
Content-Type: application/json

{
  "email": "test.person@abacus.ch",
  "comment": "Please sign the PDF file",
  "autographPosition": {
    "pageNumber": 0,
    "x": 100,
    "y": 400,
    "width": 0,
    "height": 50
  },
  "signOrder": 0
}

The above request returns JSON structured like this:

{
  "signeeId":"56f16b80-0058-44d8-bf33-2847612b24b1",
  "signeeType":"sign",
  "email":"test.person@abacus.ch",
  "signatureType":"signature",
  "signUrl":null,
  "documentId":"bb602c43-caae-4656-a447-233b2317b14a",
  "viewedTime":null,
  "signedTime":null,
  "completionTime":null,
  "signStatus":"on-hold",
  "initiatorComment":"Please sign the PDF file",
  "signeeComment":null,
  "language":null,
  "autographPosition":{
    "pageNumber":1,
    "x":100.0,
    "y":400.0,
    "width":0.0,
    "height":50.0
  },
  "signOrder":0,
  "policy":{
    "canModifyAutographPosition":true
  }
}

Update an existing signee for an existing DeepSign document.

HTTP Request

PUT https://api.sign.deepbox.swiss/api/v1/documents/{documentId}/signees/{signeeId}

Swagger Reference

PUT/api/v1/documents/{documentId}/signees/{signeeId}

Delete signee

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();

      // Example code for DELETE https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1
      HttpRequest request = HttpRequest.newBuilder()
        .DELETE(HttpRequest.BodyPublishers.ofString())
        .uri(URI.create("https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1"))
        .setHeader("Accept-Charset", "UTF-8")
        .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
        .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
      ge.printStackTrace();
    }
  }
}

public async void simpleDeleteRequestExample()
{
    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1";
    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");

    // Example code for DELETE https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1
    StringContent scData = new StringContent("", Encoding.UTF8, "application/json");
    HttpResponseMessage response = await httpClient.DeleteAsync(requestUrl, scData, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -X DELETE --location "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \
  -H "Accept-Charset: UTF-8"

DELETE /api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1 HTTP/1.1
Accept-Charset: UTF-8
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ

The above request returns JSON structured like this:

{
  "signeeId":"56f16b80-0058-44d8-bf33-2847612b24b1",
  "email":"test.person@abacus.ch",
  "signUrl":null,
  "documentId":"bb602c43-caae-4656-a447-233b2317b14a",
  "viewedTime":null,
  "signedTime":null,
  "completionTime":null,
  "signStatus":"on-hold",
  "initiatorComment":"PDF file for testing",
  "signeeComment":null,
  "language":null,
  "autographPosition":null,
  "signOrder":0,
  "policy":
  {
    "canModifyAutographPosition":true
  }
}

This endpoint deletes an existing signee for a specified DeepSign document

HTTP Request

DELETE https://api.sign.deepbox.swiss/api/v1/documents/{documentId}/signees/{signeeId}

URL Parameters

Parameter	Description
documentId	The ID of the document where the signee is defined
signeeId	The ID of signee in the specified document

Swagger Reference

DELETE/api/v1/documents/{documentId}/signees/{signeeId}

Resend Invitation

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();

      String requestContent = "";
      String requestUrl = "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1/resend-invitation";
      // Example code for POST ../api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1/resend-invitation
      HttpRequest request = HttpRequest.newBuilder()
          .POST(HttpRequest.BodyPublishers.ofString(requestContent))
          .uri(URI.create(requestUrl))
          .setHeader("Accept-Charset", "UTF-8")
          .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
          .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
        ge.printStackTrace();
    }
  }
}

public async void simplePostRequestExample()
{
    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1/resend-invitation";
    String requestContent = "";

    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");
    requestHttpHeaders.Add("Accept", "application/json");
    requestHttpHeaders.Add("Accept-Charset", "UTF-8");

    // Example code for POST ../api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1/resend-invitation
    StringContent scData = new StringContent(requestContent, Encoding.UTF8, "application/json");
    HttpResponseMessage response = await httpClient.PostAsync(requestUrl, scData, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -X POST --location "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1/resend-invitation" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \
  -d ''

POST /api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees/56f16b80-0058-44d8-bf33-2847612b24b1/resend-invitation HTTP/1.1
Content-Length: 0
Host: api.sign.deepbox.swiss
User-Agent: Java-http-client/11.0.14.1
Accept-Charset: UTF-8
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ

The above request returns an empty response with HTTP 204 No Content
HTTP/1.1 204 No Content

This endpoint resends the invitation email to an existing signee for a specified DeepSign document

HTTP Request

POST https://api.sign.deepbox.swiss/api/v1/documents/{documentId}/signees/{signeeId}/resend-invitation

URL Parameters

Parameter	Description
documentId	The ID of the document where the signee is defined
signeeId	The ID of signee in the specified document

Swagger Reference

POST/api/v1/documents/{documentId}/signees/{signeeId}/resend-invitation

Observers

Add observer

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();

      // Example code for POST https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/observers
      HttpRequest request = HttpRequest.newBuilder()
          .POST(HttpRequest.BodyPublishers.ofString("{\"email\": \"test.person@abacus.ch\",\"comment\": \"Observer for PDF file\",\"isAdmin\":false}"))
          .uri(URI.create("https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/observers"))
          .setHeader("Accept-Charset", "UTF-8")
          .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
          .setHeader("Content-Type", "application/json")
          .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
        ge.printStackTrace();
      }
    }
  }

public async void simplePostRequestExample()
{
    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/observers";
    String requestContent = "{\"email\": \"test.person@abacus.ch\",\"comment\": \"Observer for PDF file\",\"isAdmin\":false}");

    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");
    requestHttpHeaders.Add("Accept", "application/json");
    requestHttpHeaders.Add("Accept-Charset", "UTF-8");

    // Example code for POST https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/observers
    StringContent scData = new StringContent(requestContent, Encoding.UTF8, "application/json");
    HttpResponseMessage response = await httpClient.PostAsync(requestUrl, scData, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -X POST --location "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/observers" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \
  -H "Content-Type: application/json" \
  -d '{"email":"test.person@abacus.ch","comment":"Observer for PDF file","isAdmin":false}'

POST /api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/observers HTTP/1.1
Accept-Charset: UTF-8
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ
Content-Length: 68

{
  "email": "test.person@abacus.ch",
  "comment": "Observer for PDF file",
  "isAdmin": false
}

The above request returns JSON structured like this:

{
  "observerId":"3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email":"test.person@abacus.ch",
  "signUrl":null,
  "documentId":"bb602c43-caae-4656-a447-233b2317b14a",
  "viewedTime":null,
  "initiatorComment":"Observer for PDF file",
  "language":null,
  "isAdmin":false
}

This endpoint adds an observer to a DeepSign document.

HTTP Request

POST https://api.sign.deepbox.swiss/api/v1/documents/{documentId}/observers

URL Parameters

Parameter	Description
documentId	The ID of the document where the observer is added

Swagger Reference

POST/api/v1/documents/{documentId}/observers

Note: Observers can also be updated in an existing document using the following URL extension with the observer ID

PUT https://api.sign.deepbox.swiss/api/v1/documents/{documentId}/observers/{observerId}

Delete observer

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();

      // Example code for DELETE https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/observers/3fa85f64-5717-4562-b3fc-2c963f66afa6
      HttpRequest request = HttpRequest.newBuilder()
        .DELETE(HttpRequest.BodyPublishers.ofString())
        .uri(URI.create("https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/observers/3fa85f64-5717-4562-b3fc-2c963f66afa6"))
        .setHeader("Accept-Charset", "UTF-8")
        .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
        .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
      ge.printStackTrace();
    }
  }
}

public async void simpleDeleteRequestExample()
{
    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/observers/3fa85f64-5717-4562-b3fc-2c963f66afa6";
    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");

    // Example code for DELETE https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/observers/3fa85f64-5717-4562-b3fc-2c963f66afa6
    StringContent scData = new StringContent("", Encoding.UTF8, "application/json");
    HttpResponseMessage response = await httpClient.DeleteAsync(requestUrl, scData, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -X DELETE --location "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/observers/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \
  -H "Accept-Charset: UTF-8"

DELETE /api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/observers/3fa85f64-5717-4562-b3fc-2c963f66afa6 HTTP/1.1
Accept-Charset: UTF-8
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ

The above request returns JSON structured like this:

{
  "observerId":"3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email":"test.person@abacus.ch",
  "signUrl":null,
  "documentId":"bb602c43-caae-4656-a447-233b2317b14a",
  "viewedTime":null,
  "initiatorComment":"Observer for PDF file",
  "language":null,
  "isAdmin":false
}

This endpoint deletes an existing observer for a specified DeepSign document

HTTP Request

DELETE https://api.sign.deepbox.swiss/api/v1/documents/{documentId}/observers/{observerId}

URL Parameters

Parameter	Description
documentId	The ID of the document where the observer is defined
observerId	The ID of observer in the specified document

Swagger Reference

DELETE/api/v1/documents/{documentId}/observers/{observerId}

Visual Signature

Text Field Pattern

There are several text pattern fields possible, that can be placed in the document file to pre-configure various DeepSign properties. Pre-configuring properties in the document file may reduce the configurations that are necessary via the DeepSign API after the document is uploaded.

The following text patterns are available:

Pattern	Description
#deepsign#	Configuration of signature field with email, sign-order and size
#deepsign-mode#	Configuration of signature-mode and jurisdiction
#deepsign-observer#	Configuration of observers and admin access rights
#deepsign-reminder#	Configuration of number of reminder days for signees
#deepsign#seal#	Configuration for visible seal position

#deepsign#

A coded text can be included in the document file to predefine the signees, the signee position and the sign order. The format of the coded text is as follows :
#deepsign#{email-address};{sign-order};{size}#

The sign order can be defined with the {sign-order} number. The {sign-order} can be omitted or defined as zero, if no sign-order is defined. More than one signee can have the same order number, when they can sign simultaneously.

Example	Description
#deepsign#test.person@abacus.ch;0;40#	- size defined as 40mm width
#deepsign#test.person@abacus.ch;0;S#	- size defined as Small

The size of the signature field width can be defined with the optional {size} parameter. The size can be defined in millimetres or as S, M or L for Small, Medium and Large, respectively.

Size	pt (width x height)	mm (width x height)	px (width x height)	Comment
S - Small	109.50 x 57.85	38.63 x 20.41	146 x 77
M - Medium	159.00 x 84.00	56.09 x 29.63	212 x 112	Default
L - Large	195.00 x 103.02	68.79 x 36.34	260 x 137

View of original document before uploading:
Signee positioning text
View of positioned signature fields after uploading:
Signees positioned on the text

#deepsign-mode#

The signature mode and jurisdiction can be defined by including the #deepsign-mode# text field pattern in the document file.
#deepsign-mode#{signature mode};{jurisdiction}#

The field content can combine the signature mode ses, aes or qes with the jurisdiction zertes or eidas, where the combinations are supported. For example, the combination of AES with Eidas is currently not possible.

Example	Description
#deepsign-mode#ses#	- SES is default and will also be used when not defined
#deepsign-mode#aes;zertes#	- combination of AES and Zertes
#deepsign-mode#qes;eidas#	- combination of QES and Eidas

Detailed information about the possible signature modes and jurisdictions is available in the Message Stucture for Upload Document details.

#deepsign-observer#

An observer can be defined by including the #deepsign-observer# text field pattern in the document file.
#deepsign-observer#{email-address};{admin}#

The field content can combine the signature mode ses, aes or qes with the jurisdiction zertes or eidas, where the combinations are supported. For example, the combination of AES with Eidas is currently not possible.

Example	Description
#deepsign-observer#test.person@abacus.ch#	Observer defined with predefined email
#deepsign-observer#test.person@abacus.ch;admin#	Observer defined with Admin rights

#deepsign-reminder#

The interval in days that the reminder emails will be sent to signees can be defined by including the #deepsign-reminder# text field pattern in the document file.
#deepsign-reminder#{number-of-days}}#

The field content contains the number of days to wait before the reminder emails are sent to the signees, if the document has not been completely signed.

Example	Description
#deepsign-reminder#4#	Reminder emails will be sent to signees after an interval of 4 days, if the document has not been completely signed

Note: This value can also be set via the parameter "sendReminderMail" in the AddDocumentFile data structure when uploading the document file to DeepSign with the API.

#deepsign#seal#

Positions a visual seal in the document.

Example	Description
#deepsign#seal#	Placeholder for visual seal in the document. If no seal position is defined then the seal will no be visible
#deepsign#seal:{seal-key}#	Placeholder for visual seal in the document, using the {seal-key} obtained from the Company Seals in the DeepCloud Administration.

Note: The text field patterns for #deepsign#seal# are normally used together with the API parameter "scanPredefined"=true. The information defined in the text field patterns for #deepsign#seal#, takes priority over the values sent via the API.

PDF Signature Field

The PDF format has a designated PDF Signature fields. The signature field is recognized by DeepSign, and can be used to position the DeepSign Signature field.

Position via API

// No java example currently available (see shell or http examples)

// No csharp example currently available (see shell or http examples)

curl -X POST --location "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \
  -H "Content-Type: application/json" \
  -d '{"email":"test.person@abacus.ch","comment":"Please sign the PDF file", \
       "autographPosition":{"pageNumber":0,"x":100,"y":400,"width":0,"height":50 },"signOrder":0}'

POST /api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/signees HTTP/1.1
Accept-Charset: UTF-8
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ

{
  "email": "test.person@abacus.ch",
  "comment": "Please sign the PDF file",
  "autographPosition": {
    "pageNumber": 0,
    "x": 100,
    "y": 400,
    "width": 0,
    "height": 50
  },
  "language": "de",
  "signOrder": 0,
  "signFieldName": "Test Person"
}

The above request returns JSON structured like this:

{
  "signeeId":"56f16b80-0058-44d8-bf33-2847612b24b1",
  "email":"test.person@abacus.ch",
  "signUrl":null,
  "documentId":"bb602c43-caae-4656-a447-233b2317b14a",
  "viewedTime":null,
  "signedTime":null,
  "completionTime":null,
  "signStatus":"on-hold",
  "initiatorComment":"PDF file for testing",
  "signeeComment":null,
  "language":null,
  "autographPosition": {
    "pageNumber": 0,
    "x": 100,
    "y": 400,
    "width": 0,
    "height": 50
  },
  "signOrder":0,
  "policy":
  {
    "canModifyAutographPosition":true
  }
}

The position of the signature can be defined via the API using "autographPosition", when the Signee is added or modified. The sign order can be defined with the "signOrder" property. The "signOrder" is zero-based (1st to sign is "0"). More than one signee can have the same order number, when they can sign simultaneously.

The following parameters are available in the "autographPosition" to define the position and size of the signature field.

Parameter	Description
pageNumber	the page number in the document file (e.g. 1, 2, 3, etc.)
x	the x, horizontal position of the signature field in "pts" from the bottom left corner of the page
y	the y, vertical position of the signature field in "pts" from the bottom left corner of the page
width	the width of the signature field in pts (default width is 159.00 "pts")
height	the height of the signature field in pts (default width is 84.00 "pts")

Note: The signature position is referenced to the bottom left corner of the signature field, from the bottom left corner of the page in "pts".

Company Seals

Electronic seals can be applied to the document via the API. Seals are applied as a digital certificate to verify the identity of the organization. The available seals must be pre-configured in the DeepCloud account for the organisation (See DeepCloud Administration). The Service-User must also be configured with access to one or more seals, so that seals can be used via the API.

Signees positioned on the text
Company Seals can be managed in the DeepCloud Administration. The access for the Service-User must also be configured, prior to using the seal certificate via the API.

Get available seals

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      String requestUrl = "https://api.sign.deepbox.swiss/api/v1/users/me/seals";
      HttpClient httpClient = getHttpClient();

      // Example code for GET https://api.sign.deepbox.swiss/api/v1/users/me/seals
      HttpRequest request = HttpRequest.newBuilder()
          .GET()
          .uri(URI.create(requestUrl))
          .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
          .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
      ge.printStackTrace();
    }
  }
}

// No csharp example currently available (see shell examples)

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \ 
       "https://api.sign.deepbox.swiss/api/v1/users/me/seals"

GET /api/v1/users/me/seals HTTP/1.1
Content-Length: 0
Host: api.sign.deepbox.swiss
User-Agent: Java-http-client/11.0.14.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ

If no seals are available for the current user, an empty array [] is returned.

The above request returns JSON structured like this:

[
  {
    "company":
    {
      "companyId":"09795a43-baaf-48ae-91a6-a533168f803a",
      "displayName":"Abacus Software AG"
    },
    "sealId":"e20459fc-bf3c-4a79-81d4-9541c5899e75",
    "displayName":"Example Seal 1"
  },
  {
    "company":
    {
      "companyId":"09795a43-baaf-48ae-91a6-a533168f803a",
      "displayName":"Abacus Software AG"
    },
    "sealId":"b9f5721f-38f2-4d27-881e-dfcf1a64e65d",
    "displayName":"Example Seal 2"
  }
]

The following endpoint is used to retrieve the available seals for the current user

HTTP Request

GET https://api.sign.deepbox.swiss/api/v1/users/me/seals

Swagger Reference

GET/api/v1/users/me/seals

Apply Seal to Document

Note : If no autographPosition is defined the seal will not be visible, and only electronically certified.

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      String requestUrl = "https://api.sign.deepbox.swiss/api/v1/service/file/seal";
      String mimeBoundary = "-----" + UUID.randomUUID().toString().replace("-", "");

      MultipartEntityBuilder multipartEntitybuilder = MultipartEntityBuilder.create();
      multipartEntitybuilder.setMode(HttpMultipartMode.STRICT);
      multipartEntitybuilder.setBoundary(mimeBoundary);

      // Only ContentType with "application/pdf" is accepted
      File uploadFile = new File("testupload.pdf");
      FileBody fileBody = new FileBody(uploadFile, ContentType.create("application/pdf"));
      multipartEntitybuilder.addTextBody("data", "{\"sealId\": \"b9f5721f-38f2-4d27-881e-dfcf1a64e65d\",\"acceptSealIds\":[\"*\"]," +
               "\"autographPosition\":{...[abbreviated for display]...}}", ContentType.APPLICATION_JSON);
      multipartEntitybuilder.addPart("file", fileBody);

      HttpEntity entity = multipartEntitybuilder.build();

      final ByteArrayOutputStream os = new ByteArrayOutputStream();
      entity.writeTo(os);
      os.flush();

      HttpClient httpClient = getHttpClient();

      // Example code for POST https://api.sign.deepbox.swiss/api/v1/service/file/seal
      HttpRequest request = HttpRequest.newBuilder()
          .POST(HttpRequest.BodyPublishers.ofByteArray(os.toByteArray()))
          .uri(URI.create(requestUrl))
          .setHeader("Accept-Charset", "UTF-8")
          .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
          .setHeader("Content-Type", "multipart/form-data; boundary=" + mimeBoundary)
          .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
      ge.printStackTrace();
    }
  }
}

public async void simpleRequestExample()
{
    String requestUrl = "http://api.sign.deepbox.swiss/api/v1/service/file/seal";
    String requestContent = "{\"sealId\": \"b9f5721f-38f2-4d27-881e-dfcf1a64e65d\",\"acceptSealIds\":[\"*\"]," + 
                               "\"autographPosition\":{...[abbreviated for display]...}";

    String authorizationHeader = "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ";

    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", authorizationHeader);
    requestHttpHeaders.Add("Accept-Charset", "UTF-8");

    // Example code for POST file seal with "multi-part" https://api.sign.deepbox.swiss/api/v1/service/file/seal
    String uploadLocalFilePath = "c:\\temp\\example.pdf";
    String targetLocalFilePath = "c:\\temp\\example_with_seal.pdf";
    String shortFileName = uploadLocalFilePath;
    int ipos = shortFileName.LastIndexOf("\\");
    if (ipos > 0)
    {
        shortFileName = shortFileName.Substring(ipos + 1);
    }
    StringContent scDataPart = new StringContent(requestContent, Encoding.UTF8, "application/json");

    FileStream fileStream = new FileStream(uploadLocalFilePath, FileMode.Open);
    StreamContent fileDataPart = new StreamContent(fileStream);
    fileDataPart.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");

    MultipartFormDataContent multiPartData = new MultipartFormDataContent();
    multiPartData.Add(scDataPart, "data");
    multiPartData.Add(fileDataPart, "file", shortFileName);

    HttpResponseMessage response = await httpClient.PostAsync(requestUrl, multiPartData, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        // Read the returned binary PDF content with seal
        byte[] binaryResp = await response.Content.ReadAsByteArrayAsync();
        if ( binaryResp != null )
        {
            File.WriteAllBytes(targetLocalFilePath, binaryResp);
            if ( File.Exists(targetLocalFilePath) )
            {
                responseResult = "File with seal saved locally to : " + targetLocalFilePath; 
            }
        }
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -X POST --location "https://api.sign.deepbox.swiss/api/v1/service/file/seal" \
                -H 'Authorization: Bearer ...' -H 'Content-Type: multipart/form-data' \ 
                -F 'file=@/path/to/example.pdf;type=application/pdf' \
                -F 'data={"sealId":"b9f5721f-38f2-4d27-881e-dfcf1a64e65d","acceptSealIds":["*"], \ 
                      "autographPosition":{"pageNumber": 1,"x": 302.0,"y": 250.0,"width": 159.0,"height": 84.0}};type=application/json'

POST /api/v1/service/file/seal HTTP/1.1
Content-Length: 48052
Host: api.sign.deepbox.swiss
User-Agent: Java-http-client/11.0.14.1
Accept-Charset: UTF-8
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ
Content-Type: multipart/form-data; boundary=---------0B4EC7B86B5E4B8BA379F01883ED6280

-----------0B4EC7B86B5E4B8BA379F01883ED6280
Content-Disposition: form-data; name="data"
Content-Type: application/json; charset=UTF-8
Content-Transfer-Encoding: 8bit

{
  "sealId": "b9f5721f-38f2-4d27-881e-dfcf1a64e65d",
  "acceptSealIds" : ["*"],
  "autographPosition": {
   "pageNumber": 1,
   "x": 302.0,
   "y": 290.0,
   "width": 159.0,
   "height": 84.0
  }
}
-----------0B4EC7B86B5E4B8BA379F01883ED6280
Content-Disposition: form-data; name="file"; filename="example.pdf"
Content-Type: application/pdf
Content-Transfer-Encoding: binary

%PDF-1.4
    ...[abbreviated for display]...
    ...[abbreviated for display]...
%%EOF

-----------0B4EC7B86B5E4B8BA379F01883ED6280--

The above request returns the PDF stream of the sealed PDF document :

HTTP/1.1 200 
vary: Origin
vary: Access-Control-Request-Method
vary: Access-Control-Request-Headers
content-disposition: attachment; filename="=?UTF-8?Q?example.pdf?="; filename*=UTF-8''example.pdf
accept-ranges: bytes
x-content-type-options: nosniff
x-xss-protection: 0
x-frame-options: DENY
content-type: application/pdf
content-length: 256934
date: Thu, 25 Jan 2024 13:48:31 GMT
strict-transport-security: max-age=31536000

%PDF-1.4
    ...[abbreviated for display]...
    ...[abbreviated for display]...
%%EOF

The following endpoint is used to apply the seal to the document

HTTP Request

POST https://api.sign.deepbox.swiss/api/v1/service/file/seal

Swagger Reference

POST/api/v1/service/file/seal

The request is a multipart mime message similar to the file Upload request. The main data body can contain the "sealId" to reference the seal of the organisation that will be used to seal the document.

The following information can also be defined in the request body when sealing the document :

Parameter	Possible values	Default value
sealId	The seal ID obtained from the available Seals for the service user	none
autographPosition	Defines the position and size of the visual seal field (if omitted, the seal will be not be visible) See description below	none
scanPredefined	false - Predefine signatures and seals in the document will not be scanned true - the document is scanned for predefined test pattern fields	false
acceptSealIds	A list of sealId's allowed, to ensured that only sealId's are used, for the specified service user and company signees. To allow all seals, use ["*"]	must be defined

The following parameters are available in the "autographPosition" to define the position and size of the visual seal field.

Parameter	Description
pageNumber	the page number in the document (e.g. 1, 2, 3, etc.)
x	the x, horizontal position of the seal field in "pts" from the bottom left corner of the page
y	the y, vertical position of the seal field in "pts" from the bottom left corner of the page
width	the width of the seal field in pts (default width is 159.00 "pts")
height	the height of the seal field in pts (default width is 84.00 "pts")

Note: The seal position is referenced to the bottom left corner of the seal field, from the bottom left corner of the page in "pts".

Hash

The DeepCloud Hash functionality must be activated in the DeepCloud configuration, before is can be used. Please contact the DeepCloud administration if the Hash options should be activated.

Hash Sign

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  private String generateSha256FileHash(File file) {
    if ( file == null || !file.isFile() ) return "";
    String hashValue = "";
    try {
      byte[] data = Files.readAllBytes(Paths.get(file.getPath()));
      byte[] hash = MessageDigest.getInstance("SHA-256").digest(data);
      hashValue = Base64.getEncoder().encodeToString(hash);
    } catch( Exception ge) {
      ge.printStackTrace();
      hashValue = "";
    }
    return hashValue;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();

      File documentFile = new File("example.pdf");
      String digestValue = generateSha256FileHash(documentFile);  // Example hash "digestValue": "e6rldxg1N6dj4LEWinVfpbM2dgQwA184TubtiZmIL/4="

      String requestUrl = "https://api.sign.deepbox.swiss/api/v1/service/hash/sign";
      String requestContent = "{\"hashes\":[{\"hashId\":\"document_reference_01\"," + 
        "\"digestValue\":\"" + digestValue + "\",\"digestAlgorithm\":\"SHA-256\"}]," +
        "\"signatureMode\":\"timestamp\",\"jurisdiction\":\"zertes\",\"documentName\":\"" + documentFile.getName() + "\"}";

      // Example code for POST https://api.sign.deepbox.swiss/api/v1/service/hash/sign
      HttpRequest request = HttpRequest.newBuilder()
          .POST(HttpRequest.BodyPublishers.ofString(requestContent))
          .uri(URI.create(requestUrl))
          .setHeader("Accept-Charset", "UTF-8")
          .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
          .setHeader("Content-Type", "application/json")
          .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
        ge.printStackTrace();
    }
  }
}

public async void simplePostRequestExample()
{
    String documentFileName = "example.pdf";
    String digestValue = "";    // Example hash "digestValue": "e6rldxg1N6dj4LEWinVfpbM2dgQwA184TubtiZmIL/4="
    using (FileStream stream = File.OpenRead(documentFileName))
    {
        SHA256Managed sha = new SHA256Managed();
        byte[] hashedVal = sha.ComputeHash(stream);
        digestValue = System.Convert.ToBase64String(hashedVal);
    }

    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/service/hash/sign";
    String requestContent = "{\"hashes\":[{\"hashId\":\"document_reference_01\"," + 
        "\"digestValue\":\"" + digestValue + "\",\"digestAlgorithm\":\"SHA-256\"}]," +
        "\"signatureMode\":\"timestamp\",\"jurisdiction\":\"zertes\",\"documentName\":\"" + documentFileName + "\"}";

    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");
    requestHttpHeaders.Add("Accept", "application/json");
    requestHttpHeaders.Add("Accept-Charset", "UTF-8");

    // Example code for POST https://api.sign.deepbox.swiss/api/v1/service/hash/sign
    StringContent scData = new StringContent(requestContent, Encoding.UTF8, "application/json");
    HttpResponseMessage response = await httpClient.PostAsync(requestUrl, scData, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -X POST --location "https://api.sign.deepbox.swiss/api/v1/service/hash/sign" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \
  -H "Content-Type: application/json" \
  -d '{"hashes":[{"hashId":"document_reference_01","digestValue":"e6rldxg1N6dj4LEWinVfpbM2dgQwA184TubtiZmIL/4=","digestAlgorithm":"SHA-256"}], \
           "signatureMode":"timestamp","jurisdiction":"zertes","documentName":"example.pdf"}'

POST /api/v1/service/hash/sign HTTP/1.1
Accept-Charset: UTF-8
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ
Content-Length: 221

{
  "hashes": [
  {
    "hashId": "document_reference_01",
    "digestValue": "e6rldxg1N6dj4LEWinVfpbM2dgQwA184TubtiZmIL/4=",
    "digestAlgorithm": "SHA-256"
  }],
  "signatureMode":"timestamp",
  "jurisdiction":"zertes",
  "documentName":"example.pdf"
}

The above request returns JSON structured like this:

{
  "signatureData":
  {
    "signatures":[
      {
        "hashId":"document_reference_01",
        "signature":"MIIgrQYJKoZIhvcNAQc...[abbreviated for display]...Tt+hhU84SLfD9dxn19lUDgS7hTzBqPqXzM="
      }],
    "crls":["MIIGwzCCAncCAQEwQQYJ...[abbreviated for display]...YTvetHkW4JDU7KBWOt9IpXWg=="],
    "ocsps":["MIIKwwoBAKCCCrwwggq4...[abbreviated for display]...omQoFvyvjNFJPGIlslg62cti26ZQ="]
  },
  "signStatus":"signed",
  "lastError":null
}

This endpoint allows a document to be signed via DeepSign using a file hash, rather than uploading the actual document file. The returned "signature" can be used by the client program to sign the document for self-signing applications.

HTTP Request

POST https://api.sign.deepbox.swiss/api/v1/service/hash/sign

Swagger Reference

POST/api/v1/service/hash/sign

The "hashId" is used to reference the returned signature in the response, and must conform to the pattern [a-z-_0-9] (only lower-case characters) with a maximum length of 50. Future implementations of the hash-sign, will allow multiple hashes to be sent in the "hashes" array, and the hashId can be used to reference the returned "signature" in the "signatures" array.

The main content of the request body can also contain additional request parameters such as "companyId", "authorityService", "didIdentityId", "phoneNumber" and "language". Further information can be viewed in the Swagger documentation. See DeepID Identity for more information about retrieving and registering DeepID personal identifiers.

Parameter	Description	Default value
"hashId"	A self-generated hashId used to identify the hash array element. It must conform to the pattern [a-z-_0-9] with a maximum length of 50	must be defined
"digestValue"	The digest value of the file hash encoded as Base64	must be defined
"digestAlgorithm"	The algorithm used to create the file digest value (e.g. SHA-256, SHA-384, SHA-512)	must be defined
"signatureMode"	"timestamp" - SES - simple timestamp "advanced" - AES - advanced signature with 2FA "qualified" - QES - statutory EU and Swiss signature	"timestamp"
"jurisdiction"	"zertes" - Swiss defined legal jurisdiction "eidas" - European defined legal jurisdiction	"zertes"
"documentName"	The document name to be displayed on the signature authorization. Maximum length is 200.	none

Hash Seal

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  private String generateSha256FileHash(File file) {
    if ( file == null || !file.isFile() ) return "";
    String hashValue = "";
    try {
      byte[] data = Files.readAllBytes(Paths.get(file.getPath()));
      byte[] hash = MessageDigest.getInstance("SHA-256").digest(data);
      hashValue = Base64.getEncoder().encodeToString(hash);
    } catch( Exception ge) {
      ge.printStackTrace();
      hashValue = "";
    }
    return hashValue;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();

      File documentFile = new File("example.pdf");
      String digestValue = generateSha256FileHash(documentFile);  // Example hash "digestValue": "e6rldxg1N6dj4LEWinVfpbM2dgQwA184TubtiZmIL/4="

      String requestUrl = "https://api.sign.deepbox.swiss/api/v1/service/hash/seal";
      String requestContent = "{\"hashes\":[{\"hashId\":\"document_reference_01\"," + 
        "\"digestValue\":\"" + digestValue + "\",\"digestAlgorithm\":\"SHA-256\"}]," +
        "\"sealId\":\"b9f5721f-38f2-4d27-881e-dfcf1a64e65d\"}";

      // Example code for POST https://api.sign.deepbox.swiss/api/v1/service/hash/seal
      HttpRequest request = HttpRequest.newBuilder()
          .POST(HttpRequest.BodyPublishers.ofString(requestContent))
          .uri(URI.create(requestUrl))
          .setHeader("Accept-Charset", "UTF-8")
          .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
          .setHeader("Content-Type", "application/json")
          .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
        ge.printStackTrace();
    }
  }
}

public async void simplePostRequestExample()
{
    String documentFileName = "example.pdf";
    String digestValue = "";    // Example hash "digestValue": "e6rldxg1N6dj4LEWinVfpbM2dgQwA184TubtiZmIL/4="
    using (FileStream stream = File.OpenRead(documentFileName))
    {
        SHA256Managed sha = new SHA256Managed();
        byte[] hashedVal = sha.ComputeHash(stream);
        digestValue = System.Convert.ToBase64String(hashedVal);
    }

    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/service/hash/seal";
    String requestContent = "{\"hashes\":[{\"hashId\":\"document_reference_01\"," + 
        "\"digestValue\":\"" + digestValue + "\",\"digestAlgorithm\":\"SHA-256\"}]," +
        "\"sealId\":\"b9f5721f-38f2-4d27-881e-dfcf1a64e65d\"}";

    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");
    requestHttpHeaders.Add("Accept", "application/json");
    requestHttpHeaders.Add("Accept-Charset", "UTF-8");

    // Example code for POST https://api.sign.deepbox.swiss/api/v1/service/hash/seal
    StringContent scData = new StringContent(requestContent, Encoding.UTF8, "application/json");
    HttpResponseMessage response = await httpClient.PostAsync(requestUrl, scData, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -X POST --location "https://api.sign.deepbox.swiss/api/v1/service/hash/seal" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \
  -H "Content-Type: application/json" \
  -d '{"hashes":[{"hashId":"document_reference_01","digestValue":"e6rldxg1N6dj4LEWinVfpbM2dgQwA184TubtiZmIL/4=","digestAlgorithm":"SHA-256"}], \
           "sealId": "b9f5721f-38f2-4d27-881e-dfcf1a64e65d"}'

POST /api/v1/service/hash/seal HTTP/1.1
Accept-Charset: UTF-8
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ
Content-Length: 221

{
  "hashes": [
  {
    "hashId": "document_reference_01",
    "digestValue": "e6rldxg1N6dj4LEWinVfpbM2dgQwA184TubtiZmIL/4=",
    "digestAlgorithm": "SHA-256"
  }],
  "sealId": "b9f5721f-38f2-4d27-881e-dfcf1a64e65d"
}

The above request returns JSON structured like this:

{
  "signatureData":
  {
    "signatures":[
      {
        "hashId":"document_reference_01",
        "signature":"MIIgrQYJKoZIhvcNAQc...[abbreviated for display]...Tt+hhU84SLfD9dxn19lUDgS7hTzBqPqXzM="
      }],
    "crls":["MIIGwzCCAncCAQEwQQYJ...[abbreviated for display]...YTvetHkW4JDU7KBWOt9IpXWg=="],
    "ocsps":["MIIKwwoBAKCCCrwwggq4...[abbreviated for display]...omQoFvyvjNFJPGIlslg62cti26ZQ="]
  }
}

Possible returned error message HTTP/1.1 400 if invalid "hashId" patterns are sent. If this occurs check the request "hashId" for invalid characters :

{
  "timestamp":"2024-05-13T09:10:04.238+00:00",
  "status":400,
  "error":"Bad Request",
  "message":["hashes[0].hashId: must match \"^[a-z-_0-9]{1,50}$\""]
}

This endpoint allows a document to be sealed via DeepSign using a file hash, rather than uploading the actual document file. The returned "signature" can be used by the client program to seal the document for self-signing applications.

HTTP Request

POST https://api.sign.deepbox.swiss/api/v1/service/hash/seal

Swagger Reference

POST/api/v1/service/hash/seal

Parameter	Description	Default value
"hashId"	A self-generated hashId used to identify the hash array element. It must conform to the pattern [a-z-_0-9] with a maximum length of 50	must be defined
"digestValue"	The digest value of the file hash encoded as Base64	must be defined
"digestAlgorithm"	The algorithm used to create the file digest value (e.g. SHA-256, SHA-384, SHA-512)	must be defined
"sealId"	The seal ID obtained from the available Seals for the service user. See Company Seals for more information about seals.	none

DeepID Identity

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();

      String requestUrl = "https://deepgateway.deepcloud.swiss/api/v1/persons/register";
      String requestContent = "{\"personRef\": \"my-company-application-test.person@abacus.ch\"}";

      // Example code for POST https://deepgateway.deepcloud.swiss/api/v1/persons/register
      HttpRequest request = HttpRequest.newBuilder()
          .POST(HttpRequest.BodyPublishers.ofString(requestContent))
          .uri(URI.create(requestUrl))
          .setHeader("Accept-Charset", "UTF-8")
          .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
          .setHeader("Content-Type", "application/json")
          .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
        ge.printStackTrace();
      }
    }
  }

public async void simplePostRequestExample()
{
    String requestUrl = "https://deepgateway.deepcloud.swiss/api/v1/persons/register";
    String requestContent = "{\"personRef\": \"my-company-application-test.person@abacus.ch\"}";

    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");
    requestHttpHeaders.Add("Accept", "application/json");
    requestHttpHeaders.Add("Accept-Charset", "UTF-8");

    // Example code for POST https://deepgateway.deepcloud.swiss/api/v1/persons/register
    StringContent scData = new StringContent(requestContent, Encoding.UTF8, "application/json");
    HttpResponseMessage response = await httpClient.PostAsync(requestUrl, scData, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -X POST --location "https://deepgateway.deepcloud.swiss/api/v1/persons/register" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \
  -H "Content-Type: application/json" \
  -d '{"personRef": "my-company-application-test.person@abacus.ch"}'

POST /api/v1/persons/register HTTP/1.1
Content-Length: 372
Host: deepgateway.deepcloud.swiss
User-Agent: Java-http-client/11.0.14.1
Accept-Charset: UTF-8
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ
Content-Type: application/json

{
   "personRef": "my-company-application-test.person@abacus.ch"
}

If the person with the personRef is already registered in DeepID then the "personIdentityUid" will be returned:

{
  "personIdentityUid": "6b9206e0-2ede-42ab-913b-7ba6d475778e"
}

If the person with the personRef is not register in DeepID then an URL will be returned:

{
  "registrationDeepLink": "https://get.deepid.swiss/QdegakcvaNvBummg6"
}

The returned URL must be opened in DeepID by the person on their mobile device

The Hash Sign can also contain a personal identity "didIdentityId", which is used together with AES or QES signatures.
This is a unique identifier that identifies the person via DeepID. To obtain the DeepID the "didIdentityId" via the API the following Endpoints can be used.

HTTP Requests

POST https://deepgateway.deepcloud.swiss/api/v1/persons/register

Swagger Reference

POSThttps://deepgateway.deepcloud.swiss/swagger/index.html#/register/register

The "personRef" value must uniquely identify the person for each client implementation. It is recommended to prefix the email or telephone number with the company and/or application identification.

If the person is already registered in DeepID, then the personal unique identifier "personIdentityUid" will be returned. The "personIdentityUid" can be used in the Hash Sign request as "didIdentityId" to identify the signee. The person will receive a message in the DeepID mobile application, to confirm the signature.

If the person is not registered in DeepID, then a DeepID registration URL will be returned, in "registrationDeepLink". This URL must be opened on the person's mobile device, where they will be guided through the registration process directly in the DeepID mobile application. Typically, the returned DeepID registration URL, would be displayed as a QR-code, that can be scanned on the person's mobile device, and the registration process can be started on the mobile device.

curl -X POST --location "https://deepgateway.deepcloud.swiss/api/v1/persons/status" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \
  -H "Content-Type: application/json" \
  -d '{"personRef": "my-company-application-test.person@abacus.ch"}'

POST /api/v1/persons/status HTTP/1.1
Content-Length: 372
Host: deepgateway.deepcloud.swiss
User-Agent: Java-http-client/11.0.14.1
Accept-Charset: UTF-8
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ
Content-Type: application/json

{
   "personRef": "my-company-application-test.person@abacus.ch"
}

The status of an existing or a new registration can be polled with the following URL.

HTTP Requests

POST https://deepgateway.deepcloud.swiss/api/v1/persons/status

Swagger Reference

POSThttps://deepgateway.deepcloud.swiss/swagger/index.html#/status/post-status

If the person is not registered in DeepID, then "isRegistered" will be false.

When the person with the specified personRef is registered in DeepID then the "personIdentityUid" will be returned:

{
  "isRegistered": true,
  "personIdentityUid": "6b9206e0-2ede-42ab-913b-7ba6d475778e"
}

Webhook Callbacks

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();

      String requestContent = "{\"initiatorAliasName\":\"Mr. Tester\",\"comment\":\"Please sign the PDF file\"," +
        "\"signatureMode\":\"timestamp\",\"jurisdiction\": \"zertes\",\"callbackEventTypes\": [\"signee-completed\",\"document-completed\"]," +
        "\"callbackUrl\":\"https://some-self-define-uri.org/deepservice/deepsign_events.html\"," +
        "\"callbackSecret\":\"DBFF5B904FFA4EEF9CE03597D0664822\"}";

      // Example code for PUT https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a
      HttpRequest request = HttpRequest.newBuilder()
          .PUT(HttpRequest.BodyPublishers.ofString(requestContent))
          .uri(URI.create("https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a"))
          .setHeader("Accept-Charset", "UTF-8")
          .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
          .setHeader("Content-Type", "application/json")
          .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
        ge.printStackTrace();
    }
  }
}

public async void simplePostRequestExample()
{
    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a";
    String requestContent = "{\"initiatorAliasName\":\"Mr. Tester\",\"comment\":\"Please sign the PDF file\"," + 
        "\"signatureMode\":\"timestamp\",\"jurisdiction\": \"zertes\",\"callbackEventTypes\": [\"signee-completed\",\"document-completed\"]," +
        "\"callbackUrl\":\"https://some-self-define-uri.org/deepservice/deepsign_events.html\"," + 
        "\"callbackSecret\":\"DBFF5B904FFA4EEF9CE03597D0664822\"}";

    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");
    requestHttpHeaders.Add("Accept", "application/json");
    requestHttpHeaders.Add("Accept-Charset", "UTF-8");

    // Example code for PUT https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a
    StringContent scData = new StringContent(requestContent, Encoding.UTF8, "application/json");
    HttpResponseMessage response = await httpClient.PutAsync(requestUrl, scData, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -X PUT --location "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \
  -H "Content-Type: application/json" \
  -d '{"initiatorAliasName":"Mr. Tester","comment":"Please sign the PDF file","signatureMode": "timestamp", \
        "jurisdiction": "zertes","callbackEventTypes": ["signee-completed","document-completed"], \
        "callbackUrl": "https://some-self-define-uri.org/deepservice/deepsign_events.html", \
        "callbackSecret": "DBFF5B904FFA4EEF9CE03597D0664822"}'

PUT /api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a HTTP/1.1
Content-Length: 372
Host: api.sign.deepbox.swiss
User-Agent: Java-http-client/11.0.14.1
Accept-Charset: UTF-8
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ
Content-Type: application/json

{
  "initiatorAliasName": "Mr. Tester",
  "comment": "Please sign the PDF file",
  "signatureMode": "timestamp",
  "jurisdiction": "zertes",
  "callbackEventTypes": [
        "signee-completed",
        "document-completed"
        ],
  "callbackUrl": "https://some-self-define-uri.org/deepservice/deepsign_events.html",
  "callbackSecret": "DBFF5B904FFA4EEF9CE03597D0664822"
}

The above request returns an empty response with HTTP 204 No Content
HTTP/1.1 204 No Content

When a document is uploaded to DeepSign, or the document is updated, the JSON data structure allows callback-Urls to be configured. The configured callback-Urls must be accessible to DeepCloud, therefore it is generally required that callback-Urls are used together with a Web-Based-Solution.

The following endpoints can be used to configure the callback-Urls and events.

HTTP Requests

POST https://api.sign.deepbox.swiss/api/v1/documents/file

PUT https://api.sign.deepbox.swiss/api/v1/documents/{documentId}

Swagger Reference

POST/api/v1/documents/file

PUT/api/v1/documents/{documentId}

The JSON structures for the Upload document and the Update document both contain the following 3 parameters.

Parameter	Description
callbackEventTypes	The event type array with "signee-completed" and/or "document-completed"
callbackUrl	A callback-Url that is accessible to DeepCloud
callbackSecret	A self defined unique secret used for the SHA-256 message encryption

Example data JSON structure for the update can be seen in the examples on the right

Note: The callback parameters can be set, but will not be exported with the document details.

The possible callback events contain the following 2 values.

Event Type	Event
signee-completed	A signee has signed the document
document-completed	The document has been completely signed by all signees

The "callbackUrl" is a self-defined URI that will be called by the DeepCloud/DeepSign in response the specified event types. e.g. "https://some-self-define-uri.org/deepservice/deepsign_events.html",

Documents that are rejected or withdrawn, will also trigger the "document-completed" event. The document status can be retrieved via the available document endpoints.

The encrypted signature is sent in the HTTP headers for the POST request with "X_DEEPSIGN_SIGNATURE_256".
For example:
X_DEEPSIGN_SIGNATURE_256: a730cece29e161139ed9ace74ae036b5a1b28de5f8a2105968ee1ce3a378c358

Example of content sent for a "signee-completed" event
{"eventType":"signee-completed","documentId":"bb602c43-caae-4656-a447-233b2317b14a","signeeId":"56f16b80-0058-44d8-bf33-2847612b24b1","timestamp":"2023-05-16T14:24:42.033+00:00"}

Example of content sent for a "document-completed" event
{"eventType":"document-completed","documentId":"bb602c43-caae-4656-a447-233b2317b14a","timestamp":"2023-05-16T14:24:42.041+00:00"}

POST /deepservice/deepsign_events.html HTTP/1.1
Host: some-self-define-uri.org
Accept-Charset: UTF-8
X_DEEPSIGN_SIGNATURE_256: a730cece29e161139ed9ace74ae036b5a1b28de5f8a2105968ee1ce3a378c358
Content-Type: application/json

{
   "eventType":"document-completed",
   "documentId":"bb602c43-caae-4656-a447-233b2317b14a",
   "timestamp":"2023-05-16T14:24:42.041+00:00"
}

Example PHP Script to verify signature with SHA-256 encryption :

// The callback secret set for a particular documentId must be available for the callback-Url $callbackSecret = "DBFF5B904FFA4EEF9CE03597D0664822"; $deepsignSignature = $_SERVER['HTTP_X_DEEPSIGN_SIGNATURE_256']; // The request body content is extracted from the POST call to the callback-Url $requestBodyContent = "{\"eventType\":\"document-completed\"," . "\"documentId\":\"bb602c43-caae-4656-a447-233b2317b14a\"," . "\"timestamp\":\"2023-05-16T14:24:42.041+00:00\"}"; $calculatedSignature = hash_hmac("SHA256", $requestBodyContent, $callbackSecret, false); $isValidatedWithSecret = strcmp($calculatedSignature, $deepsignSignature) == 0;

The "callbackSecret" is a unique string (e.g. "DBFF5B904FFA4EEF9CE03597D0664822") that will be used with the SHA-256 encryption to verify the callback-URL. A callback secret can be configured per document, but the secret must be known at the time of the callback event, in order to successfully verify the callback event using the SHA-256 encryption.

Document Access URL

class Example {

  private HttpClient mHttpClient = null;

  private HttpClient getHttpClient() {
    if ( mHttpClient == null ) {
      mHttpClient = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    }
    return mHttpClient;
  }

  public void main(String[] args) {
    try {
      HttpClient httpClient = getHttpClient();

      String requestContent = "";

      // Example code for POST https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/document-access-url
      HttpRequest request = HttpRequest.newBuilder()
          .POST(HttpRequest.BodyPublishers.ofString(requestContent))
          .uri(URI.create("https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/document-access-url"))
          .setHeader("Accept-Charset", "UTF-8")
          .setHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ")
          .build();

      HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

      // The Response headers can sometimes contain certain error states
      HttpHeaders headers = response.headers();
      if ( headers != null ) {
        headers.map().forEach((key, val) -> {
          System.out.println(key + ":" + val);
        });
      }

      // The HTTP Response Status code
      int httpResponseCode = response.statusCode();

      // Echo response body
      System.out.println(response.body());
    } catch(IOException | InterruptedException ge) {
        ge.printStackTrace();
    }
  }
}

public async void simplePostRequestExample()
{
    String requestUrl = "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/document-access-url";
    String requestContent = "";

    HttpClient httpClient = new HttpClient();

    HttpRequestHeaders requestHttpHeaders = httpClient.DefaultRequestHeaders;
    requestHttpHeaders.Add("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ");
    requestHttpHeaders.Add("Accept", "application/json");
    requestHttpHeaders.Add("Accept-Charset", "UTF-8");

    // Example code for POST https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/document-access-url
    StringContent scData = new StringContent(requestContent, Encoding.UTF8, "application/json");
    HttpResponseMessage response = await httpClient.PostAsync(requestUrl, scData, CancellationToken.None);

    // The Response headers can sometimes contain certain error states
    HttpResponseHeaders httpResponseHeaders = response.Headers;
    foreach (var headerItem in httpResponseHeaders)
    {
        string headerName = headerItem.Key;
        string headerContent = string.Join(",", headerItem.Value.ToArray());
        System.Diagnostics.Debug.WriteLine("      HEADER [" + headerName + "] : " + headerContent);
    }

    String responseResult = "";

    // The HTTP Response Status code
    HttpStatusCode httpResponseCode = response.StatusCode;
    if (response.IsSuccessStatusCode)
    {
        responseResult = await response.Content.ReadAsStringAsync();
    }
    else
    {
        responseResult = String.Format("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }

    response.Dispose();

    System.Diagnostics.Debug.WriteLine(responseResult);
}

curl -X POST --location "https://api.sign.deepbox.swiss/api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/document-access-url" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ" \
  -d ''

POST /api/v1/documents/bb602c43-caae-4656-a447-233b2317b14a/document-access-url HTTP/1.1
Content-Length: 0
Host: api.sign.deepbox.swiss
User-Agent: Java-http-client/11.0.14.1
Accept-Charset: UTF-8
Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...[abbreviated for display]...PsdqNfifKC9r5JKVoQ

The above request returns the DeepSign URL like this:

https://sign.deepbox.swiss/document-access#L5BVbRY7RPquf5f1gsL...[abbreviated for display]...OSNrRV_UnY8mi-CdQA78gS3iPyNXA

The returned URL can be used to open the document in the DeepSign Application in the Internet Browser

The Document Access URL allows the document to be opened in the DeepSign Application and used as an editor for document. The user does not need to login, but has full control of the signature process. The URL is issued by service user, by calling the following endpoint

HTTP Request

POST https://api.sign.deepbox.swiss/api/v1/documents/{documentId}/document-access-url

The document-access-url returns an URL, that can be used to open the DeepSign document in the Internet Browser. The document can then be configured further manually (e.g. place signature positions, add signees, etc) and visually checked, before starting the signing process from the DeepSign Application

Errors

The DeepCloud API uses the following error codes:

HTTP Code	Error	Meaning
400	Bad Request	Your request is invalid.
401	Unauthorized	Your API "access_token" is wrong.
403	Forbidden	The request is not allowed.
404	Not Found	No data could not be found.
405	Method Not Allowed	The method call is invalid.
408	Request Timeout	The request has taken too long.
429	Too Many Requests	Too many requests within a given time interval.
500	Internal Server Error	There was a problem with the server. Try again later.
503	Service Unavailable	Temporarily offline for maintenance. Please try again later.
504	Gateway Timeout	The server gateway or proxy, did not response within a specified time. Please try again later.

Error Message Patterns

The following sections list some typical error messages to show the various error data structures that can occur in the DeepCloud environment.

Typically, an error message can contain the following properties :

"timestamp" - the time and data of the error
"status" - the HTTP status code
"error" - the HTTP status text
"message" - additional single text message or multiple text messages as an array of text messages
"type" - the type of error
"title" - error message title
"detail" - further details of the error messages.
"instance" - normally the URL instance of the called endpoint
"messageId" - a message Id to identify the error message.
"error_description" - description for the error message.

Depending on the type of error message, some of these fields may, or may not, be present in the error response.

Generic errors

This error structure represents a basic message structure used for many types of error formatting

Generic error

{
  "timestamp": "2024-05-08T07:39:42.603+00:00",
  "status": 403,
  "error": "Forbidden",
  "message": "create deepbox transient resource failed. (api access to box denied for null)"
}

The message can also contain a "messageId"

Generic error with messageId

{
  "messageId": "error.pdf.password.protected",
  "timestamp": "2024-05-08T07:41:36.266+00:00",
  "status": 400,
  "error": "Bad Request",
  "message": "pdf is password protected"
}

Web error

This type of error message would be returned, for example, if an incorrect URL Endpoint is called.

Web Error:

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "No static resource api/v1/documentsaaa/deepbox.",
  "instance": "/api/v1/documentsaaa/deepbox"
}

Validation error

This type of error message would be returned, for example, if a request is called with missing or incorrect data structure properties.

Validation error:

{
  "timestamp": "2024-05-08T07:31:50.396+00:00",
  "status": 400,
  "error": "Bad Request",
  "message": [
    "deepboxDocumentId: must not be null"
  ]
}

DeepCloud error

This type of error message would be returned from the DeepCloud authorization URL, for example, if a request is called with missing or incorrect data structure properties.

DeepCloud error:

{
  "error":"invalid_request",
  "error_description":"Missing form parameter: grant_type"
}

Special cases

Some errors may not have a response body. For example 401 Unauthorized would just return a HTTP Code 401, with not further error message in the response body.

Example Web Errors

Media Type wrong

Returned if the requested media type is not supported

Media Type wrong

{
  "type": "about:blank",
  "title": "Unsupported Media Type",
  "status": 415,
  "detail": "Content-Type 'text/plain' is not supported.",
  "instance": "/api/v1/documents/deepbox"
}

Requested URL does not exist

The requested URL does not exist or the called HTTP method is not supported

Requested URL does not exist

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "No static resource api/v1/documentsaaa/deepbox.",
  "instance": "/api/v1/documentsaaa/deepbox"
}

or requested HTTP Method is not supported

{
  "type": "about:blank",
  "title": "Method Not Allowed",
  "status": 405,
  "detail": "Method 'POST' is not supported.",
  "instance": "/api/v1/documents/deepboxa"
}

Validation errors

This type of error message would be returned, for example, if a request is called with missing or incorrect data structure properties.

Generic errors

A typical generic error message data structure

Generic errors

{
  "timestamp": "2024-05-08T07:39:42.603+00:00",
  "status": 403,
  "error": "Forbidden",
  "message": "create deepbox transient resource failed. (api access to box denied for null)"
}

UUID in request body is incorrect

Returned if a reference UUID is incorrect or missing in the request body

UUID in request body is incorrect

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Failed to read request",
  "instance": "/api/v1/documents/deepbox"
}

UUID in the called URL is incorrect

Returned if a called URL contains an incorrect reference UUID

UUID in the called URL is incorrect

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Failed to convert 'documentId' with value: 'aaa4f83384a-c438-4900-979b-cad06cbb819d'",
  "instance": "/api/v1/documents/aaa4f83384a-c438-4900-979b-cad06cbb819d"
}

Variable in request body is required and not defined or is null

Returned if required properties are missing or not defined in the request data structure

Variable in request body is required and not defined or is null

{
  "timestamp": "2024-05-08T07:31:50.396+00:00",
  "status": 400,
  "error": "Bad Request",
  "message": [
    "deepboxDocumentId: must not be null"
  ]
}

With messageId

The response message structure contains the "messageId" property

Error message with messageId

{
  "messageId": "error.pdf.password.protected",
  "timestamp": "2024-05-08T07:41:36.266+00:00",
  "status": 400,
  "error": "Bad Request",
  "message": "pdf is password protected"
}