CM Sign

Introduction

CM Sign offers the ability to have end users sign PDF documents online. You can use the CM webapplication or if you want a more complete integration with your own systems you can request access to our API.

Before starting integration of CM Sign into your services, we advise you to read our implementation guide. This guide can be used for a step-by-step implementation of CM Sign.

Download: implementation guide (PDF)

For a full API specification with parameter formats, a Swagger specification is available.

If you need technical assistance, please contact support@cmdisp.com.

Authentication

Before you can start using the API, you need to be provided with credentials. You will have received these credentials, consisting of a Key and a Key Id, when you registered for CM Sign. If you have not yet received any credentials, you can request them via this link.

The credentials provided by CM are confidential and should be kept secret.

In order to authenticate you need to use your credentials to generate a JWT Bearer token. The JWT token has to be generated using the HS256 algorithm and your credentials. This JWT has to contain the usual attributes like iat, nbf, exp in the payload, as well as the attribute kid in the header of the JWT. This kid attribute needs to contain the Key Id of your credentials.

The generated token needs to be passed via the HTTP Authorization header like:

Authorization: Bearer GENERATED_TOKEN

Making requests

All requests require authentication. Almost all requests, with the exception of file uploads, are JSON requests and responses. So be sure to set the Content-Type of your HTTP requests to application/json.

Select your server

CM Sign provides two environments for you to work with:

The sandbox environment is ideally suited to do your initial experimentation with. Unlike the production environment, it doesn't add a cryptographic signature to the document and you will not be billed for using this environment.

Service description

CM Sign offers the ability to have end users sign PDF documents online. The steps for using the service are roughly:

  1. Upload a PDF document that needs to be signed
  2. Create a dossier which references this document. A dossier includes information about the end users who need to sign the document, as well as the location within the PDF document where they need to place their signature and initials.
  3. Create an invitation URL for each invitee to sign the document
  4. The end user is directed to the invitation URL
  5. The end user is presented a web interface where he can read and sign the document
  6. The dossier owner is notified of the completion of the dossier
  7. The dossier owner downloads the signed document and audit log

Dossiers

A dossier is a collection of information related to the signing process of a document. Dossiers consist of:

  • Documents (files): the PDF document to be signed
  • Invitees: the persons who have to sign the dossier (see 2.2)
  • Owners (optional): the contact person, who will be informed about status updates of the dossier. If set, the owner's name will be used in communication to the invitees, otherwise the organisation name is used instead.

A dossier automatically expires after 30 days by default, this can be customised when creating the dossier (with a maximum of 90 days).

Invitees

Invitees are persons asked by the customer to sign a specific dossier. An invitee has:

  • Fields: locations within a PDF document for information to be added (see 2.3)
  • Name (optional): the name that will be used in communication to address the invitee
  • Email (optional): the email address that will be used to notify the invitee about this dossier and send the signed document
  • Reference (optional): allows the invitee it to be linked to an ID known within your organisation

Fields

Fields are locations within a PDF document where information will be added. Fields belong to a specific file and invitee and have parameters to configure its position(s) in the document.

The following field types are supported:

  • Signature: the invitee is asked for a signature
  • Signature date: the date the invitee signed the document, automatically determined
  • Initials: the invitee is asked for its initials. Initials can be specified for a page range and the invitee has to confirm its initials each page.
  • Text: a text field that can be filled in by the invitee
  • Label: a text field that contains a predefined text and cannot be modified

Invites

An invite is a unique URL for each invitee to view the dossier. CM Sign can email these invites to the invitees or you can distribute the URL yourself, for example by redirecting or sending customised emails yourself.

An invite can have a custom expiration time, specified during creation. Creating multiple invites for an invitee is possible and this might be required if an invite expires before the invitee signed the document.

Uploading a file

Every dossier is started with at least one file and the first step is therefore to upload your PDF.

POST https://api.cmdisp.com/sign/v1/upload

Request

file=<binary>

This is a multipart/form request where the file parameter is the key for the file to be uploaded. The result of this request will be a JSON response containing a description of the file as registered within CM Sign. The most important attribute in this response is the id. This id is the unique identifier for this file and you will have to pass it along when you create your actual dossier.

Response:

{
  "id": "8d817359-7eb8-4b6e-9030-17ac286b7dc0",
  "name": "Purchase contract 2018 v12.pdf",
  "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "uploadDateTime": "2018-11-02T12:51:56.638Z",
  "contentType": "application/pdf"
}

Creating your dossier

A dossier is the primary container for all your interactions for signing documents. It contains the file to be signed, the people (invitees) who will be invited to view and or sign the document, etc etc.

In order to create a dossier you post a JSON object describing the request to the /dossiers/ endpoint

Now you can create an entire dossier in one go. You create a dossier by listing the id of your file in the files array object. You will also need to add invitees. Invitees are the persons that will have to sign the document.

Each invitee can have one or more fields. Fields are locations in the document where this invitee will have to sign the document.

POST https://api.cmdisp.com/sign/v1/dossiers

Request:

