From the Trenches: Setting up a Joint Agreement Network using the eSignature REST API

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 account

• displayName: A friendly name that can identify your account in your partners’ connected networks

• autoApproveInvitationResponses: If any requests to join your network should be auto-approved or should be sent to the administrators on the account for approval

• sendLinkRequestNotification: If the previous parameter is set to true, 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 network

• recipientAuthRequirements: If recipient authentication is mandatory on joint agreements in your network, and what authentication methods are allowed 

• clickwrapId: If a clickwrap is to be presented to recipients on each joint agreement sent in your network

• clickwrapAgreeEachTime: If recipients are required to agree to the clickwrap each time they open a new joint agreement envelope

• recipientAddress: A valid recipient on your account that you would like to be added to all joint agreements sent by partners

• enabled: 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

• Docusign Developer Center

• Docusign Developers Community

• @DocusignDevs on X

• Docusign for Developers on LinkedIn

• Docusign for Developers on YouTube

• Docusign Developer Newsletter