pactsafe API

Vault: The PactSafe Developer Toolkit

Hi there! Welcome to PactSafe's Developer Portal. We have a rich set of developer tools to help you easily integrate our legal system of record into your own apps.

We have 3 options for integration into your app that are all really easy to get plugged into:

  1. Our JavaScript Library
  2. Our Activity API
  3. Our REST API

Our JavaScript Library

What is it?

The JavaScript library is designed to be as seamless and straightforward as possible to get PactSafe integrated, to start tracking who accepted important legal terms, and get back to innovating!

When should I use it?

You should be using our JavaScript library when you're plugging us into your website and web app. This would include ecommerce, your SaaS app, and more.

Where do I learn more?

  1. Learn how to get started with our JavaScript library here.
  2. Once you've done that, more advanced documentation on configuration is here.

Our Activity API

What is it?

Our Activity API is a legal microservice located at https://pactsafe.io that was built from the ground up to support the functionality behind our JavaScript library. It has 3 calls:

  1. latest returns a JSON object set of Contract IDs and boolean true/false values based on whether or not a signer has accepted the latest versions of a Group of Contracts.
  2. retrieve returns a JSON object set of Contract IDs and Version IDs to tell you which versions your signer has accepted.
  3. send will send us Contract IDs and Version IDs (as well as signer information and site Access ID) to track who's accepted what.

When should I use it?

Generally, customers will use our Activity API directly when you have a strong preference of not using JavaScript on your site, or you have a specific need to retrieve information on a user outside the context of a form on a page.

For example, if you have a persistent session in your web app you can call the following to determine whether or not to show a clickwrap agreement to a user:

GET https://pactsafe.io/latest?sig=sample@pactsafe.com&sid=ACCESS_ID&gkey=register-clickwrap

That call would return:

{"53":false,"316":false}

Where do I learn more?

Read up more on our Activity API here.

Our REST API

What is it?

Our REST API is a comprehensive set of APIs to connect to PactSafe for things like creating or versioning contracts, updating user information, sending contracts manually, and more.

When should I use it?

Our entire user interface is built on top of our REST API, so any function besides the simple latest, retrieve, and send calls of our Activity API will require our REST API.

Here are some examples for when you'd want to use our API:

  • You need to retrieve the content of a Contract stored in PactSafe.
  • You want to send a Contract to an individual for electronic signature.
  • You want to retrieve or update metadata about a contract like tags, name, or description.
  • You want to update a user's login details.
  • You want to retrieve detailed activity for a signer.

Where do I learn more?

Check out our REST API docs for more information. There are a lot of amazing resources to help you get started—including sample code, API explorer, and more.

Getting Started: REST API

Who is PactSafe? PactSafe is a secure contract management platform, the world's fastest electronic signature, and contract analaytics solution for business contracts, web and mobile apps, and other contracts that are executed online with your customers. The Vault Developer Toolkit provides you tools to plug in to your websites or mobile apps to help your business unify signatures across all your contracts.

The REST API exposes CRUD operations on all of the core PactSafe resources. We follow conventional REST methods and protocols using POST (create), GET (retrieve), PATCH (update), and DELETE (delete).

All data is sent and received as JSON, and all requests require an OAuth Access Token for authorization. An OAuth Access Token can be created for your user by creating one in your account.

API Resource Overview

The endpoint for the PactSafe API is https://api.pactsafe.com. The current version of the API is 1.1.

