PactSafe

The PactSafe Developer Hub

Welcome to the PactSafe developer hub. You'll find comprehensive guides and documentation to help you start working with PactSafe as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Guides

Tracking Acceptance via Activity API

Overview

PactSafe offers the ability to track and send acceptance of legal agreements using API calls. This can be useful for customers that prefer to leverage the PactSafe API as an alternative to integrating using the PactSafe JavaScript library.

The steps below provide guidance on how to fully integrate your online legal terms so that they can be managed and acceptance can be tracked by PactSafe. This can all be done entirely via API calls that are outlined below to fully meet the needs of legal while keeping the engineering effort to a minimum.

Tracking Acceptance of Terms

PactSafe is 100% API-first in how we’ve architected our system to support API-driven use cases like managing acceptance for your online legal terms. Our API allows for quick and easy integration to ensure that the latest online terms are always presented and acceptance is captured in a few simple calls. First we’ll start with the basics in explaining the data structure, integration flow with calls that you will make, and we’ll provide some suggestions for the roll-out.

PactSafe Clickwrap

PactSafe offers a fully comprehensive clickwrap solution for managing acceptance of online legal terms. A clickwrap is a digital prompt that offers individuals the opportunity to accept a digitally mediated policy (often times this is a company’s Terms of Use and Privacy Policy).

Clickwrap is often presented in the form of a checkbox asking an individual to explicitly acknowledge their agreement to the digitally mediated policy(s). In other cases a clickwrap is presented without a checkbox stating that by taking an action (i.e. clicking a button) an individual is implicitly acknowledging their agreement. In both cases the clickwrap contains a link(s) to the digitally mediated policy(s) giving the individual an opportunity to review before consenting.

Electronic Records of Contract

In order to enforce the legal terms accepted on your web and mobile apps, PactSafe offers an API and integration that will enable the generation of records by your legal team. Metadata from the acceptance of terms is assembled into an Electronic Record of Contract which can be generated on demand from the PactSafe dashboard.

The key elements that need to be consistently tracked across all deployed clickwrap agreements are:

  • Who signed
  • Which contracts and what versions were accepted
  • When they were accepted
  • Additional optional (but recommended) metadata related to the transaction (IP address, name, company, title, etc.)

The Electronic Record of Contract itself is a legally binding, tamper-proof record stored within the PactSafe platform that proves that a customer entered in to a legally binding contract with your company. These records will be available to generate at any time by the your legal team via a simple search within Pactsafe to locate and generate the record on demand.

Electronic Record of Contract Components

  • Contract Title
  • Contract Version Number
  • Contract Version Unique ID - UUID generated for each version of a contract
  • Signer ID - Unique identifier of the person that accepted the contract
  • Date/Time of acceptance
  • IP Address
  • User Agent - Identifies device type (mobile/desktop), OS, browser, and page details

PactSafe APIs

PactSafe offers two different methods for integrating via API.

  • Activity API - A legal microservice located at https://pactsafe.io that is dedicated to supporting legal acceptance tracking for online legal terms. The Activity API is highly responsive because it is solely dedicated to handling these types of transactions.
  • REST API - Traditional API that offers a comprehensive set of APIs to connect to PactSafe for things like powering tradition eSignature-like workflows, pulling in additional data that may not be available via the Activity API about a configuration item (i.e. Contract) or transaction, and managing any PactSafe configuration element. The entire PactSafe UI is built on top of the PactSafe REST API

For the Tracking Acceptance use case, we will primarily be focusing on the Activity API.

Authentication - A key difference to be aware of between our Activity and REST APIs is that the REST API requires an API access token to be included in the header for all REST API calls. The Activity API requires what we refer to as a Site Access ID for authentication which should be included as a query parameter for all Activity API calls.

Data structures in PactSafe

Within PactSafe, there are a common language or set of data structures to consider when interacting with the API that will help you formulate the ideal integration:

  • A signer is any person or organization identified by any unique identifier to your company that is accepting documents
  • A signer can accept contracts via clickwrap through a series of events we call activities
  • An activity is an event that’s logged for a signer against a given contract and, optionally, a group. Common activities include:
    • Visited - A specific signer viewed a clickwrap contract(s)
    • Displayed - An individual viewed the full text of the clickwrap contract (usually by clicking on the link in the clickwrap)
    • Agreed - A specific signer agreed to a clickwrap contract(s)
    • Disagreed (optional) - A specific signer disagreed to a clickwrap contract(s).
    • Custom Event - Additional custom events are available for optional use
  • A contract has many versions that are drafted and published
  • A contract has both a latest_version and a published_version
  • A group can contain one or more contracts to present to an individual for review and acceptance
  • All signers, contracts, and activities live within a site which lives within an account
  • 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

