Previous Changes

July 15th, 2026 — Version 2026-07-15

A new API version 2026-07-15 has been released. All future additions to the API will be made against this version. The 2024-01-01 version is now locked and will not receive further changes. To use this version, set the X-Affinity-Api-Version: 2026-07-15 header on your requests, or update the Default API Version on your API key in Settings > Manage Apps. You can also update existing keys to use the new version when you’re ready to switch. Learn more about Versioning

Breaking changes

Restricted opportunity field access in list-entry fields Field values for opportunities that the caller does not have permission to manage are now redacted in list-entry field responses: type is returned as "hidden" and value.data as null. Write requests (PATCH/POST) targeting fields on a restricted opportunity return 403 Forbidden.

Method	URL	Summary
GET	`/v2/lists/{listId}/list-entries/{listEntryId}/fields`	Get field values on a single List Entry
GET	`/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}`	Get a single field value
PATCH	`/v2/lists/{listId}/list-entries/{listEntryId}/fields`	Perform batch operations on a list entry’s fields
POST	`/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}`	Update a single field value on a List Entry

quarter added to relative date unit enum quarter is now a valid value for the unit property in relative date filter requests, and is included in the relativeDateUnits field of filterability responses.

New features

win_rate on status dropdown option updates The dropdown option update endpoint now accepts a win_rate property when the option’s status category is Open. Providing win_rate when the effective status is not Open returns a validation error.

Method	URL	Summary
POST	`/v2/lists/{listId}/fields/{fieldId}/dropdown-options/{dropdownOptionId}`	Update a dropdown option for a List Field

June 19th, 2026

Added the following endpoints in Beta:

Method	URL	Summary
POST	`/v2/companies/search`	Search Companies
POST	`/v2/persons/search`	Search Persons
POST	`/v2/lists/{listId}/list-entries/search`	Search List Entries

These endpoints support filtering, sorting, and keyword search across Companies, Persons, and List Entries. Use GET /v2/companies/fields, GET /v2/persons/fields, or GET /v2/lists/{listId}/fields?includes=filterability (for list searches) to discover the fields available for filtering and sorting.

Added the optional createdAt property to the POST /v2/notes request body. A note can now be backfilled with a past creation time:

Method	URL	Summary
POST	`/v2/notes`	Create a Note

June 18th, 2026

Added the createdAt property (the date and time the list was created) to the responses of the following endpoints:

Method	URL	Summary
GET	`/v2/lists`	Get all Lists
GET	`/v2/lists/{listId}`	Get a single List
POST	`/v2/lists`	Create a List

Added the createdAt property to each field in the responses of the following field metadata endpoints. It is the date and time the field was created, and is null for system-defined fields (identity, association, and relationship intelligence fields), which are not created by a user:

Method	URL	Summary
GET	`/v2/persons/fields`	Get metadata on Person Fields
GET	`/v2/companies/fields`	Get metadata on Company Fields
GET	`/v2/lists/{listId}/fields`	Get metadata on a single List’s Fields

Added the optional creator property to the POST /v2/notes request body. A note can now be attributed to a specific internal person instead of the calling user:

Method	URL	Summary
POST	`/v2/notes`	Create a Note

June 3rd, 2026

Added the following endpoints in Beta:

Method	URL	Summary
GET	`/v2/lists/{listId}/list-entries/{listEntryId}/field-value-changes`	Get all field value changes for a list entry
POST	`/v2/notes`	Create a Note
POST	`/v2/notes/{noteId}`	Update a single Note
DELETE	`/v2/notes/{noteId}`	Delete a single Note
POST	`/v2/notes/search`	Search Notes by keyword
POST	`/v2/files/search`	Search Files by keyword

May 26th, 2026

Added the following endpoints in Beta:

