---
title: "Connect Namely to AI Agents: Automate Employee Feeds and Job Tiers"
slug: connect-namely-to-ai-agents-automate-employee-feeds-and-job-tiers
date: 2026-10-22
author: Sidharth Verma
categories: ["AI & Agents"]
excerpt: "Learn how to connect Namely to AI agents using Truto's /tools endpoint. Build autonomous workflows for employee feeds, HR reports, and job tiers."
tldr: "Connect Namely to AI agents natively using Truto's /tools API. This guide covers bypassing Namely's unique API quirks, handling positional report data, and building multi-step agentic HR workflows."
canonical: https://truto.one/blog/connect-namely-to-ai-agents-automate-employee-feeds-and-job-tiers/
---

# 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](https://truto.one/how-to-architect-a-scalable-oauth-token-management-system-for-saas-integrations/).

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](https://truto.one/connect-namely-to-chatgpt-sync-profiles-and-organization-data/), or if you are building on Anthropic's models, read our guide on [connecting Namely to Claude](https://truto.one/connect-namely-to-claude-manage-hr-resources-and-export-reports/). 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](https://truto.one/architecting-ai-agents-langgraph-langchain-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:
```json
{
  "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.

```typescript
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](https://truto.one/integrations/detail/namely).

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

```mermaid
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](https://truto.one/best-practices-for-handling-api-rate-limits-and-retries-across-multiple-third-party-apis/). 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:

```typescript
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. 

> Ready to connect your AI agents to Namely and 100+ other SaaS applications? Truto gives your models safe, structured, and reliable access to enterprise APIs.
>
> [Talk to us](https://truto.one/book-a-demo/)