KosmoKrator

crm

Affinity Lua API for KosmoKrator Agents

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

8 functions 6 read 2 write API key auth
Submit Affinity feedback View package source

Lua Namespace

Agents call this integration through app.integrations.affinity.*. Use lua_read_doc("integrations.affinity") 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.

Affinity CRM — Lua API Reference

list_contacts

List contacts from Affinity CRM.

Parameters

NameTypeRequiredDescription
limitintegernoMaximum number of contacts to return (default: 100, max: 500)
pageintegernoPage number for pagination (starts at 1)

Example

local result = app.integrations.affinity.list_contacts({
  limit = 50,
  page = 1
})

for _, contact in ipairs(result) do
  print(contact.first_name .. " " .. contact.last_name)
end

get_contact

Get details for a specific contact by ID.

Parameters

NameTypeRequiredDescription
idintegeryesThe Affinity contact ID

Example

local result = app.integrations.affinity.get_contact({
  id = 12345
})

print(result.first_name .. " " .. result.last_name)
if result.emails then
  for _, email in ipairs(result.emails) do
    print("  Email: " .. email.email)
  end
end

create_contact

Create a new contact in Affinity.

Parameters

NameTypeRequiredDescription
first_namestringno*The contact’s first name
last_namestringno*The contact’s last name
emailsarraynoList of email addresses, e.g. {"[email protected]"}
organization_idsarraynoList of organization IDs to link

*At least one of first_name or last_name is required.

Example

local result = app.integrations.affinity.create_contact({
  first_name = "Jane",
  last_name = "Smith",
  emails = {"[email protected]", "[email protected]"},
  organization_ids = {42}
})

print("Created contact ID: " .. result.id)

list_organizations

List organizations from Affinity CRM.

Parameters

NameTypeRequiredDescription
limitintegernoMaximum number of organizations to return (default: 100, max: 500)
pageintegernoPage number for pagination (starts at 1)

Example

local result = app.integrations.affinity.list_organizations({
  limit = 50
})

for _, org in ipairs(result) do
  print(org.name .. " — " .. (org.domain or "no domain"))
end

get_organization

Get details for a specific organization by ID.

Parameters

NameTypeRequiredDescription
idintegeryesThe Affinity organization ID

Example

local result = app.integrations.affinity.get_organization({
  id = 42
})

print(result.name)
if result.domain then
  print("Domain: " .. result.domain)
end

create_organization

Create a new organization in Affinity.

Parameters

NameTypeRequiredDescription
namestringyesThe organization’s name
domainstringnoWebsite domain (e.g., "example.com")

Example

local result = app.integrations.affinity.create_organization({
  name = "Acme Corp",
  domain = "acme.com"
})

print("Created organization ID: " .. result.id)

list_lists

List all lists in Affinity CRM.

Parameters

None.

Example

local result = app.integrations.affinity.list_lists()

for _, list in ipairs(result) do
  print(list.name .. " (type: " .. list.type .. ")")
end

get_current_user

Get the currently authenticated Affinity user’s profile.

Parameters

None.

Example

local result = app.integrations.affinity.get_current_user()

print("Logged in as: " .. result.first_name .. " " .. result.last_name)
print("Email: " .. result.email)

Multi-Account Usage

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

-- Default account (always works)
app.integrations.affinity.list_contacts({})

-- Explicit default (portable across setups)
app.integrations.affinity.default.list_contacts({})

-- Named accounts
app.integrations.affinity.work.list_contacts({})
app.integrations.affinity.client.list_contacts({})

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

Raw agent markdown 
# Affinity CRM — Lua API Reference

## list_contacts

List contacts from Affinity CRM.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Maximum number of contacts to return (default: 100, max: 500) |
| `page` | integer | no | Page number for pagination (starts at 1) |

### Example

```lua
local result = app.integrations.affinity.list_contacts({
  limit = 50,
  page = 1
})

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

---

## get_contact

Get details for a specific contact by ID.

### Parameters

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

### Example

```lua
local result = app.integrations.affinity.get_contact({
  id = 12345
})

print(result.first_name .. " " .. result.last_name)
if result.emails then
  for _, email in ipairs(result.emails) do
    print("  Email: " .. email.email)
  end
end
```

---

## create_contact

Create a new contact in Affinity.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `first_name` | string | no* | The contact's first name |
| `last_name` | string | no* | The contact's last name |
| `emails` | array | no | List of email addresses, e.g. `{"[email protected]"}` |
| `organization_ids` | array | no | List of organization IDs to link |

*At least one of `first_name` or `last_name` is required.

### Example

```lua
local result = app.integrations.affinity.create_contact({
  first_name = "Jane",
  last_name = "Smith",
  emails = {"[email protected]", "[email protected]"},
  organization_ids = {42}
})

