Blog
Home/

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

Karan Kaushik
Karan KaushikDeveloper Support Engineer
Summary4 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

      Table of contents

      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 Kaushik
      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.

      More posts from this author

      Related posts

      • Developer Support Articles

        From the Trenches: Sending a Joint Agreement using the eSignature REST API

        Karan Kaushik
        Karan Kaushik
      • From the Trenches: Sending envelopes asynchronously

        Karan Kaushik
        Karan Kaushik

      From the Trenches: Sending envelopes asynchronously

      Karan Kaushik
      Karan Kaushik

      Discover what's new with Docusign IAM or start with eSignature for free

      Explore Docusign IAMTry eSignature for Free
      Person smiling while presenting