![](https://images.ctfassets.net/9pvazpst9iwl/giWLm6W1UrjoyeYS5AmQx/9db902cf37bf204f58ca212080e700c8/illustration-isometric_leaning-cubes_inkwell.png)
From the Trenches: Setting up a Joint Agreement Network using the eSignature REST API
Joint Agreements offer enterprises, their business partners, and customers a unified signing experience. Discover Joint Agreements and see how to create a joint agreement network with the eSignature REST API.
Table of contents
![](https://images.ctfassets.net/9pvazpst9iwl/3fxlpxrPc3ffAAFurs1y76/50b24b68de5d97b7b92a5d0111c4b0d4/illustration-isometric_ball-rectangle-stage_inkwell.png)
In this blog, I’ll be covering how to create a Joint Agreement network using our eSignature REST API and how a network partner can join your network.
But first, what are joint agreements? Joint Agreements is a Docusign offering that enables organizations to collaborate with their business partners to share a single DocuSign envelope, with documents provided by all parties, for their shared consumers to sign in a single DocuSign signing session. This feature is designed to help network creators (usually, enterprise organizations) seamlessly partner with their business network and their mutual consumers to provide an improved B2B2C experience for all parties involved. For more details on how this works, see my first blog post on this topic, Sending a Joint Agreement using the eSignature REST API.
Let’s take a look at how to set up a Joint Agreements network from the network creator’s (also referred to as the Custodian) account. Any administrator on the account can make the following API call to create a Joint Agreements network on their DocuSign account:
HTTPS POST to https://accountlink-d.docusign.net/v1/primary_accounts/YOUR_ACCOUNT_ID/link_configurations
Scopes required: signature
With the following request body:
{
"configurationName": "Test Joint Agreements Network",
"displayName": "DocuSign Joint Agreements Test Account",
"autoApproveInvitationResponses": "False",
"sendLinkRequestNotification": "SendToAllAdmins",
"pdfFieldHandlingOption": "PrefillAndRecipient",
"recipientAuthRequirements": {
"accessCode": "False",
"phone": "True",
"kba": "False",
"idVerification": "False"
},
"clickwrapId": "",
"clickwrapAgreeEachTime": "True",
"recipientAddress": "A valid user on the account",
"enabled": "True"
}
Let's take a look at what each parameter does:
configurationName
: What this configuration is called internally within your accountdisplayName
: A friendly name that can identify your account in your partners’ connected networksautoApproveInvitationResponses
: If any requests to join your network should be auto-approved or should be sent to the administrators on the account for approvalsendLinkRequestNotification
: If the previous parameter is set totrue
, this parameter dictates if email notifications are sent to the administrators about new requests to join, or if the requests are only viewable on the Web UI.pdfFieldHandlingOption
: What options are available for the way Form Fields can be used on joint agreements in your networkrecipientAuthRequirements
: If recipient authentication is mandatory on joint agreements in your network, and what authentication methods are allowedclickwrapId
: If a clickwrap is to be presented to recipients on each joint agreement sent in your networkclickwrapAgreeEachTime
: If recipients are required to agree to the clickwrap each time they open a new joint agreement enveloperecipientAddress
: A valid recipient on your account that you would like to be added to all joint agreements sent by partnersenabled
: If the network should be enabled immediately upon creation
If successful, the call will return a response like the following.
{
"linkConfigurationId": "98582fcc-1529-xxxx-xxxx-xxxxxxxxxxx",
"configurationName": "Test Joint Agreements Network",
"displayName": "DocuSign Joint Agreements Test Account",
"linkInvitationUrl": "https://accountlink-d.docusign.net/invite/xxxxxxxxxxxxxxxxxxxxxx",
"autoApproveInvitationResponses": "False",
"enforceAutoNavigation": "None",
"enforceSignatureFormat": "None",
"enforceDateTimeFormat": "None",
"allowSignWithMobileDevice": "None",
"enableSignerCommentsInEnvelope": "None",
"sendLinkRequestNotification": "SendToAllAdmins",
"pdfFieldHandlingOption": "PrefillAndRecipient",
"recipientAuthRequirements": {
"accessCode": "False",
"phone": "True",
"kba": "False",
"idVerification": "False"
},
"clickwrapId": "",
"clickwrapAgreeEachTime": "True",
"recipientAddress": "A valid user on the test account",
"lastModified": "2024-03-18T02:45:09Z",
"enabled": "True"
}
The two important parameters returned in this response are the linkConfigurationId
and the linkInvitationUrl
. The linkInvitationUrl
can be shared with any administrator on an account that you would like to ask to join your network. They can access this URL and join from there.
Once joined, the next step is for the network creator to get and share the linkConfigurationId
with all their partners, as the partners would need this parameter in their subsequent API calls.
If you need to retrieve this information again at a later time, you can use the following API call:
HTTPS GET https://accountlink-d.docusign.net/v1/primary_accounts/YOUR_ACCOUNT_ID/link_configurations
Scopes required: signature
This endpoint will return all the “Network Configurations” set up on your account, each having all the details returned in the response above.
We will be exploring how Network Partners can use the linkConfigurationId
to create and send out Joint Agreements in the second part of this series.
You can then use the linkConfigurationId
to create and send out Joint Agreements.
Additional resources
Karan Kaushik
Developer Support Engineer
Related posts