Digital Signing API

The Digital Signing API creates signing orders from your own system and follows them until the documents are signed. For the application, read Digital Signing.

Every call needs a bearer token, see Authentication, and a company that has the signing licence. The orders belong to your own company.

https://api.digitalsigning.metaforce.net/DigitalSigningOrders

Property names in requests and responses are written in camel case, for example packageName.

Check before you create

GET /DigitalSigningOrders/GetCreateOrderInitialData/{langCode} returns what you need to prepare an order. langCode is optional and picks the language of the default texts. The response has:

Create an order

POST /DigitalSigningOrders takes a JSON body.

Each signatory has:

{
    "packageName": "Employment contract, Ingrid Berg",
    "language": "en",
    "emailNotificationSubject": "Please sign your employment contract",
    "emailNotificationMessage": "Hi Ingrid, your employment contract is ready to sign.",
    "signingNotificationTitle": "Employment contract",
    "signingNotificationMessage": "Read the contract and sign it.",
    "signatories": [
        {
            "emailAddress": "ingrid.berg@example.com",
            "firstName": "Ingrid",
            "lastName": "Berg",
            "signingSequence": "Initial",
            "signUrl": ""
        }
    ],
    "signingOrderFiles": [
        { "name": "contract.pdf", "fileContent": "JVBERi0xLjQK..." }
    ],
    "completedWebhookUrl": "https://example.com/signing/completed"
}

A request that misses a required field is answered with 400. The call answers 200 when the request is valid, so read the body. It has data, type and message. type is 0 when the order was created, 1 when it could not be created and 2 when the licence stopped it. On success, data holds the order and its id.

These messages can come back:

Follow an order

An order has a status. In responses it is a number:

Each signatory has a signStatus as well, and a signingSequence (0 for Initial, 1 for DependsOnInitial, 2 for NoOrder). The sign status goes from not set (0) and created (1) through started (2) to completed (3), rejected (4), expired (5), forwarded (6) or canceled (7).

Get the files

A file that does not exist is answered with 404.

Remind, cancel and delete

• GET /DigitalSigningOrders/SendReminders/{orderId} sends an email to every signatory who has not signed yet.
• DELETE /DigitalSigningOrders/{orderId} cancels the order.
• DELETE /DigitalSigningOrders/DeleteOrder/{orderId} deletes the order.

Each of these answers true or false in the body.

Webhooks

When the order is completed, Doc Gen calls completedWebhookUrl. When it is cancelled, Doc Gen calls cancelledWebhookUrl. The call is a GET without a body, so use it as a signal and then fetch the order with GET /DigitalSigningOrders/{id}. If Doc Gen cannot reach the URL, it tries again, up to four attempts in all, about half a second apart. An answer with an error status is not tried again.

Example

const axios = require('axios').default;

async function createOrder(accessToken) {
  const response = await axios({
      method: 'POST',
      url: 'https://api.digitalsigning.metaforce.net/DigitalSigningOrders',
      headers: {
          'content-type': 'application/json',
          'Authorization': `Bearer ${accessToken}`
      },
      data: {
          packageName: 'Employment contract, Ingrid Berg',
          language: 'en',
          emailNotificationSubject: 'Please sign your employment contract',
          emailNotificationMessage: 'Hi Ingrid, your employment contract is ready to sign.',
          signingNotificationTitle: 'Employment contract',
          signingNotificationMessage: 'Read the contract and sign it.',
          signatories: [
              { emailAddress: 'ingrid.berg@example.com', firstName: 'Ingrid', lastName: 'Berg', signUrl: '' }
          ],
          signingOrderFiles: [
              { name: 'contract.pdf', fileContent: '<base64 of the PDF>' }
          ]
      }
  });
  console.log(response.data.type, response.data.message);
}