# SmartHR

```json
{
  "name": "SmartHR",
  "slug": "smarthr",
  "url": "https://composio.dev/toolkits/smarthr",
  "markdown_url": "https://composio.dev/toolkits/smarthr.md",
  "logo_url": "https://logos.composio.dev/api/smarthr",
  "categories": [
    "hr & recruiting"
  ],
  "is_composio_managed": false,
  "updated_at": "2026-10-24T05:35:36.884Z"
}
```

![SmartHR logo](https://logos.composio.dev/api/smarthr)

## Description

Securely connect your AI agents and chatbots (Claude, ChatGPT, Cursor, etc) with SmartHR MCP or direct API to read employee records, query organization data, review payroll documents, and manage HR workflows through natural language.

## Summary

SmartHR is a cloud human resources platform for employee records, organization data, payroll documents, and HR workflows.
It helps teams manage core HR operations in one secure, centralized workspace.

## Categories

- hr & recruiting

## Toolkit Details

- Tools: 116

## Images

- Logo: https://logos.composio.dev/api/smarthr

## Authentication

- **Api Key**
  - Type: `api_key`
  - Description: Api Key authentication for SmartHR.
  - Setup:
    - Configure Api Key credentials for SmartHR.
    - Use the credentials when creating an auth config in Composio.

## Suggested Prompts

- List employees with missing profile fields
- Find recently updated employee records
- Review organization data for inactive employees

## Supported Tools

| Tool slug | Name | Description |
|---|---|---|
| `SMARTHR_BULK_CREATE_PAYSLIPS` | Bulk Create Payslips | Create up to 100 sensitive payslip entries in one SmartHR payroll group. The connected API access token must have payroll Update permission and any applicable employee-field Update permissions. |
| `SMARTHR_CREATE_DEPARTMENT` | Create Department | Create a SmartHR department. The connected API access token must have the department resource Update permission. |
| `SMARTHR_CREATE_EMPLOYEE` | Create Employee | Create an employee using the documented SmartHR employee fields. The connected API token must have employee resource and field Update permissions. |
| `SMARTHR_CREATE_EMPLOYEE_CUSTOM_FIELD_TEMPLATE` | Create Employee Custom Field Template | Create an employee custom-field template. The connected API token must have the custom employee field resource Update permission. |
| `SMARTHR_CREATE_EMPLOYEE_CUSTOM_FIELD_TEMPLATE_GROUP` | Create Employee Custom Field Template Group | Create an employee custom-field template group. |
| `SMARTHR_CREATE_EMPLOYEE_DEPENDENT` | Create Employee Dependent | Create a dependent for one employee using the documented family fields. The connected API token must have the required family and employee-field Update permissions. |
| `SMARTHR_CREATE_EMPLOYMENT_TYPE` | Create Employment Type | Create a SmartHR employment type. The connected API access token must have the employment type resource Update permission. |
| `SMARTHR_CREATE_GRADE` | Create Grade | Create a SmartHR grade. The connected API access token must have the grade resource Update permission. |
| `SMARTHR_CREATE_JOB_CATEGORY` | Create Job Category | Create a SmartHR job category. The connected API access token must have the job category resource Update permission. |
| `SMARTHR_CREATE_JOB_TITLE` | Create Job Title | Create a SmartHR job title. The connected API access token must have the job title resource Update permission. |
| `SMARTHR_CREATE_PAYROLL` | Create Payroll | Create a sensitive SmartHR payroll group. The connected API access token must have payroll Update permission. |
| `SMARTHR_CREATE_PAYSLIP` | Create Payslip | Create a sensitive employee payslip in one SmartHR payroll group. The connected API access token must have payslip resource Update permission, and employee-field Update permissions may constrain writable data. |
| `SMARTHR_CREATE_RECRUITMENT_TYPE` | Create Recruitment Type | Create a SmartHR recruitment type. The connected API access token must have the recruitment type resource Update permission. |
| `SMARTHR_CREATE_TAX_WITHHOLDING` | Create Tax Withholding | Create a sensitive SmartHR tax-withholding group in the unconfirmed state. The connected API access token must have tax-withholding-group Update permission. |
| `SMARTHR_CREATE_TAX_WITHHOLDING_SLIP` | Create Tax Withholding Slip | Create a file-backed or field-backed sensitive tax-withholding slip for an employee in one SmartHR tax-withholding group. The connected API access token must have the tax-withholding-slip resource and applicable employee-field Update permissions. |
| `SMARTHR_CREATE_USER_SAML_CONFIGURATION` | Create User SAML Configuration | Create the SAML SSO account configuration for one SmartHR user. The tenant must have SAML SSO enabled, and the connected API access token must have the user resource Update permission. |
| `SMARTHR_CREATE_WEBHOOK` | Create Webhook | Create a SmartHR webhook configuration for future employee and dependent events. Matching events can send data to the configured destination, so confirm the URL, event selections, payload exposure, and secret token before calling. The connected API access token must have the webhook resource Update permission. |
| `SMARTHR_DELETE_EMPLOYEE` | Delete Employee | Permanently delete one employee by SmartHR employee ID. This requires the employee resource Update permission on the connected access token. |
| `SMARTHR_DELETE_EMPLOYEE_CUSTOM_FIELD_TEMPLATE` | Delete Employee Custom Field Template | Delete one employee custom-field template by ID. This permanently deletes all employee values set for the template. SmartHR rejects deletion when the field has a scheduled employee update whose effective date has not arrived. |
| `SMARTHR_DELETE_EMPLOYEE_CUSTOM_FIELD_TEMPLATE_GROUP` | Delete Employee Custom Field Template Group | Delete one employee custom-field template group by ID. This also permanently deletes every custom-field template in the group and all values set for those templates. SmartHR rejects deletion when a group field has a scheduled employee update whose effective date has not arrived. |
| `SMARTHR_DELETE_EMPLOYEE_DEPENDENT` | Delete Employee Dependent | Permanently delete one dependent and their sensitive family data from an employee record. This cannot be undone. |
| `SMARTHR_DELETE_EMPLOYMENT_TYPE` | Delete Employment Type | Delete one SmartHR employment type by ID. SmartHR does not allow deletion of a system-standard employment type or one referenced by a scheduled employee update whose effective date has not arrived. The connected API access token must have the employment type resource Update permission. |
| `SMARTHR_DELETE_GRADE` | Delete Grade | Delete one SmartHR grade by ID. A grade referenced by a scheduled employee update whose effective date has not arrived cannot be deleted. The connected API access token must have the grade resource Update permission. |
| `SMARTHR_DELETE_JOB_CATEGORY` | Delete Job Category | Delete one SmartHR job category by ID. A job category referenced by a scheduled employee update whose effective date has not arrived cannot be deleted. The connected API access token must have the job category resource Update permission. |
| `SMARTHR_DELETE_JOB_TITLE` | Delete Job Title | Delete one SmartHR job title by ID. A job title referenced by a scheduled employee update whose effective date has not arrived cannot be deleted. The connected API access token must have the job title resource Update permission. |
| `SMARTHR_DELETE_PAYROLL` | Delete Payroll | Permanently delete one sensitive SmartHR payroll group by ID. The connected API access token must have the payroll resource Update permission. |
| `SMARTHR_DELETE_PAYSLIP` | Delete Payslip | Permanently delete one sensitive SmartHR payslip from its payroll group. The connected API access token must have the payslip resource Update permission, and employee fields may also require Update permission. |
| `SMARTHR_DELETE_RECRUITMENT_TYPE` | Delete Recruitment Type | Delete one SmartHR recruitment type by ID. A recruitment type referenced by a scheduled employee update whose effective date has not arrived cannot be deleted. The connected API access token must have the recruitment type resource Update permission. |
| `SMARTHR_DELETE_TAX_WITHHOLDING` | Delete Tax Withholding | Permanently delete one sensitive SmartHR tax-withholding group by ID. The connected API access token must have the tax-withholding-group resource Update permission. |
| `SMARTHR_DELETE_TAX_WITHHOLDING_SLIP` | Delete Tax Withholding Slip | Permanently delete one sensitive SmartHR tax-withholding slip from its tax-withholding group. The connected API access token must have the tax-withholding-slip resource Update permission, and employee fields may also require Update permission. |
| `SMARTHR_DELETE_USER_SAML_CONFIGURATION` | Delete User SAML Configuration | Delete the SAML SSO account configuration for one SmartHR user. The tenant must have SAML SSO enabled, and the connected API access token must have the user resource Update permission. |
| `SMARTHR_DELETE_WEBHOOK` | Delete Webhook | Permanently delete one SmartHR webhook configuration by ID. The connected API access token must have the webhook resource Update permission. |
| `SMARTHR_DISABLE_USER_SAML_CONFIGURATION` | Disable User SAML Configuration | Disable the SAML SSO account configuration for one SmartHR user. The tenant must have the SAML/SSO option enabled, and the connected API access token must have the user resource Update permission. |
| `SMARTHR_DISCONTINUE_DEPARTMENT` | Discontinue Department | Irreversibly discontinue one SmartHR department as of its final active date. The date must be in the past. SmartHR rejects discontinuation when a scheduled employee update references this department or a descendant; the connected access token must have department Update permission. |
| `SMARTHR_DOWNLOAD_BATCH_JOB_ATTACHMENT` | Download Batch Job Attachment | Download the binary file for a SmartHR batch-job attachment. SmartHR deletes the provider attachment five minutes after it is retrieved, so use the returned offloaded file reference for subsequent work. |
| `SMARTHR_ENABLE_USER_SAML_CONFIGURATION` | Enable User SAML Configuration | Enable the SAML SSO account configuration for one SmartHR user. The tenant must have the SAML/SSO option enabled, and the connected API access token must have the user resource Update permission. |
| `SMARTHR_FINALIZE_PAYROLL` | Finalize Payroll | Finalize one sensitive SmartHR payroll group. The connected API access token must have the payroll-group resource Update permission. |
| `SMARTHR_GET_BATCH_JOB` | Get Batch Job | Get one SmartHR background batch job by ID, optionally embedding its attachments. The access token needs the corresponding resource Reference permission. |
| `SMARTHR_GET_DEPARTMENT` | Get Department | Get one SmartHR department by its department ID. |
| `SMARTHR_GET_EMPLOYEE` | Get Employee | Get one employee by SmartHR employee ID, with optional comma-separated field selection. The access token needs employee Reference permission, and returned attributes may be limited by employee-field Reference permissions. |
| `SMARTHR_GET_EMPLOYEE_CUSTOM_FIELD_TEMPLATE` | Get Employee Custom Field Template | Get one employee custom-field template by ID. Set embed to group to include the custom field group that contains the template. |
| `SMARTHR_GET_EMPLOYEE_CUSTOM_FIELD_TEMPLATE_GROUP` | Get Employee Custom Field Template Group | Get one employee custom-field template group by ID. Set embed to templates to include the custom field templates belonging to the group. |
| `SMARTHR_GET_EMPLOYEE_DEPENDENT` | Get Employee Dependent | Get one dependent belonging to an employee. |
| `SMARTHR_GET_EMPLOYEE_INPUT_FORM` | Get Employee Input Form | Get one SmartHR employee information-collection form by ID, preserving its nested field groups, fields, and embedded custom-field definitions. |
| `SMARTHR_GET_EMPLOYMENT_TYPE` | Get Employment Type | Get one SmartHR employment type by its employment type ID. |
| `SMARTHR_GET_GRADE` | Get Grade | Get one SmartHR grade by its grade ID. |
| `SMARTHR_GET_JOB_CATEGORY` | Get Job Category | Get one SmartHR job category by its job category ID. |
| `SMARTHR_GET_JOB_TITLE` | Get Job Title | Get one SmartHR job title by its job title ID. |
| `SMARTHR_GET_MAIL_FORMAT` | Get Mail Format | Get one SmartHR mail format by ID, optionally embedding the employee information-collection forms that use it. |
| `SMARTHR_GET_PAYMENT_PERIOD` | Get Payment Period | Get one SmartHR payroll payment period by its payment period ID. |
| `SMARTHR_GET_PAYROLL` | Get Payroll | Get one sensitive SmartHR payroll group by ID. The access token needs payroll Reference permission, and returned data may contain sensitive financial information. |
| `SMARTHR_GET_PAYSLIP` | Get Payslip | Get one highly sensitive SmartHR payslip from a payroll group. The access token needs payslip Reference permission, and returned employee fields may be permission-filtered. |
| `SMARTHR_GET_RECRUITMENT_TYPE` | Get Recruitment Type | Get one SmartHR recruitment type by its recruitment type ID. |
| `SMARTHR_GET_TAX_WITHHOLDING` | Get Tax Withholding | Get one highly sensitive SmartHR tax-withholding group by ID. The access token needs tax-withholding-group Reference permission. |
| `SMARTHR_GET_TAX_WITHHOLDING_SLIP` | Get Tax Withholding Slip | Get one highly sensitive SmartHR tax-withholding slip from a tax-withholding group. The access token needs tax-withholding-slip Reference permission, and employee fields may be permission-filtered. |
| `SMARTHR_GET_USER` | Get User | Get one SmartHR user account by user ID with an optional related object embedded in the response. |
| `SMARTHR_GET_USER_SAML_CONFIGURATION` | Get User SAML Configuration | Get the SAML SSO account configuration for one SmartHR user. This endpoint requires the tenant's SAML/SSO option to be enabled. |
| `SMARTHR_GET_WEBHOOK` | Get Webhook | Get one SmartHR webhook configuration by webhook ID. |
| `SMARTHR_INVITE_EMPLOYEE` | Invite Employee | Send the documented SmartHR invitation to one employee's configured email address. Repeating the action resends the invitation unless the employee has already accepted it; the inviter must be an administrator. |
| `SMARTHR_LIST_BANK_ACCOUNT_SETTINGS` | List Bank Account Settings | List one page of SmartHR bank-account setting definitions. This does not return employee bank-account values. |
| `SMARTHR_LIST_BATCH_JOBS` | List Batch Jobs | List one page of SmartHR background batch jobs. Optionally embed attachment metadata for each job. |
| `SMARTHR_LIST_BUSINESS_ESTABLISHMENTS` | List Business Establishments | List one page of SmartHR business establishments, optionally embedding the social insurance representative, labor insurance representative, or company. |
| `SMARTHR_LIST_COMPANIES` | List Companies | List one page of SmartHR companies with an optional embedded owner. |
| `SMARTHR_LIST_DEPARTMENTS` | List Departments | List one page of SmartHR departments using the documented code and sort filters. Returns hierarchy and company details when present. |
| `SMARTHR_LIST_DEPENDENT_CUSTOM_FIELD_TEMPLATES` | List Dependent Custom Field Templates | List one page of SmartHR custom-field templates for employee dependents. |
| `SMARTHR_LIST_DEPENDENT_RELATIONS` | List Dependent Relations | List one page of configured SmartHR dependent relationship types. |
| `SMARTHR_LIST_EMPLOYEE_CUSTOM_FIELD_TEMPLATE_GROUPS` | List Employee Custom Field Template Groups | List one page of employee custom-field template groups. Set embed to templates to include the custom fields belonging to each group. |
| `SMARTHR_LIST_EMPLOYEE_CUSTOM_FIELD_TEMPLATES` | List Employee Custom Field Templates | List one page of SmartHR employee custom-field templates. Set embed to group to include each template's custom-field group. |
| `SMARTHR_LIST_EMPLOYEE_DEPENDENTS` | List Employee Dependents | List one page of sensitive family and dependent records for a SmartHR employee. The access token needs dependent Reference permission, and returned fields may be limited by employee-field Reference permissions. |
| `SMARTHR_LIST_EMPLOYEE_INPUT_FORMS` | List Employee Input Forms | List one page of SmartHR employee information-collection forms with their nested field definitions. Set embed to mail_format to include linked mail formats. |
| `SMARTHR_LIST_EMPLOYEE_MATERNITY_CHILDCARE_LEAVES` | List Employee Maternity and Childcare Leaves | List one page of sensitive maternity and childcare leave records for a SmartHR employee. The access token needs leave-record Reference permission. |
| `SMARTHR_LIST_EMPLOYEES` | List Employees | List one page of employees matching SmartHR's documented employee filters. Employee records contain sensitive HR data; use fields to request only the attributes needed. |
| `SMARTHR_LIST_EMPLOYMENT_TYPES` | List Employment Types | List one page of SmartHR employment types. |
| `SMARTHR_LIST_GRADES` | List Grades | List one page of SmartHR grades. |
| `SMARTHR_LIST_JOB_CATEGORIES` | List Job Categories | List one page of SmartHR job categories. |
| `SMARTHR_LIST_JOB_TITLES` | List Job Titles | List one page of SmartHR job titles using the documented sort option. |
| `SMARTHR_LIST_MAIL_FORMATS` | List Mail Formats | List one page of SmartHR mail formats. Set embed to crew_input_forms to include the employee input forms linked to each format. |
| `SMARTHR_LIST_PAYMENT_PERIODS` | List Payment Periods | List one page of SmartHR payroll payment periods. |
| `SMARTHR_LIST_PAYROLLS` | List Payrolls | List one page of sensitive SmartHR payroll groups using payment-date and payment-type filters. The access token needs payroll Reference permission. |
| `SMARTHR_LIST_PAYSLIPS` | List Payslips | List one page of highly sensitive SmartHR payslips in a payroll group. The access token needs payslip Reference permission, and employee fields may be permission-filtered. |
| `SMARTHR_LIST_RECRUITMENT_TYPES` | List Recruitment Types | List one page of SmartHR recruitment types. |
| `SMARTHR_LIST_TAX_WITHHOLDINGS` | List Tax Withholdings | List one page of sensitive SmartHR tax-withholding groups. The access token needs tax-withholding-group Reference permission. |
| `SMARTHR_LIST_TAX_WITHHOLDING_SLIPS` | List Tax Withholding Slips | List one page of sensitive tax-withholding slips in a SmartHR tax-withholding group. The access token needs tax-withholding-slip Reference permission, and employee fields may be permission-filtered. |
| `SMARTHR_LIST_USERS` | List Users | List one page of SmartHR user accounts with the documented sort and embed options, invitation status, role, and email-delivery status. |
| `SMARTHR_LIST_WEBHOOKS` | List Webhooks | List one page of SmartHR webhook configurations. |
| `SMARTHR_PARTIALLY_UPDATE_DEPARTMENT` | Partially Update Department | Partially update a SmartHR department by ID. The connected API access token must have the department resource Update permission. |
| `SMARTHR_PARTIALLY_UPDATE_EMPLOYEE_CUSTOM_FIELD_TEMPLATE` | Partially Update Employee Custom Field Template | Partially update an employee custom-field template. Elements apply only to enum templates. When a future-dated employee update is pending for the template, SmartHR permits updating only the hint. |
| `SMARTHR_PARTIALLY_UPDATE_EMPLOYMENT_TYPE` | Partially Update Employment Type | Partially update a SmartHR employment type by ID. SmartHR does not allow renaming a system preset employment type or updating an employment type used by a pending future-dated employee update. The connected API access token must have the employment type resource Update permission. |
| `SMARTHR_PARTIALLY_UPDATE_PAYROLL` | Partially Update Payroll | Partially update the administrator-facing and employee-facing names of a sensitive SmartHR payroll group by ID. Both names are required by SmartHR. The connected API access token must have the payroll resource Update permission. |
| `SMARTHR_PARTIALLY_UPDATE_USER_SAML_CONFIGURATION` | Partially Update User SAML Configuration | Partially update the SAML SSO account configuration for one SmartHR user. The tenant must have SAML SSO enabled, and the connected API access token must have the user resource Update permission. |
| `SMARTHR_PARTIALLY_UPDATE_WEBHOOK` | Partially Update Webhook | Partially update a SmartHR webhook by ID. Changing its destination or event selections can redirect future employee and dependent data externally, so confirm them before calling. The connected API access token must have the webhook resource Update permission. |
| `SMARTHR_PUBLISH_PAYROLL` | Publish Payroll | Irreversibly publish one sensitive SmartHR payroll group immediately or at a scheduled time within one month, optionally notifying employees. The connected API access token must have payroll Update permission. |
| `SMARTHR_REMOVE_EMPLOYEE_DEPARTMENTS` | Remove Employee Departments | Remove all department assignments from one employee using the documented SmartHR endpoint. This requires the employee resource and field Update permissions assigned to the connected access token. |
| `SMARTHR_REOPEN_PAYROLL` | Reopen Payroll | Reopen one sensitive SmartHR payroll group. Reopening a published payroll may also unpublish it. The connected API access token must have payroll Update permission. |
| `SMARTHR_REPLACE_DEPARTMENT` | Replace Department | Replace a SmartHR department through PUT. Omitted optional attributes are deleted; use the partial-update action to preserve attributes that are not being changed. Departments with pending employee updates in their hierarchy cannot be updated. |
| `SMARTHR_REPLACE_EMPLOYEE_CUSTOM_FIELD_TEMPLATE` | Replace Employee Custom Field Template | Replace an employee custom-field template through the documented PUT operation. Omitted optional attributes are deleted; use the PATCH action to preserve attributes that are not being changed. Existing dropdown elements omitted from elements are also deleted. |
| `SMARTHR_REPLACE_EMPLOYEE_CUSTOM_FIELD_TEMPLATE_GROUP` | Replace Employee Custom Field Template Group | Replace an employee custom-field template group through the documented PUT operation. Omitted optional attributes are deleted; use the PATCH action to preserve attributes that are not being changed. |
| `SMARTHR_REPLACE_EMPLOYMENT_TYPE` | Replace Employment Type | Replace a SmartHR employment type through PUT. Attributes omitted from the PUT contract are deleted; use the partial-update action to preserve them. System-standard employment types and employment types used by pending employee updates cannot be changed. |
| `SMARTHR_REPLACE_GRADE` | Replace Grade | Replace a SmartHR grade by ID using full PUT semantics. The PUT contract allows name and rank to be omitted. Grades used by pending future-dated employee updates cannot be changed. The connected API access token must have the grade resource Update permission. |
| `SMARTHR_REPLACE_JOB_CATEGORY` | Replace Job Category | Replace a SmartHR job category by ID using full PUT semantics. The PUT contract allows name to be omitted. Job categories used by pending future-dated employee updates cannot be changed. The connected API access token must have the job category resource Update permission. |
| `SMARTHR_REPLACE_JOB_TITLE` | Replace Job Title | Replace a SmartHR job title by ID using full PUT semantics. The PUT contract allows name and rank to be omitted. Job titles used by pending future-dated employee updates cannot be changed. The connected API access token must have the job title resource Update permission. |
| `SMARTHR_REPLACE_RECRUITMENT_TYPE` | Replace Recruitment Type | Replace a SmartHR recruitment type by ID using full PUT semantics. Name is required for the complete replacement. Recruitment types used by pending future-dated employee updates cannot be changed. The connected API access token must have the recruitment type resource Update permission. |
| `SMARTHR_REPLACE_TAX_WITHHOLDING` | Replace Tax Withholding | Replace a sensitive SmartHR tax-withholding group by ID using full PUT semantics. Name, status, and year are all required for the complete replacement. Finalized tax withholdings cannot be updated. The connected API access token must have the tax-withholding-group resource Update permission. |
| `SMARTHR_REPLACE_WEBHOOK` | Replace Webhook | Replace a SmartHR webhook through PUT. Omitted optional attributes are deleted; use the partial-update action to preserve attributes that are not being changed. Changing its destination or event selections can redirect future employee and dependent data externally, so confirm them before calling. |
| `SMARTHR_START_DEPENDENT_IMPORT_JOB` | Start Dependent Import Job | Start an asynchronous SmartHR dependent-data import from a Base64-encoded CSV or Excel file. This creates a background job that processes sensitive family HR data; the connected API access token must have the corresponding resource and employee-field Update permissions. |
| `SMARTHR_START_EMPLOYEE_EXPORT_JOB` | Start Employee Export Job | Start a SmartHR background job that exports employee information using an existing custom download format. A successful 201 response only confirms that the asynchronous job was registered; use the batch-job actions to monitor it and retrieve any resulting attachment. The connected access token must have the required resource and employee-field Update permissions. |
| `SMARTHR_START_EMPLOYEE_IMPORT_JOB` | Start Employee Import Job | Start a SmartHR background job that inserts or updates employees from a sensitive base64-encoded CSV or Excel file. The connected API access token must have the required resource and employee-field Update permissions. |
| `SMARTHR_UPDATE_EMPLOYEE` | Update Employee | Update the supplied documented fields of one employee by SmartHR employee ID. |
| `SMARTHR_UPDATE_EMPLOYEE_CUSTOM_FIELD_TEMPLATE_GROUP` | Update Employee Custom Field Template Group | Update one or more supplied fields of an employee custom-field template group. |
| `SMARTHR_UPDATE_EMPLOYEE_DEPENDENT` | Update Employee Dependent | Update the supplied fields of one dependent belonging to an employee. |
| `SMARTHR_UPDATE_GRADE` | Update Grade | Update the supplied fields of a SmartHR grade by ID. Grades used by pending future-dated employee updates cannot be changed. The connected API access token must have the grade resource Update permission. |
| `SMARTHR_UPDATE_JOB_CATEGORY` | Update Job Category | Update the supplied fields of a SmartHR job category by ID. Job categories used by pending future-dated employee updates cannot be changed. The connected API access token must have the job category resource Update permission. |
| `SMARTHR_UPDATE_JOB_TITLE` | Update Job Title | Update the supplied fields of a SmartHR job title by ID. Job titles used by pending future-dated employee updates cannot be changed. The connected API access token must have the job title resource Update permission. |
| `SMARTHR_UPDATE_RECRUITMENT_TYPE` | Update Recruitment Type | Update a SmartHR recruitment type by ID. Recruitment types used by pending future-dated employee updates cannot be changed. The connected API access token must have the recruitment type resource Update permission. |
| `SMARTHR_UPDATE_TAX_WITHHOLDING` | Update Tax Withholding | Update the supplied fields of a sensitive SmartHR tax-withholding group by ID. SmartHR does not allow updates after the group is fixed. The connected API access token must have the tax-withholding-group resource Update permission. |
| `SMARTHR_UPDATE_TAX_WITHHOLDING_SLIP` | Update Tax Withholding Slip | Update a sensitive SmartHR tax-withholding slip. The full body is required: structured updates require the complete identity, payer, tax-year, and payment body, and sparse field updates are rejected by SmartHR. Confirmed slips cannot be updated, and switching between file-backed and field-backed data requires deleting and recreating the slip. The connected API access token must have the tax-withholding-slip resource Update permission. |

## Supported Triggers

None listed.

## Installation and MCP Setup

### Path 1: SDK Installation

#### Path 1, Step 1: Install Composio

Install the Composio SDK, the OpenAI provider, and the OpenAI SDK
```python
pip install composio composio_openai openai
```

```typescript
npm install @composio/core @composio/openai openai
```

#### Path 1, Step 2: Create a Composio session

Initialize Composio with the OpenAI Responses provider and create a session scoped to SmartHR
```python
import json
from openai import OpenAI
from composio import Composio
from composio_openai import OpenAIResponsesProvider

composio = Composio(provider=OpenAIResponsesProvider())
client = OpenAI()

session = composio.create(user_id="your-user-id", toolkits=["smarthr"])
tools = session.tools()
```

```typescript
import OpenAI from "openai";
import { Composio } from "@composio/core";
import { OpenAIResponsesProvider } from "@composio/openai";

const composio = new Composio({ provider: new OpenAIResponsesProvider() });
const client = new OpenAI();

const session = await composio.create("your-user-id", { toolkits: ["smarthr"] });
const tools = await session.tools();
```

#### Path 1, Step 3: Run SmartHR tools with your agent

Send a request, execute the SmartHR tool calls through the session, and print the final answer
```python
response = client.responses.create(
    model="gpt-5.6-sol",
    tools=tools,
    input=[{"role": "user", "content": "List all employees in SmartHR and show their names and employment status."}],
)

while True:
    tool_calls = [o for o in response.output if o.type == "function_call"]
    if not tool_calls:
        break
    results = composio.provider.handle_tool_calls(response=response, session=session)
    response = client.responses.create(
        model="gpt-5.6-sol",
        tools=tools,
        previous_response_id=response.id,
        input=[
            {"type": "function_call_output", "call_id": call.call_id, "output": json.dumps(results[i])}
            for i, call in enumerate(tool_calls)
        ],
    )

print(response.output_text)
```

```typescript
let response = await client.responses.create({
  model: "gpt-5.6-sol",
  tools,
  input: [{ role: "user", content: "List all employees in SmartHR and show their names and employment status." }],
});

while (response.output.some((o) => o.type === "function_call")) {
  const outputs = await composio.provider.handleToolCalls(session, response.output);
  response = await client.responses.create({
    model: "gpt-5.6-sol",
    tools,
    previous_response_id: response.id,
    input: outputs,
  });
}

console.log(response.output_text);
```

### Path 2: MCP Server Setup

#### Path 2, Step 1: Install Composio

Install the Composio SDK and your agent framework
```python
pip install composio claude-agent-sdk
```

```typescript
npm install @composio/core ai @ai-sdk/mcp @ai-sdk/openai
```

#### Path 2, Step 2: Create a session with MCP enabled

Create a session scoped to SmartHR and read its MCP URL and headers
```python
from composio import Composio

composio = Composio()
session = composio.create(user_id="your-user-id", toolkits=["smarthr"], mcp=True)
```

```typescript
import { Composio } from "@composio/core";

const composio = new Composio();
const { mcp } = await composio.create("your-user-id", {
  toolkits: ["smarthr"],
  mcp: true,
});
```

#### Path 2, Step 3: Connect your agent to the MCP server

Pass the session's MCP URL and headers to your agent and run a SmartHR request
```python
import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock

options = ClaudeAgentOptions(
    mcp_servers={
        "composio": {
            "type": "http",
            "url": session.mcp.url,
            "headers": session.mcp.headers,
        }
    },
    system_prompt="You are a helpful assistant with access to SmartHR tools.",
    tools=[],
    allowed_tools=["mcp__composio__*"],
)

async def main():
    async with ClaudeSDKClient(options=options) as client:
        await client.query("List all employees in SmartHR and show their names and employment status.")
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(block.text)

asyncio.run(main())
```

```typescript
import { createMCPClient } from "@ai-sdk/mcp";
import { openai } from "@ai-sdk/openai";
import { generateText, stepCountIs } from "ai";

const client = await createMCPClient({
  transport: { type: "http", url: mcp.url, headers: mcp.headers },
});

const { text } = await generateText({
  model: openai("gpt-5.6-sol"),
  tools: await client.tools(),
  prompt: "List all employees in SmartHR and show their names and employment status.",
  stopWhen: stepCountIs(10),
});

console.log(text);
await client.close();
```

## Why Use Composio?

### 1. AI Native SmartHR Integration

- Supports both SmartHR MCP and direct API based integrations
- Structured, LLM-friendly schemas for reliable employee and organization data access
- Rich coverage for reading, writing, and querying your SmartHR data

### 2. Managed Auth

- Securely connect SmartHR with API key authentication
- Central place to manage, scope, and revoke SmartHR access
- Per user and per environment credentials instead of hard-coded keys

### 3. Agent Optimized Design

- Tools are tuned using real error and success rates to improve reliability over time
- Comprehensive execution logs so you always know what ran, when, and on whose behalf

### 4. Enterprise Grade Security

- Fine-grained RBAC so you control which agents and users can access SmartHR
- Scoped, least privilege access to employee and organization resources
- Full audit trail of agent actions to support review and compliance

## Use SmartHR with any AI Agent Framework

Choose a framework you want to connect SmartHR with:

- [ChatGPT](https://composio.dev/toolkits/smarthr/framework/chatgpt)
- [Claude Cowork](https://composio.dev/toolkits/smarthr/framework/claude-cowork)
- [Hermes](https://composio.dev/toolkits/smarthr/framework/hermes-agent)
- [Atomic Agent](https://composio.dev/toolkits/smarthr/framework/atomic-agent)

## Related Toolkits

- [Ashby](https://composio.dev/toolkits/ashby) - Ashby is an applicant tracking system that handles job postings, candidate management, and hiring analytics.
- [7shifts](https://composio.dev/toolkits/7shifts) - 7shifts is a restaurant team management platform for scheduling, time clocks, payroll, and team communication. It helps operators keep labor, shifts, and staff workflows organized in one place.
- [Async interview](https://composio.dev/toolkits/async_interview) - Async interview is an on-demand video interview platform for streamlined hiring. Candidates record responses on their schedule, so employers can review anytime.
- [Bamboohr](https://composio.dev/toolkits/bamboohr) - BambooHR is a cloud-based HR management platform for small and mid-sized businesses. It streamlines employee data, HR workflows, and reporting in one easy interface.
- [Breathe HR](https://composio.dev/toolkits/breathehr) - Breathe HR is cloud-based HR software for SMEs to manage employee data, absences, and performance. It simplifies HR admin, making it easy to keep employee records accurate and up to date.
- [Breezy Hr](https://composio.dev/toolkits/breezy_hr) - Breezy HR is a recruiting and applicant tracking platform for managing jobs, candidates, pipelines, and hiring teams. It helps teams move faster from job posting to offer without losing track of applicants.
- [Connecteam](https://composio.dev/toolkits/connecteam) - Connecteam is a workforce management platform for deskless teams, streamlining operations, HR, and team communication. It helps businesses save time by automating scheduling, time tracking, and staff engagement tasks.
- [ContactOut](https://composio.dev/toolkits/contactout) - ContactOut is a professional profile enrichment and contact discovery API. Find and verify email addresses to power recruiting, sales, and outreach.
- [Coresignal](https://composio.dev/toolkits/coresignal) - Coresignal is a real-time public web data platform for employee, company, and professional profile intelligence. It helps teams access fresh workforce data for research, recruiting, sales, and market analysis.
- [Dice MCP](https://composio.dev/toolkits/dice_mcp) - Dice MCP is an MCP server for searching Dice's tech-job database by role, company, location, and employment type. It helps agents find relevant tech roles fast with conversational filters.
- [Greenhouse](https://composio.dev/toolkits/greenhouse) - Greenhouse is applicant tracking and recruiting software for managing jobs, candidates, interviews, and hiring workflows. It helps recruiting teams move faster with structured pipelines, collaboration tools, and hiring data in one place.
- [Gusto](https://composio.dev/toolkits/gusto) - Gusto is a payroll, benefits, and HR platform for small and medium businesses. It helps teams run payroll, manage people, and stay compliant with less busywork.
- [Hireflix](https://composio.dev/toolkits/hireflix) - Hireflix is a one-way video interview platform for hiring teams. It helps teams manage positions, candidate interviews, templates, and branded hiring workflows in one place.
- [HR Partner](https://composio.dev/toolkits/hr_partner) - HR Partner is a human resources platform for managing employee records, leave, recruitment, performance, timesheets, and expenses. Use it to centralize HR workflows, automate manual HR tasks, and keep employee data organized.
- [Job Search (Rapid API)](https://composio.dev/toolkits/job_search) - Job Search (Rapid API) is a unified service that searches approved job-listing sources via RapidAPI hosts. Use it to aggregate and query listings across providers with a single API.
- [Lever](https://composio.dev/toolkits/lever) - Lever is an applicant tracking system that blends sourcing, CRM, and analytics for recruiting. It helps companies scale hiring with collaborative workflows and actionable insights.
- [Personio](https://composio.dev/toolkits/personio) - Personio is an HR platform for managing employee records, attendance, absences, projects, and documents. It centralizes HR data and streamlines workforce administration for teams and HR leaders.
- [Recruitee](https://composio.dev/toolkits/recruitee) - Recruitee is collaborative hiring software that centralizes recruitment tasks for teams. It streamlines sourcing, interviewing, and hiring so you can fill roles faster.
- [Remote retrieval](https://composio.dev/toolkits/remote_retrieval) - Remote retrieval is a logistics automation tool for managing laptop and monitor returns. It streamlines return tracking, saving time and hassle for IT and ops teams.
- [Sap successfactors](https://composio.dev/toolkits/sap_successfactors) - Sap successfactors is a cloud-based human capital management suite for HR, payroll, recruiting, and talent management. It helps organizations centralize employee data and streamline the entire employee lifecycle.

## Frequently Asked Questions

### Do I need my own developer credentials to use SmartHR with Composio?

Yes, SmartHR requires you to configure your own API key credentials. Once set up, Composio handles secure credential storage and API request handling for you.

### Can I use multiple toolkits together?

Yes! Composio's Tool Router enables agents to use multiple toolkits. [Learn more](https://docs.composio.dev/tool-router/overview).

### Is Composio secure?

Composio is SOC 2 and ISO 27001 compliant with all data encrypted in transit and at rest. [Learn more](https://trust.composio.dev).

### What if the API changes?

Composio maintains and updates all toolkit integrations automatically, so your agents always work with the latest API versions.

---
[See all toolkits](https://composio.dev/toolkits) · [Composio docs](https://docs.composio.dev/llms.txt)