Documentation

General

The API we provide is a JSON RESTful API. That means your requests should be made with Content-Type: application/json and you should expect JSON back, unless the request is about file transfer.

When you make an invalid request, expect to receive a 400 Bad Request with the errors. The format is like so:

{
    "message": "Your request is invalid",
    "errors": {
        "name": [
            "Required"
        ]
    }
}

API Key

You need an API key to perform any operations with the API. Go in your account settings and create an API key with a useful description. We recommend creating a key for each different usage. For example, if you have a phone application and a desktop application, each one should have it's own key, so that they can be disabled individually.

Once you have the key, you have to add the Authorization HTTP header to each request you make. We use HTTP Basic authentication mechanism. The username is the API key, and there is no password. Like so:

Authorization: Basic {Base64(YOUR_API_KEY:)}

For example, if your API key is XDnwdOgvQtUU00x42Y8IUlH817ZZoD7f, the username:password will be XDnwdOgvQtUU00x42Y8IUlH817ZZoD7f:, and the HTTP header will be:

Authorization: Basic WERud2RPZ3ZRdFVVMDB4NDJZOElVbEg4MTdaWm9EN2Y6

Creating a Contract

To create a contract, you have to make more than one request.

The first one is to create the contract itself. You have to POST to https://app.signsquid.com/api/v1/contracts.

{
    "name": "My new contract name"
}

You should expect to receive a 201 Created with a Location header. You can make a GET request to that URL to get the current state of your contract. You should get back somethig like this:

{
    "id": "5211a032e536381594f460b8",
    "name": "My new contract name",
    "versions": [
        {
            "signatories": [],
            "published": false,
            "expires": "2013-09-19T04:33:53.976Z",
            "status": "NotPublished"
        }
    ],
    "agreed": null,
    "status": "NotPublished"
}

The contract you created has a first version. You now have to add signatories. You do that by doing a POST to https://app.signsquid.com/api/v1/contracts/{CONTRACT_ID}/versions/1/signatories.

{
    "name": "John Doe",
    "email": "john.doe@example.com"
}

You should receive a 201 Created. You make one POST by signatory.

Then you have to add a file. You can do so by doing a POST to https://app.signsquid.com/api/v1/contracts/{CONTRACT_ID}/versions/1/files?filename={FILENAME}. The request body should be the binary file itself. Don't forget to put the filename in the URL. Also, do not use multipart/form-data encoding. The file must be the request body, not encoded as a submitted HTML form.

Then you can send the invitations by doing a POST to https://app.signsquid.com/api/v1/contracts/{CONTRACT_ID}/versions/1.

If you make another GET to the contract URL, you should have something that look like this:

{
    "id": "5211a032e536381594f460b8",
    "name": "My new contract name",
    "versions": [
        {
            "signatories": [
                {
                    "name": "John Doe",
                    "email": "john.doe@example.com",
                    "code": "NSZX7G",
                    "status": "WaitingForSignatoryAction",
                    "mobilePhone": null,
                    "smsStatus": null
                },
                {
                    "name": "Alex Doe",
                    "email": "alex.doe@example.com",
                    "code": "8ZHG9J",
                    "status": "WaitingForSignatoryAction",
                    "mobilePhone": null,
                    "smsStatus": null
                }
            ],
            "published": true,
            "expires": "2013-09-19T04:33:53.976Z",
            "status": "WaitingForSignatoryAction"
        }
    ],
    "agreed": null,
    "status": "WaitingForSignatoryAction"
}

And when signed, by everyone, you should get something like this:

{
    "id": "5211a032e536381594f460b8",
    "name": "My new contract name",
    "versions": [
        {
            "signatories": [
                {
                    "name": "John Doe",
                    "email": "john.doe@example.com",
                    "code": "NSZX7G",
                    "status": "Agreed",
                    "mobilePhone": null,
                    "smsStatus": null
                },
                {
                    "name": "Alex Doe",
                    "email": "alex.doe@example.com",
                    "code": "8ZHG9J",
                    "status": "Agreed",
                    "mobilePhone": null,
                    "smsStatus": null
                }
            ],
            "published": true,
            "expires": "2013-09-19T04:33:53.976Z",
            "status": "Agreed"
        }
    ],
    "agreed": "2013-09-19T04:45:33.344Z",
    "status": "Agreed"
}

Sending Code by SMS

Like in the web application, you can send the secret code to signatories by SMS. You just have to provide the mobile phone number when adding the signatory. Make sure to include the country code when the number is not located within Canada or United States.

{
    "name": "John Doe",
    "email": "john.doe@example.com",
    "mobilePhone": "7065551234"
}

The SMS will be sent to that number when sending the invitations. Also, the smsStatus will have one of the following values: null, "Pending", "Sent", "Failed".

Webhooks, or How Do I Know When It's Signed?

Signsquid can call your application when something happens. In your account settings, go in Api Keys (https://app.signsquid.com/ApiKey). You can add an URL you wish to be called by Signsquid to each of your API keys. For example: https://myapp.example.com/api/signsquidwebhook.

Signsquid will POST to each of the URL you provide for the current user (one by API key) when an event happens.

Someone signed

When someone signs, you will receive something of this form:

{
    "id": "11cdd494-de5b-460e-9ddf-4e84bad6f596",
    "privateId": "30a7e1b3-e763-4789-a54d-fcc53dcf973a",
    "created": "2013-09-20T05:44:23.354Z",
    "type": "SomeoneSigned",
    "event": {
        "contractId":  "5211a032e536381594f460b8",
        "contractVersion": 1,
        "name": "John Doe",
        "email": "john.doe@example.com"
    }
}

Everyone signed

When everyone signed, you will also receive an event of this form:

{
    "id": "a53e98e4-0197-4513-be6d-49836e406aaa",
    "privateId": "e33898de-6302-4756-8f0c-5f6c5218e02e",
    "created": "2013-09-21T02:11:22.110Z",
    "type": "EveryoneSigned",
    "event": {
        "contractId":  "5211a032e536381594f460b8",
        "contractVersion": 1
    }
}

Event Authenticity

Anyone could POST fake events to your webhook URL. The way to ensure the request really came from Signsquid is to take the id of the event (not the privateId), and make a GET request to the URL https://app.signsquid.com/api/v1/webhookevents/{id}. You should receive exactly what you had received with the POST. That way, you can make sure the privateId matches the one you received.

Reference

Possible values for the status of a contract version are:

NotPublished
WaitingForSignatoryAction
Agreed
Refused
NewVersionAvailable

The contract status is the same as the last version.

The possible values for signatory status are:

WaitingForSignatoryAction
Agreed
Refused