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

•

Summary•4 min read

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.

Additional resources

Additional resources

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

Karan KaushikDeveloper Support Engineer

Karan Kaushik began his Docusign career in January 2022. As a front-line developer support engineer, Karan enjoys working on complex technical problems. He is passionate about using technology to make people's day-to-day lives easier and simpler, leveraging his array of experience across information technology, cloud operations, and software development.