Connect Namely to AI Agents: Automate Employee Feeds and Job Tiers

You want to connect Namely to an AI agent so your system can independently onboard employees, broadcast announcements to the company feed, and extract live HR reports based on historical context. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to write custom integration code and maintain fragile OAuth lifecycles.

Giving a Large Language Model (LLM) read and write access to your core HRIS platform is an engineering challenge. You either spend weeks building, hosting, and maintaining a custom connector, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Namely to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Namely to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for Namely, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex HR automation workflows. For a deeper look at the architecture behind this approach, refer to our research on architecting AI agents and the SaaS integration bottleneck.

The Engineering Reality of the Namely API

Giving an LLM access to external HR data sounds simple in a prototype. You write a Node.js function that makes a fetch request and wrap it in an @tool decorator. In production against complex HR systems, this approach collapses quickly.

Namely's API introduces several specific integration challenges that break standard REST assumptions. If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code instead of improving your model's reasoning capabilities.

The Profiles Array Wrapping Requirement

Standard REST APIs typically accept a single JSON object when creating or updating a single record. For example, sending POST /users with {"first_name": "John"}. Namely does not follow this pattern for its core objects. When you create or update a profile in Namely, the payload must be wrapped inside a profiles array within the request body, even if you are only operating on a single employee record. If an LLM assumes standard REST behavior and sends a flat object, the API will reject it. Your tool layer must strictly define this nested array structure in its JSON schema so the model generates the correct payload shape every single time.

Effective-Dated Fields

HR data is rarely static. In Namely, fields like salary, job title, and reporting structure (reports_to) are effective-dated. You cannot simply patch a profile's salary string without considering the timeline. When you push these updates through the API, the system is recording an event that occurs at a specific point in time (often defaulting to the start date). If your agent updates a job title without the proper contextual understanding of these effective dates, it can silently overwrite historical records or create disjointed employee timelines.

Positional Array Structures in Reports

One of the most valuable endpoints in Namely is get_single_namely_report_by_id, which returns live HR data. However, the response format is notoriously hostile to LLMs. Instead of returning a clean array of objects (e.g., [{"First Name": "Jane", "Last Name": "Doe"}]), Namely returns a metadata object containing an ordered array of columns, and a separate content array of rows where values map positionally to the columns.

It looks like this:

{
  "columns": [{"name": "First Name"}, {"name": "Last Name"}],
  "content": [["Jane", "Doe"], ["John", "Smith"]]
}

If you feed this raw positional array to an LLM, it frequently hallucinates which index belongs to which column as the context window grows. The agent needs a tool definition that correctly sets expectations for this schema, allowing it to programmatically zip the arrays together if it intends to analyze the data row by row.

Fetching Namely Tools via Truto

A unified tool layer collapses these API quirks behind strict schemas. Your agent interacts with predefined function names like list_all_namely_profiles or create_a_namely_event.

Every integration on Truto represents how an underlying product's API behaves. Integrations have a concept of Resources (which map to the endpoints on Namely's API) and Methods (the operations on those resources, like List, Create, Update). These Methods operate as Proxy APIs, where Truto handles all pagination, authentication, and query parameter processing.

Truto provides a set of tools for your LLM frameworks by offering a description and schema for all the Methods defined on the Resources for an integration. By calling the /integrated-account/<id>/tools endpoint, Truto returns all of these Proxy APIs with their descriptions and schemas, creating Tools that LLM frameworks can consume directly.

Connecting Truto to Your Agent Framework

Whether you are using LangChain, LangGraph, or Vercel AI SDK, binding these tools takes only a few lines of code. Here is how you initialize the Truto toolset using our LangChain.js SDK.

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "truto-langchainjs-toolset";
 
