Sending Contracts via REST API
What you need to get started
You only need a few things to get started sending Contracts via the REST API:
- A PactSafe account with REST API access. Looking to test first? Request a developer account here.
- You'll need to create an API key in your PactSafe profile here: . All REST API calls require authentication.
- 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:
- Create the Request:
HTTP POSTtohttps://api.pactsafe.com/v1.1/sites/:id/requests - Publish the Request for Signing (will send email or SMS if enabled):
HTTP POSTtohttps://api.pactsafe.com/v1.1/requests/:id/send
Upon receiving successful 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
{
"contracts": [ 123 ],
"signers": [
{
"signer_id": "example_signer_id",
"signer": {
"email": "[email protected]",
"mobile_number": "13175551234"
}
}
],
"fields": [
{
"name": "first_name",
"default_value": "Eric",
"assigned_to": "example_signer_id"
},
{
"name": "individual_sole_proprietor",
"default_value": true,
"assigned_to": "example_signer_id"
}
],
"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:
- 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.
- There must be a Signer. Signers are upserted when sent as part of your call.
- 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.
{
...
"signers": [
{
"signer_id": "123456789",
"signer": {
"email": "[email protected]",
"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": "[email protected]"
}
...
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 [email protected].
Updated 4 months ago