Postman is a platform for building and using APIs. Postman makes it simple to explore, debug, and test APIs, as well as to define complicated API requests for HTTP, REST, SOAP, GraphQL, and WebSockets. The following topics walk you through using Postman Collections for Conga Sign REST APIs:

Getting Started

This topic describes the steps to set up the Postman collections and environments to run the Conga Sign API.

Step1: Import Postman Collections and Environments

  1. Download the Sign.postman_collection.json and Sign Prod.postman_environment.json files for Sign APIs: 

    Sign.postman_collection.json  

    Sign Prod.postman_environment.json

  2. Download the Sign Callback.postman_collection.json and Sign Callback Prod.postman_environment.json files for Sign Callback APIs: 

    Sign Callback.postman_collection.json 

    Sign Callback Prod.postman_environment.json

  3. Import all these files into Postman.

Step 2: Configure Postman Environments 

  1. In the left navigation bar, click the Environments tab .
  2. Configure the environments by populating the following fields for Sign and Sign Callback collections:
    1. AUTH_CUSTOMER_CLIENT_ID: It is an unique AppClient client id. The value must be the same in the both Sign and Sign Callback collection.

    2. AUTH_CUSTOMER_CLIENT_SECRET: It is an unique AppClient client secret. The value must be the same in the both Sign and Sign Callback collection.

  3. Click Persist All and Save. 

Step 3: Configure Postman Collection

  1. In the left navigation bar, click the Collection tab .
  2. In the top right corner, select an environment from the dropdown list from which you want to make request.

Step 4: Register a New Callback URL in Sign Callback

If the callback URL is already registered or if you do not want to receive transaction notifications from Conga Sign, skip this step.

  1. In the top right corner, select the Sign Callback environment from the dropdown list.
  2. You can configure callback using three different types of authentication. For more details on configuring callback, see Using Callbacks.     

Creating a Package

This topic describes the steps to create and send a package for the signature. 

In the top right corner, select the Sign environment from the dropdown list. You must use the Sign Postman collection.

Send "Auth Customer" POST Request

This call retrieves the access token from Conga Sign. The access token is required to make requests on behalf of the configured auth customer. The access token is saved in a postman variable to be used for subsequent requests.

Send "Create Package Without Documents" POST Request

This call creates a package. The minimum requirement of the payload body is a package name. 

{ "name": "A Package Name" }
CODE

The response returns a package ID that is saved in a postman variable to be used for subsequent requests.

Send "Create Role" POST Request

This call adds a new role to an existing package. A role can be a signer in a transaction as shown in the example below. The minimum requirement of the payload body is as follows:

{
  "signers": [
    {
      "firstName": "Signer",
      "lastName": "Name",
      "email": "signer.name@example.com"
    }
  ],
  "name": "Signer Name",
  "type": "SIGNER"
}
CODE

The response returns the role ID, signer ID, signer information provided in the request, and default values of a signer (role). The role ID and signer ID are saved in their own postman variables to be used for subsequent requests.

Send "Create Document" POST Request

This call adds a new document to an existing package. You must provide a document to upload and a payload body for the document. The minimum requirement of the payload body is a document name. 

{ "name": "MyDocumentName" }
CODE

The response returns the document ID, document information provided in the request, and default values of the document. The document ID is saved in its own postman variable to be used for subsequent requests.

Send "Create Approval" POST Request

This call adds a signature field to the document. You can specify the size of the tag and its position in the document. The minimum requirement of the payload body is as follows:

{
  "fields": [
    {
      "value": "MyValue",
      "name": "MyField",
      "type": "SIGNATURE",
      "id": "MyId",
      "page": 0,
      "left": 0,
      "extract": true,
      "subtype": "FULLNAME",
      "width": 200,
      "top": 0,
      "height": 50
    }
  ],
  "role": "{{ROLE_ID}}",
  "optional": false,
  "enforceCaptureSignature": true
}
CODE

The response returns the approval ID, approval information provided in the request, and default values of the approval. The approval ID is saved in its own postman variable to be used for subsequent requests.

Send "Send Package" PUT Request

This call updates the package. The code example below updates the package status from Draft to Sent. The minimum requirement of the payload body is as follows:

{"status": "SENT"}
CODE

The response returns a 204 OK.

Open the Signing Invitation Email and Sign the Document

The signing invitation emails have been sent to the signers at this stage. Once the signers have completed signing you can complete the transaction, if auto complete was turned off while creating the package.