Acceptance Requirements

Creating a legally defensible Electronic Record of Contract while minimizing the data that’s required for a given record is a delicate balance. More data can help establish an airtight legal record but privacy concerns necessitate offering solutions that allow companies to choose what the right amount of data is necessary for their legal defense. PactSafe is happy to outline what’s required at minimum and what’s optional but can be helpful.

Minimum Data Required

PactSafe recognizes that you have customers that trust you with their personal data. This trust dictates that there must be an option to keep the amount of data that’s necessary to generate and store Electronic Records of Contract to a minimum. PactSafe is happy to support this effort by providing a method of tracking acceptance that requires minimal data input.

Minimum data required to log a legal event within PactSafe:

  • SIGNER ID - Unique identifier defined by you to track the acceptance of all Contracts for an individual. PactSafe can accept any unique identifier (typically an email address or a UUID).
  • VERSION ID - Unique identifier (UUID) for the version of the Contract template
  • EVENT TYPE - Legal event being captured (i.e. agreed, displayed, visited, declined, opt-in, opt-out)
  • TERMS (CONTRACT) ID - Unique identifier (integer) for the Contract template
  • CONTRACT GROUP ID - Unique identifier (integer) for the Group the event should be recorded against. Groups are used to organize captured events in a specific context (i.e. User accepted Terms as part of your sign up/registration)

Legend: REQUIRED, OPTIONAL BUT RECOMMENDED

NOTE: Signer ID must be defined and provided by you. All other identifiers are defined/generated by PactSafe.

Optional (but helpful) Data

As noted in Electronic Record of Contract Components above, additional details can be optionally passed when sending acceptance to PactSafe to help create a more comprehensive and legally enforceable acceptance record. Details that we typically capture by default (including example values) are:

  • First Name
  • Last Name
  • Company
  • Job Title
  • Remote Address: addr=192.0.0.1
  • Operating System: os=MacOS
  • Environment: env=desktop
  • Screen Color Depth: scd=24-bit
  • Screen Resolution: res=1280x800
  • Browser Locale: bl=en-us
  • Browser Time Zone: btz=5
  • Browser: {"name":"Chrome","major":"79"}
  • User/Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.88 Safari/537.36
  • Page Encoding: pae=UTF-8
  • Origin: https://neighborino.co
  • Referrer: https://neighborino.co/saas/app/register.html
  • Page Path: pap=/saas/app/register.html
  • Page Domain: pad=neighborino.co
  • Page URL: pau=https://neighborino.co/saas/app/register.html
  • Page Title: pat=Angle - Bootstrap Admin Template

For more information on what URL parameters are supported when passing activities please reference our URL Parameters for Sending page.

Additionally, you have the freedom to pass any additional custom data it deems as necessary for the Electronic Record of Contract.

Logging Acceptance via API

Please review the PactSafe What is the Activity API? documentation for the most up-to-date information on API calls.

Below are example API calls you can use for tracking acceptance of terms. Separate examples are provided for leveraging Tags and Groups.

Query Parameter Definitions

The following are definitions for various query parameters seen in the example API calls below:

  • sid - Site Access ID. A GUID that’s unique for each Site within your account. Information on finding your sid can be found in the Authentication section of the Activity API page.
  • sig - Signer ID. The unique identifier used to save your signer’s signature. Can be email, mobile number, GUID, UUID, or any integer. Should be URLl encoded.
  • gkey - Group Key. The key for a group of Contracts that will be evaluated. Information on defining and finding your gkey can be found on our Creating and Managing Groups page.
  • cid - Contract IDs. A set of comma separated values to specify which contracts a signer is accepting or confirming acceptance of.
  • vid - Version IDs. Note NOT an integer, this is a UUID found in the version details of a contract. A set of comma separated values to specify which versions of which contracts a signer is accepting. Comma separated values must correspond to Contract IDs values.
  • et - Event Type. The type of event being logged. Default values are displayed, updated, agreed, visited, sent and disagreed.

Groups vs Tags