Method	URL	Summary
GET	`/v2/companies/fields/{fieldId}/dropdown-options`	Get dropdown options for a Company Field
POST	`/v2/lists/{listId}/fields/{fieldId}/dropdown-options`	Create a dropdown option for a List Field
GET	`/v2/lists/{listId}/fields/{fieldId}/dropdown-options/{dropdownOptionId}`	Get a dropdown option for a List Field
POST	`/v2/lists/{listId}/fields/{fieldId}/dropdown-options/{dropdownOptionId}`	Update a dropdown option for a List Field
DELETE	`/v2/lists/{listId}/fields/{fieldId}/dropdown-options/{dropdownOptionId}`	Delete a dropdown option for a List Field
POST	`/v2/lists`	Create a List
GET	`/v2/persons/fields/{fieldId}/dropdown-options`	Get dropdown options for a Person Field
GET	`/v2/reminders`	Get all Reminders
POST	`/v2/reminders`	Create a Reminder
GET	`/v2/users`	Get a collection of users
GET	`/v2/users/{userId}`	Get a single user
GET	`/v2/field-value-changes`	Get all field value changes

May 22nd, 2026

Added the filter query parameter to the following endpoints. The name property supports = (exact match) and =~ (case-insensitive substring):

Method	URL	Summary
GET	`/v2/companies/fields`	Get metadata on Company Fields
GET	`/v2/persons/fields`	Get metadata on Person Fields
GET	`/v2/lists/{listId}/fields`	Get metadata on a single List’s Fields

April 28th, 2026

Added the following endpoints in BETA:

Method	URL	Summary
GET	`/v2/companies/{companyId}/fields`	Get field values on a single Company
PATCH	`/v2/companies/{companyId}/fields`	Perform batch operations on a company’s fields
GET	`/v2/companies/{companyId}/fields/{fieldId}`	Get a single field value on a Company
POST	`/v2/companies/{companyId}/fields/{fieldId}`	Update a single field value on a Company
GET	`/v2/persons/{personId}/fields`	Get field values on a single Person
PATCH	`/v2/persons/{personId}/fields`	Perform batch operations on a person’s fields
GET	`/v2/persons/{personId}/fields/{fieldId}`	Get a single field on a Person
POST	`/v2/persons/{personId}/fields/{fieldId}`	Update a single field value on a Person

March 2nd, 2026

Removed “Export All People directory” permission from the following endpoint:

Method	URL	Summary
GET	`/v2/persons/{personId}`	Get a single Person

Removed “Export All Organizations directory” permission from the following endpoint:

Method	URL	Summary
GET	`/v2/companies/{companyId}`	Get a single Company

Removed “Export data from Lists” permission from the following endpoints:

Method	URL	Summary
GET	`/v2/companies/{companyId}/list-entries`	Get a Company’s List Entries
GET	`/v2/persons/{personId}/list-entries`	Get a Person’s List Entries
GET	`/v2/lists/{listId}/list-entries/{listEntryId}`	Get a single List Entry on a List
GET	`/v2/lists/{listId}/list-entries/{listEntryId}/fields`	Get field values on a single List Entry
GET	`/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}`	Get a single field value
GET	`/v2/opportunities/{opportunityId}`	Get a single Opportunity

February 26th, 2026

Added the following endpoint:

Method	URL	Summary
POST	`/v2/semantic-search`	Perform an AI-powered semantic search

February 5th, 2026

Added the following endpoint:

Method	URL	Summary
POST	`/v2/feedback`	Send feedback to Affinity

January 30th, 2026

The following endpoints are no longer in BETA:

Method	URL	Summary
GET	`/v2/notes`	Get all Notes
GET	`/v2/notes/{noteId}`	Get a Note with a given id
GET	`/v2/notes/{noteId}/attached-companies`	Get directly attached companies for a Note
GET	`/v2/notes/{noteId}/attached-opportunities`	Get directly attached opportunities for a Note
GET	`/v2/notes/{noteId}/attached-persons`	Get directly attached persons for a Note
GET	`/v2/notes/{noteId}/replies`	Get reply notes for a given Note

January 26th, 2026

Added the following endpoints in BETA:

Method	URL	Summary
GET	`/v2/transcripts`	Get All Transcripts
GET	`/v2/transcripts/{transcriptId}`	Get Transcript
GET	`/v2/transcripts/{transcriptId}/fragments`	Get Fragments on a single Transcript