Complete the Transaction as a Sender

When creating a package, if you do not include and set the autocomplete variable to true, the sender must manually complete the transaction after all signers have signed. There are two ways to complete the transaction through API or UI. 

Complete the transaction by executing "Complete Package" PUT Request

This call update the package. The code example below updates the package status from Sent to Completed. The minimum requirement of the payload body is as follows:

{"status": "COMPLETED"}
CODE

The response returns a 204 OK.

Complete the transaction from UI

  1. Open the transaction edit page. For more information on accessing the transaction edit page, see Transaction Edit Page. 
  2. Click the Complete icon on the top right.

Creating Multiple Packages

This topic describes the steps to create and send multiple packages for the signature. 

Prerequisite

  • Enable the bulk send feature in your account.
  • Create an eligible template. A template is considered eligible if it contains at least one document that is not the consent agreement, placeholder role, and signature field.
  • Create a CSV file with recipient details. The file must include placeholder, first name, last name, and email columns.

In the top right corner, select the Sign environment from the dropdown list. You must use the Sign Postman collection.

Send "Auth Customer" POST Request

This call retrieves the access token from Conga Sign. The access token is required to make requests on behalf of the configured auth customer. The access token is saved in a postman variable to be used for subsequent requests. 

Send "Create Package With Documents" POST Request

This call creates a template. You must provide the document(s) to upload and a payload body for the template. An example of the payload body is as follows:

{   
  "name": "My template for bulk send from scratch REST",   
  "visibility": "ACCOUNT",   
  "description": "",   
  "roles": [   
    {   
      "name": "PlaceholderId1",      
      "id": "PlaceholderId1"   
    }
  ],   
  "type": "TEMPLATE",   
  "due": null,   
  "autocomplete": true,   
  "emailMessage": "",   
  "documents": [   
    {   
      "approvals": [   
        {   
          "role": "PlaceholderId1",   
          "fields": [   
            {   
              "page": 0,   
              "subtype": "FULLNAME",   
              "width": 200,   
              "binding": null,   
              "extract": false,   
              "left": 175,   
              "top": 165,   
              "validation": null,   
              "height": 50,   
              "data": null,   
              "type": "SIGNATURE",   
              "value": ""   
            }   
          ]   
        }
      ],   
      "name": "MyDocumentName"   
    }   
  ]   
}
CODE

The response returns package ID that is saved in a postman variable to be used for subsequent requests. 

Send "Create Packages Using Bulk Send" POST Request

This call creates multiple packages in bulk. You must prepare a .csv file of the recipients to upload in the request. An example of the .csv file is as follows: 

Bulk Send List.csv

The response returns a bulk send batch ID. When listing your packages, if a package was created using the bulk send feature, the package details include a bulkSendBatchUid attribute. For example, "bulkSendBatchUid": "67d7c5a7-56d9-41e6-97c7-37831ff086d0". Using the attribute and its ID, you can identify if a package was created using a bulk send request and which bulk send request created the package.

Bulk send transactions are placed in a queue. The queue is checked after every 15 minutes. If new Bulk Send jobs appear, transactions are processed in order until the queue is empty.

Integrating UI Pages

You can integrate the following three UI pages into your application:

  • Transaction Edit page
  • Designer page
  • Signing page

Retrieve Sender Auth Token

An auth token for the sender is required when loading the Transaction Edit or the Designer pages. To retrieve the token, send the Create Sender Auth Token POST request. The resulting value is a token that can be used to load the Transaction Edit or Designer pages.

Transaction Edit Page

After creating a package, you can access the Transaction Edit page by using the auth token and package ID obtained while retrieving the auth token. To open the Transaction Edit page, substitute these values for the ones shown in the following URL and enter them in your browser.

{{BASE_URL}}/?senderTransactionEditToken=MWY2MGUxYzktOWYxZC00NzYyLWFiYzYtOWQwMmI5MDhkMbOb&packageId=3HTX-GSQwB0NpumbRtDq4XNO35s=
CODE
The Transaction Edit Page can only be accessed while the package is in the Draft status (not yet sent). It is the only status that allows the administrator to edit the package before sending it to signers.

Designer Page

After creating a package, you can access this page by using the auth token and package ID obtained while retrieving the auth token. To open the Designer page, substitute these values for the ones shown in the following URL and enter them in your browser.

