Skip to content

Your first signing - tutorial

Introduction

So, you need to integrate your product with Addo Sign. Good!

This guide will show you how to get started. It assumes the following:

  • You have already created an access token for the API (Howto).
  • An Advanced Signing template has been created in Addo Sign.
  • The user owning the access token can access the template to be used. F.ex. put the user in the same group as the template.
  • To keep it simple, it will be one recipient signing one file.
  • We will do this in the Addo Sign demo environment. For production, strip the [demo.]-part of the URLs.

Bearer token

Whenever you access the Addo Sign API you must add the following HTTP header to your request:

Authorization: Bearer your-token-from-your-profile-page

Template

The template used in this guide is laid out as follows:

Template, part1

Notes! The number highlighted in green in the upper right corner is the Template ID. You will use the Template ID in the Create Signing API method

This template is setup so that the recipient will be notifed by e-mail, sign with a touchscreen signature and the recipient will get a download link to the signed file when the process completes.

Template, part2

Notes! This is the simplest setup for an Advanced Signing template. It has no Signer Roles or Filegroups. Everything will be supplied when we call Create Signing.

Tutorial Data

For this tutorial we will assume:

  1. One recipient.
  2. One file to sign.
  3. The recipient is Brian (with the attributes listed below), placed in the first recipient group (with ID #1).
  4. The file to sign is called BlankPage.pdf placed in the first file group (with ID #1).

Upload the file to be signed

The first thing to be done is to transfer the file to be signed to Addo Sign. The file must be a valid PDF-file and it must either be a non-PDF/A file or, if a PDF/A file, version A-3 or better.

To upload the file, send the file as a POST-request to:

https://demo.addosign.net/api/v1/uploads

The Content-Type must be set to multipart/form-data. The formfile parameter must be the actual file to upload.

The Addo Sign API will respond with:

{
    "fileId": "38bb4147-5487-4e8f-b74b-4b41c6f075e2",
    "name": "BlankPage.pdf",
    "contentType": "application/pdf"
}

For the Postman-users among us, it will look like this:

Postman, file upload

Pay attention to the fileId. This will be used in the next call when creating the signing.

Create the signing

To create the signing, POST the request json to:

https://demo.addosign.net/api/v1/signing-templates/351097/signings

That strange number, 351097, is our Template ID as discussed above.

When a signing is created, Addo Sign will:

  1. Create an empty signing with default values.
  2. Then overwrite with template values.
  3. And then merge in what you send in your request body.

So, send only what you need to overwrite.

The full (minimal) JSON to POST is presented below in all it's glory - below the JSON a discussion of the properties will follow:

{
  "stages": [{
    "fileGroups": [{
      "fileGroupId": 1,
      "recipientGroupIds": [ 1 ]
    }]
  }],
  "files": [{
    "id": 1,
    "isSigningRequired": true,
    "fileGroupId": 1,
    "storageId": "38bb4147-5487-4e8f-b74b-4b41c6f075e2"
  }],
  "recipientGroups": [{
    "id": 1,
    "name": "Special People"
  }],
  "fileGroups": [{
    "id": 1,
    "name": "Contracts"
  }],
  "recipients": [{
    "id": 1,
    "name": "Brian Schau",
    "email": "brian.schau@xxx",
    "recipientGroupId": 1
  }] 
}

Visually, in Addo Sign, this is how our signing looks like:

Overview

So, we have one Filegroup (ID #1, "Contracts") in one Step (as set in the stages property above). This Filegroup must be signed by the Recipientgroup (ID #1, "Special People"). This Recipientgroup contains one Recipient (ID #1, "Brian Schau").

The stages property is a multidimensional array containing along the Y-axis the Filegroups and along the X-axis the various Steps.

Each (x, y)-cell contains one or more Recipientgroups each containing one or more Recipients.

The files property contains links (by means of the storageId) to all the files in this signing. A file can only be in one Filegroup and you cannot share their storageId. The isSigningRequired controls if the file must be signed or if it is a non-signable attachment.

The recipientGroups property defines the Recipientgroups. Not shown here, is that each group takes an order property to give some basic ranking before the group. Lower numbers bubble to the top.

The fileGroups property defines the Filegroups much the same way as Recipientgroups for recipients. It too have an order property.

Last we have the recipients property. This is where all the recipients goes.

The result of the above Create Signing request was:

{
    "token": "4323756c-5ed3-4144-9fd0-b0d97462a186",
    "id": 5131
}

Fetch the signed file

When the signing completes, it will be time to fetch the signed file.

Use the Download Signing File method for that. It's a GET-request:

https://demo.addosign.net/api/v1/signings/5131/files/38bb4147-5487-4e8f-b74b-4b41c6f075e2/data

The two numbers are:

  • 5131: the id from the response to the Create Signing method (as seen above), and
  • 38bb4147-5487-4e8f-b74b-4b41c6f075e2: the fileId from the response to the Upload File method.

You can only download the signed file when the signing has completed. To get signing details use the Get Signing Details method. It's a GET-request:

https://demo.addosign.net/api/v1/signings/5131

(Pssst! 5131 is the id mention above).

You will get a lot of details from this call. When the signing has completed it's state will be 3.

Another way to learn about when the signing has completed is by listening to a callback from us. Add to the root of your request:

"callbacks": [{
  "url": "https://google.com",
  "type": 1
}]

The "type": 1 is the Distribution (former Completed) callback. When Addo Sign is about to send out the signed file we will call you instead. And then you just fetch the file as described above.

Sender Information

When Addo Sign sends out an e-mail to the recipient the sender will be set to the user sending the signing.

If you want to override that, you can add senderDetails to the root of your request:

"senderDetails": {
  "name": "John Doe",
  "companyName": "The Good Hearted Company",
  "email": "johnd@localhost",
  "phone": "+4512345678"
}

Please note, the email above is purely for presentation purposes. The actual e-mail will be no-reply@addosign.net.

Everything in one file

Expanded, just as JSONlint would do it:

{
  "senderDetails": {
    "name": "John Doe",
    "companyName": "The Good Hearted Company",
    "email": "johnd@localhost",
    "phone": "+4512345678"
  },
  "files": [
    {
      "id": 1,
      "isSigningRequired": true,
      "fileGroupId": 1,
      "storageId": "38bb4147-5487-4e8f-b74b-4b41c6f075e2"
    }
  ],
  "recipientGroups": [
    {
      "id": 1,
      "name": "Signers"
    }
  ],
  "fileGroups": [
    {
      "id": 1,
      "name": "Contracts"
    }
  ],
  "stages": [
    {
      "fileGroups": [
        {
          "fileGroupId": 1,
          "recipientGroupIds": [
            1
          ]
        }
      ]
    }
  ],
  "recipients": [
    {
      "id": 1,
      "pin": "1234567890",
      "name": "Brian Schau",
      "email": "brian.schau@xxx",
      "recipientGroupId": 1
    }
  ],
  "callbacks": [
    {
      "url": "https://google.com",
      "type": 1
    }
  ] 
}