Working with Field Data

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`*

*Note that 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:

Crunchbase, including Crunchbase UUID
Pitchbook
Dealroom “exclusive” fields

Field Value Changes

The field value change endpoints are currently in beta.

Field value changes let you see the history of how a Field’s value evolved over time, including who made each change and when it occurred. This is useful for tracking an entity’s progress through a pipeline (for example, a “Status” Field moving from 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.

Multi-value Field types (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.

API V2

Data Model

Changelog

Field Types and IDs

Field Value Types

Retrieving Field Data

Specifying Desired Fields (Field Selection)

Saved Views

Partner Data Restrictions

Field Value Changes

Which Fields support change tracking

The Field Value Change resource

Action types

Retrieving changes

​Field Types and IDs

​Field Value Types

​Retrieving Field Data

​Specifying Desired Fields (Field Selection)

​Saved Views

​Partner Data Restrictions

​Field Value Changes

​Which Fields support change tracking

​The Field Value Change resource

​Action types

​Retrieving changes

Field Types and IDs

Field Value Types

Retrieving Field Data

Specifying Desired Fields (Field Selection)

Saved Views

Partner Data Restrictions

Field Value Changes

Which Fields support change tracking

The Field Value Change resource

Action types

Retrieving changes