> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To act on Guild from an MCP client, connect to https://api.guild.ai/mcp (OAuth) or run `guild mcp` locally. Setup: https://docs.guild.ai/api-reference/mcp.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Manage Affinity CRM records and relationships from Guild agents

> Connect Guild agents to Affinity to read and update companies, people, opportunities, notes, meetings, files, and relationship paths via the Affinity API.

Integrations · Affinity

A Guild agent reads and updates your Affinity CRM, searches records, retrieves interaction history, and resolves introduction paths without exposing credentials to agent code. Guild stores the Affinity API key server-side and injects it through its credential proxy, so the key never appears in agent logic. Credential policies let you restrict which operations each agent can call, and every request is auditable through that same proxy.

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Affinity.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Affinity to your first agent.

## What the Affinity integration exposes

The tools cover companies, people, opportunities, and list entries, including reading and writing field values in batch. They also cover notes, meetings, calls, emails, chat messages, transcripts, files, reminders, webhooks, and teams. Tools for duplicate detection let an agent retrieve suggestions and initiate merges for both company and person profiles. Relationship tools return interaction scores, inferred connections, and ranked introduction paths.

## How it works

**1. Open credentials in Guild**

Go to your organization at app.guild.ai and open **Access & setup > Credentials**. Guild supports account, workspace, member, and agent-scoped credentials for Affinity; see [Credentials](https://docs.guild.ai/platform/credentials.md) for the differences.

**2. Connect the Affinity integration**

Click **Connect**, select **affinity-openapi**, and paste your Affinity API key into the **API Key** field. Guild sends the key as a bearer token in the Authorization header on every request.

**3. Import tools into your agent**

Import `AffinityOpenapiTools` from `@guildai-services/guildai~affinity-openapi` and spread it into your agent's `tools` object. Use [`pick()`](https://docs.guild.ai/sdk/tools#selecting-specific-tools) with the `affinity_openapi_` prefix to include only the tools your agent needs.

## Why Affinity access needs governing

Affinity holds sensitive relationship data: interaction scores, communication history, investor connections, and deal information. An agent with unrestricted access could read every contact, update opportunity fields, merge profiles, or create webhooks across the whole organization. Guild's credential proxy enforces credential policies before any request leaves Guild, so you can write ALLOW and DENY rules scoped to specific operations, agents, or workspaces. A rule that allows only read operations on companies and persons, for example, blocks an agent from updating fields or initiating merges even if the underlying API key permits it.

Guild stores the API key server-side and injects it after the policy check passes. Agent code never sees the key. You can scope a credential to one workspace, one member, or one agent using the [Credentials](https://docs.guild.ai/platform/credentials.md) page, and pair it with [Credential policies](https://docs.guild.ai/platform/credential-policies.md) that limit the operations each agent may call. That combination keeps a narrowly scoped research agent separate from a pipeline agent that writes field values.

## About the Affinity integration

Agents can read and update CRM data in Affinity, including companies, people, opportunities, and list entries. They can create and manage notes, search records, retrieve meeting and email history, and work with files and reminders. Agents can also merge duplicate profiles and explore relationship paths and inferred connections. The integration is `guildai~affinity-openapi`.

## Authentication

* **Type:** API key
* **Header:** Guild sends the key as a bearer token in the `Authorization` header

### Setup

**1. Connect Affinity**

In Guild, go to **Access & setup > Credentials**, click **Connect**, select **affinity-openapi**, and paste the key into **API Key**.

See [Credentials](https://docs.guild.ai/platform/credentials.md) for workspace, member, and agent-scoped credentials.

## Usage

```typescript theme={null}
import { AffinityOpenapiTools } from "@guildai-services/guildai~affinity-openapi"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  systemPrompt: "You work with Affinity.",
  tools: { ...AffinityOpenapiTools },
})
```

### Selecting specific tools

Tools are named with the `affinity_openapi_` prefix. Use [`pick()`](https://docs.guild.ai/sdk/tools#selecting-specific-tools) to include only what your agent needs.

## Tools

Tools in the latest published version of `guildai~affinity-openapi`:

> [accordion] All 115 tools
>
> | Tool | What it does |
> | - | - |
> | `affinity_openapi_v2_auth_whoami_get` | Returns information about the authenticated user, their current organization, and API key permissions. |
> | `affinity_openapi_v2_calls_get` | Paginate through all calls in Affinity. |
> | `affinity_openapi_v2_chat_messages_get` | Paginate through all chat messages in Affinity. |
> | `affinity_openapi_v2_companies_company_id_fields_field_id_get` | Retrieve a single field on a company. |
> | `affinity_openapi_v2_companies_company_id_fields_field_id_post` | Update a single field value on a company. |
> | `affinity_openapi_v2_companies_company_id_fields_field_id_values_get` | Paginate through all values for a field on a company. |
> | `affinity_openapi_v2_companies_company_id_fields_get` | Paginate through field values on a single company. |
> | `affinity_openapi_v2_companies_company_id_fields_patch` | Perform batch operations on a company's fields. |
> | `affinity_openapi_v2_companies_company_id_get` | Returns basic information and non-list-specific field data on the requested Company. |
> | `affinity_openapi_v2_companies_company_id_list_entries_get` | Paginate through the List Entries (AKA rows) for the given Company across all Lists. |
> | `affinity_openapi_v2_companies_company_id_lists_get` | Paginate through all Lists where the given Company appears as an entry and that you have access to view. |
> | `affinity_openapi_v2_companies_company_id_notes_get` | Returns relevant notes for a given company which includes directly attached notes and notes attached to persons on this company. |
> | `affinity_openapi_v2_companies_company_id_relationships_get` | Returns the relationships for a given company, including the interaction score that measures the strength of each relationship based on communication patterns such as emails, meetings, and other… |
> | `affinity_openapi_v2_companies_fields_field_id_dropdown_options_get` | Returns the dropdown options for a specific dropdown or ranked-dropdown field on a Company. |
> | `affinity_openapi_v2_companies_fields_get` | Returns metadata on non-list-specific Company Fields. |
> | `affinity_openapi_v2_companies_get` | Paginate through Companies in Affinity. |
> | `affinity_openapi_v2_companies_search_post` | Search for Companies matching the given criteria. |
> | `affinity_openapi_v2_company_merges_get` | Retrieve paginated company merges for the organization. |
> | `affinity_openapi_v2_company_merges_merge_id_get` | Retrieve the status and details of a specific company merge. |
> | `affinity_openapi_v2_company_merges_post` | Initiate a company merge to combine a duplicate company profile into a primary company profile. |
> | `affinity_openapi_v2_duplicates_company_suggestions_get` | Retrieves company duplicate suggestions detected for your organization. |
> | `affinity_openapi_v2_duplicates_person_suggestions_get` | Retrieves person duplicate suggestions detected for your organization. |
> | `affinity_openapi_v2_emails_get` | Paginate through all emails in Affinity. |
> | `affinity_openapi_v2_feedback_post` | Send feedback to Affinity about a particular product area or feature. |
> | `affinity_openapi_v2_field_value_changes_get` | Retrieve field value changes across all entities and fields in your Affinity workspace. |
> | `affinity_openapi_v2_files_file_id_get` | Returns a single file's metadata and a temporary signed download URL. |
> | `affinity_openapi_v2_files_get` | Returns a page of Files visible to the caller. |
> | `affinity_openapi_v2_files_search_post` | Search files by keyword. |
> | `affinity_openapi_v2_inferred_connections_coworkers_get` | Returns inferred connections based on shared work history, grouped by the target person, strongest first. |
> | `affinity_openapi_v2_inferred_connections_investor_executive_connections_get` | Returns investor-executive inferred connections, grouped by the target person, strongest first. |
> | `affinity_openapi_v2_intro_paths_get` | Returns ranked introduction paths from an internal person to a target, strongest first. |
> | `affinity_openapi_v2_lists_get` | Paginate through all Lists in your organization that you have access to view. |
> | `affinity_openapi_v2_lists_list_id_fields_field_id_dropdown_options_dropdown_option_id_delete` | Delete a dropdown option for a List Field. |
> | `affinity_openapi_v2_lists_list_id_fields_field_id_dropdown_options_dropdown_option_id_get` | Get a single dropdown option for a List Field. |
> | `affinity_openapi_v2_lists_list_id_fields_field_id_dropdown_options_dropdown_option_id_post` | Update a dropdown option for a List Field. |
> | `affinity_openapi_v2_lists_list_id_fields_field_id_dropdown_options_get` | Returns the dropdown options for a specific dropdown, ranked-dropdown, or status-dropdown field on a List. |
> | `affinity_openapi_v2_lists_list_id_fields_field_id_dropdown_options_post` | Create a dropdown option for a List Field. |
> | `affinity_openapi_v2_lists_list_id_fields_get` | Returns metadata on the Fields available on a single List. |
> | `affinity_openapi_v2_lists_list_id_get` | Retrieve detailed information about a specific List you have access to view. |
> | `affinity_openapi_v2_lists_list_id_list_entries_get` | Paginate through the List Entries (AKA rows) on a given List. |
> | `affinity_openapi_v2_lists_list_id_list_entries_list_entry_id_fields_field_id_get` | Returns a single field value on a list entry. |
> | `affinity_openapi_v2_lists_list_id_list_entries_list_entry_id_fields_field_id_post` | Update a single field value. |
> | `affinity_openapi_v2_lists_list_id_list_entries_list_entry_id_fields_field_id_values_get` | Paginate through all values for a field on a list entry. |
> | `affinity_openapi_v2_lists_list_id_list_entries_list_entry_id_fields_get` | Paginate through all field values on a single list entry. |
> | `affinity_openapi_v2_lists_list_id_list_entries_list_entry_id_fields_patch` | Perform batch operations on a list entry's fields. |
> | `affinity_openapi_v2_lists_list_id_list_entries_list_entry_id_field_value_changes_get` | Paginate through the historical value changes on the fields of a List Entry. |
> | `affinity_openapi_v2_lists_list_id_list_entries_list_entry_id_get` | Retrieve a single list entry. |
> | `affinity_openapi_v2_lists_list_id_list_entries_post` | Adds a Company or Person to a List as a new List Entry. |
> | `affinity_openapi_v2_lists_list_id_list_entries_search_post` | Search for List Entries on a List matching the given criteria. |
> | `affinity_openapi_v2_lists_list_id_saved_views_get` | Paginate through all Saved Views you have access to view for a specific List. |
> | `affinity_openapi_v2_lists_list_id_saved_views_view_id_get` | Retrieve detailed information about a specific Saved View you have access to view. |
> | `affinity_openapi_v2_lists_list_id_saved_views_view_id_list_entries_get` | Paginate through the List Entries (AKA rows) on a given Saved View. |
> | `affinity_openapi_v2_lists_post` | Create a new List. |
> | `affinity_openapi_v2_meetings_get` | Paginate through all Meetings in Affinity. |
> | `affinity_openapi_v2_meetings_meeting_id_get` | Meetings meeting id get. |
> | `affinity_openapi_v2_notes_get` | Returns all notes, with the exception of replies. |
> | `affinity_openapi_v2_notes_note_id_attached_companies_get` | Returns directly attached companies for a given Note. |
> | `affinity_openapi_v2_notes_note_id_attached_opportunities_get` | Returns directly attached opportunities for a given Note. |
> | `affinity_openapi_v2_notes_note_id_attached_persons_get` | Returns directly attached persons for a given Note. |
> | `affinity_openapi_v2_notes_note_id_delete` | Delete a note. |
> | `affinity_openapi_v2_notes_note_id_get` | Get a Note with a given id |
> | `affinity_openapi_v2_notes_note_id_post` | Make an update to an existing note's body content or its entity associations. |
> | `affinity_openapi_v2_notes_note_id_replies_get` | This endpoint returns reply notes for a given note id. |
> | `affinity_openapi_v2_notes_post` | Create a new note. |
> | `affinity_openapi_v2_notes_search_post` | Search notes by keyword. |
> | `affinity_openapi_v2_opportunities_get` | Paginate through Opportunities in Affinity. |
> | `affinity_openapi_v2_opportunities_opportunity_id_delete` | Deletes an Opportunity. |
> | `affinity_openapi_v2_opportunities_opportunity_id_get` | Returns basic information but not field data on the requested Opportunity. |
> | `affinity_openapi_v2_opportunities_opportunity_id_notes_get` | Returns Notes for a given Opportunity which includes directly attached notes and those attached to persons on this Opportunity. |
> | `affinity_openapi_v2_opportunities_opportunity_id_post` | Updates an Opportunity. |
> | `affinity_openapi_v2_person_merges_get` | Retrieve paginated person merges for the organization. |
> | `affinity_openapi_v2_person_merges_merge_id_get` | Retrieve the status and details of a specific person merge. |
> | `affinity_openapi_v2_person_merges_post` | Initiate a person merge to combine a duplicate person profile into a primary person profile. |
> | `affinity_openapi_v2_persons_fields_field_id_dropdown_options_get` | Returns the dropdown options for a specific dropdown or ranked-dropdown field on a Person. |
> | `affinity_openapi_v2_persons_fields_get` | Returns metadata on non-list-specific Person Fields. |
> | `affinity_openapi_v2_persons_get` | Paginate through Persons in Affinity. |
> | `affinity_openapi_v2_persons_person_id_delete` | This endpoint is currently in BETA. |
> | `affinity_openapi_v2_persons_person_id_fields_field_id_get` | Retrieve a single field on a person. |
> | `affinity_openapi_v2_persons_person_id_fields_field_id_post` | Update a single field value on a person. |
> | `affinity_openapi_v2_persons_person_id_fields_field_id_values_get` | Paginate through all values for a field on a person. |
> | `affinity_openapi_v2_persons_person_id_fields_get` | Paginate through field values on a single person. |
> | `affinity_openapi_v2_persons_person_id_fields_patch` | Perform batch operations on a person's fields. |
> | `affinity_openapi_v2_persons_person_id_get` | Returns basic information and non-list-specific field data on the requested Person. |
> | `affinity_openapi_v2_persons_person_id_list_entries_get` | Paginate through the List Entries (AKA rows) for the given Person across all Lists. |
> | `affinity_openapi_v2_persons_person_id_lists_get` | Paginate through all Lists where the given Person appears as an entry and that you have access to view. |
> | `affinity_openapi_v2_persons_person_id_notes_get` | Returns notes for a given person id which includes directly attached notes, notes on meetings this person attended, and notes where this person is mentioned. |
> | `affinity_openapi_v2_persons_person_id_relationships_get` | Returns the relationships for a given person, including the interaction score that measures the strength of each relationship based on communication patterns such as emails, meetings, and other… |
> | `affinity_openapi_v2_persons_post` | This endpoint is currently in BETA. |
> | `affinity_openapi_v2_persons_search_post` | Search for Persons matching the given criteria. |
> | `affinity_openapi_v2_rate_limit_get` | Returns the current rate limit usage for the authenticated caller. |
> | `affinity_openapi_v2_reminders_get` | Returns a page of Reminders visible to the caller. |
> | `affinity_openapi_v2_reminders_post` | Creates a new Reminder. |
> | `affinity_openapi_v2_reminders_reminder_id_delete` | Deletes a Reminder. |
> | `affinity_openapi_v2_reminders_reminder_id_get` | Returns a single Reminder. |
> | `affinity_openapi_v2_reminders_reminder_id_post` | Updates a Reminder. |
> | `affinity_openapi_v2_semantic_search_post` | Perform an AI-powered semantic search. |
> | `affinity_openapi_v2_tasks_company_merges_get` | Retrieve paginated company merge tasks for the organization. |
> | `affinity_openapi_v2_tasks_company_merges_task_id_get` | Retrieve the status and details of a specific task for company merges. |
> | `affinity_openapi_v2_tasks_person_merges_get` | Retrieve paginated person merge tasks for the organization. |
> | `affinity_openapi_v2_tasks_person_merges_task_id_get` | Retrieve the status and details of a specific task for person merges. |
> | `affinity_openapi_v2_teams_get` | Paginate through all Teams in your organization that you have access to view. |
> | `affinity_openapi_v2_teams_team_id_accessible_lists_get` | Paginate through all Lists this Team has been granted access to. |
> | `affinity_openapi_v2_teams_team_id_get` | Retrieve detailed information about a specific Team. |
> | `affinity_openapi_v2_teams_team_id_members_get` | Paginate through all members of a specific Team. |
> | `affinity_openapi_v2_transcripts_get` | Paginate through all transcripts and return basic metadata only. |
> | `affinity_openapi_v2_transcripts_transcript_id_delete` | Delete a transcript. |
> | `affinity_openapi_v2_transcripts_transcript_id_fragments_get` | Get fragments of a transcript given a transcript id. |
> | `affinity_openapi_v2_transcripts_transcript_id_get` | Get a transcript with a given id with the first 100 fragments of the transcript. |
> | `affinity_openapi_v2_users_get` | Paginate through internal Users in your organization. |
> | `affinity_openapi_v2_users_user_id_get` | Returns information about a single internal User, including name, primary email address, all email addresses, photo URL, account status, and account role. |
> | `affinity_openapi_v2_webhooks_get` | Returns a page of the Webhooks created by the caller. |
> | `affinity_openapi_v2_webhooks_post` | Creates a new Webhook. |
> | `affinity_openapi_v2_webhooks_webhook_id_delete` | Deletes a Webhook. |
> | `affinity_openapi_v2_webhooks_webhook_id_get` | Returns a single Webhook created by the caller. |
> | `affinity_openapi_v2_webhooks_webhook_id_post` | Updates a Webhook. |

## Frequently asked questions

> [accordion] Can an agent listen for real-time events from Affinity, like a new company being added?
>
> Not yet. The catalog entry for `guildai~affinity-openapi` lists no webhook events, so the integration does not deliver inbound event triggers to Guild agents.

> [accordion] How do I stop one agent from merging duplicate profiles while another agent can?
>
> Write a DENY rule in [Credential policies](https://docs.guild.ai/platform/credential-policies.md) that targets the merge operations and scopes it to the agent that should be blocked. The other agent, not covered by that rule, continues to call the merge tools normally.

> [accordion] Can I use a different Affinity account in one workspace than the rest of my organization uses?
>
> Yes. Connect a workspace-scoped credential on that workspace's Credentials page and choose **The whole workspace**. Guild resolves the workspace credential ahead of the account-level credential for agents running in that workspace.

> [accordion] Does the agent code ever receive the Affinity API key?
>
> No. Guild injects the key server-side through its credential proxy after the credential policy check passes. The key is never passed to agent code.

## Put a governed agent on Affinity this week

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Affinity.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Affinity to your first agent.

## Related

**Also runs on Guild:** [Attio](https://docs.guild.ai/integrations/attio.md) · [Brex](https://docs.guild.ai/integrations/brex-openapi.md) · [Gong](https://docs.guild.ai/integrations/gong-openapi.md) · [Google Ads](https://docs.guild.ai/integrations/google-ads.md)

**Read:** Docs: [Credential policies](https://docs.guild.ai/platform/credential-policies.md) · [Credentials](https://docs.guild.ai/platform/credentials.md) · [Tools in agents](https://docs.guild.ai/sdk/tools.md)
