> ## 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. # 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](https://support.affinity.co/hc/en-us/articles/115001608232-How-to-create-a-new-column-in-a-list). 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](https://support.affinity.co/hc/en-us/articles/360058255052-Affinity-Data) fields and select [Dealroom fields](https://support.affinity.co/hc/en-us/articles/6106558518797-Dealroom-co-data-in-Affinity#h_01G2N22SVH7TJR3DJV3NQDE9HQ). 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](https://support.affinity.co/hc/en-us/articles/6106558518797-Dealroom-co-data-in-Affinity#h_01G2N22YEAZJ5TC1X9ENKZFWF5) ### 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](#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](/pages/external-api-v2/filtering) for the filter syntax, and the endpoint reference for the exact properties and operators each one supports.