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

Creating Signature Requests

You may want to build a contract execution flow into your own app, but you're not quite ready (or able, based on your business requirements) to use a straight up click-through agreement using our JavaScript Library, ps.js. We've also got a very robust REST API that can support almost any signing flow you may be more familiar with if you've done an esignature implementation.

The basic steps for integrating into our signature flow are as follows:

  1. Create a Request that includes the contract template, your signer information (email or mobile number, for example), and pre-populated data (if you have it).
  2. "Publish" or "Send" that Request to get a Execution URL for your Signer.
  3. Redirect the user (or open a new tab) to direct them to the Execution URL.

What you need to get started

You only need a couple of things to get started creating Requests via the REST API:

  1. A PactSafe account with REST API access. We do offer limited functionality in a developer account. Learn more at https://www.pactsafe.com/developers
  2. You'll need to create an App and generate an API Access Token in your PactSafe profile here: https://app.pactsafe.com/user/profile
  3. You'll need to create & publish a Contract in PactSafe and get the ID (it's the integer in the URL). Learn more on that here.

API Flow for Integration

To get going, there is a simple sequence of calls that you need to make in order to create and send a Request for Contract Execution:

  1. Create the Request: HTTP POST to https://api.pactsafe.com/v1.1/sites/:id/requests
  2. Publish the Request for Signing (will send email or SMS if enabled): HTTP POST to https://api.pactsafe.com/v1.1/requests/:id/send

Upon receiving 200 OK responses from each of these API calls, you'll be able to do whatever's next in your app, which may include redirecting your user to an Execution URL (which we'll cover towards the bottom of the article).

Create a Request via the API

Creating a Request is super easy with the PactSafe platform and gives you a ton of options for pre-populating data based on contract fields (tokens) or signer fields on your contracts. Here's an example call to create a request as barebones as possible.

POST => https://api.pactsafe.com/v1.1/sites/:id/requests

Request body should be JSON:

{
  "contracts": [ 123 ],
  "signers": [
    {
      "signer_id": "RAND123_ID",
      "signer": {
        "email": "eric@pactsafe.com",
        "mobile_number": "13175551234"
      }
    }
  ],
  "fields": [
    {
      "name": "first_name",
      "completed_value": "Eric",
      "assigned_to": "eric@pactsafe.com"
    },
    {
      "name": "individual_sole_proprietor",
      "completed_value": true,
      "assigned_to": "eric@pactsafe.com"
    },
    {
      "assigned_to": "eric@pactsafe.com"
    }
  ],
  "render_data": {
    "salesforce_Number_of_Seats__c": "5",
    "salesforce_Cost_per_Seat__c": "$0" 
  },
  "redirect_url": "https://yourapp.com/completed/eric%4Dpactsafe.com"
}

Note: mobile_number will only work for US-based mobile numbers for the time being.

That's a lot to digest. What's happening?

There are 3 requirements to sending a Request through PactSafe:

  1. There must be a Contract you're sending. You can upload a contract dynamically to a Request, but that's outside the scope of this Guide.
  2. There must be a Signer. Signers are upserted when sent as part of your call.
  3. If there are any Signer fields, they must be assigned prior to sending.

Passing in contracts: The array for contracts is based upon an integer id for every contract template loaded into PactSafe. You can create and publish a new Contract template by going here: https://app.pactsafe.com/contracts

Signer info for signers: The only information required to process signer information is the signer_id of your signer which can be email address, a 10 digit mobile number, a GUID, or any unique identifier of your choosing.

Redirecting a user upon signature: You can also pass redirect_url as a parameter that will send the user back to your app once they're done.

When passing in an email address or mobile number, we will automatically detect and attach a mobile number to your signer. You can pass additional parameters in your Signer object to determine if an email or SMS is sent (SMS is a feature of PactSafe's Expanded Edition or higher:

{
  ...
  "signers": [
    {
      "signer_id": "123456789",
      "signer": {
        "email": "eric@pactsafe.com",
        "mobile_number": "13174037298"
      },
     "send_to": {
          "mobile_number": false,
          "email": true
      }
    },
    ...
  ],
  ...
}

When to use fields. Fields are generally used on PDFs and give the signer the flexibility to fill out information on a contract that will be executed. Fields are generally saved for signer input. Here's an example of a field rendered on a Contract when signing:

Note: All fields must be assigned in order to send the request. If you'd like to auto-assign all fields to a signer (or remaining fields to a signer), you can use this syntax as noted above:

    ...
    {
      "assigned_to": "eric@pactsafe.com"
    }
    ...

When to use render_data. Render data is actually merged with your contract so that it appears to be a part of any HTML contract. Note: This is not supported with PDFs at this time. To pre-populate data on a PDF, use fields as mentioned above. Here's an example of render_data before and after being populated on an Order Form:

For more optional parameters, check out the full documentation for how to create a Request in our API docs.

Publish/Send your Request via the API

Once you've created your Request, you're now ready to send your Request or publish it for re-directing in your app:

POST https://api.pactsafe.com/v1.1/requests/:id/send

That's it! Then you're done. Note: If send_to is set to true for "email", an email will be sent to your signer as well (unless you've only specified a mobile number or GUID for your signer_id).

Redirect your user to sign

Now that you've "published" your contract for sending, you may want to direct your user to execute the contract right away. In your initial HTTP POST to /v1.1/requests, you'll get an Execution URL back for each of your signers that will be live once you "send"/publish your Request:

    ...
    "signers": [
        {
            ...
            "request_url": "https://dev-app.pactsafe.com/sign?r=596939ebe15da17d5b7094cf&s=5728cabf187107ea523435c4&signature=LkDtEldm3ZbCFe9S40cj2eZHY2G4b6yv~EhYM~~lgpq6lqvV~G5Yrht03FyUpV-daz2E-H1W0N4LnJj7G4iP~m3qxVJ2mmnNtjgW~sG8qF5VRMDFHnVuuDtsPaRLTLtOq0VKeqHacFjRi68MtptIaEDEkh14YAyfrdCK-hj39uQ-ZP3Oh9~H2rakGBQlPNk4n2sW~67Q6aljzxP1-C61HJGlm4DW8fhUPSfwvzRUbh42M7rLBtbWjqebnS2gmTwSczzNVd94W1Bgl6c~XWe521De2AOza6Iei6siC-jAgBEDT1mO0WNWfdN2QGBf~8LUWU1WvqUnYP9uoTGbHgM4pA__",
    ...

That request_url parameter in your response is what you'll want to save to redirect the user to complete their signing flow.

Redirecting the User back to your App

You can also pass in a property in your HTTP POST call to /site/:id/requests called redirect_url that will redirect your user back to your app after your signer has signed the contract. This makes the flow completely seamless.

VOILA! You did it! With that, you should be able to complete the full-scale signing flow for your app. Questions? Give us a shout at help@pactsafe.com.