Signature API

The Signature API creates and follows signing orders from your own system. It does what the Digital Signing Creator and Orders do in the application: send PDF files to signers, read the status, remind, stop and delete orders, and download the result.

The API runs on api.digitalsigning.metaforce.net. This page describes the calls, the fields you send and the responses you get back.

Authentication

Use an API client and a bearer token, as described in Authentication. Your company needs a Signature licence, or every call is refused.

Create an order

Send a POST to /DigitalSigningOrders with a JSON body:

curl -X POST "https://api.digitalsigning.metaforce.net/DigitalSigningOrders" \
-H "Authorization: Bearer <access token>" \
-H "Content-Type: application/json" \
-d '{
  "packageName": "Service agreement",
  "language": "en",
  "useSignatureOrder": false,
  "distributeSignedDocumentToAllSignatories": true,
  "signingOrderFiles": [
    { "name": "Service agreement.pdf", "fileContent": "<PDF file as base64>" }
  ],
  "signatories": [
    { "emailAddress": "kari.nordmann@example.com", "signingSequence": 2 }
  ],
  "signingNotificationTitle": "Document to be signed - [DOCUMENTNAME]",
  "signingNotificationMessage": "Please sign the agreement.",
  "emailNotificationSubject": "Document to be signed - [DOCUMENTNAME]",
  "emailNotificationMessage": "Please sign here: [SIGN-URL]"
}'

The title, message and subject fields are required, and they follow the same rules as in the application. See Create a signing order.

Each signer takes these fields:

The response

A successful call returns 200 with the order in data and type set to 0:

{ "data": { "id": "<order id>" }, "type": 0, "message": null }

Keep the id. Every other call uses it. The order in data also lists the signers in signatories, each with signUrl, the personal link that opens the signing page. With Scrive, signUrl is filled in only for signers sent with signViaUrl. Save the links you need from this response: GET /{id} does not return them. When the provider or the licence stops the order, the call still returns 200, but type is 1 (failure) or 2 (warning) and message says why:

A body that breaks a rule, such as more than 10 files or a missing subject, returns 400 with the field and the reason.

Follow and act on orders

All paths start at https://api.digitalsigning.metaforce.net/DigitalSigningOrders.

GET /Activities is at https://api.digitalsigning.metaforce.net/Activities and returns the five most recently changed orders of your company, the same as Your latest activity in the application. Each item has id, packageName, totalSignatories, signedSignatories, numOfDocuments, status (the same values as orderStatus below) and updatedDate.

The list does not filter by status or e-mail address on the server. Read the list and filter it in your system.

What an order looks like

GET /{id} and the items of POST /GetListOfOrders describe an order with these fields:

Each signer in signatories has id, emailAddress, signingSequence and signStatus.

Status values

An order has an orderStatus number:

Each signer has a signStatus: 0 Not Set, 1 Created, 2 Started, 3 Completed, 4 Rejected, 5 Expired, 6 Forwarded, 7 Canceled.

Webhooks

Set completedWebhookUrl and cancelledWebhookUrl when you create the order to learn about the end of an order without polling. When the order is completed or stopped, Signature sends a GET request to the matching address. The request has no body, so put something in the address that tells you which order it is, for example https://example.com/signing-done?order=agreement-42. If the address cannot be reached, Signature tries again a few times. Then read the order with GET /{id} for the details.