KosmoKrator

hr

Freshteam Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Freshteam KosmoKrator integration.

7 functions 7 read 0 write Bearer token auth
Submit Freshteam feedback View package source

Lua Namespace

Agents call this integration through app.integrations.freshteam.*. Use lua_read_doc("integrations.freshteam") inside KosmoKrator to discover the same reference at runtime.

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Freshteam — Lua API Reference

list_candidates

List recruitment candidates with optional status filtering and pagination.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
per_pageintegernoResults per page (default: 20)
statusstringnoFilter by status (e.g., "active", "hired", "rejected", "on_hold")

Example

local result = app.integrations.freshteam.list_candidates({
  page = 1,
  per_page = 10,
  status = "active"
})

for _, candidate in ipairs(result) do
  print(candidate.first_name .. " " .. candidate.last_name .. " - " .. candidate.email)
end

get_candidate

Retrieve details for a specific candidate.

Parameters

NameTypeRequiredDescription
idintegeryesThe candidate ID

Example

local candidate = app.integrations.freshteam.get_candidate({ id = 12345 })
print(candidate.first_name .. " " .. candidate.last_name)
print("Email: " .. candidate.email)
print("Status: " .. candidate.status)

list_job_postings

List job postings with optional filtering by status and department.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
per_pageintegernoResults per page (default: 20)
statusstringnoFilter by status (e.g., "published", "draft", "closed")
department_idintegernoFilter by department ID

Example

local result = app.integrations.freshteam.list_job_postings({
  page = 1,
  per_page = 10,
  status = "published"
})

for _, job in ipairs(result) do
  print(job.title .. " (" .. job.status .. ")")
end

get_job_posting

Retrieve details for a specific job posting.

Parameters

NameTypeRequiredDescription
idintegeryesThe job posting ID

Example

local job = app.integrations.freshteam.get_job_posting({ id = 67890 })
print(job.title)
print("Department: " .. (job.department and job.department.name or "N/A"))
print("Location: " .. (job.location or "Remote"))

list_employees

List employees with optional department filtering.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
per_pageintegernoResults per page (default: 20)
department_idintegernoFilter by department ID

Example

local result = app.integrations.freshteam.list_employees({
  page = 1,
  per_page = 50
})

for _, emp in ipairs(result) do
  print(emp.first_name .. " " .. emp.last_name .. " - " .. (emp.email or ""))
end

get_employee

Retrieve details for a specific employee.

Parameters

NameTypeRequiredDescription
idintegeryesThe employee ID

Example

local emp = app.integrations.freshteam.get_employee({ id = 54321 })
print(emp.first_name .. " " .. emp.last_name)
print("Email: " .. emp.email)
print("Department: " .. (emp.department and emp.department.name or "N/A"))

get_current_user

Retrieve the currently authenticated user’s profile. Useful for verifying the connection.

Parameters

None.

Example

local user = app.integrations.freshteam.get_current_user({})
print("Logged in as: " .. user.email)

Multi-Account Usage

If you have multiple Freshteam accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.freshteam.list_candidates({})

-- Explicit default (portable across setups)
app.integrations.freshteam.default.list_candidates({})

-- Named accounts
app.integrations.freshteam.acme.list_candidates({})
app.integrations.freshteam.other_company.list_employees({})

All functions are identical across accounts — only the credentials differ.

Raw agent markdown 
# Freshteam — Lua API Reference

## list_candidates

List recruitment candidates with optional status filtering and pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 20) |
| `status` | string | no | Filter by status (e.g., `"active"`, `"hired"`, `"rejected"`, `"on_hold"`) |

### Example

```lua
local result = app.integrations.freshteam.list_candidates({
  page = 1,
  per_page = 10,
  status = "active"
})

for _, candidate in ipairs(result) do
  print(candidate.first_name .. " " .. candidate.last_name .. " - " .. candidate.email)
end
```

---

## get_candidate

Retrieve details for a specific candidate.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The candidate ID |

### Example

```lua
local candidate = app.integrations.freshteam.get_candidate({ id = 12345 })
print(candidate.first_name .. " " .. candidate.last_name)
print("Email: " .. candidate.email)
print("Status: " .. candidate.status)
```

---

## list_job_postings

