Blog
Home/

Common API Tasks🐈: Use a transactionId to find the envelope you created

Inbar Gazit
Inbar GazitSr. Manager, Developer Content
Summary3 min read

See how to use the eSignature REST API apply a transactionId to envelopes you create, and then use that transactionId to find them later.

    • C#
    • Java
    • Node.js
    • PHP
    • Python
    • Ruby
    • Additional resources

    Table of contents

    Common API Tasks: Use a transactionId to find the envelope you created

    Welcome to a stellar new edition of the CAT🐈 (Common API Tasks) blog series. The CAT blogs provide all you need to complete small, specific, SDK-supported tasks using one of our APIs. You can find all articles in this series on the Docusign Developer Blog.

    In this post, I’m going to show you a useful technique to locate envelopes that your integration created in situations where you didn’t receive a response from the Docusign eSignature REST API. (Typically, that response includes the envelopeId**,** which is the unique identifier primarily used to locate an envelope in the Docusign platform.)

    Why, you might ask, would you not have the API response available to your application? I can think of several reasons this may occur. First, in a situation where the internet connection is slow or unavailable, you may be able to create the envelope, but you will not be able to receive a timely response to your API call. Second, when you create an envelope containing a large document, the processing of the API may take longer than usual, and your application may choose to make the call asynchronously instead of waiting for the response from the server. Lastly, you may run code that creates a large number of envelopes one after the other, and you may wish to make it more efficient, by not waiting for a response for each envelope before you create the next one. In that case, your application will also not have the information about the envelopeId readily available to be used later.

    This is where the transactionId property comes in handy. This string is one that your application chooses. You can use any string you wish. I would recommend using something unique within the system that your application manages (using GUIDs is a common way to ensure uniqueness). These special identifiers are added to the createEnvelope call that your application makes such that you can later use them to get the information about that envelope. You do that by using the listStatus endpoint and providing one or more transactionIDs to locate the envelope(s) you previously created. Note that the transactionIDs are stored in the system for seven days only and do not have to be unique across accounts (meaning that if you and I use different accounts, we can use the same transactionId without an issue.)

    Note: Before I show you how to do this in code, I want to warn you about the polling technique I use here. It is not the intention of this blog post to suggest you should use polling to query the status of your envelope. You should use a Connect webhook instead and get information about the envelope without having to poll Docusign for the latest status of the envelope. The purpose of this blog post is just to show you how you can utilize a transactionId of your choosing to find the envelope you created later. 

    The code snippets here show two things. First, I will briefly show how to add a transactionId when you create an envelope. The little snippet doesn’t show you all the code to create an envelope; see How to request a signature by email for complete code to create an envelope. Second,  I will show you how to find the envelope that was created with the transactionId previously. 

    C#

    DocuSignClient docuSignClient = new DocuSignClient(basePath);
    // You will need to obtain an access token using your chosen authentication method
    docuSignClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken);
    // Create an envelope
    EnvelopeDefinition envelope = new EnvelopeDefinition();
    envelope.TransactionId = "test-from-CAT-blog";
    // ... Rest of the code to create an envelope...
    
    // Find the envelope and its envelopeId
    EnvelopesApi envelopesApi = new EnvelopesApi(docuSignClient);
    EnvelopeIdsRequest envelopeIdsRequest = new EnvelopeIdsRequest();
    EnvelopesApi.ListStatusOptions options = new EnvelopesApi.ListStatusOptions();
    options.transactionIds = "test-from-CAT-blog"; // Use a comma if you need more than one
    EnvelopesInformation envelopesInformation  = envelopesApi.ListStatus(accountId, envelopeIdsRequest, options);
    string myEnvelopeId = envelopesInformation.Envelopes[0].EnvelopeId;
    
    

    Java

    Configuration config = new Configuration(new ApiClient(basePath));
    // You will need to obtain an access token using your chosen authentication method
    config.addDefaultHeader("Authorization", "Bearer " + accessToken);
    // Create an envelope
    EnvelopeDefinition envelope = new EnvelopeDefinition();
    envelope.setTransactionId("test-from-CAT-blog");
    // ... Rest of the code to create an envelope...
    
    // Find the envelope and its envelopeId
    EnvelopesApi envelopesApi = new EnvelopesApi(config);
    EnvelopeIdsRequest envelopeIdsRequest = new EnvelopeIdsRequest();
    EnvelopesApi.ListStatusOptions options = envelopesApi.new ListStatusOptions();
    options.setTransactionIds("test-from-CAT-blog"); // Use a comma if you need more than one
    EnvelopesInformation envelopesInformation  = envelopesApi.ListStatus(accountId, envelopeIdsRequest, options);
    string myEnvelopeId = envelopesInformation.getEnvelopes().get(0).getEnvelopeId();
    
    

    Node.js

    let dsApiClient = new docusign.ApiClient();
    dsApiClient.setBasePath(basePath);
    // You will need to obtain an access token using your chosen authentication method
    dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + accessToken);
    // Create an envelope
    EnvelopeDefinition envelope = new EnvelopeDefinition();
    envelope.transactionId = 'test-from-CAT-blog';
    // ... Rest of the code to create an envelope...
    
    // Find the envelope and its envelopeId
    let envelopesApi = new EnvelopesApi(dsApiClient);
    let envelopesInformation  = envelopesApi.listStatus(accountId, {'transactionIds' : 'test-from-CAT-blog'}); // Use a comma if you need more than one
    let myEnvelopeId = envelopesInformation.envelopes[0].envelopeId;
    
    

    PHP

    $api_client = new \Docusign\eSign\client\ApiClient($base_path);
    $config = new \Docusign\eSign\Model\Configuration($api_client);
    # You will need to obtain an access token using your chosen authentication method
    $config->addDefaultHeader('Authorization', 'Bearer ' + $access_token);
    # Create an envelope
    $envelope = new EnvelopeDefinition();
    $envelope->setTransactionId('test-from-CAT-blog');
    # ... Rest of the code to create an envelope...
    
    # Find the envelope and its envelopeId
    $envelopes_api = new \Docusign\eSign\Api\EnvelopesApi($api_client);
    $envelope_ids_request = new \Docusign\eSign\Model\EnvelopeIdsRequest();
    $options = new ListStatusOptions();
    $options->setTransactionIds('test-from-CAT-blog'); # Use a comma if you need more than one
    $envelopes_information = $envelopesApi->ListStatus($account_id, $envelope_ids_request, $options);
    $my_envelope_id = envelopesInformation->getEnvelopes()[0]->getEnvelopeId();
    
    

    Python

    api_client = ApiClient()
    # You will need to obtain an access token using your chosen authentication method
    api_client.set_default_header('Authorization', 'Bearer ' + access_token)
    # Create an envelope
    envelope = new EnvelopeDefinition();
    envelope.transactionId = 'test-from-CAT-blog'
    # ... Rest of the code to create an envelope...
    
    # Find the envelope and its envelopeId
    envelopes_api = EnvelopesApi(api_client)
    envelope_ids_request = EnvelopeIdsRequest()
    options = ListStatusOptions()
    options.transaction_ids = 'test-from-CAT-blog' # Use a comma if you need more than one
    envelopes_information  = envelopes_api.list_status(account_id, envelope_ids_request, options)
    my_envelope_id = envelopes_information.envelopes[0].envelope_id
    
    

    Ruby

    config = DocuSign_eSign::Configuration.new
    config.host = base_path
    api_client = DocuSign_eSign::ApiClient.new config
    # You will need to obtain an access token using your chosen authentication method
    api_client.DefaultHeader['Authorization'] = 'Bearer ' + access_token
    # Create an envelope
    envelope = new EnvelopeDefinition();
    envelope.transactionId = 'test-from-CAT-blog'
    # ... Rest of the code to create an envelope...
    
    # Find the envelope and its envelopeId
    envelopes_api = DocuSign_eSign::EnvelopesApi.new api_client
    envelope_ids_request = DocuSign_eSign::EnvelopeIdsRequest.new
    options = DocuSign_eSign::ListStatusOptions.new
    options.transaction_ids = 'test-from-CAT-blog' # Use a comma if you need more than one
    envelopes_information  = envelopes_api.list_status(account_id, envelope_ids_request, options)
    my_envelope_id = envelopes_information.envelopes[0].envelope_id
    
    

    Additional resources

    Inbar Gazit
    Inbar GazitSr. Manager, Developer Content

    Inbar Gazit has been with Docusign since 2013 in various engineering roles. Since 2019 he has focused on developer content. Inbar works on code examples including the launchers, available on GitHub in eight languages, and helps build sample apps showcasing the various Docusign APIs. He is also active on StackOverflow, answering your questions. Inbar can be reached at inbar.gazit@docusign.com.

    More posts from this author

    Related posts

    • Developer Spotlight

      Developer Spotlight is Coming to Docusign Community!

      Matthew Lusher
      Matthew Lusher
    • Breaking the Language Barrier: Why Large Language Models Need Open Text Formats

      Dan Selman
      Dan Selman
    • Understanding Levenshtein Distance: Applications to AI-Generated Text

      Vincent Pan
      Vincent Pan

    Developer Spotlight is Coming to Docusign Community!

    Matthew Lusher
    Matthew Lusher

    Understanding Levenshtein Distance: Applications to AI-Generated Text

    Vincent Pan
    Vincent Pan

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

    Explore Docusign IAMTry eSignature for Free
    Person smiling while presenting