{{BASE_URL}}/?senderDesignerToken=MWY2MGUxYzktOWYxZC00NzYyLWFiYzYtOWQwMmI5MDhkMbOb&packageId=3HTX-GSQwB0NpumbRtDq4XNO35s=
CODE

The Designer page can only be accessed while the package is in the Draft status (not yet sent). It is the only status that allows the administrator to edit the package before sending it to signers.

Signing Page

After creating and sending a package, you can access this page with the login token or without it.

The Signing page can only be accessed while the package is in the Sent status.

Accessing the Signing Page Using the "Get Signing URL GET" request

Send the Get Signing URL request. To open the Signing page, enter the URL into your browser. The URL and its token never expires. Use this URL when sending an email to the user to sign the document.

Accessing the Signing Page Using the Package and Signer IDs

Send the Get Package request to get the signer's package ID and signer ID to access the Signing page. Copy and paste these values in the URL below. To open the Signing page, enter the URL into your browser. As there is no token, this URL never expires. Use this URL when embedding the signing page in your application.

{{BASE_URL}}/?signerId=51060790-a44e-4e03-9732-5983aca9bdd2&packageId=3HTX-GSQwB0NpumbRtDq4XNO35s=
CODE

Best Practices 

Using Callbacks

Callback event notifications allow you to be automatically notified of events that are related to a package or transactions. When a specific event occurs, the system automatically sends a message to a destination that you specify. This avoids the constant querying for status updates.

Use the following example of a callback endpoint to handle Conga Sign notifications:

using System;
using System.Diagnostics.CodeAnalysis;
using System.Net.Mime;
using System.Threading.Tasks;
using congasign.Application.Models;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using ControllerBase = Conga.AspNetCore.Mvc.ControllerBase;

namespace congasign.Web.ESignature.Controllers;

/// <summary>
/// The API that handles callbacks from Conga Sign. An example of how to handle callbacks from Conga Sign.
/// </summary>
[ApiController]
[Route("v1")]
[Consumes(MediaTypeNames.Application.Json)]
[Produces(MediaTypeNames.Application.Json)]
[AllowAnonymous]
[ExcludeFromCodeCoverage]
public class ESignatureCallbackController : ControllerBase
{
    private readonly ILogger<ESignatureCallbackController> _logger;

    /// <summary>
    /// ESignatureCallbackController
    /// </summary>
    public ESignatureCallbackController(ILogger<ESignatureCallbackController> logger)
    {
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
    }

    /// <summary>
    /// Handle callback. An example of how to handle callbacks from Conga Sign.
    /// </summary>
    /// <remarks>
    /// Helpful conga sign resource around events.
    /// <para>
    /// https://community.onespan.com/documentation/onespan-sign/guides/feature-guides/developer/setting-callback-notifications
    /// </para>
    /// </remarks>
    /// <param name="signEvent"></param>
    /// <returns></returns>
    [HttpPost]
    [Route("callback")]
    [ProducesResponseType(StatusCodes.Status204NoContent)]
    public async Task<IActionResult> HandleCallback([FromBody] CongaSignEvent signEvent)
    {
        if ("PACKAGE_COMPLETE".Equals(signEvent.name) // A package has completed the signing process. If there are multiple signers then the "sessionUser": "...", will be the signer ID of the last signer to sign.
            || "PACKAGE_ACTIVATE".Equals(signEvent.name) // A package was moved from the status DRAFT or DELETED to the status SENT. By default, a package is created in the DRAFT state, and is moved to the SENT state when it's ready to be processed by signers.
            || "PACKAGE_DECLINE".Equals(signEvent.name) // A recipient has declined to sign a package, and has specified a reason for doing so.
            || "PACKAGE_EXPIRE".Equals(signEvent.name) // A package has exceeded its expiration date.
            || "SIGNER_COMPLETE".Equals(signEvent.name) // A signer has completed signing all documents.
            || "ROLE_REASSIGN".Equals(signEvent.name)) // A signer has delegated their signature to another signer.
        {
            _logger.LogInformation(string.Format("A sign event of interest: {0}", JsonConvert.SerializeObject(signEvent)));
        }
        return new NoContentResult();
    }
}
CODE

When making calls to the callback endpoint, Conga Sign supports three types of authentication: Bearer, Basic, and None.

In the top right corner, select the Sign Callback environment from the dropdown list. You must use the Sign Callback Postman collection.

Send "Auth Customer" POST Request