async function runAgent() {
  // 1. Initialize the LLM
  const model = new ChatOpenAI({ 
    modelName: "gpt-4o",
    temperature: 0 
  });
 
  // 2. Initialize the Truto Tool Manager with your Namely integrated account ID
  const toolManager = new TrutoToolManager({
    trutoApiKey: process.env.TRUTO_API_KEY,
    integratedAccountId: "your_namely_integrated_account_id"
  });
 
  // 3. Fetch all available Namely tools
  const tools = await toolManager.getTools();
  
  // 4. Bind the tools to the model
  const modelWithTools = model.bindTools(tools);
 
  // The agent is now ready to autonomously execute Namely operations
  console.log(`Successfully bound ${tools.length} Namely tools to the agent.`);
}

Hero Tools for Namely

When building HR agentic workflows, you do not need to expose the entire surface area of the Namely API. By selecting high-leverage tools, you minimize the LLM's cognitive load and reduce the chance of hallucination. Here are the most powerful Namely tools to expose to your agent.

1. list_all_namely_profiles

This is the core discovery tool for your agent. It allows the LLM to search for employees by first name, last name, email, job title, or user status.

Usage Note: The agent must pass filters in the format filter [email] or filter [job_title]. This tool is strictly rate limited by Namely to 100 requests per minute.

"Find the active profile for the employee with the email address j.smith@example.com and return their Namely ID and current job title."

2. create_a_namely_profile

This tool allows the agent to onboard new employees. The LLM must supply at least the first name, last name, email, and user status.

Usage Note: The agent must format the payload by placing the data inside a profiles array. If your organization uses the Onboarding feature, the agent can create this profile as a draft session by passing the appropriate onboarding fields.

"We just hired Sarah Jenkins as a Senior Product Manager. Her start date is next Monday. Create an active profile for her using the email s.jenkins@ourcompany.com."

3. update_a_namely_profile_by_id

This tool modifies existing employee records. It is critical for automated promotion workflows, organizational restructuring, or simple data corrections.

Usage Note: The agent only needs to include the fields that are changing inside the profiles array. Omitted fields are left intact.

"Update John Doe's profile (ID: 1045) to reflect his new job title as 'Director of Engineering' and assign his reports_to field to the VP of Engineering (ID: 890)."

4. create_a_namely_event

This tool enables the agent to publish announcements directly to the Namely home feed. It is perfect for automating welcome messages, birthday announcements, or company-wide updates.

Usage Note: The agent must specify the event type. While some events are auto-generated, custom announcements can be created and formatted with HTML content.

"Create a new announcement on the home feed welcoming Sarah Jenkins to the team. Make sure comments are enabled so the team can say hello."

5. list_all_namely_job_tiers

This tool fetches the organizational job tiers. Job tiers act as the parent category for specific job titles. This is essential context for an agent tasked with auditing organizational structure or validating compensation bands.

Usage Note: Each job title must have one and only one linked job tier. The agent should use this tool to discover the correct numerical_id before attempting to create new job titles.

"Fetch all the current job tiers in Namely and identify the ID for the 'Executive Leadership' tier."

6. get_single_namely_report_by_id

This tool is the gateway for deep analytical workflows. It returns the live output of a saved Namely report as JSON.

Usage Note: The agent must understand that the response separates the column definitions from the row data. It will need to map the values in the content array positionally against the columns array to extract meaningful answers.

"Run the Q3 Headcount Report (ID: 5542). Parse the output and tell me the total number of active employees in the Engineering department."

To view the complete inventory of available tools, query parameters, and JSON schemas, visit the Namely integration page.

Workflows in Action

With these tools bound to your agent, you can orchestrate complex, multi-step operations that previously required manual HR intervention.

1. The Autonomous Onboarding Flow

When a candidate accepts an offer, the agent can handle the initial HRIS setup without manual data entry.

"We just finalized the hire for David Kim as a Backend Developer. His personal email is david.k@email.com. Add him to Namely as an active employee starting on the 15th, and post a welcome announcement to the home feed."

Step-by-step execution:

1. The agent calls create_a_namely_profile, wrapping David's details (name, email, job_title, start_date) inside the required profiles array.
2. The API returns the newly created profile object, including David's new internal Namely id.
3. The agent calls create_a_namely_event with the type announcement, generating HTML content to welcome David to the team.