print("Created contact ID: " .. result.id)
```

---

## list_organizations

List organizations from Affinity CRM.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Maximum number of organizations to return (default: 100, max: 500) |
| `page` | integer | no | Page number for pagination (starts at 1) |

### Example

```lua
local result = app.integrations.affinity.list_organizations({
  limit = 50
})

for _, org in ipairs(result) do
  print(org.name .. " — " .. (org.domain or "no domain"))
end
```

---

## get_organization

Get details for a specific organization by ID.

### Parameters

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

### Example

```lua
local result = app.integrations.affinity.get_organization({
  id = 42
})

print(result.name)
if result.domain then
  print("Domain: " .. result.domain)
end
```

---

## create_organization

Create a new organization in Affinity.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | yes | The organization's name |
| `domain` | string | no | Website domain (e.g., `"example.com"`) |

### Example

```lua
local result = app.integrations.affinity.create_organization({
  name = "Acme Corp",
  domain = "acme.com"
})

print("Created organization ID: " .. result.id)
```

---

## list_lists

List all lists in Affinity CRM.

### Parameters

None.

### Example

```lua
local result = app.integrations.affinity.list_lists()

for _, list in ipairs(result) do
  print(list.name .. " (type: " .. list.type .. ")")
end
```

---

## get_current_user

Get the currently authenticated Affinity user's profile.

### Parameters

None.

### Example

```lua
local result = app.integrations.affinity.get_current_user()

print("Logged in as: " .. result.first_name .. " " .. result.last_name)
print("Email: " .. result.email)
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.affinity.list_contacts({})

-- Explicit default (portable across setups)
app.integrations.affinity.default.list_contacts({})

-- Named accounts
app.integrations.affinity.work.list_contacts({})
app.integrations.affinity.client.list_contacts({})
```

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

Metadata-Derived Lua Example

local result = app.integrations.affinity.affinity_list_contacts({
  limit = 1,
  page = 1
})
print(result)

Functions

affinity_list_contacts

List contacts from Affinity CRM. Returns contact names, emails, phone numbers, and associated organizations. Use pagination to retrieve large result sets.

Operation
Read read
Full name
affinity.affinity_list_contacts
ParameterTypeRequiredDescription
limit integer no Maximum number of contacts to return (default: 100, max: 500).
page integer no Page number for pagination (starts at 1).

affinity_get_contact

Get details for a specific contact in Affinity by its ID. Returns the contact's full profile including name, emails, phone numbers, organization, and custom fields.

Operation
Read read
Full name
affinity.affinity_get_contact
ParameterTypeRequiredDescription
id integer yes The Affinity contact ID.

affinity_create_contact

Create a new contact in Affinity CRM. Provide at least a first name or last name. Optionally include email addresses.

Operation
Write write
Full name
affinity.affinity_create_contact
ParameterTypeRequiredDescription
first_name string no The contact's first name.
last_name string no The contact's last name.
emails array no List of email addresses for the contact, e.g. ["[email protected]"].
organization_ids array no List of Affinity organization IDs to link this contact to.

affinity_list_organizations

List organizations from Affinity CRM. Returns organization names, domains, and details. Use pagination to retrieve large result sets.

Operation
Read read
Full name
affinity.affinity_list_organizations
ParameterTypeRequiredDescription
limit integer no Maximum number of organizations to return (default: 100, max: 500).
page integer no Page number for pagination (starts at 1).

affinity_get_organization

Get details for a specific organization in Affinity by its ID. Returns the organization's full profile including name, domain, people, and custom fields.

Operation
Read read
Full name
affinity.affinity_get_organization
ParameterTypeRequiredDescription
id integer yes The Affinity organization ID.

affinity_create_organization

Create a new organization in Affinity CRM. Provide a name (required) and optionally a domain.

Operation
Write write
Full name
affinity.affinity_create_organization
ParameterTypeRequiredDescription
name string yes The organization's name.
domain string no The organization's website domain (e.g., "example.com").

affinity_list_lists

List all lists in Affinity CRM. Returns list names, types (contact or organization), and ownership details.

Operation
Read read
Full name
affinity.affinity_list_lists
ParameterTypeRequiredDescription
No parameters.

affinity_get_current_user

Get the currently authenticated Affinity user's profile. Useful for verifying API credentials and identifying the active account.

Operation
Read read
Full name
affinity.affinity_get_current_user
ParameterTypeRequiredDescription
No parameters.