Verify authentication and get current user info, organization details, and API key permissions.

Use this to confirm your API key is working and see what you have access to.

Returns (JSON): { "user": { "id": number, // User ID "email": string, // Email address "name": string // Full name }, "tenant": { "id": number, // Organization ID "name": string, // Organization name "subdomain": string // Affinity subdomain }, "permissions": string[], // API permissions granted "summary": string // Human-readable summary }

Example usage:

• Verify API key is valid and working

• Check which organization you're connected to

• See what permissions are available

List companies (organizations) from Affinity CRM.

Returns company records with optional field data. Without fieldTypes parameter, returns only basic info (id, name, domain, domains, isGlobal).

Field Types:

• enriched: Data from Affinity Data and Dealroom (description, employees, funding, location, LinkedIn, industry, etc.)

• global: Your account's custom company fields

Important Notes:

• This endpoint does NOT support text/name filtering

• To find specific companies: use the 'ids' parameter with known company IDs

• To search/filter companies: use Saved Views via affinity_get_list_entries

• Returns max 100 companies per request; use cursor for pagination

Returns (JSON): { "data": [ { "id": number, // Company ID "name": string, // Company name "domain": string, // Primary domain "domains": string[], // All domains "isGlobal": boolean, // Is shared record "fields": [...] // Field data (if requested) } ], "count": number, // Items in response "hasMore": boolean, // More results available "nextCursor": string|null, // Pagination cursor "summary": string // Human-readable summary }

Example enriched fields returned:

• affinity-data-description (company description)

• affinity-data-number-of-employees (employee count)

• affinity-data-location (city, state, country)

• affinity-data-total-funding-amount (USD)

• affinity-data-linkedin-url

Get a single company by ID from Affinity CRM.

Returns company details with optional field data. Without fieldTypes/fieldIds, returns only basic info (id, name, domain, domains, isGlobal).

Field Types:

• enriched: Data from Affinity Data and Dealroom (description, employees, funding, location, LinkedIn, etc.)

• global: Your account's custom company fields

Returns (JSON): { "id": number, // Company ID "name": string, // Company name "domain": string, // Primary domain "domains": string[], // All domains "isGlobal": boolean, // Is shared record "fields": [ // Field data (if requested) { "id": string, // Field ID "type": string, // "enriched" or "global" "name": string, // Field name "value": { "type": string, // Value type "data": any // Field value } } ] }

Example field IDs you can request:

• affinity-data-description

• affinity-data-number-of-employees

• affinity-data-location

• affinity-data-total-funding-amount

• affinity-data-linkedin-url

• affinity-data-industry

Search for companies (organizations) in Affinity by name or domain.

This is a V1 API endpoint - search is NOT available in V2.

Use this tool to:

• Find a company by its domain (e.g., "acme.com")

• Search for companies by name

• List all companies (omit term parameter)

Search Behavior:

• Domain search: Exact and partial matching (e.g., "acme" matches "acme.com")

• Name search: Partial matching on organization name

• Empty term: Returns all organizations (paginated)

Global vs Custom Organizations:

• global=true: Shared record from Affinity's database (cannot modify/delete)

• global=false: Custom organization you created (can modify/delete)

Parameters:

• term: Company name or domain to search

• withInteractionDates: Include first/last email and event timestamps

• pageSize: Results per page (max 500)

• pageToken: Pagination token for next page

Returns (JSON): { "organizations": [ { "id": number, // Use with V2 affinity_get_company "name": string, "domain": string | null, "domains": string[], "global": boolean, // true=shared, false=custom "interaction_dates": {} // if requested } ], "next_page_token": string | null, "count": number, "hasMore": boolean }

Example use cases:

• Look up company by domain: term="acme.com"

• Search by name: term="Acme Corporation"

• Find companies at a TLD: term=".io"

Create a new company (organization) in Affinity.

This is a V1 API endpoint - creation is NOT available in V2.

Required fields:

• name: Company name

Optional fields:

• domain: Primary domain (e.g., "acme.com")

• domains: Additional domains

Important:

• Created companies are always custom (global=false)

• Global companies from Affinity's shared database cannot be created this way

• Use affinity_search_companies first to check if company exists

• Created company can be retrieved via V2 affinity_get_company using returned ID

Returns (JSON): { "id": number, // Use this ID with other tools "name": string, "domain": string | null, "domains": string[], "global": false // Always false for created companies }

Example workflow:

1. Search: affinity_search_companies with term="acme.com"

2. If not found: affinity_create_company with name, domain

3. Get full details: affinity_get_company with the returned ID

4. Add note: affinity_add_note with the returned company ID

List persons (contacts) from Affinity CRM.

Returns person records with optional field data. Without fieldTypes parameter, returns only basic info (id, firstName, lastName, primaryEmailAddress, emailAddresses, type).

Field Types:

• enriched: Data from Affinity Data (8 fields: job title, organization, location, phone, LinkedIn, etc.)

• global: Your account's custom person fields

• relationship-intelligence: Email/calendar derived data (9 fields: first/last email, events, etc.)

Important Notes:

• This endpoint does NOT support text/name filtering

• To find specific persons: use the 'ids' parameter with known person IDs

• To search/filter persons: use Saved Views via affinity_get_list_entries

• Returns max 100 persons per request; use cursor for pagination

• type="internal" means person is in your organization

Returns (JSON): { "data": [ { "id": number, // Person ID "firstName": string, // First name "lastName": string, // Last name "primaryEmailAddress": string, // Main email "emailAddresses": string[], // All emails "type": string, // "internal" or "external" "fields": [...] // Field data (if requested) } ], "count": number, // Items in response "hasMore": boolean, // More results available "nextCursor": string|null, // Pagination cursor "summary": string // Human-readable summary }

Enriched fields (8):

• affinity-data-current-job-title, affinity-data-current-organization

• affinity-data-job-titles, affinity-data-industry

• affinity-data-location, affinity-data-phone-number

• affinity-data-linkedin-url, companies (Organizations)

Relationship Intelligence fields (9):

• first-email, last-email, last-contact

• first-event, last-event, next-event

• first-chat-message, last-chat-message

• source-of-introduction

Get a single person by ID from Affinity CRM.

Returns person details with optional field data. Without fieldTypes/fieldIds, returns only basic info (id, firstName, lastName, primaryEmailAddress, emailAddresses, type).

Field Types:

• enriched: Data from Affinity Data (job title, organization, location, phone, LinkedIn)

• global: Your account's custom person fields

• relationship-intelligence: Email/calendar derived data (first/last email, events, etc.)

Returns (JSON): { "id": number, // Person ID "firstName": string, // First name "lastName": string, // Last name "primaryEmailAddress": string, // Main email "emailAddresses": string[], // All emails "type": string, // "internal" or "external" "fields": [ // Field data (if requested) { "id": string, // Field ID "type": string, // "enriched", "global", or "relationship-intelligence" "name": string, // Field name "value": { "type": string, // Value type "data": any // Field value } } ] }

Example field IDs you can request:

• affinity-data-current-job-title

• affinity-data-current-organization

• affinity-data-location

• last-email, first-email

• source-of-introduction

Search for persons (contacts) in Affinity by email, first name, or last name.

This is a V1 API endpoint - search is NOT available in V2.

Use this tool to:

• Find a person by their email address

• Search for persons by first or last name

• List all persons (omit term parameter)

Search Behavior:

• Email search: Partial domain matching works (e.g., "@company.com" finds all at that domain)

• Name search: Partial matching on first_name or last_name

• Empty term: Returns all persons (paginated)

Parameters:

• term: Email, first name, or last name to search

• withInteractionDates: Include first/last email and event timestamps

• withCurrentOrganizations: Include organization IDs the person belongs to

• pageSize: Results per page (max 500)

• pageToken: Pagination token for next page

Returns (JSON): { "persons": [ { "id": number, "first_name": string, "last_name": string, "primary_email": string | null, "emails": string[], "type": number, // 0=external, 1=internal "interaction_dates": {}, // if requested "current_organization_ids": [] // if requested } ], "next_page_token": string | null, "count": number, "hasMore": boolean }

Example use cases:

• Look up person by email before creating: term="john@example.com"

• Find all persons at a company: term="@acme.com"

• Search by name: term="John"

Create a new person (contact) in Affinity.

This is a V1 API endpoint - creation is NOT available in V2.

Required fields:

• firstName: Person's first name

• lastName: Person's last name

Optional fields:

• emails: Array of email addresses (first becomes primary)

• organizationIds: Array of organization IDs to associate

Important:

• Duplicate email addresses will return a 422 error

• Use affinity_search_persons first to check if person exists

• Created person can be retrieved via V2 affinity_get_person using returned ID

Returns (JSON): { "id": number, // Use this ID with other tools "first_name": string, "last_name": string, "primary_email": string | null, "emails": string[], "type": 0 // 0 = external contact }

Example workflow:

1. Search: affinity_search_persons with term="john@example.com"

2. If not found: affinity_create_person with firstName, lastName, emails

3. Add note: affinity_add_note with the returned person ID

Get all lists in Affinity CRM.

Lists are spreadsheet-like collections containing companies, persons, or opportunities. Each list has custom fields for tracking deals, contacts, etc.

Returns (JSON): { "data": [ { "id": number, // List ID (use for affinity_get_list_entries) "name": string, // List display name "type": string, // "company", "person", or "opportunity" "creatorId": number, // User who created the list "ownerId": number, // User who owns the list "isPublic": boolean // Whether visible to all users } ], "count": number, // Items in response "hasMore": boolean, // More results available "nextCursor": string|null, // Pagination cursor "summary": string // Human-readable summary }

Note: To get list fields/columns, use GET /v2/lists/{listId}/fields (not yet implemented). To get list entries (rows), use affinity_get_list_entries with the list ID.

Get entries (rows) from a specific Affinity list.

Each entry represents a company, person, or opportunity on the list with its field values.

Returns (JSON): { "data": [ { "id": number, // Entry ID (unique within this list) "listId": number, // The list this entry belongs to "creatorId": number, // User who added the entry "type": string, // "company", "person", or "opportunity" "createdAt": string, // When entry was added (ISO timestamp) "entity": { "id": number, // Company/Person/Opportunity ID "name": string, // Entity name "domain": string, // Domain (for companies) "isGlobal": boolean, // Is shared record "fields": [ // Field values (if requested) { "id": string, "type": string, "name": string, "value": { "type": string, "data": any } } ] } } ], "count": number, // Items in response "hasMore": boolean, // More results available "nextCursor": string|null, // Pagination cursor "summary": string // Human-readable summary }

Field Types:

• enriched: Affinity Data fields (description, employees, funding, etc.)

• global: Account-wide custom fields

• list: List-specific fields (Status, Amount, Owners, Priority, etc.)

Important: Fields are nested inside entity.fields, not at the entry level.

List opportunities from Affinity CRM.

Opportunities represent deals, fundraising leads, or other tracked items that belong to opportunity-type lists.

Returns (JSON): { "data": [ { "id": number, // Opportunity ID "name": string, // Opportunity name "listId": number // The list this opportunity belongs to } ], "count": number, // Items in response "hasMore": boolean, // More results available "nextCursor": string|null, // Pagination cursor "summary": string // Human-readable summary }

Important Notes:

• Opportunities only return basic info (id, name, listId)

• To get field data (Status, Amount, etc.), use affinity_get_list_entries with the listId

Example workflow:

1. Call affinity_list_opportunities to find opportunities

2. Use the listId to call affinity_get_list_entries with fieldTypes: ["list"] to get field values

Get a single opportunity by ID from Affinity CRM.

Returns basic opportunity info only (id, name, listId).

Returns (JSON): { "id": number, // Opportunity ID "name": string, // Opportunity name "listId": number // The list this opportunity belongs to }

Important: To get field data (Status, Amount, Owners, etc.), use affinity_get_list_entries with the opportunity's listId and fieldTypes: ["list"].

List all notes attached to a specific company in Affinity.

This is a V2 BETA endpoint - API may change.

Returns notes with HTML content, creator information, and timestamps.

Parameters:

• companyId: Company ID (required) - get from affinity_search_companies or affinity_get_company

• cursor: Pagination cursor from previous response

• limit: Items per page (default 20, max 100)

Returns (JSON): { "notes": [ { "id": number, "content": { "html": string }, "creator": { "id": number, "firstName": string, "lastName": string, "primaryEmailAddress": string }, "createdAt": string, // ISO 8601 "type": "entities" | "interaction" } ], "count": number, "hasMore": boolean, "nextCursor": string | null }

Note Types:

• "entities": Note attached directly to company/person

• "interaction": Note attached to a meeting or email

Example: Get notes for Sure Valley Ventures (ID: 223449211)

Create a new note attached to companies, persons, or opportunities in Affinity.

This is a V1 API endpoint.

IMPORTANT: Notes are add-only. Edit and delete are not supported by this MCP.

Required:

• content: Note text (plain or HTML)

• At least ONE of: companyIds, personIds, or opportunityIds

Optional:

• contentType: "text" (default) or "html" for rich formatting

HTML Content Examples:

• Bold: important

• Italic: emphasis

• Links: Pitch Deck

• Lists: Item 1Item 2

Returns (JSON): { "success": true, "note": { "id": number, // New note ID "content": string, "creator_id": number, "organization_ids": number[], "person_ids": number[], "opportunity_ids": number[], "created_at": string // ISO 8601 } }

Example - Add note with link to company: { "content": "Received pitch deck: View Deck", "companyIds": [223449211], "contentType": "html" }

Use Cases:

• Record meeting notes

• Add document links (Google Drive, Dropbox)

• Log call summaries

• Document investment decisions

Get metadata for a single Affinity list (deal pipeline).

Returns basic list information: name, type, visibility, owner.

Parameters:

• listId: List ID (required) - get from affinity_list_lists

Returns (JSON): { "id": number, "name": string, // e.g., "SVV Deal Funnel" "type": string, // "company", "person", or "opportunity" "isPublic": boolean, "creatorId": number, "ownerId": number }

List Types:

• company: Organization tracking lists

• person: Contact tracking lists

• opportunity: Deal/fundraising lists

Next Steps:

• Use affinity_get_list_fields to see available fields

• Use affinity_get_swimlanes to see pipeline stages

• Use affinity_get_list_entries to see entries

Get field definitions for an Affinity list.

Returns all fields available on a list, including:

• List-specific fields (Status, Amount, Owners, etc.)

• Global fields (account-wide custom fields)

• Enriched fields (auto-populated data for company/person lists)

Parameters:

• listId: List ID (required)

• cursor: Pagination cursor (optional)

• limit: Items per page (default 100, max 100)

Returns (JSON): { "fields": [ { "id": "field-1022243", "name": "Status", "type": "list", // "list", "global", or "enriched" "valueType": "ranked-dropdown", "allowedValues": [ // Only for dropdown fields { "text": "Lead", "rank": 0, "color": "none" }, { "text": "Portfolio", "rank": 7, "color": "purple" } ] } ], "count": number, "hasMore": boolean }

Field Types:

• list: List-specific fields (deal data)

• global: Account-wide custom fields

• enriched: Auto-populated enrichment data

Value Types:

• ranked-dropdown: Pipeline stages (Status)

• dropdown: Single-select

• dropdown-multi: Multi-select

• person-multi: Person references

• number: Numeric values

• text: Plain text

• datetime: Date/time

Get pipeline stages (swimlanes) for an Affinity list.

Swimlanes are the columns in a deal pipeline view (e.g., Lead, Meeting, Portfolio). They come from the Status field which is a ranked-dropdown.

Parameters:

• listId: List ID (required) - get from affinity_list_lists

Returns (JSON): { "listId": number, "listName": string, "statusFieldId": string, // Use this to filter entries "swimlanes": [ { "id": number, // dropdownOptionId - use for filtering "text": "Lead", // Display name "rank": 0, // Sort order (0 = first) "color": "none" // Visual indicator }, { "id": number, "text": "Portfolio", "rank": 7, "color": "purple" } ], "count": number }

Use Cases:

• Display pipeline columns in UI

• Get stage IDs for filtering list entries

• Understand deal flow progression

Note: If no Status field exists, returns error. Not all lists have swimlanes.

Get all companies at a specific pipeline stage (swimlane).

Returns companies filtered by their Status field value in a list.

Important: This tool performs client-side filtering since the Affinity API doesn't support server-side filtering by status. For large lists (>100 entries), use pagination parameters.

Parameters:

• listId: List ID (required) - get from affinity_list_lists

• swimlaneId: Swimlane/stage ID (required) - get from affinity_get_swimlanes (this is the dropdownOptionId)

• cursor: Pagination cursor (optional)

• limit: Items per page (default 100, max 100)

Returns (JSON): { "companies": [ { "id": number, "name": string, "domain": string, "isGlobal": boolean, "status": { "text": "Portfolio", "rank": 7, "color": "purple", "dropdownOptionId": number }, "listEntryId": number, "createdAt": string } ], "count": number, "swimlaneText": string, "listName": string, "hasMore": boolean }

Workflow:

1. Use affinity_list_lists to find lists

2. Use affinity_get_swimlanes to see available stages

3. Use this tool to get companies in a specific stage

Use Cases:

• "Get all companies in the Lead stage"

• "Show me portfolio companies"

• "List companies in Meeting Scheduled stage"

Get all lists where a specific company appears.

Returns list metadata for each list containing this company. Useful for discovering which deal pipelines track a specific company.

Parameters:

• companyId: Company ID (required) - get from affinity_search_companies or affinity_get_company

• cursor: Pagination cursor (optional)

• limit: Items per page (default 100, max 100)

Returns (JSON): { "lists": [ { "id": number, "name": string, // e.g., "SVV Deal Funnel" "type": string, // "company", "person", or "opportunity" "isPublic": boolean, "creatorId": number, "ownerId": number } ], "count": number, "hasMore": boolean, "nextCursor": string | null }

Note: Returns empty array if company not on any lists (very common).

Use Cases:

• "Which deal pipelines is this company in?"

• "Find all lists tracking this portfolio company"

• "Check if company is already being tracked"

Next Steps:

• Use affinity_get_company_list_entries to see full field data for each list

Get all list entries for a company across ALL lists with full field data.

Returns complete list entry data including:

• List-specific fields (Status, Amount, Owners, etc.)

• Global fields (account-wide custom fields)

• Enriched fields (auto-populated enrichment data)

• Relationship-intelligence fields (email/calendar derived)

Parameters:

• companyId: Company ID (required) - get from affinity_search_companies or affinity_get_company

• cursor: Pagination cursor (optional)

• limit: Items per page (default 100, max 100)

Returns (JSON): { "entries": [ { "id": number, // List entry ID "listId": number, // Which list this entry is on "creatorId": number, "createdAt": string, // ISO 8601 "fields": [ { "id": "field-1022243", "name": "Status", "type": "list", // "list", "global", "enriched", "relationship-intelligence" "value": { "type": "ranked-dropdown", "data": { "text": "Portfolio", "rank": 7, "color": "purple" } } } ] } ], "count": number, "hasMore": boolean, "nextCursor": string | null, "summary": { "totalEntries": number, "listsWithEntries": number, "fieldsPerEntry": number } }

Note: Returns empty array if company not on any lists (very common).

Use Cases:

• "Get all deal data for this company across pipelines"

• "Export company's complete list information"

• "See Status, Amount, Owners fields for this portfolio company"

Field Types Included:

• list: List-specific fields (Status, Amount, Owners, etc.)

• global: Account-wide custom fields

• enriched: Auto-populated enrichment data

• relationship-intelligence: Email/calendar derived data

List all notes attached to a specific person in Affinity.

This is a V2 BETA endpoint - API may change.

Returns notes with HTML content, creator information, and timestamps. Includes notes attached to meetings/emails if interaction info is present.

Parameters:

• personId: Person ID (required) - get from affinity_search_persons or affinity_get_person

• cursor: Pagination cursor from previous response

• limit: Items per page (default 20, max 100)

Returns (JSON): { "notes": [ { "id": number, "content": { "html": string }, "creator": { "id": number, "firstName": string, "lastName": string, "primaryEmailAddress": string }, "createdAt": string, // ISO 8601 "type": "entities" | "interaction", "interaction": { // Only if type === "interaction" "id": number, "type": "meeting" | "email" } } ], "count": number, "hasMore": boolean, "nextCursor": string | null }

Note Types:

• "entities": Note attached directly to person

• "interaction": Note attached to a meeting or email with this person

Example: Get notes for Barry Downes (ID: 66880587)

List all notes attached to a specific opportunity in Affinity.

This is a V2 BETA endpoint - API may change.

Returns notes with HTML content, creator information, and timestamps.

Parameters:

• opportunityId: Opportunity ID (required) - get from affinity_list_opportunities or affinity_get_opportunity

• cursor: Pagination cursor from previous response

• limit: Items per page (default 20, max 100)

Returns (JSON): { "notes": [ { "id": number, "content": { "html": string }, "creator": { "id": number, "firstName": string, "lastName": string, "primaryEmailAddress": string }, "createdAt": string, // ISO 8601 "type": "entities" | "interaction" } ], "count": number, "hasMore": boolean, "nextCursor": string | null }

Note Types:

• "entities": Note attached directly to opportunity

• "interaction": Note attached to a meeting or email about this opportunity

Use Cases:

• View deal progress notes

• Export opportunity documentation

• Review fundraising lead history

Retrieve all field values for a specific entity (person, organization, opportunity, or list entry).

This is a V1 API endpoint - field values GET is NOT available in V2.

Returns complete custom field data for an entity including:

• Global fields (account-wide custom fields)

• List-specific fields (pipeline stages, deal amounts, etc.)

• Field metadata (types, creation/update timestamps)

Use Cases:

• Get all custom fields for a company: "What data is populated for this company?"

• Inspect deal pipeline data: "Show me all fields for this list entry"

• Data quality assessment: "Which companies are missing funding amount?"

• Field comparison: "Compare field data between two opportunities"

Important: Exactly ONE Entity Parameter Required The API enforces that you must specify exactly one of:

• person_id: Get field values for a person

• organization_id: Get field values for an organization/company

• opportunity_id: Get field values for an opportunity

• list_entry_id: Get field values for a specific list entry

Providing zero parameters or multiple parameters will result in a 422 error.

Field Types: Field values include a value_type that indicates the data type:

• 0 = Person (references person ID)

• 1 = Organization (references organization ID)

• 2 = Dropdown (single-select text)

• 3 = Number (numeric value)

• 4 = Date (ISO timestamp)

• 5 = Location (city, state, country object)

• 6 = Text (free-form text)

• 7 = Ranked Dropdown (pipeline stages with id, text, rank, color)

• 8 = Formula (computed value)

• 9 = Interaction (email/meeting reference)

Global vs List-Specific Fields:

• list_entry_id = null: Global field (applies across all lists)

• list_entry_id = number: List-specific field (only for that list entry)

Field Name Resolution: Field values only contain field_id. To get field names:

1. Call GET /fields or GET /fields?list_id={id}

2. Map field_id to field name

3. Use the mapping to display human-readable field names

Parameters: Choose exactly ONE:

• person_id: Person identifier (number)

• organization_id: Organization/Company identifier (number)

• opportunity_id: Opportunity identifier (number)

• list_entry_id: List entry identifier (number)

Returns (JSON): { "fieldValues": [ { "id": number, // Field value ID "field_id": number, // Field definition ID (resolve with GET /fields) "entity_id": number, // Entity this value belongs to "entity_type": number, // 0=person, 1=organization, 2=opportunity "list_entry_id": number | null, // null=global, number=list-specific "value": any, // The actual value (type varies) "value_type": number, // 0-9 (see types above) "value_type_name": string, // Human-readable type name "created_at": string, // ISO timestamp "updated_at": string | null // ISO timestamp or null } ], "count": number, "entity_type": string, // "Person", "Organization", "Opportunity" "summary": string }

Example Use Cases:

1. Get company custom fields: { "organization_id": 303073231 } Returns: Description, Tech tags, LinkedIn URL, Location, Employee count, etc.

2. Get deal pipeline fields: { "list_entry_id": 227497865 } Returns: Status (Ranked Dropdown), Owners, Raise Amount, Stage, Female Founders, etc.

3. Get person fields: { "person_id": 250862100 } Returns: Source of Introduction, custom contact fields, etc.

Error Handling:

• 422: Must specify exactly one entity parameter

• 422: Invalid entity ID (entity does not exist)

• Empty array: Entity exists but has no field values

Retrieve change history for a specific field, showing who changed what and when.

This is a V1 API endpoint - field value changes GET is NOT available in V2.

Returns complete audit trail for field modifications including:

• Who made the change (name, email)

• When the change occurred (timestamp)

• What changed (new value, previous value for updates)

• Type of change (create, update, delete)

CRITICAL: Not All Fields Support Change Tracking

The API only supports change tracking for SOME fields. Common patterns:

• ✅ Status fields (Ranked Dropdown - type 7): SUPPORTED

• ✅ Owners fields (Person - type 0): SUPPORTED

• ✅ Number fields (type 3): SUPPORTED

• ❌ Some Text fields (type 6): NOT SUPPORTED

• ❌ Some Dropdown fields (type 2): NOT SUPPORTED

If a field doesn't support tracking, the API returns 422 error: "Tracking changes for this entity attribute is not yet supported"

Use Cases:

• Track deal progression: "Show me how this deal moved through pipeline stages"

• Accountability: "Who changed the deal amount and when?"

• Audit trail: "What changes were made to this field in the last week?"

• Team activity: "Which team members are most active in updating deals?"

• Data quality: "What values were deleted and when?"

Required Parameter:

• field_id: The specific field to track changes for (REQUIRED)

Optional Filters:

• action_type: Filter by change type (0=Create, 1=Update, 2=Delete)

• person_id: Show changes only for this person

• organization_id: Show changes only for this organization

• list_entry_id: Show changes only for this list entry

• page_size: Number of results (default 100, max 500)

Action Type Enum (INTEGER values):

• 0 = Create: Field value was created/added

• 1 = Update: Field value was modified in place

• 2 = Delete: Field value was removed/deleted

Returns (JSON): { "changes": [ { "id": number, // Change record ID "field_id": number, // Field that changed "field_value_id": number|null, // Field value record "changer": { "id": number, "first_name": string, "last_name": string, "primary_email": string|null }, "changed_at": string, // ISO timestamp "action_type": number, // 0, 1, or 2 "action_type_name": string, // "Create", "Update", "Delete" "value": any, // New value "previous_value": any // Old value (if update) } ], "count": number, "field_id": number, "action_type_distribution": { // Summary stats "create": number, "update": number, "delete": number }, "unique_changers": number, "summary": string }

Example Use Cases:

1. Track Status field changes: { "field_id": 4494246 } Returns: Complete history of stage movements

2. Filter by action type (deletes only): { "field_id": 4494246, "action_type": 2 } Returns: Only deleted/removed values

3. Track who changed Owners field: { "field_id": 4494247 } Returns: History of ownership changes with user details

Important Notes:

• field_id is REQUIRED

• action_type must be integer (0, 1, or 2), not string

• API may return ALL results regardless of page_size

• Use affinity_get_list_fields to find field IDs for a list

• Try Status fields first (most likely to have change tracking)

Error Handling:

• 422 + "not yet supported": Field doesn't support change tracking

• 422 + "valid id for model": Invalid field_id

• Empty array: Field exists and supports tracking, but no changes yet

Retrieve all global (account-wide) field definitions for persons.

This is a V1 API endpoint - persons fields GET is NOT available in V2.

Returns complete schema information for person fields including:

• Field names and IDs

• Field types (text, number, dropdown, etc.)

• Dropdown options (available choices)

• Multiple value support

• Enrichment sources (external data providers)

Use Cases:

• Schema discovery: "What person fields exist in our CRM?"

• Form generation: Build dynamic forms based on available fields

• Field validation: Check if input values are valid for dropdown fields

• Field resolution: Map field IDs to human-readable names

• Data source tracking: Identify which fields come from enrichment providers

No Parameters Required: This is a simple GET request with no parameters. Returns all global person fields.

Returns (JSON): { "fields": [ { "id": number, // Field identifier "name": string, // Field display name "value_type": number, // 0-9 enum (see types below) "value_type_name": string, // Human-readable type "allows_multiple": boolean, // Can have multiple values "dropdown_options": [...], // Available choices (if dropdown) "enrichment_source": string // e.g., "affinity-data", "crunchbase" } ], "count": number, "by_type": { // Distribution by field type "Dropdown": number, "Text": number, ... }, "by_source": { // Distribution by data source "affinity-data": number, "none": number, ... }, "summary": string }

Field Value Types:

• 0 = Person: References another person

• 1 = Organization: References an organization

• 2 = Dropdown: Single/multi-select from predefined options

• 3 = Number: Numeric value

• 4 = Date: Date/timestamp

• 5 = Location: Geographic location (city, state, country)

• 6 = Text: Free-form text

• 7 = Ranked Dropdown: Ordered dropdown (e.g., pipeline stages)

• 8 = Formula: Computed/calculated value

• 9 = Interaction: Email/meeting reference

Enrichment Sources:

• "affinity-data": Affinity's proprietary data

• "crunchbase": Crunchbase data

• "dealroom": Dealroom data

• "none" or null: Custom fields created by your team

Example Use Cases:

1. Discover all person fields: No parameters needed Returns: Complete list of person field schemas

2. Find dropdown fields: Filter response by fields that have dropdown_options

3. Identify enriched fields: Filter by enrichment_source to see external data

4. Build dynamic forms: Use field definitions to generate input forms programmatically

Response Format: Use responseFormat parameter to get either:

• "json": Structured data with statistics (default)

• "markdown": Human-readable formatted output

Retrieve all global (account-wide) field definitions for organizations/companies.

This is a V1 API endpoint - organizations fields GET is NOT available in V2.

Returns complete schema information for organization fields including:

• Field names and IDs

• Field types (text, number, dropdown, etc.)

• Dropdown options (available choices)

• Multiple value support

• Enrichment sources (external data providers like Crunchbase, Dealroom)

Use Cases:

• Schema discovery: "What company fields exist in our CRM?"

• Form generation: Build dynamic forms based on available fields

• Field validation: Check if input values are valid for dropdown fields

• Field resolution: Map field IDs to human-readable names

• Data source tracking: Identify which fields come from enrichment providers

• Integration planning: Understand what data is available for export/sync

No Parameters Required: This is a simple GET request with no parameters. Returns all global organization fields.

Returns (JSON): { "fields": [ { "id": number, // Field identifier "name": string, // Field display name "value_type": number, // 0-9 enum (see types below) "value_type_name": string, // Human-readable type "allows_multiple": boolean, // Can have multiple values "dropdown_options": [...], // Available choices (if dropdown) "enrichment_source": string // e.g., "crunchbase", "dealroom" } ], "count": number, "by_type": { // Distribution by field type "Dropdown": number, "Text": number, "Number": number, ... }, "by_source": { // Distribution by data source "crunchbase": number, "dealroom": number, "affinity-data": number, "none": number }, "custom_fields": number, // Count of non-enriched fields "enriched_fields": number, // Count of enriched fields "summary": string }

Field Value Types:

• 0 = Person: References a person

• 1 = Organization: References another organization

• 2 = Dropdown: Single/multi-select from predefined options

• 3 = Number: Numeric value (funding, employees, revenue, etc.)

• 4 = Date: Date/timestamp (founding date, last contact, etc.)

• 5 = Location: Geographic location (HQ, offices)

• 6 = Text: Free-form text (description, notes)

• 7 = Ranked Dropdown: Ordered dropdown (stages, priorities)

• 8 = Formula: Computed/calculated value

• 9 = Interaction: Email/meeting reference

Enrichment Sources:

• "crunchbase": Company data from Crunchbase (funding, employees, investors)

• "dealroom": European startup data from Dealroom

• "affinity-data": Affinity's proprietary enrichment data

• "none" or null: Custom fields created by your team

Example Use Cases:

1. Discover all organization fields: No parameters needed Returns: Complete list of organization field schemas

2. Find enriched fields: Filter response by enrichment_source to see external data

3. Identify custom fields: Filter by enrichment_source = "none" to see team-created fields

4. Get dropdown options: Filter by fields with dropdown_options to see valid choices

5. Plan data exports: Understand complete schema before building integrations

Response Format: Use responseFormat parameter to get either:

• "json": Structured data with statistics (default)

• "markdown": Human-readable formatted output

Find who on your team has the strongest connections to an external contact.

This is a V1 API endpoint - NOT available in V2.

Essential for warm introductions - discover hidden network connections between your team and prospects.

Use Case: "Who should make the introduction to this prospect?"

Required Parameter:

• external_id: The external person you want to find connections to (REQUIRED)

Optional Parameters:

• internal_id: Filter to specific team member's connection

• page_size: Results per page (default 100, max 500)

Returns: Array of relationships with strength scores (0.0-1.0):

• 0.8-1.0: Very Strong (ideal for warm intros)

• 0.6-0.8: Strong (good for introductions)

• 0.4-0.6: Moderate (may be useful)

• 0.0-0.4: Weak (limited connection)

Important Limitations:

• Can only query "who knows this person", not "who does this person know"

• Cannot query by organization to find team connections to a company

• Must query one external person at a time

• Relationship data may be sparse

Example: Query: external_id=123456 Result: Shows Alice (92% strength), Bob (65% strength) know this person Action: Ask Alice to make the warm introduction