The user receives confirmation that the profile was created successfully and the welcome message is live on the company feed.

2. Departmental Reorganization

When organizational structures change, updating individual profiles manually is tedious and error-prone. Agents can automate bulk updates.

"The QA team is moving under the DevOps department. Find all employees currently reporting to 'Manager of QA' and update their profiles to report to the 'Director of DevOps'."

Step-by-step execution:

1. The agent calls list_all_namely_profiles with a filter query to locate the 'Manager of QA' and the 'Director of DevOps' to retrieve their exact profile IDs.
2. The agent calls list_all_namely_profiles again, using filter [reports_to] to get the list of all QA employees.
3. The agent loops through the resulting IDs, calling update_a_namely_profile_by_id for each employee, patching the reports_to field with the new Director's ID.

The user gets a summary report detailing exactly which employee records were modified and successfully realigned.

Building Multi-Step Workflows

In a production environment, AI agents do not just fire off a single request and stop. They enter an execution loop where they reason about the data they receive, decide on the next steps, and handle errors.

sequenceDiagram
    participant User as User
    participant Agent as Agent Framework
    participant Truto as Truto API
    participant Namely as Namely API

    User->>Agent: "Generate the Q3 turnover report"
    Agent->>Truto: GET /proxy/namely/reports/5542
    Truto->>Namely: GET /api/v1/reports/5542
    Namely-->>Truto: 200 OK (Positional Array Data)
    Truto-->>Agent: Normalized JSON
    Agent->>Agent: LLM parses columns and content
    Agent-->>User: "The turnover rate was 4.2%."

The Reality of API Rate Limits

When building autonomous loops, your agent will inevitably hit rate limits. Namely restricts endpoints like list_all_namely_profiles to 100 requests per minute.

It is critical to understand how Truto handles this: Truto does not retry, throttle, or apply backoff on rate limit errors.

When the upstream Namely API returns an HTTP 429 (Too Many Requests), Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec.

The caller (your agent framework) is completely responsible for handling the retry and backoff logic. Do not expect the infrastructure to absorb these errors for you.

Here is how you must handle it defensively in your agent's tool execution wrapper:

async function executeNamelyToolWithRetry(toolName, args, maxRetries = 3) {
  let attempt = 0;
  
  while (attempt < maxRetries) {
    try {
      // Execute the tool call generated by the LLM
      const result = await toolManager.execute(toolName, args);
      return result;
      
    } catch (error) {
      if (error.status === 429) {
        // Truto passes the 429 directly. We must read the headers.
        const resetTime = error.headers.get('ratelimit-reset');
        const waitSeconds = resetTime ? 
          Math.max(1, parseInt(resetTime, 10) - Math.floor(Date.now() / 1000)) : 
          Math.pow(2, attempt); // Fallback to exponential backoff
          
        console.warn(`Rate limited by Namely. Waiting ${waitSeconds} seconds...`);
        await new Promise(resolve => setTimeout(resolve, waitSeconds * 1000));
        attempt++;
      } else {
        // If it's a 400 or 500 error, pass it back to the agent to reason about
        return `Error executing tool: ${error.message}`;
      }
    }
  }
  
  return "Execution failed: Rate limit exceeded and max retries reached.";
}

By forcing the agent framework to handle the 429, you maintain full control over the execution loop. If the agent hits a limit while generating a massive report, it can inform the user it is pausing, rather than the connection silently timing out in a black box.

Moving Beyond Proof of Concepts

Connecting Namely to an AI agent fundamentally changes how HR teams operate. Instead of logging into a portal to patch reporting structures or downloading CSVs to parse positional data, operators can simply state their intent.

By leveraging a unified tool layer, you remove the operational burden of maintaining nested JSON schemas, tracking effective dates manually, and fighting with pagination loops. Your engineering team can focus on improving the agent's contextual reasoning, while Truto handles the translation layer.