This call retrieves the access token from Conga Sign. The access token is required to make requests on behalf of the configured auth customer. The access token is saved in a postman variable to be used for subsequent requests. 

Send "Callback Registration Bearer Auth" PUT Request

This call configures:

  • The callback endpoint that Conga Sign will use.
  • The bearer authorization used as part of the callback endpoint request.
Authorization: Bearer <Your Bearer Token>
CODE 
{
    "callbackUrl":"https://webhook.site/98d89f37-deff-49fc-945c-25a18554b9d1",
    "bearerToken":"<Your Bearer Token>",
    "authType": "Bearer"
}
CODE

Send "Callback Registration Basic Auth" PUT Request

This call configures:

  • The callback endpoint that Conga Sign will use.
  • The basic authorization used as part of the callback endpoint request.
Authorization: Basic <credentials>
CODE 
{
    "callbackUrl":"https://webhook.site/98d89f37-deff-49fc-945c-25a18554b9d1",
    "authType": "Basic",
    "username": "<Your Username>",
    "password": "<Your Password>"
}
CODE

Send "Callback Registration No Auth" PUT Request

This call configures the callback endpoint that Conga Sign will use without any authentication.

{
    "callbackUrl":"https://webhook.site/98d89f37-deff-49fc-945c-25a18554b9d1",
    "authType": "None"
}
CODE

Receiving Callbacks

Conga Sign makes a call to the configured “callbackUrl” with the following payload:

{ 
  "name": "PACKAGE_COMPLETE",
  "sessionUser": "{{GUID}}",
  "packageId": "{{PACKAGE_ID}}", 
  "message": null,
  "documentId": null 
}
CODE

The following are the possible event name values in the payload:

  • DOCUMENT_SIGNED: A document is signed, or consent and/or disclosure agreements are accepted.
  • DOCUMENT_VIEWED: A document is viewed.
  • EMAIL_BOUNCE: An email has bounced. The bounce types are: Bounce, Complaint, Ooto, Unknown.
  • KBA_FAILURE: A knowledge-based authentication (KBA) failure has occurred.
  • PACKAGE_ACTIVATE: A package's status is changed from Draft or Deleted to Sent. By default, a package is created in the Draft state. When a package is ready to be processed by signers, its status changes to Sent.
  • PACKAGE_ARCHIVE: A callback notification indicates that a package has been archived.
  • PACKAGE_ATTACHMENT: A callback notification indicates that a signer has uploaded an attachment.
  • PACKAGE_COMPLETE: The package signing process is completed. If there are multiple signers, the "sessionUser": "...", is the last signer's signer ID to sign.
  • PACKAGE_CREATE: A package has been created.
  • PACKAGE_DEACTIVATE: A package's status is changed from Sent to Draft.
  • PACKAGE_DECLINE: A recipient has declined to sign a package with a reason.
  • PACKAGE_DELETE: A package has been deleted.
  • PACKAGE_EXPIRE: A package has exceeded its expiration date.
  • PACKAGE_READY_FOR_COMPLETE: A package has been marked as DO_NOT_AUTOCOMPLETE. The sender must take an action to complete the package.
  • PACKAGE_RESTORE: A package is restored from the trash status.
  • PACKAGE_TRASH: A package is moved to the trash folder (status = Trash).
  • ROLE_REASSIGN: A signer has delegated signature authority to another signer.
  • SIGNER_COMPLETE: A signer has completed signing all documents.
  • SIGNER_LOCKED: A callback notification indicates that a signer has been locked out due to repeated SMS/Q&A authentication failures.
  • TEMPLATE_CREATE: A callback notification indicates that a template has been created.

Using Templates and Layouts

Templates and layouts fulfill the same goal of automating the eSignature process by minimizing the time required to send documents that include several signature blocks and data fields. Templates are ideal to use at the transaction level: you can predefine your signers, documents, signature locations and eSignature workflows to streamline the eSignature process. A Layout, on the other hand, is a type of template that allows you to create predefined locations for your signature blocks and data fields within a document. It acts like a marker where signature blocks and data fields will sit in the document. Layouts are helpful when you send forms that may differ slightly by recipient but signature blocks and data fields remain in the same location throughout the document. You can use multiple layouts per document, and apply them to individual pages within your transaction.

In the top right corner, select the Sign environment from the dropdown list. You must use the Sign Postman collection.

Send "Auth Customer" POST request

This call retrieves the access token from Conga Sign. The access token is required to make requests on behalf of the configured auth customer. The access token is saved in a postman variable to be used for subsequent requests. 

Send "Create Package With Documents" POST request

This call creates a template. You must provide the document(s) to upload and a payload body for the template. Here is an example payload body:

{   
  "name": "My template from scratch REST",   
  "visibility": "ACCOUNT",   
  "description": "",   
  "roles": [   
    {   
      "name": "PlaceholderId1",   
      "index": 0,   
      "id": "PlaceholderId1"   
    },   
    {   
      "name": "PlaceholderId2",   
      "index": 0,   
      "id": "PlaceholderId2"   
    }   
  ],   
  "type": "TEMPLATE",   
  "due": null,   
  "autocomplete": true,   
  "emailMessage": "",   
  "documents": [   
    {   
      "approvals": [   
        {   
          "role": "PlaceholderId1",   
          "fields": [   
            {   
              "page": 0,   
              "subtype": "FULLNAME",   
              "width": 200,   
              "binding": null,   
              "extract": false,   
              "left": 175,   
              "top": 165,   
              "validation": null,   
              "height": 50,   
              "data": null,   
              "type": "SIGNATURE",   
              "value": ""   
            }   
          ]   
        },   
        {   
          "role": "PlaceholderId2",   
          "fields": [   
            {   
              "page": 0,   
              "subtype": "FULLNAME",   
              "width": 200,   
              "binding": null,   
              "extract": false,   
              "extractAnchor": null,   
              "left": 550,   
              "top": 165,   
              "validation": null,   
              "height": 50,   
              "data": null,   
              "type": "SIGNATURE",   
              "value": ""   
            }   
          ]   
        }   
      ],   
      "name": "MyDocumentName"   
    }   
  ]   
}
CODE

The response returns package ID that is saved in a postman variable to be used for subsequent requests. 

Create a Package Using a Template

Get the package ID for the template you want to use for your transaction.

Send "List Packages" GET request

Append &type=TEMPLATE at the end of the URL. You will only get packages of the template type.

Send "Clone Package" POST request

In the URL, replace {{PACKAGE_ID}} with the package ID. An example of the payload body is as follows:

{   
   "name":"Package created from template through REST API",   
   "autocomplete":true,   
   "type":"PACKAGE",   
   "status" : "SENT",   
   "roles": [   
     {   
       "id": "PlaceholderId1",   
       "type": "SIGNER",   
       "signers": [   
         {   
           "id": "PlaceholderId1",   
           "firstName": "Signer",   
           "lastName": "One",   
           "email": "signer.one@example.com"   
         }   
      ],   
      "name": "Signer One"   
    },
    {   
       "id": "PlaceholderId2",   
       "type": "SIGNER",   
       "signers": [   
         {   
           "id": "PlaceholderId2",   
           "firstName": "Signer",   
           "lastName": "Two",   
           "email": "signer.two@example.com"   
         }   
      ],   
      "name": "Signer Two"   
    }
  ]   
}
CODE

Use a single request when creating a package

In the Creating a Package topic, multiple requests are made to create a package for example purposes. Do not make multiple requests, when creating a package. If creating packages with templates does not make sense, create and send a package in one request with the following endpoint.

Send "Create Package With Documents" POST request

All the package details, including setting the package's status to Sent, can be included in the json payload. Setting the status to Sent sends the package to the configured recipients. The documents are included in the request. The following request includes all of the details from the Creating a Package topic.

{
  "name": "A Package Name",
  "roles": [
    {
      "signers": [
        {
          "firstName": "Signer",
          "lastName": "Name",
          "email": "signer.name@example.com"
        }
      ],
      "name": "Signer Name",
      "type": "SIGNER",
      "id": "SignerNameRoleId"
    }
  ],
  "status": "SENT",
  "autocomplete": true,
  "documents": [
    {
      "name": "MyDocumentName",
      "approvals": [
        {
          "fields": [
            {
              "value": "MyValue",
              "name": "MyField",
              "type": "SIGNATURE",
              "id": "MyId",
              "page": 0,
              "left": 0,
              "extract": true,
              "subtype": "FULLNAME",
              "width": 200,
              "top": 0,
              "height": 50
            }
          ],
          "role": "SignerNameRoleId",
          "optional": false,
          "enforceCaptureSignature": true
        }
      ]
    }
  ]
}
CODE