Groups - Used to group one or more contracts together for a specific use case. An example is you may place the Terms of Use contract in both the United States Sign Up group and the Canada Sign Up Group. This provides two different contexts for presenting one contract (Terms of Use) along with additional contracts for the specific Group.

Tags - Tags can be used to dynamically identify which clickwrap(s) to present to a user. An example is if you have a single webpage that you display in multiple languages and need to pull in the appropriate language based on the language of the user. You can use tags to query for the appropriate contracts in the appropriate languages and present them dynamically to the user for acceptance.

NOTE: PactSafe recommends using Groups for easily organizing contracts in to logic groupings. Tags should only be used, when necessary, for more complex use cases when clickwrap agreements need to be presented more dynamically on a page.

Get latest published terms using groups

Use the PactSafe Get Published API call to retrieve the latest versions of one or more contracts in a Group using the Group Key (gkey) as a filter. The response provides both the Contract ID and Version ID which can then be used to verify if a signer has signed the latest version of a contract or to send acceptance for a signer.

GET => https://pactsafe.io/published?sid=<site-access-id>&gkey=<group-key>

Example Response Body:

{
   "1604": "5deea00c5d187b2830681313",
   "1618": "5df00251ef6fb9074d9264ec"
}

Get latest published terms using tags

Use the below API call to find contracts based on tags. The response provides a JSON array with each contract that matches the tags which can be used to verify if a signer has signed the latest version of a contract, dynamically build a virtual group, or to send acceptance for a signer.

GET => https://pactsafe.io/load/json?sid=<site-access-id>&filter=tags==English%20or%20tags==Terms

Example Response Body:

{
   "key": "group-5dfa9f5456f2850cc6141e27",
   "type": "group",
   "style": "scroll",
   "virtual": true,
   "group": null,
   "container_selector": "",
   "signer_id_selector": "",
   "form_selector": "",
   "block_form_submission": true,
   "force_scroll": false,
   "alert_message": "Before you can submit this form, you must accept all of our legal contracts.",
   "confirmation_email": false,
   "triggered": false,
   "contracts": [
       1588
   ],
   "versions": [
       "5dea75adb9f693146643ec24"
   ],
   "major_versions": [
       "5dea75adb9f693146643ec24"
   ],
   "render_id": "5dfa9f5456f2850cc6141e28",
   "rendered_time": 1576705876,
   "auto_run": true,
   "display_all": true,
   "contract_html": <html-body-of-contract>
}

Get latest terms signed by signer

The Get Contracts Signed by Signer call allows you to query the API and pull back what a signer has agreed to. The response body will provide a list of Contract IDs and the corresponding latest Version ID accepted by a signer. This can be used to determine if a signer has signed the latest version of a contract.

GET => https://pactsafe.io/retrieve?sid=<site-access-id>&[email protected]

Example Response Body:

{
   "1604": "5deea00c5d187b2830681313",
   "1618": "5df00251ef6fb9074d9264ec"
}

Check if signer has signed latest terms

While it's common to capture the acceptance of terms as part of a registration or signup flow there are times when a material change is made to your terms and it's necessary to force users to accept an updated version. Similar to how you can prompt your user on login using the PactSafe JavaScript library, this same flow can be accomplish using the PactSafe API. This flow requires that a Group be set up with the appropriate Contracts to check.

Note: Display All Contracts Immediately must be disabled on the Group

The API call below can be used to check if the signer has agreed to the latest material version. A simple true/false is provided in the JSON response next to each contract_id to indicate if the signer has agreed to the latest version.

GET => https://pactsafe.io/latest?sid=<site-access-id>&[email protected]&gkey=trial-signup

Example Response Body:

{
    "822": true,
    "46026": false
}

Once the above API call has been made an additional flow will be needed to be built to determine which contracts, if any, the signer hasn't accepted, present versions that need to be accepted, and send acceptance.

Send acceptance of a contract for a signer

Send a signer acceptance event for one or more contracts using the Send Agreed API call. This call allows you to send an event for one or more contracts for a signer with the option to include a Group (gkey) as additional context. The response will simply be a 200 OK.

POST => https://pactsafe.io/send?sid=<site-access-id>&gkey=<group-key>&vid=<version-id1>,<version-id2>&et=agreed&[email protected]

Example Response: 200 OK

Updated 4 days ago


Tracking Acceptance via Activity API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.