There are several objects with important relationships core to the PactSafe system to think about as you're integrating your app. Here are some basic concepts that will introduce you to how the system works.

  • A contract is a first party object and houses basic metadata like title, description, and more.
  • A contract has many versions that are drafted and published (all of which can be done either in our interface or via the REST API.
  • A contract has both a latest_version and a published_version object attached to it to keep track of new versions that are still in draft.
  • A signer is someone who is actually signing a contract either inside a clickwrap or through a signature request.
  • You can create a request (for signature) between one or many signer(s).
  • A version of a contract can have many revision(s) within a request.

Other things of note

There are many other facets to the system that are important to know when it comes to our system architecture as you become more familiar with the system:

  • An account can have many site(s) which act as a sub-tenant within your environment. One site is your default, which controls how a contract can be shared across an account.
  • A user can have access to one account or many, one site or many.

Basics of the API

  • Want to limit the number of results on your GET request? Simply add ?per_page=5 to define your own pages. Default is 25 per page.
  • For pagination, add ?page=2 to your GET request.
  • You can expand the data you return on any GET call by adding ?expand=<field_name>,<field_name> where <field_name> is the name of any top-level property on the object you are calling.
  • To filter your API requests, there's a simple parameter filter you can append to your call with the field name and value.
  • Filtering example: /agreements?filter=classification==privacy_policy and published==true will return a filtered set of agreements. Note: Please URL encode your requests for reliable responses!
  • Filtering dates can be done with > or < and the date format YYYY-MM-DD. Times are filtered against GMT.

Authentication

The REST API requires a valid OAuth 2 Access Token to be present in the Authorization header of every request. In order to generate an Access Token, you must first provision an API Key pair (Client ID and Client Secret) for your user via the PactSafe app.

To do this, you can Once you have the Consumer Key and Consumer Secret, you can go to your user profile and create a new "Application" (requires access to our REST API or a developer edition). Once you get a Client ID and Client Secret, you can do a POST call to https://api.pactsafe.com/oauth/token one time. The access_token returned to you can be used as a static token in all subsequent API calls to PactSafe. If you generate a NEW access_token, your previous access_token will expire after 15 minutes.

Important: Every REST call you make to PactSafe must have the header Authorization Bearer {access_token} in order to get you the data you need.

What is the Activity API?

The PactSafe Activity API is a system designed purely to accept & retrieve the minimum amount of information required to determine what your customers have or have not agreed to. It's designed for maximum up-time, speed, and reliability. It is also an asynchronous service that our Javascript library uses when being included on a web or mobile app. You can simply cURL the URL with the correct parameters to call our system.

The Activity API exposes a super fast, highly available API that is connected directly to our Javascript library. The purpose of this API is exclusively to manage 3 things:

  • Determine in super real-time whether or not your user has agreed to the latest version of a contract
  • Retrieving which versions and revisions of a Contract a Signer has agreed to
  • Sending activity ("Signed", "Visited", etc.) in real-time as it happens in a web or mobile app

All PactSafe Activity can be passed as an HTTP GET call to the endpoints directly and parameters passed as URL parameters.

The endpoint for the PactSafe Activity API is https://pactsafe.io.

Activity API Docs

Get the Latest Versions signed

GET /latest?sig={signer_id}&sid={site_id}&gkey={group_key}&gid={group_id}&cid={contract_id}

"Latest" versions by Signer The purpose of the "Latest" call is so that you can get a fast, real-time response to determine if your Signer has accepted the latest versions of Contracts in a Group or a list of comma-separated IDs.

Parameters

NAME REQUIRED TYPE DESCRIPTION
signer_id True Varchar (eric@pactsafe.com) The unique identifier used to save your signer's signature.
site_id True Varchar (25b2b173-632a-4227-9877-31d2109d8c98) GUID for your site (can be accessed at http://app.pactsafe.com/settings/site).
group_key False Varchar (clickwrap-example) The key for a group of Contracts that will be evaluated, with all the latest versions being accepted returned as true or false.
group_id False Integer (1022) The ID for a group of Contracts that will be evaluated, with all the latest versions being accepted returned as true or false.
contract_id False Integer (282,1241) A set of comma separated values requesting if a Signer has accepted the latest version of a set of Contract IDs.

Response 200 (application/json)

Returns a JSON object of contract IDs with a true or false value based upon whether or not the signer has signed/accepted the latest contract version.

{
    "282": true,
    "1241": false
}

Get the Latest Published Versions for a Group

GET /published?sid={site_id}&gkey={group_key}&gid={group_id}&cid={contract_id}

"Published" versions for the Contracts included in a Group. The purpose of the "Published" call is so that you can get a fast, real-time response to get the Version IDs of the Contracts you're displaying to your Signer. If you're doing a full server-side flow using the Activity API, you'll be able to follow this flow using the Activity API:

  1. To get the Versions your signer should be accepting, use HTTP GET => /published?sid={site_access_id}&gkey={group_key}
  2. If you want to get the latest Version IDs already accepted by your user, do something like HTTP GET => /latest?sig={signer_id}&sid={site_access_id}&gkey={group_key}
  3. Load form on the page to capture user sign up and acceptance.
  4. Pass Version IDs and Contract IDs to HTTP POST => /send?sid={site_access_id}&cid={contract_ids}&vid={version_ids}&sig={signer_id}&gid={group_id}

Parameters

NAME REQUIRED TYPE DESCRIPTION
site_id True Varchar (25b2b173-632a-4227-9877-31d2109d8c98) GUID for your site (can be accessed at http://app.pactsafe.com/settings/site).
group_key False Varchar (clickwrap-example) The key for a group of Contracts that will be evaluated, with all the latest versions being accepted returned as true or false.
group_id False Integer (1022) The ID for a group of Contracts that will be evaluated, with all the latest versions being accepted returned as true or false.
contract_id False Integer (282,1241) A set of comma separated values requesting if a Signer has accepted the latest version of a set of Contract IDs.

Response 200 (application/json)

Returns a JSON object of contract IDs with the latest published Version IDs based upon the Group key, ID, or list of comma-separated Contract IDs.

{
    "282": "592491db0a8eb8133e7a3c5b",
    "1241": "592494670a8eb8133e7a3c67"
}

"Retrieve" Contracts by Signer

GET /retrieve?sig={signer_id}&sid={site_id}&cid={contract_id}

The purpose of the "Retrieve" call is so that you can get a fast, real-time response of the actual Version IDs accepted by a user. You can then use the REST API (if applicable) to dig deeper into an Contract's content.

Parameters

NAME REQUIRED TYPE DESCRIPTION
signer_idTrue Varchar (eric@pactsafe.com) The unique identifier used to save your signer's signature.
site_id True Varchar (25b2b173-632a-4227-9877-31d2109d8c98) GUID for your site (can be accessed at http://app.pactsafe.com/settings/site).
contract_id False Integer (282,1241) A comma-separated list that will return the version IDs accepted by a user.

Response 200 (application/json)

Returns a JSON object of the contract IDs with the version IDs of the contracts signed by the signer. Will return with a version ID of null if no version has been signed.

{
    "282": "568eb1c566b712cd11aec1ca",
    "1241": "5234908adas09asd123asfksl"
}

"Send" Contracts signed by Signer

GET /send?sig={signer_id}&sid={site_id}&cid={contract_id}&et={event_type}&vid={version_id}&gid={group_id}&cnf={email_confirmation}&cus={custom_data}

The purpose of the "Send" call is so that you can send a fast, real-time call to PactSafe to capture an electronic signature of your Contracts.

NAME REQUIRED TYPE DESCRIPTION
signer_id True Varchar (eric@pactsafe.com) The unique identifier used to save your signer's signature.
site_id True Varchar (25b2b173-632a-4227-9877-31d2109d8c98) GUID for your site (can be accessed at http://app.pactsafe.com/settings/site).
contract_id False Integer (282,1241) A comma-separated list that will return the version IDs accepted by a user. Only optional if passing an updated event type.
version_id False Varchar (5469405860fds09r8w342,55523kldfsa12311dh193e) A set of comma separated values requesting if a Signer has accepted the latest version of a set of Contract IDs. Only optional if passing an updated event type.
event_type True Varchar (agreed) Any value can be accepted here, but the default events you can pass to the Activity API are displayed, updated, agreed, visited, sent, and disagreed
group_id False Integer (12) The Group ID that all the Contracts are a part of will also be added to your call if added.
email_confirmation False Boolean Use 1 or true here to send an email confirmation to the signer.
custom_data True Object (%7B%20%22firstname%22%3A%20%22Eric%22%20%7D) URL encode a JSON object to attach custom data to your Activity. The example is URL encoded for { "firstname": "Eric" } Using this in an update Activity will append the data to the Signer, otherwise it will be added to the specific Activity call/transaction.

Response 200 (application/json)

Basically a web beacon call. All calls are added to an asynchronous queue and processed. A 200 response is returned acknowledging receipt of the call (but not synchronous completion of the call).