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

# Version Migration

Affinity API v2 uses date-based versioning: breaking changes are introduced only in new versions,
so your existing integrations remain stable on the version they were created against. Beta endpoints
are an exception — see [Beta Endpoints](https://developer.affinity.co/pages/external-api-v2/beta-endpoints.md), where breaking
changes may occur without notice or versioning.

For how an app's default version is set and overridden per request, see
[Versioning](https://developer.affinity.co/pages/external-api-v2/versioning.md). This page lists the migration steps, if any,
required to adopt each version.

For additive, non-breaking changes (new endpoints, new response properties, and other improvements
within a version), see [Previous Changes](https://developer.affinity.co/pages/changelog/previous-changes.md).

## 2024-01-01

**2024-01-01** is the initial stable release of Affinity API v2. No migration steps are required
to adopt this version.

## 2026-07-15

### Restricted opportunity field access in list-entry fields

If your integration reads list-entry fields via any of the endpoints below, field values for
opportunities that your app does not have permission to manage will now be returned with
`type: "hidden"` and `value.data: null` instead of the real value.

**Action required:**

* Update your code to handle `type: "hidden"` responses gracefully. Do not assume all field values
  in a list-entry response will have a known type and non-null data.
* If your integration writes to list-entry fields (PATCH/POST), calls targeting a field on a
  restricted opportunity will now return `403 Forbidden`. Check the response status and handle
  accordingly.

Affected endpoints:

| Method | URL |
| - | - |
| GET | `/v2/lists/{listId}/list-entries/{listEntryId}/fields` |
| GET | `/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}` |
| PATCH | `/v2/lists/{listId}/list-entries/{listEntryId}/fields` |
| POST | `/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}` |

### `quarter` added to relative date unit enum

The `unit` property in relative date filter requests now accepts `quarter` as a valid value, and
`relativeDateUnits` in filterability responses now includes `quarter`.

**Action required:**

* If your integration validates or switches on the `relativeDateUnits` values returned by
  filterability endpoints, add `quarter` as a handled case.
* No action is required if you only use relative date filters with existing unit values.

## 2026-09-17

### `is-between-relative` date filter now uses a range value

The `is-between-relative` operator's `value` is now a range object (`{ amount: [start, end], unit }`
with exactly two amounts) instead of the shape used by other relative-date operators.

For the `is-within-the-last`, `is-not-within-the-last`, `is-within-the-next`,
`is-not-within-the-next`, and `is-between-relative` operators, relative date filter `amount` values
must now be at least `1`; a value of `0` is no longer accepted. Other relative-date operators (for
example `is-exactly-relative` on Time in Current Status) are unaffected and continue to accept `0`.

**Action required:**

* If your integration sends `is-between-relative` filters, update the request to send the new range
  value shape.
* If your integration sends `is-within-the-last`, `is-not-within-the-last`, `is-within-the-next`,
  `is-not-within-the-next`, or `is-between-relative` filters with an `amount` of `0`, update it to
  send `1` or greater.

### `is-between` and `is-between-relative` filters reject inverted bounds

Search filters using the `is-between` operator now return a validation error when the first value
is greater than the second; for most date fields, equal bounds are rejected too (the
`notes.created-date` field is an exception and continues to accept equal bounds). The
`is-between-relative` operator returns a validation error when the first amount is greater than the
second amount.

**Action required:**

* Update your integration to send correctly ordered bounds for `is-between`/`is-between-relative`
  filters. Requests with inverted or (for dates) equal bounds now return `400 Bad Request` instead of
  being silently accepted.

Affected endpoints:

| Method | URL |
| - | - |
| POST | `/v2/companies/search` |
| POST | `/v2/persons/search` |
| POST | `/v2/lists/{listId}/list-entries/search` |

### New field value types: `note`, `reminder`, `list-multi`

Field metadata responses (`FieldMetadata.valueType`) and field-value responses (`value.type`) across
Companies, Persons, and Lists may now include `note`, `reminder`, or `list-multi`.

**Action required:**

* If your integration enumerates or switches on `valueType` (field metadata) or `value.type` (field
  values), add handling for `note`, `reminder`, and `list-multi`.
* No action is required if your integration already handles unrecognized field value types
  gracefully.

### `transcriptId` may be `null` on AI Notetaker notes

`transcriptId` on AI Notetaker notes can now be `null` when the org does not retain transcripts,
instead of always being an integer.

**Action required:**

* Update your integration to handle `transcriptId: null` on AI Notetaker notes.

Affected endpoints:

| Method | URL |
| - | - |
| GET | `/v2/notes` |
| GET | `/v2/notes/{noteId}` |
| GET | `/v2/notes/{noteId}/replies` |
| GET | `/v2/companies/{companyId}/notes` |
| GET | `/v2/persons/{personId}/notes` |
| GET | `/v2/opportunities/{opportunityId}/notes` |

***


## Related topics

- [Versioning & Deprecation](https://developer.affinity.co/pages/data-share/versioning.md)
- [Versioning](https://developer.affinity.co/pages/external-api-v2/versioning.md)
- [OAuth Apps and MCP Clients (CIMD)](https://developer.affinity.co/pages/external-api-v2/oauth-apps.md)
- [Previous Changes](https://developer.affinity.co/pages/changelog/previous-changes.md)
- [Authentication](https://developer.affinity.co/pages/mcp/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.