January 14th, 2026

Rate limit response headers have been updated to use lowercase formatting. This change affects all API endpoints. The new lowercase headers are:

Header	Description
x-ratelimit-limit-user	Number of requests allowed per minute for the user
x-ratelimit-limit-user-remaining	Number of requests remaining for the user
x-ratelimit-limit-user-reset	Time in seconds before the limit resets for the user
x-ratelimit-limit-org	Number of requests allowed per month for the account
x-ratelimit-limit-org-remaining	Number of requests remaining for the account
x-ratelimit-limit-org-reset	Time in seconds before the limit resets for the account

January 1st, 2026

Handling timestamps for date fields. Affinity is standardizing how dates are represented across the platform to ensure consistency between the application and the API. Starting January 1st, 2026, the API will change how it handles timestamps for date fields. Today, timestamps sent to date fields over the API are not visible to users in any CRM interface. After this change, the API will ignore any time information included in requests, storing and returning values at midnight Pacific Time (PT) on the submitted date.

Example:

API request includes: 2024-04-01T15:30:00Z
Affinity will store and return: 2024-04-01T07:00:00.000Z (equivalent to midnight PT)

Any existing date field values that currently include timestamps will also be updated to reflect midnight PT on their stored date. No action is required unless your integration depends on time data within date fields.

September 25th, 2025

Added the following endpoints in BETA:

Method	URL	Summary
GET	`/v2/company-merges`	Get All Company Merge status
POST	`/v2/company-merges`	Initiate Company Merge
GET	`/v2/company-merges/{mergeId}`	Get Company Merge status
GET	`/v2/tasks/company-merges`	Get All Company Merge Tasks
GET	`/v2/tasks/company-merges/{taskId}`	Get Company Merge Task

July 30th, 2025

Added the following endpoints in BETA:

Method	URL	Summary
GET	`/v2/person-merges`	Get All Person Merge status
POST	`/v2/person-merges`	Initiate Person Merge
GET	`/v2/person-merges/{mergeId}`	Get Person Merge status
GET	`/v2/tasks/person-merges`	Get All Person Merge Tasks
GET	`/v2/tasks/person-merges/{taskId}`	Get Person Merge Task
GET	`/v2/notes`	Get all Notes
GET	`/v2/notes/{noteId}`	Get a Note with a given id
GET	`/v2/notes/{noteId}/attached-companies`	Get directly attached companies for a Note
GET	`/v2/notes/{noteId}/attached-opportunities`	Get directly attached opportunities for a Note
GET	`/v2/notes/{noteId}/attached-persons`	Get directly attached persons for a Note
GET	`/v2/notes/{noteId}/replies`	Get reply notes for a given Note

May 14th, 2025

Renamed all path parameters named simply “id” to a more descriptive name (eg. “personId”). This will not have any effect on the API at runtime, but may impact code relying on the OpenAPI spec doing type generation.

April 9th, 2025

The following endpoints are no longer in BETA:

Method	URL	Summary
GET	`/v2/lists/{listId}/list-entries/{listEntryId}`	Get a single List Entry on a List
GET	`/v2/lists/{listId}/list-entries/{listEntryId}/fields`	Get field values on a single List Entry
PATCH	`/v2/lists/{listId}/list-entries/{listEntryId}/fields`	Perform batch operations on a list entry’s fields
GET	`/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}`	Get a single field value
POST	`/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}`	Update a single field value on a List Entry

March 31st, 2025

The following beta endpoints now support updating association fields.

Method	URL	Summary
PATCH	`/v2/lists/{listId}/list-entries/{listEntryId}/fields`	Perform batch operations on a list entry’s fields
POST	`/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}`	Update a single field value on a List Entry

February 28th, 2025

Added the following endpoints in BETA:

Method	URL	Summary
GET	`/v2/lists/{listId}/list-entries/{listEntryId}`	Get a single List Entry on a List
GET	`/v2/lists/{listId}/list-entries/{listEntryId}/fields`	Get field values on a single List Entry
PATCH	`/v2/lists/{listId}/list-entries/{listEntryId}/fields`	Perform batch operations on a list entry’s fields
GET	`/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}`	Get a single field value
POST	`/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}`	Update a single field value on a List Entry

