Field Types and IDs
Here is a deeper look at the types of Fields in Affinity, differentiated by the scope and source of
their data:
| Field Type | Description | Example Fields | Field ID Pattern |
|---|
enriched | Firmographic, funding, and people Fields populated by Affinity. These can be “Affinity Data” Fields or come from distinct data partners. | ”Affinity Data: Description”, “Dealroom: Number of Employees” | A string representing the enrichment source, followed by the field name, e.g. affinity-data-description or dealroom-number-of-employees. |
list | Fields that are specific to the context of a given list. These can only be accessed through */list-entries endpoints in this version of the API. | Default “Status” and “Amount” columns, custom columns that pertain to a given List of deals or founders | field-, followed by a unique integer, e.g. field-1234 |
global | Fields that persist across an Affinity account and are not list-specific. | ”My Firm’s Founder Scoring Column” | field-, followed by a unique integer, e.g. field-1234 |
relationship-intelligence | Fields populated by Affinity from users’ email and calendar data that provide insight into your firm’s relationship with a given Person/Company/Opportunity. | ”Source of Introduction”, “First Email”, “Last Email”, “First Event”, “Last Event”, “Next Event”, “First Chat Message”, “Last Chat Message”, “Last Contact” | A string similar to the field’s name in-product, e.g. source-of-introduction |
Field Value Types
Field data can take a variety of shapes. These value types are described in the Affinity Help Center
creating columns in lists.
Here is a list of the same value types, as represented in this API. Notice how array types end with
-multi:
| Single Type | Array Type |
|---|
text | Not supported in Affinity |
number | number-multi |
datetime | Not supported in Affinity |
location | location-multi |
dropdown | dropdown-multi |
ranked-dropdown | Not supported in Affinity |
person | person-multi |
company | company-multi |
filterable-text* | filterable-text-multi* |
filterable-text and filterable-text-multi are special types that operate similarly
to dropdown and dropdown-multi. They are reserved for Affinity-populated Fields, and users
cannot create Fields with these types.
When an array-typed value has no data in it, the API will return null (rather than an empty
array).
Retrieving Field Data
To retrieve field data on companies, persons, or opportunities, call GET /v2/companies, GET
/v2/persons, or one of our GET */list-entries endpoints. (Note that Opportunities only have
list-specific Fields, so all their field data will live on the */list-entries endpoints.) For most
of these endpoints, you will need to specify the Fields for which you want data returned via the
fieldIds or fieldTypes parameter — Otherwise, entities will be returned without any field data
attached.
The GET /v2/companies and /v2/persons endpoints can return entities with enriched, global, and
relationship intelligence field data attached, but do not support list-specific field data. To get
comprehensive field data including list-specific field data on Companies and Persons, use the GET
*/list-entries endpoints.
Specifying Desired Fields (Field Selection)
As mentioned above, you will need to specify the Fields (either by ID or by Type) for which you want
data returned when using the following endpoints:
- GET
/v2/companies
- GET
/v2/companies/{id}
- GET
/v2/persons
- GET
/v2/persons/{id}
- GET
/v2/lists/{listId}/list-entries
Each of these endpoints has a fieldIds parameter that accepts an array of Field IDs, and a
fieldTypes parameter that accepts an array of Field Types. Use the GET */fields endpoints to get
Field IDs, Field Types, and other Field-level metadata:
- Call GET
/v2/companies/fields and /v2/persons/fields to get a list of the enriched, global,
and relationship intelligence (AKA non-list-specific) Fields that exist on Companies and Persons,
respectively. These are the Fields whose values are available to pull via GET /v2/companies, GET
/v2/companies/{id}, GET /v2/persons, and /v2/persons/{id}.
- Call GET
/v2/lists/{listId}/fields to get a list of the enriched, global, relationship
intelligence, and list-specific Fields for a given List. These are the Fields whose values are
available to pull via GET /v2/lists/{listId}/list-entries.
The following endpoints don’t require field selection:
- GET
/v2/lists/{listId}/saved-views/{viewId}/list-entries — See below. This endpoint returns just
the field data that has been pulled into the given Saved View via UI.
- GET
/v2/companies/{id}/list-entries and GET /v2/persons/{id}/list-entries — These endpoints
return comprehensive field data for the given person or company in the context of each List Entry.
Saved Views
A Saved View allows a user to configure the Fields they want to see in the UI for a given List, and
set filters and sorts on the rows on that List. A List can have multiple Saved Views. In the context
of this API, Saved Views can be useful for specifying the exact Fields for which data is needed. The
*/saved-views/{viewId}/list-entries endpoint also respects the filters that have been set on the
given Saved View in the Affinity web app. (It does not, however, respect sorts just yet.)
Partner Data Restrictions
This API supports pulling data from
Affinity Data fields and
select
Dealroom fields.
Due to the agreements we have with some of our data partners, the API does not expose data from the
following sources:
Field Value Changes
The field value change endpoints are currently in beta.
Lead to Closed Won) or for keeping an
external system in sync with Affinity.
Which Fields support change tracking
Not every Field records its history. Enriched and system-populated Fields (such as Affinity Data and
Dealroom Fields, and relationship intelligence Fields) do not track changes. Change tracking applies
to user-managed global and list Fields. When you query changes for a Field that does not support
tracking, the endpoint returns no changes for that Field rather than an error.
The Field Value Change resource
Each change record describes a single mutation to a single Field value:
| Property | Type | Description |
|---|
id | integer | The unique identifier of the change record. |
field | object | The Field whose value changed, including its id and name. |
entity | object | The Company, Person, or Opportunity the change occurred on. |
listEntry | object | The List Entry the change occurred on, or null for changes that are not scoped to a List Entry. |
changer | object | The user who made the change, or null for system-generated changes such as enrichment updates. |
changedAt | datetime | When the change occurred, in RFC 3339 format. |
actionType | string | The kind of change: add, update, or delete. See below. |
type | string | The value type of the Field (for example, dropdown, number, person-multi). Determines the shape of value. |
value | various | The value associated with the change. Its shape depends on type. See Field Value Types. |
Action types
The actionType property describes what happened to the value:
| Action Type | Meaning |
|---|
add | A value was set for the first time, or a value was added to a multi-value Field. |
update | An existing single-value Field changed from one value to another. |
delete | A value was cleared, or a value was removed from a multi-value Field. |
person-multi, company-multi, dropdown-multi, number-multi,
location-multi, filterable-text-multi) only ever produce add and delete actions, never
update. To update a multi-value Field, Affinity records a delete for the removed value and an
add for the new one.
When a referenced entity (such as a dropdown option) is deleted from Affinity after the change was
recorded, the value contains a snapshot of the value as it was at the time of the change rather
than a live reference.
Retrieving changes
There are two ways to read field value changes:
- Workspace-wide:
GET /v2/field-value-changes returns changes across every entity and Field in
your workspace. Results are returned in ascending order of changedAt. This endpoint is built for
delta-sync: within a single sync, follow pagination.nextUrl to page through results until it
becomes null, which means you have reached the most recent change. To run the next incremental
sync, record the changedAt of the last change you processed and, on your next sync, filter for
changes newer than that timestamp (for example, filter=changedAt>2024-06-01T12:00:00Z). Do not
persist nextUrl between syncs, since it is null once you are caught up.
- Per List Entry:
GET /v2/lists/{listId}/list-entries/{listEntryId}/field-value-changes
returns the change history for the Fields of a single List Entry.
Both endpoints accept a filter query parameter so you can narrow results by field.id,
changer.id, changedAt, actionType, and (on the workspace-wide endpoint) listEntry.id. See
Filtering for the filter syntax, and the endpoint reference for
the exact properties and operators each one supports.
