canonical: https://jentic.com/apis/affinity.co/affinity

# Affinity CRM API

Jentic publishes the only available OpenAPI specification for Affinity CRM API, keeping it validated and agent-ready. Affinity is a relationship-intelligence CRM used heavily by venture capital, private equity, and investment-banking teams to track deal pipelines and the relationship graph behind them. The API exposes 42 endpoints covering Lists and ListEntries, custom Fields and FieldValues, Persons, Organizations, Opportunities, Notes, Interactions, Webhook subscriptions, and the /whoami and /rate-limit utility endpoints. Authentication uses HTTP basic auth with the API key as the password and an empty username.

## For AI agents

Manage Affinity relationship-intelligence CRM lists, persons, organizations, opportunities, and interactions across 42 REST endpoints.

## Scope

Does not handle email sending, calendar scheduling, or document signing - use for relationship-intelligence CRM data only.

## Capabilities

- Create and manage custom Lists and add entries for persons, organizations, or opportunities
- Define custom Fields and write FieldValues against any list entry
- Read and update Persons, Organizations, and Opportunities in the CRM
- Pull the Interactions graph - emails, meetings, and other touchpoints - for any record
- Manage Notes attached to people, companies, and opportunities
- Subscribe to webhook notifications for changes across the workspace
- Check rate-limit status via /rate-limit and identify the calling user via /whoami

## Use cases

### Deal Pipeline Sync for Investment Teams

Keep an Affinity deal list in sync with an external data source - a portfolio system, BI dashboard, or signal feed. POST /lists/{list_id}/list-entries adds organizations to a pipeline list and POST /field-values writes custom field values such as stage, owner, or check size. The rich /opportunities, /persons, and /organizations endpoints back this with full CRUD on the underlying records.

Example prompt: Call POST /lists/{list_id}/list-entries with an organization_id, then POST /field-values to set the stage field to 'Term Sheet'

### Relationship Intelligence Lookup

Surface who-knows-whom data for outreach. GET /interactions returns the email, calendar, and meeting touchpoints Affinity has captured, /persons/{person_id} returns the full profile, and /organizations/{organization_id} returns the firmographic context. Agents and BD teams can answer 'who on my team has the strongest relationship with this fund?' before reaching out.

Example prompt: Call GET /organizations to find the org id for Acme Capital, then GET /interactions?organization_id={id} and rank colleagues by recent interaction count

### Bidirectional Sync with External Tools

Hook Affinity into other systems via /webhook-subscriptions. POST /webhook-subscriptions registers a callback URL for events on opportunities, list entries, or notes; consumers can then update a data warehouse or trigger a Slack notification when a deal moves stages. Combine with /notes to write back commentary from external tools.

Example prompt: Call POST /webhook-subscriptions with a callback URL and event types ['list_entry.created','list_entry.updated'] to receive pipeline change events

### AI Agent Deal Research Assistant

Let an AI agent answer 'tell me about this deal' or 'who introduced us to this fund' in chat. Through Jentic, the agent searches by intent, loads the matching Affinity schema, and executes with the basic-auth credentials isolated in the vault. Useful for analysts and partners who want CRM context without leaving Slack or a notebook.

Example prompt: Search Jentic for 'find an organization in affinity', load /organizations schema, and execute with name='Acme Capital' to return the matching record

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /lists | List all custom lists in the workspace |
| POST | /lists/{list_id}/list-entries | Add a person, organization, or opportunity to a list |
| POST | /field-values | Write a custom field value on a list entry |
| GET | /organizations | List or search organizations |
| GET | /persons | List or search persons |
| GET | /opportunities | List or search opportunities |
| GET | /interactions | Read the interaction graph for persons or organizations |
| POST | /webhook-subscriptions | Subscribe to event notifications |

## Key resources

- **Lists** — Create and manage custom lists used for pipelines and segments
- **ListEntries** — Add and remove persons, organizations, or opportunities from a list
- **Fields** — Define custom fields available on lists and entries
- **FieldValues** — Write and update custom field values for list entries
- **Persons** — Manage person records in the CRM
- **Organizations** — Manage organization records in the CRM
- **Opportunities** — Manage opportunity records and stages
- **Interactions** — Read the email, calendar, and meeting interaction graph
- **Notes** — Attach notes to persons, organizations, and opportunities
- **Webhooks** — Subscribe to event notifications across the workspace
- **Auth** — /whoami and /rate-limit utility endpoints

## Why Jentic

- **Setup:** Wiring the Affinity CRM API by hand means setting up its basic-auth scheme and coding calls across lists, organizations, persons, and opportunities. Through Jentic you install once, import the Affinity CRM API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Affinity puts the list id in the URL path for list entries (/lists/{list_id}/list-entries), so a rule can pin the agent to one list, while reads of organizations, persons, and opportunities take their input as query parameters. You choose which operations are in the allowed set, so webhook subscriptions are not included unless you add them.
- **Credential handling:** Your Affinity API key is stored once, encrypted, by your own Jentic One instance as basic-auth credentials and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find an organization in Affinity', and Jentic returns the matching CRM operation with its query parameters or body schema so the agent calls organizations or opportunities without browsing the reference docs.

## Related APIs

- **Salesforce** — Enterprise CRM with the broadest customisation surface
- **Attio** — Modern relationship CRM with flexible data modelling
- **Copper** — Google Workspace native CRM
- **HubSpot Deals API** — Marketing-and-sales CRM that pairs with Affinity for inbound flows

## FAQ

### Why is there no official OpenAPI spec for the Affinity CRM API?

Affinity publishes Markdown reference docs but does not distribute an OpenAPI 3 specification. Jentic generates and maintains this spec so that AI agents and developers can call Affinity CRM API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Affinity CRM API use?

Affinity uses HTTP basic authentication with an empty username and the API key as the password, base64-encoded in the Authorization header. Through Jentic the key is stored in the vault and injected at execution time.

### Can I add an organization to an Affinity list through the API?

Yes. Call GET /lists to find the target list, then POST /lists/{list_id}/list-entries with the organization_id (or person_id, or opportunity_id) to add it as an entry. Custom field values can then be set with POST /field-values.

### How do I read the interaction history for an organization?

Call GET /interactions with the organization_id query parameter and Affinity returns the email, meeting, and other touchpoints captured for that organization, including which colleagues were involved. Use this to identify the strongest internal relationship before outreach.

### What are the rate limits for the Affinity CRM API?

Affinity exposes the current limit and remaining calls via GET /rate-limit. Specific allowances depend on plan tier; HTTP 429 responses indicate the limit has been reached and Jentic surfaces them verbatim.

### How do I subscribe a webhook through Jentic?

Run pip install jentic, search Jentic with 'subscribe to affinity changes', load the /webhook-subscriptions schema, and execute with the callback URL and event types. Jentic injects the basic-auth credentials at execution time.

### Can I limit what my agent is allowed to do with the Affinity CRM API?

Yes. Jentic One is self-hosted, so you run it and your own rules decide which Affinity operations and credentials the agent may use. Because the list id sits in the URL path for list entries (POST /lists/{list_id}/list-entries), a rule can pin the agent to a single list, while reads of organizations, persons, and opportunities are constrained through their query parameters. You choose which operations sit in the allowed set, so webhook subscriptions stay out unless you add them.