Skip to main content
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, where breaking changes may occur without notice or versioning. For how an app’s default version is set and overridden per request, see Versioning. 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.

​
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:

​
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:

​
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: