Docs

Signature.io documentation

View the Project on GitHub signatureio/docs

Signature.io Documentation

Quickstart

Using Signature.io is just 3 easy steps.

1. Create An Account

curl -X POST https://www.signature.io/api/v0/people.json \
-d "first_name=YOUR_FIRST_NAME" \
-d "email=YOUR_EMAIL" \
-d "password=YOUR_PASSWORD"

On a success response, you will receive your secret_api_key and your public_api_key. Save these somewhere safe. You need your secret key in the next step.

2. Create Signable Document

curl -X POST https://www.signature.io/api/v0/documents.json \
-u YOUR_SECRET_KEY: \
-d "url=https://www.signature.io/pdfs/sign-below.pdf"

On a success response, you will receive a share_url.

3. Visit the share_url

Visit or share the share_url with the person you need to sign the document. That's it. You are done. You will be notified by email when the document is signed.

Full API Reference (beta)

The Signature.io API is based around REST. It uses standard HTTP authentication. JSON is returned in all responses from the API, including errors. The API is encrypted with SSL.

To make testing your application easier, person accounts have test-mode API keys as well as live-mode API keys. These keys can be active at the same time. Data created with test-mode credentials will never cost anyone money.

We've tried to make it as easy to use as possible, but if you have any feedback please let us know.

Example

Let's convert sign-below.pdf into a signable document. Paste the following code into your terminal. You will need to replace YOUR_SECRET_KEY with a valid Signature.io private API key. If you don't yet have a private API key, go to the Sessions section to get one.

curl -X POST https://www.signature.io/api/v0/documents.json \
-u YOUR_SECRET_KEY: \
-d "url=https://www.signature.io/pdfs/sign-below.pdf"

As long as you used a valid private api key and url, you will get a json response back containing the share_url of the signable document.

{
  success: true,
  document: {
    url: "https://www.signature.io/pdfs/sign-below.pdf",
    pdf_url: "https://www.signature.io/pdfs/sign-below.pdf",
    filename: "sign-below.pdf",
    share_url: "https://www.signature.io/documents/DOC_8703243DB5D272FAE06D",
  }
}

Open the share_url in a browser to sign the document. Or email the share_url to a friend for signing. That's it you are done.

As you can see, the only thing the request requires is a valid url. You can pass PDFs, Microsoft Word docs, and HTML pages to the url parameter. Signature.io will convert it into a signable document. For example, try again, but this time pass http://news.ycombinator.com to the url.

curl -X POST https://www.signature.io/api/v0/documents.json \
-u YOUR_SECRET_KEY: \
-d "url=http://news.ycombinator.com"

If you have any questions, please email me.

Sessions

The /sessions request returns your secret API key. Before you can use it, you must have a person account. If you don't, go to the people section, create your account, and then come back here.

POST /sessions

Authenticates a person's session. Upon success you will receive live-mode API keys and test-mode API keys. Use the appropriate key for subsequent requests. You will typically be using the secret_api_key. The publishable_api_key is used for hidden features like Pad.js.

Definition
POST https://www.signature.io/api/v0/sessions.json
Required Parameters
Example Request
curl -X POST https://www.signature.io/api/v0/sessions.json \
-d "email=test@example.com" \
-d "password=password"
Example Response
{
  success: true,          
  test_secret_api_key: "YOUR_TEST_SECRET_KEY",
  test_public_api_key: "YOUR_TEST_PUBLIC_KEY",
  secret_api_key: "YOUR_SECRET_KEY",
  public_api_key: "YOUR_PUBLIC_KEY"
}

Documents

You can turn many of your documents into signable documents - pdf, word, google doc, and even html pages can be converted into a signable document. To create a document you will need your secret api key. If you don't have this go to the sessions section.

POST /documents

Create a document for signing.

Definition
POST http://{YOUR_SECRET_KEY}:@www.signature.io/api/v0/documents.json
Required Parameters
Example Request
curl -X POST https://www.signature.io/api/v0/documents.json \
-u YOUR_SECRET_KEY: \
-d "url=https://www.signature.io/pdfs/sign-below.pdf"
Example Response
{
  success: true,
  document: {
    id: "DOC_8703243DB5D272FAE06D",
    url: "https://www.signature.io/pdfs/sign-below.pdf",
    pdf_url: "https://www.signature.io/pdfs/sign-below.pdf",
    share_url: "https://www.signature.io/documents/DOC_8703243DB5D272FAE06D",
    filename: "sign-below.pdf"
  }
}

GET /documents

Returns a list of all the documents you've previously created.

Definition

GET https://www.signature.io/api/v0/documents.json

Required Parameters

None

Example Request
curl -X GET https://www.signature.io/api/v0/documents.json \
-u YOUR_SECRET_KEY:
Example Response
{
  success: true,
  total_count: 212,
  count: 10,
  offset: 0,
  documents: [
    {
      id: "DOC_8703243DB5D272FAE06D",
      url: "https://www.signature.io/pdfs/sign-below.pdf",
      pdf_url: "https://www.signature.io/pdfs/sign-below.pdf",
      share_url: "https://www.signature.io/documents/DOC_8703243DB5D272FAE06D",
      filename: "sign-below.pdf"
    },
    {...},
    {...}
  ]
}

GET /documents/{ID}

Get the results of a document.

Definition
GET https://www.signature.io/api/v0/documents/{ID}.json
Required Parameters
Example Request
curl -X GET https://www.signature.io/api/v0/documents/DOC_8703243DB5D272FAE06D.json
Example Response
{
  success: true,
  document: {
    id: "DOC_8703243DB5D272FAE06D",
    url: "https://www.signature.io/pdfs/sign-below.pdf",
    pdf_url: "https://www.signature.io/pdfs/sign-below.pdf",
    filename: "sign-below.pdf",
    share_url: "https://www.signature.io/documents/DOC_8703243DB5D272FAE06D",
  }
}

GET /documents/{ID}/pages

Get the pages of a document.

Definition
GET https://www.signature.io/api/v0/documents/{ID}/pages.json
Required Parameters
Example Request
curl -X GET https://www.signature.io/api/v0/documents/DOC_8703243DB5D272FAE06D/pages.json
Example Response
{
  success: true,
  pages: [
    { 
      id: "PG_7FD2ADF484BD736F1666400F8A4642EC69D199C0",
      url: "https://carveproduction.s3.amazonaws.com/documents/8703243DB5D272FAE06D/pngs/1.png",
      sort: 1
      text_elements: [
        {
          id: "TE_B64F031FB3AE72065DB6211C4E64202F4255DF51",
          x: 420,
          y: 909,
          content: 'Some text'
        },
        {...}
      ],
      signature_elements: [
        {
          id: "SE_3A91F3FF20374916DF41AC5B1378754085807B02",
          x: 100,
          y: 100,
          url: "path/to/signature"
        },
        {...}
      ]
    }, 
    {...},
    {...}
  ]
}

GET /documents/:id/signed

Returns a list of all signed copies of a specific signable document.

Definition
GET https://www.signature.io/api/v0/documents/{ID}/signed.json
Required Parameters

None

Example Request
curl -X GET https://www.signature.io/api/v0/documents/DOC_8703243DB5D272FAE06D/signed.json \
-u YOUR_SECRET_KEY:
Example Response
{
  success: true,
  total_count: 200,
  count: 10,
  offset: 0,
  documents: [
    {
      id: "DOC_8703243DB5D272FAE06D",
      url: "https://www.signature.io/pdfs/sign-below.pdf",
      pdf_url: "https://www.signature.io/pdfs/sign-below.pdf",
      share_url: "https://www.signature.io/documents/DOC_8703243DB5D272FAE06D",
      filename: "sign-below.pdf",
      signed_url: "https://www.signature.io/documents/SIGNED-DOC_8703243DB5D272FAE06D.pdf"
    },
    {...},
    {...}
  ]
}

GET /documents/signed

Returns a list of all the copies of signed documents.

Definition
GET https://www.signature.io/api/v0/documents/signed.json
Required Parameters

None

Example Request
curl -X GET https://www.signature.io/api/v0/documents/signed.json \
-u YOUR_SECRET_KEY:
Example Response
{
  success: true,
  total_count: 200,
  count: 10,
  offset: 0,
  documents: [
    {
      id: "DOC_8703243DB5D272FAE06D",
      url: "https://www.signature.io/pdfs/sign-below.pdf",
      pdf_url: "https://www.signature.io/pdfs/sign-below.pdf",
      share_url: "https://www.signature.io/documents/DOC_8703243DB5D272FAE06D",
      filename: "sign-below.pdf",
      signed_url: "https://www.signature.io/documents/SIGNED-DOC_8703243DB5D272FAE06D.pdf"
    },
    {...},
    {...}
  ]
}

GET /documents/signed/{ID}

Get the results of a signed document.

Definition
GET https://www.signature.io/api/v0/documents/signed/{ID}.json
Required Parameters
Example Request
curl -X GET https://www.signature.io/api/v0/documents/signed/DOC_8703243DB5D272FAE06D.json
Example Response
{
  success: true,
  document: {
    id: "DOC_8703243DB5D272FAE06D",
    url: "https://www.signature.io/pdfs/sign-below.pdf",
    pdf_url: "https://www.signature.io/pdfs/sign-below.pdf",
    share_url: "https://www.signature.io/documents/DOC_8703243DB5D272FAE06D",
    filename: "sign-below.pdf",
    signed_url: "https://www.signature.io/documents/SIGNED-DOC_8703243DB5D272FAE06D.pdf"
  }
}

GET /documents/{ID}/screenshot.png

Get a screenshot of the document.

Definition
GET https://www.signature.io/api/v0/documents/{ID}/screenshot.png
Required Parameters
Example Request
<img src="https://www.signature.io/api/v0/documents/DOC_8703243DB5D272FAE06D/screenshot.png"/>

People

The /people requests let you create a person account and manage that account. You must create a person account to use the Signature.io API. After doing so you will be able to authenticate your account using /sessions.

POST /people

Pass a first name, email, and password to create your person account at Signature.io.

Definition
POST https://www.signature.io/api/v0/people.json
Required Parameters
Example Request
curl -X POST https://www.signature.io/api/v0/people.json \
-d "first_name=Test" \
-d "email=test@example.com" \
-d "password=password"
Example Response
{
  success: true,
  person: {
    id: "1",
    first_name: "Test",
    email: "test@example.com",
    test_secret_api_key: "YOUR_TEST_SECRET_KEY",
    test_public_api_key: "YOUR_TEST_PUBLIC_KEY",
    secret_api_key: "YOUR_SECRET_KEY",
    public_api_key: "YOUR_PUBLIC_KEY"
  }
}

GET /people/me

Retrieves your person information.

Definition
GET http://{YOUR_SECRET_KEY}:@www.signature.io/api/v0/people/me.json
Required Parameters

none

Example Request
curl -X GET https://www.signature.io/api/v0/people/me.json \
-u YOUR_SECRET_KEY:
Example Response
{
  success: true,
  person: {
    id: "1",
    first_name: "Test",
    email: "test@example.com",
    test_secret_api_key: "YOUR_TEST_SECRET_KEY",
    test_public_api_key: "YOUR_TEST_PUBLIC_KEY",
    public_api_key: "YOUR_PUBLIC_KEY",
    secret_api_key: "YOUR_SECRET_KEY"
  }
}

POST /people/forgot_password

Sends an email to the person with password reset instructions.

Definition
POST https://www.signature.io/api/v0/people/forgot_password.json
Required Parameters
Example Request
curl -X POST https://www.signature.io/api/v0/people/forgot_password.json \
-d "email=test@example.com"
Example Response
{
  success: true,
  message: "Email sent to test@example.com"
}

POST /people/reset_forgotten_password

Resets forgotten password.

Definition
POST https://www.signature.io/api/v0/people/reset_forgotten_password.json
Required Parameters
Example Request
curl -X POST https://www.signature.io/api/v0/people/forgot_password.json \
-d "email=test@example.com" \
-d "reset_password_token={RESET_PASSWORD_TOKEN}" \
-d "new_password=password"
Example Response
{
  success: true,
  person: {
    id: "1",
    email: "test@example.com"
  }
}

Events

The /events requests let you find interesting events that have happened in your account. When an interesting event occurs, we create a new event object. For example, when a document is signed, we create a document.signed event.

GET /events

List all events.

Definition
GET https://www.signature.io/api/v0/events.json
Required Parameters

None

Optional Parameters
Example Request
curl -X GET https://www.signature.io/api/v0/events.json
Example Response
{
  success: true,
  events: [{
    id: "EVT_FDFD834783FJD",
    type: "document.signed",
    data: {
      object: {
        id: "DOC_FDJKE43KDFKJ3K4",
        parent_id: "DOC_ERUI34L3J34D",
        url: "https://www.signature.io/pdfs/sign-below.pdf",
        filename: "sign-below.pdf",
        status: "signed",
        signed_url: ""
      }
    }
  }]
}

Signature Pad.js (beta)

Signature.io's Pad.js makes it easy to accept signatures on your website or webapp. We'll take care of building the signing pad, securely saving the signature, and returning an image of the signature for you.

Example

Your Signature URL is: url gets inserted here

Usage

To use the Pad.js, paste the following code wherever you want it to appear. You will need to replace YOUR_PUBLIC_KEY with your publishable key.

<script src='https://www.signature.io/js/v0/pad.js' data-signature-key='YOUR_PUBLIC_KEY'></script>

If you place the script tag inside a

tag, when a signature gets added a hidden input called signature_url will be append to the form, which will then be submitted.

This signature_url parameter represents a downloadable image of the signature. You can use this in your application to display the signature.

<form action="/agree/to/terms" method="post">
  <script src='https://www.signature.io/js/v0/pad.js' data-signature-key='YOUR_PUBLIC_KEY'></script>
</form>

The form can, of course, contain other s as well.

Additional Options

Events

An alternative to appending the Pad.js to a form is to use events. The Pad.js will fire a signature_pad:save event when a signature is created. You can listen to this and, for example, submit it via Ajax to your server. For example:

<script type="text/javascript">
  var scripts = document.getElementsByTagName('script');
  var script  = scripts[scripts.length-1];

  script.addEventListener('signature_pad:save', function(e) {
    console.log(e.data);
  }, false);
</script>

Extended documentation

Browser support

Pad.js supports modern browsers including the following:

API Libraries

We try to keep the HTTP API simple to use, but we realize the usefulness of having pre-built libraries for interacting with Signature.io. The following libraries are available to help with that.

If you write your own library and would like us to link to them, just let us know.

Ruby

Available as a gem:

gem install signatureio

If you use bundler:

gem 'signatureio'

Check out the source code on GitHub.

Node.js

Available as a node module through npm:

npm install signatureio

If you use a package.json:

...
"dependencies": {
  "signatureio": "*"
  ...
}
...

Check out the source code on GitHub.