Skip to main content

​
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 TypeDescriptionExample FieldsField ID Pattern
enrichedFirmographic, 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.
listFields 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 foundersfield-, followed by a unique integer, e.g. field-1234
globalFields 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-intelligenceFields 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 TypeArray Type
textNot supported in Affinity
numbernumber-multi
datetimeNot supported in Affinity
locationlocation-multi
dropdowndropdown-multi
ranked-dropdownNot supported in Affinity
personperson-multi
companycompany-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: