How to call the Navigator API from Agentforce for smarter agreements

Quick Answer: To call the Navigator API from Agentforce, create an Apex class with an @InvocableMethod annotation that makes HTTP requests using named credentials, then configure it as a custom agent action in Salesforce Setup and add it to your agent's topic.

As AI agents become integral to everyday business practices, developers need to understand how to configure agents that can integrate business systems across different platforms.

Integrations aren’t new to Docusign developers; many developers are already integrating Docusign and Salesforce through tools like the Apex Toolkit and the Salesforce extension app. But with Salesforce’s Agentforce Opens in a new tab, and the Navigator API, these integrations can go further. The Navigator API provides programmatic access to AI-extracted data from Docusign's smart agreement repository. Agentforce is Salesforce's platform for building AI-powered conversational agents.

In my last blog post, I explained how to set up Salesforce authentication with JWT to access any Docusign API. In this post, I'll show you how to build on that and use that authentication to call the Navigator API from inside Agentforce with a custom agent action Opens in a new tab. This will enable your agents to access data from the Navigator smart agreement repository, extracting key information about your contracts and taking your integration beyond eSignature.

Prerequisites

Before you begin, ensure you have the following:

1. A Salesforce org with Agentforce enabled

2. A docusign developer account with access to the Navigator API (currently in Limited Availability) 

3. JWT authentication configured via named credentials (see prerequisite blog post)

4. Apex development permissions in your Salesforce org

How do I write the Apex class for Navigator API calls?

Before you can configure an Agentforce agent to call the Navigator API, you’ll need to write an Apex class that makes the correct HTTP request. Because the method you’ll be defining in this class needs to include the InvocableMethod Opens in a new tab annotation to be callable from Agentforce, which means the class must be an outer class — it can't be nested within another class. The @InvocableMethod annotation marks a method as callable from Agentforce, Flow Builder, and other declarative Salesforce tools, enabling no-code invocation of custom Apex logic. The method itself should be public static.

When adding the annotation, include a clear label and description; Agentforce uses these to recognize your action. In this example, the agent takes the API account ID as an input, so the method needs to accept that GUID as a parameter. Invocable methods can only accept parameters as a list, so you'll need to define an sObject Opens in a new tab as an inner class representing that parameter. They can also only return lists, so you'll do the same for the return object. The snippet below shows how to start defining the methods and inner classes for this example.

public class NavigatorCallout {

  //This method calls the Docusign Navigator API
  @InvocableMethod (label='Get a single Navigator Agreement' description='Calls the Navigator API to get an agreement')
  public static List<NavigatorResponse> getAgreement(List<NavigatorRequest> navigatorRequests){

  }
    
  public class NavigatorRequest {
    @InvocableVariable
    public String accountId;
  }

  public class NavigatorResponse {
    @InvocableVariable
    public String data;
  }
}

Now that you’ve set up your class and method definitions, you can make an API call. To do this, create an HttpRequest Opens in a new tab object inside the invocable method that you defined previously. Then, use the setEndpoint and setHeader methods to define the header and endpoint for the request. In this case, you’ll call the Agreements: getAgreement endpoint to retrieve detailed information about a specific agreement. Because authentication has already been set up through named credentials (as explained in this blog post), you can use callout:{NAMED_CREDENTIAL_NAME} in place of the endpoint’s base path. This example demonstrates how to take the account ID from the parameter and hard-code the agreement ID into the request, but you could define any inputs and outputs you need. Finally, return the response from the API call in the data property of the inner class that you created previously.

When you're done, your class will look something like this:

public class NavigatorCallout {
  //This method calls the Docusign Navigator API
  @InvocableMethod (label='Get a single Navigator Agreement' description='Calls the Navigator API to get an agreement')
  public static List<NavigatorResponse> getAgreement(List<NavigatorRequest> navigatorRequests){
    List<NavigatorResponse> responseList = new List<NavigatorResponse>();
    for (NavigatorRequest request : navigatorRequests) {
      // Create the HTTP request to call Docusign's API
      HttpRequest req = new HttpRequest();
      req.setEndpoint('callout:Navigator' + request.accountId + '/agreements/abd1472b-xxxx-xxxx-xxxx-29e834e14cee');
      req.setMethod('GET');
      req.setHeader('Content-Type', 'application/json');
      
      // Send the request
      Http http = new Http();
      HTTPResponse res = http.send(req);
      
      // Parse the JSON response
      NavigatorResponse response = new NavigatorResponse();
      Map<String, Object> jsonResponse = (Map<String, Object>)JSON.deserializeUntyped(res.getBody());
      Object dataObj = jsonResponse;
      response.data = dataObj != null ? JSON.serialize(dataObj) : '';
      System.debug(response);
      responseList.add(response);
      
      System.debug(responseList);
      System.debug(responseList[0].data);
    }
    return responseList;
  }
    
  public class NavigatorRequest {
    @InvocableVariable
    public String accountId;
  }

  public class NavigatorResponse {
    @InvocableVariable
    public String data;
  }
}

How do I configure the Agentforce agent?

Once you have a working Apex class, you’re ready to turn that class into a custom action Opens in a new tab for an AI agent. In Salesforce Setup, navigate to Agentforce Assets, choose the Actions tab, and select New Agent Action (figure 1).

Figure 1: Creating a new Agent Action

In the pop-up window (figure 2), specify the reference action type and category. Choose Apex for the type and Invocable Methods for the category. Then select the Apex class you just created by choosing the label that matches the @InvocableMethod annotation in your class.

Figure 2: Create an Agent Action popup window

Next, configure the inputs and outputs for the action. The inputs and outputs shown in figure 3 were populated based on the parameters and return objects of the Apex class. Fill in the text fields with instructions for how the agent should handle these values. Check the boxes for Require input and Collect data from user under the accountId input so the agent knows to request that value in the conversation. You can also instruct the agent to format the JSON response in a human-readable way before displaying it.

Figure 3: Configuring the inputs and outputs for the action

Next, add this action to a topic Opens in a new tab in my agent. This is where you can give the agent instructions on how to handle the action. In the Agentforce Builder, choose Topics in the left menu and select New to create a new topic (figure 4).

Figure 4: Creating a new topic

You'll be prompted to add instructions for the agent and attach actions to the topic. Select the action you created and add it to the topic. When configured, your topic details should look something like figure 5. Instructions are key here — be specific, for example: "Always ask the user for an account ID." This is also where you can instruct the agent on how to respond to different user prompts.

Figure 5: Setting topic details

Keep in mind that these instructions are nondeterministic — you may need to experiment with different prompts to understand how the agent actually behaves. You can test prompts in the conversation preview in Agentforce Builder. Figure 6 shows a sample conversation where the agent returns agreement details using the Navigator API. When the user asks about their agreement, the agent requests an account ID, makes the API call via the Apex class, and formats the JSON response in a readable way rather than returning raw JSON.

Figure 6: Sample conversation

This is just one example of how you can leverage Docusign APIs from within Agentforce. With the Docusign IAM platform, there are countless other possibilities. For example, you might ask the agent to trigger a workflow with the Maestro API, or to send an envelope with the Connected Fields API. Or you can integrate eSignature functionality into your agents with the help of the Apex Toolkit. AI agents are powerful tools that are even more powerful when they can operate across platforms. Integrating Docusign into Agentforce unlocks new potential for agents to do even more and create a seamless experience for your users.

What else can I build with Agentforce and Docusign APIs?

This is one example of how you can use Docusign APIs from within Agentforce. The Navigator API is the right fit when you need to retrieve AI-extracted agreement data and metadata from your contract repository.

For other use cases, consider the eSignature API or Apex Toolkit for sending and managing signature requests, the Maestro API for orchestrating complex agreement workflows, or the Connected Fields API for syncing agreement data with external systems. With the Docusign IAM platform, there are many other directions you can take this. AI agents are most powerful when they can operate across platforms.

After completing these steps, your Agentforce agent can retrieve agreement details from Docusign Navigator through authenticated API calls. Consider extending this pattern to trigger workflows or send envelopes to build a more comprehensive agreement automation solution.

To go deeper and learn how to sync Navigator data into structured Salesforce fields and generate AI-powered agreement health checks, read How to Ground Agentforce with Docusign Navigator Agreement Data.

Additional resources

• How to set up Salesforce authentication with JWT to access any Docusign API

• Configuring Salesforce for scalable and secure Docusign integrations

• Apex Toolkit overview

• Navigator API overview