January 17th, 2025

Document X-Ratelimit headers in the schema for all endpoints.

January 15th, 2025

Add default responses to all endpoints to document all possible error codes that can be returned by the API.
Updated 400 error responses to correctly include the bad-request error code as a possible error.

December 3rd, 2024

Properly document listId property on CompanyListEntry, PersonListEntry, and OpportunityListEntry schemas.

September 25th, 2024

Upgrade schema to OpenAPI 3.1

August 5, 2024

Correct opp to opportunity to match documentation for the List type property.

July 24, 2024

More accurate documentation for response properties that are enums — Enums with null as a possible value will have it listed as one.

March 25, 2024

Added the ability to retrieve the date and other details of your firm’s “First Email”, “Last Email”, “First Event”, “Last Event”, “Next Event”, “First Chat Message”, “Last Chat Message”, and “Last Contact” with a given entity. Use these timestamps to add relationship context to your applications, and to identify founders and companies that need investors’ attention.
Endpoints that previously required a fieldIds parameter to return field data, now accept either fieldIds or fieldTypes, and will return field data accordingly. See the Specifying Desired Fields (Field Selection) section of these docs for more information. The new fieldTypes parameter should make field data retrieval easier for users looking to pull data from many similar Fields at a time.

January 4, 2023

Most endpoints that return field data now require the user to use the fieldIds parameter to specify which Fields they want data for. Without fieldIds specified, these endpoints will return basic entity data but not field data.

December 12, 2023

Added the ability to retrieve metadata (e.g. ID, name, type, enrichment source, and data type) on Fields. See the Retrieving Field Metadata section of these docs for more information.

API V2

Data Model

Changelog

July 15th, 2026 — Version 2026-07-15

Breaking changes

New features

June 19th, 2026

June 18th, 2026

June 3rd, 2026

May 26th, 2026

May 22nd, 2026

April 28th, 2026

March 2nd, 2026

February 26th, 2026

February 5th, 2026

January 30th, 2026

January 26th, 2026

January 14th, 2026

January 1st, 2026

September 25th, 2025

July 30th, 2025

May 14th, 2025

April 9th, 2025

March 31st, 2025

February 28th, 2025

January 17th, 2025

January 15th, 2025

December 3rd, 2024

September 25th, 2024

August 5, 2024

July 24, 2024

March 25, 2024

January 4, 2023

December 12, 2023

​July 15th, 2026 — Version 2026-07-15

​Breaking changes

​New features

​June 19th, 2026

​June 18th, 2026

​June 3rd, 2026

​May 26th, 2026

​May 22nd, 2026

​April 28th, 2026

​March 2nd, 2026

​February 26th, 2026

​February 5th, 2026

​January 30th, 2026

​January 26th, 2026

​January 14th, 2026

​January 1st, 2026

​September 25th, 2025

​July 30th, 2025

​May 14th, 2025

​April 9th, 2025

​March 31st, 2025

​February 28th, 2025

​January 17th, 2025

​January 15th, 2025

​December 3rd, 2024

​September 25th, 2024

​August 5, 2024

​July 24, 2024

​March 25, 2024

​January 4, 2023

​December 12, 2023

July 15th, 2026 — Version 2026-07-15

Breaking changes

New features

June 19th, 2026

June 18th, 2026

June 3rd, 2026

May 26th, 2026

May 22nd, 2026

April 28th, 2026

March 2nd, 2026

February 26th, 2026

February 5th, 2026

January 30th, 2026

January 26th, 2026

January 14th, 2026

January 1st, 2026

September 25th, 2025

July 30th, 2025

May 14th, 2025

April 9th, 2025

March 31st, 2025

February 28th, 2025

January 17th, 2025

January 15th, 2025

December 3rd, 2024

September 25th, 2024

August 5, 2024

July 24, 2024

March 25, 2024

January 4, 2023

December 12, 2023