{
  "name": "2018 Purchase contract",
  "files": [
    {
      "id": "8d817359-7eb8-4b6e-9030-17ac286b7dc0",
    }
  ],
  "invitees": [
    {
      "name": "Peter Invited",
      "email": "user@example.com",
      "reference": "6c38955e-7324-41e7-97dd-0bcf55e275e2",
      "fields": [
        {
          "type": "initials",
          "file": "8d817359-7eb8-4b6e-9030-17ac286b7dc0",
          "range": "1-3",
          "dimensions": {
            "origin": {
              "x": 0,
              "y": 0
            },
            "size": {
              "width": 0,
              "height": 0
            }
          }
        },
        {
          "type": "signature",
          "file": "8d817359-7eb8-4b6e-9030-17ac286b7dc0",
          "tag": "{signature1}"
        }
      ]
    }
  ]
}

For each field, you have to pass the Id of the file on which the field will be placed. The dimensions of fields are specified as a floating number between 0 and 1 relative to the page. The coordinates are from top-left to bottom-right. Next to supplying dimensions, the dimensions can also be automatically determined based on a tag. The tag acts as a placeholder; the range and dimensions of the field will be determined based on the location(s) of the tag in the document. Add the tag to every page the field should include in case of initials. The tag should be hidden, for example by making it white.

Response:

{
  "id": "22470767-904e-4553-9586-d7ed4f2b330e",
  "name": "2018 Purchase contract",
  "state": "draft",
  "locale": "nl-NL",
  "completed": false,
  "expiresIn": 2592000,
  "expiresAt": "2018-11-02T12:53:45.504Z",
  "createdAt": "2018-11-02T12:53:45.504Z",
  "owners": [
    {
      "id": "c2b0ff41-f97a-421d-a4eb-85b158a2de2a",
      "name": "Mike Dossierowner",
      "email": "user@example.com"
    }
  ],
  "files": [
    {
      "id": "8d817359-7eb8-4b6e-9030-17ac286b7dc0",
      "name": "Purchase contract 2018 v12.pdf",
      "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "uploadDateTime": "2018-11-02T12:53:45.504Z",
      "contentType": "application/pdf"
    }
  ],
  "invitees": [
    {
      "id": "c6f7eb6f-7414-4f5e-9096-85c6c5a48f84",
      "name": "Peter Invited",
      "email": "user@example.com",
      "reference": "6c38955e-7324-41e7-97dd-0bcf55e275e2",
      "fields": [
        {
          "id": "50ee1534-6172-4228-84e8-653c6f65eaf0",
          "type": "initials",
          "file": "8d817359-7eb8-4b6e-9030-17ac286b7dc0",
          "tag": null,
          "range": "1-3",
          "dimensions": {
            "origin": {
              "x": 0,
              "y": 0
            },
            "size": {
              "width": 0,
              "height": 0
            }
          },
          "invitee": "c6f7eb6f-7414-4f5e-9096-85c6c5a48f84"
        },
        {
          "id": "50ee1534-6172-4228-84e8-653c6f65eaf0",
          "type": "signature",
          "file": "8d817359-7eb8-4b6e-9030-17ac286b7dc0",
          "tag": "{signature1}",
          "range": "3",
          "dimensions": {
            "origin": {
              "x": 0.1296,
              "y": 0.4939
            },
            "size": {
              "width": 0.2522,
              "height": 0.0594
            }
          },
          "invitee": "c6f7eb6f-7414-4f5e-9096-85c6c5a48f84"
        }
      ]
    }
  ]
}

This response again contains an id attribute and this will be your dossierId. With the dossierId you can access and modify this new dossier.

Creating invites

Once you have a complete dossier, you will have to send out a link to the invitees who will have to sign these documents. For this, you will have to create an invite link for each invitee who has to sign. Invite links are created by POSTing to the /invites endpoint of your dossier.

Post an JSON object containing the attribute inviteeId with the value of the id of the invitee for who you want to create an invite for. If you set email to true, CM Sign will automatically and immediately send out an email to the user with this link.

POST https://api.cmdisp.com/sign/v1/dossiers/{dossierId}/invites

Request:

[
  {
    "inviteeId": "c6f7eb6f-7414-4f5e-9096-85c6c5a48f84",
    "email": false,
    "expiresIn": 2592000
  }
]

Links have an expiration time which is configurable in seconds, the default is 30 days. If you don't set the email option, the link can be retrieved from the response of your request.

Response:

[
  {
    "id": "730c6ec8-755b-450f-9ab6-f57111ab1d93",
    "inviteeId": "c6f7eb6f-7414-4f5e-9096-85c6c5a48f84",
    "inviteUri": "https://sign.cmdisp.com/en/invites/fjDKGjSXeKSmZbH5zKDjuPmpQqoMZDfAAr7iZuXd4e8pIubzP5FwBm4Y28dwXG8zEHk",
    "expiresIn": 2592000,
    "expiresAt": "2018-11-02T12:51:56.611Z",
    "createdAt": "2018-11-02T12:51:56.611Z"
  }
]

Retrieving the signed dossier

Once the dossier is signed, you can download a zip file containing the complete result of a dossier. The zip file includes the signed documents and audit log, stating all info and events related to the dossier for evidence purposes.

GET https://api.cmdisp.com/sign/v1/dossiers/{dossierId}/download

Error Handling

When an error occurs, you will receive a JSON message describing the error. Please make sure to handle these errors.

{
  "status": 400,
  "message": "Error message"
}

Swagger API docs

For a complete technical documentation with specifications for all field types, JSON objects and methods, you can consult our complete swagger specification.

Swagger API docs