List job postings with optional filtering by status and department.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 20) |
| `status` | string | no | Filter by status (e.g., `"published"`, `"draft"`, `"closed"`) |
| `department_id` | integer | no | Filter by department ID |

### Example

```lua
local result = app.integrations.freshteam.list_job_postings({
  page = 1,
  per_page = 10,
  status = "published"
})

for _, job in ipairs(result) do
  print(job.title .. " (" .. job.status .. ")")
end
```

---

## get_job_posting

Retrieve details for a specific job posting.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The job posting ID |

### Example

```lua
local job = app.integrations.freshteam.get_job_posting({ id = 67890 })
print(job.title)
print("Department: " .. (job.department and job.department.name or "N/A"))
print("Location: " .. (job.location or "Remote"))
```

---

## list_employees

List employees with optional department filtering.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `per_page` | integer | no | Results per page (default: 20) |
| `department_id` | integer | no | Filter by department ID |

### Example

```lua
local result = app.integrations.freshteam.list_employees({
  page = 1,
  per_page = 50
})

for _, emp in ipairs(result) do
  print(emp.first_name .. " " .. emp.last_name .. " - " .. (emp.email or ""))
end
```

---

## get_employee

Retrieve details for a specific employee.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The employee ID |

### Example

```lua
local emp = app.integrations.freshteam.get_employee({ id = 54321 })
print(emp.first_name .. " " .. emp.last_name)
print("Email: " .. emp.email)
print("Department: " .. (emp.department and emp.department.name or "N/A"))
```

---

## get_current_user

Retrieve the currently authenticated user's profile. Useful for verifying the connection.

### Parameters

None.

### Example

```lua
local user = app.integrations.freshteam.get_current_user({})
print("Logged in as: " .. user.email)
```

---

## Multi-Account Usage

If you have multiple Freshteam accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations.freshteam.list_candidates({})

-- Explicit default (portable across setups)
app.integrations.freshteam.default.list_candidates({})

-- Named accounts
app.integrations.freshteam.acme.list_candidates({})
app.integrations.freshteam.other_company.list_employees({})
```

All functions are identical across accounts — only the credentials differ.

Metadata-Derived Lua Example

local result = app.integrations.freshteam.freshteam_list_candidates({
  page = 1,
  per_page = 1,
  status = "example_status"
})
print(result)

Functions

freshteam_list_candidates

List recruitment candidates from Freshteam. Returns paginated candidate records with optional filtering by status.

Operation
Read read
Full name
freshteam.freshteam_list_candidates
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
per_page integer no Number of results per page (default: 20, max: 100).
status string no Filter candidates by status (e.g., "active", "hired", "rejected", "on_hold").

freshteam_get_candidate

Retrieve detailed information about a specific candidate in Freshteam by their ID.

Operation
Read read
Full name
freshteam.freshteam_get_candidate
ParameterTypeRequiredDescription
id integer yes The candidate ID.

freshteam_list_job_postings

List job postings from Freshteam. Returns paginated job records with optional filtering by status and department.

Operation
Read read
Full name
freshteam.freshteam_list_job_postings
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
per_page integer no Number of results per page (default: 20, max: 100).
status string no Filter job postings by status (e.g., "published", "draft", "closed", "on_hold").
department_id integer no Filter by department ID.

freshteam_get_job_posting

Retrieve detailed information about a specific job posting in Freshteam by its ID.

Operation
Read read
Full name
freshteam.freshteam_get_job_posting
ParameterTypeRequiredDescription
id integer yes The job posting ID.

freshteam_list_employees

List employees from Freshteam. Returns paginated employee records with optional filtering by department.

Operation
Read read
Full name
freshteam.freshteam_list_employees
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
per_page integer no Number of results per page (default: 20, max: 100).
department_id integer no Filter by department ID.

freshteam_get_employee

Retrieve detailed information about a specific employee in Freshteam by their ID.

Operation
Read read
Full name
freshteam.freshteam_get_employee
ParameterTypeRequiredDescription
id integer yes The employee ID.

freshteam_get_current_user

Retrieve the profile of the currently authenticated Freshteam user. Useful for verifying the connection and identifying which account is active.

Operation
Read read
Full name
freshteam.freshteam_get_current_user
ParameterTypeRequiredDescription
No parameters.