> ## 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.
# Create a Note
> | ⚠️ This endpoint is currently in BETA |
|--|
Create a new note. By default it is authored by the calling user; set `creator` to attribute
it to a different internal person in your organization. Notes can be attached directly to
entities (`Persons`, `Companies`, `Opportunities`), anchored to an interaction (`meeting`,
`call`, or `chat message`), or written as a reply to an existing note.
The `type` field selects the shape of the request body. AI Notetaker note types
(`ai-notetaker`, `ai-notetaker-reply`) are system-generated and cannot be created through
this endpoint.
| **`type`** | **Description** | **Required** | **Optional** |
|------------|-----------------|--------------|--------------|
| `entities` | A note attached directly to one or more entities. | `content`, and at least one of `persons` / `companies` / `opportunities`. | Any combination of `persons` / `companies` / `opportunities`. |
| `interaction` | A note anchored to a meeting, call, or chat message. | `content`, `interaction.{type,id}`. | `persons` / `companies` / `opportunities`, added as direct associations on top of the interaction's own participants. |
| `user-reply` | A reply to an existing root note. Replies have no entity associations or interaction attachment of their own. | `content`, `parent.id` (must reference an existing root note the caller can access). | None |
By default a note is authored by the calling user. To attribute a note to a different member
of your organization, set the optional `creator` field to reference that person by id. The
referenced person must be an active internal person in your organization.
By default a note's creation time is the time of the request. To backfill a historical note,
set the optional `createdAt` field to the time the note should be recorded as created.
**Body content.** `content.html` is rendered HTML that must use only the allowed tags;
submitting restricted tags, attributes, URL schemes, or mention spans will cause the request to
fail. See the request examples below for representative payloads.
## OpenAPI
````yaml /schema/temp/publish.yml post /v2/notes
openapi: 3.1.1
info:
version: 0.0.1
x-affinity-api-version: '2024-01-01'
contact:
email: support@affinity.co
name: Affinity Support
url: https://support.affinity.co
description: >
# Introduction
Welcome to Affinity API v2! This API provides a RESTful interface for
building internal apps,
automated workflows, 3rd party integrations, and for connecting Affinity to
the rest of your tech
stack.
The legacy Affinity v1 API can be found at
[api-docs.affinity.co](https://api-docs.affinity.co/).
The v2 API is not at feature parity with v1 - we are continuing to develop
new v2 APIs to support
all v1 functionality over time.
**The Affinity APIs are only available on select license types.** See
[this Help Center
article](https://support.affinity.co/hc/en-us/articles/5563700459533-Getting-started-with-the-Affinity-API-FAQs)
or contact your Customer Success Manager for more information.
# Getting Started
All Affinity API endpoints use the base URL `https://api.affinity.co`. All
v2 endpoint paths start
with `/v2`. Requests must be sent over HTTPS.
The first few sections of these docs cover general information on the API.
Each subsequent section
covers a set of API endpoints.
Each endpoint is documented with its accepted request parameters, expected
response shapes, and a
sample request and response. The shape of a given response can vary
depending on what "type" of
object or data is being returned. When this is the case, the response
documentation will include a
dropdown that can be used to select the "type" for which to display the
response shape.
## Authentication
Affinity API v2 uses API keys and **bearer authentication**.
To generate an API key, navigate to the Manage Apps Page in your Affinity
Settings. You will need
the "Generate an API key" role-based permission controlled by your Affinity
admin. See
[this Help Center
article](https://support.affinity.co/hc/en-us/articles/360032633992-How-to-obtain-your-API-Key)
for full instructions on API key generation, and
[this
article](https://support.affinity.co/hc/en-us/articles/360015976732-Account-Level-Permissions)
for more information on role-based permissions in Affinity.
Provide your API key as your bearer authentication token to start making
calls to Affinity API v2.
You can create multiple API keys and provide a name and description for
each. Your API key is able
to read data and perform actions in Affinity on your behalf, so keep it safe
as you would a
password. To further secure an API key, you can define an IP Allowlist to
limit which IP addresses
or ranges can make API calls using that key.
## Permissions
### Overall Requirements
You must have the "Generate an API key" permission to be able to work with
the Affinity API. Most
users in Affinity have this by default — Contact your Affinity admin if you
are not able to generate
an API key, and see
[this
article](https://support.affinity.co/hc/en-us/articles/360015976732-Account-Level-Permissions)
for more information on role-based permissions in Affinity.
### Resource-Level Permissions
The Affinity API respects sharing permissions that are set in-product. For
example, if a given user
does not have access to a list, note, or interaction in-product, they will
not be able to see or
modify it via API.
### Endpoint-Level Permissions
Many API endpoints require endpoint-specific permissions in-product. These
permissions, along with
the "Generate an API key" permission, are managed by your Affinity admin in
the Settings page. In
the description of each endpoint you will see the required permissions
needed.
## Rate Limits
The Affinity API sets a limit on the number of calls that a user can make
per minute, and that all
the users on an account can make per month. It also sets a reasonable limit
on the number of
concurrent requests it will support from an account at one time.
Requests to **both** Affinity API versions will count toward the one pool of
requests allowed for a
user or account. Once a per-minute, monthly, or concurrent rate limit is
hit, subsequent requests
will return an error code of 429. **We highly recommend designing your
application to handle 429
errors.**
### Per-Minute Limits (User-Level)
To help protect our systems, API requests will be halted at **900 per user,
per minute.** We may
also lower this limit on a temporary basis to manage API availability.
### Concurrent Request Limits (Account-Level)
To protect our systems and manage availability across customers, we set a
reasonable limit on
concurrent requests at the account level. Customers should not expect to hit
this limit unless they
are hitting the API with heavy operations from many concurrent threads at
once.
### Monthly Plan Tier Limits (Account-Level)
The overall number of requests you can make per month will depend on your
account's plan tier.
**This monthly account-level limit resets at the end of each calendar
month.** Current rate limits
by plan tier are:
| Plan Tier | Calls Per Month |
| ---------- | --------------- |
| Essentials | None |
| Scale | 100k |
| Advanced | 100k |
| Enterprise | Unlimited\* |
\*Per-Minute and Concurrent Request Limits still apply.
### Rate Limit Headers
All API calls will return the following response headers with information
about per-minute and
monthly limits:
| Header |
Description |
| -------------------------------- |
------------------------------------------------------- |
| x-ratelimit-limit-user | Number of requests allowed per minute
for the user |
| x-ratelimit-limit-user-remaining | Number of requests remaining for the
user |
| x-ratelimit-limit-user-reset | Time in seconds before the limit resets
for the user |
| x-ratelimit-limit-org | Number of requests allowed per month
for the account |
| x-ratelimit-limit-org-remaining | Number of requests remaining for the
account |
| x-ratelimit-limit-org-reset | Time in seconds before the limit resets
for the account |
## Pagination
When an endpoint is expected to return multiple results, we break the
results into pages to make
them easier to handle. To cycle forward through multiple pages of data, look
for the `nextUrl`
property in the `pagination` portion of an API response, and use it for your
next request. See
endpoint documentation for more information.
## Filtering
Some endpoints support a filtering language for flexible and powerful
queries. This allows for the
creation of complex filter expressions using different operators and boolean
logic in a single
filter string. The description of each endpoint will contain information on
which filter properties
and operators are supported.
### Rules
- Spaces are insignificant by default. For example, `field = hello` and
`field=hello` are both
valid.
- If spaces are significant, they need to be inside double quotes, for
example,
`field = "hello world"`
- Special characters need to be escaped with a backslash: `field="hello\"
world"`
Full list of
special characters: `\ * ~ ! & = > < $ ^ | " ' ( ) ] [ /`
- Use `&` and `|` for boolean operations: `foo = 1 | baz = 2 & bar = 3`.
Boolean Algebra Logic is
assumed: `&` takes precedence over `|`. When evaluating the condition above, `baz = 2 & bar = 3`
will be computed first, and then the result will be `or`'ed with `foo=1`
- Parentheses can be used to specify the order of operations. In the example
above, to make sure
that `foo = 1 | baz = 2` is evaluated first, parentheses must be placed
`(foo = 1 | baz = 2) & bar = 3`
### Grammar
#### Simple Types
| Definition | Property
Type | Operator |
Example
|
| ------------------------ |
---------------------------------------------------- | -------- |
-----------------------------------------------------------------------------------------
|
| exact match |
all | = | content =
“hello world”
content=hello |
| starts with |
text | =^ | content =^
he
|
| ends with |
text | =$ | content =$
llo
|
| contains |
text | =~ | content =~
lo
|
| greater than | int32, int64, float, double, decimal, date,
datetime | \> | count >
1
|
| greater than or equal to | int32, int64, float, double, decimal, date,
datetime | \>= | content >=
1
|
| less than | int32, int64, float, double, decimal, date,
datetime | \< | count <
1
|
| less than or equal to | int32, int64, float, double, decimal, date,
datetime | \<= | content <=
1
|
| is NULL |
all | != \* | content !=
\*
|
| is not NULL |
all | =\* | content =
\*
|
| is empty |
text | ="" | content =
""
|
| negation |
all | ! | content !=
”hello world”
!(content = ”hello world”)
!(content =^ “hello
world”) |
#### Collections (all types)
| Definition | Operator |
Example |
| ------------------------- | -------- |
------------------------------------ |
| exact match with ordering | = | industries =
[Healthcare,Fintech] |
| contains all | =~ | industries =~
[Healthcare,Fintech] |
| empty | =[] | industries
=[] |
| negation | ! | !(industries =
[Healthcare,Fintech]) |
## Error Codes
Here is a list of the error codes the API will return if something goes
wrong (see endpoint
documentation for endpoint-specific errors):
| Error Code |
Meaning
|
| ---------- |
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
| 400 | Bad Request — See endpoint documentation for more
information.
|
| 401 | Unauthorized — Your API key is
invalid.
|
| 403 | Forbidden — Insufficient rights to a
resource.
|
| 404 | Not Found — Requested resource does not exist. See endpoint
documentation for more
information.
|
| 405 | Method Not Allowed — The method being used is not supported
for this
resource.
|
| 422 | Unprocessable Entity — Malformed parameters supplied. This
can also happen in cases the parameters supplied logically cannot complete
the request. In this case, an appropriate error message is delivered. |
| 429 | Too Many Requests — You have exceeded the rate
limit.
|
| 500 | Internal Server Error — We had a problem with our server. Try
again
later.
|
| 503 | Service Unavailable — This shouldn't generally happen.
Contact us if you encounter this
error.
|
## Versioning
Versioning in Affinity’s API ensures that your integrations remain stable as
updates are introduced.
Within API v2, minor versions identify releases that may include breaking or
behavior-changing
modifications, and they allow you to target the exact API behavior your
integration depends on.
When you create an API key in the Settings page, you'll select a **Default
API Version** for that
key. The current available versions are:
- **2024-01-01** - The current stable version of the v2 API
As new minor versions of Affinity API v2 are introduced, they will appear in
this list. You’ll be
able to create new keys using those versions or update an existing key to
use a newer version.
## Beta Endpoints
You’ll notice in our documentation that some endpoints will be marked as
BETA. These endpoints are
newly released and will eventually progress to General Availability (GA).
While an endpoint is in
BETA there are some important things to consider:
- The development of this endpoint may still be in progress. This means new
capabilities, request
parameters, response data, and performance improvements may be adjusted over time. Because of
this, breaking changes may occur to the endpoint WITHOUT notice or versioning.
- As this is an early release, bug fixes may still be ongoing as well, and
we encourage you to
report bugs to [support@affinity.co](mailto:support@affinity.co).
- In addition, your feedback around the capabilities of the endpoint are
highly valuable, please
reach out to your CSM to provide feedback to our product team.
# Data Model
## The Basics
The three top-level objects in Affinity are **Persons, Companies, and
Opportunities**. (Note:
Companies are called Organizations in the Affinity web app.) These have
profiles in the Affinity web
app and can be added to Lists.
A **List** is a spreadsheet-like collection of rows tied to Persons,
Companies, or Opportunities.
- Each row on a List is a **List Entry**. A List Entry contains data and
metadata about a given
Person, Company, or Opportunity in the context of a List. This includes list-specific field data,
and information about who added the row to the List and when.
- A given entity can be added to a List more than once. These List Entries
can have different
List-specific field data and List Entry-level metadata.
Each column on a List maps to a **Field**. Fields show up within Affinity
profile pages, extensions,
and integrations. There are two categories of fields:
- **List-specific fields** are scoped to a single List. In the API, their
data can only be accessed
through the List Entry resource.
- **Global fields** belong to entities directly. These can include default
fields, fields created by
you, enrichment fields, or relationship intelligence fields. They can be accessed through the
Person/Company/Opportunity resources and the List Entry resource.
## 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 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)
## Nested Associations
Some GET endpoints return "association" data under `fields`. For example,
the Persons GET endpoints
return data about which Companies a Person is associated with in Affinity.
The Opportunities GET
endpoints return similar data about associated Companies and Persons. The
List Entries GET endpoints
also return this data for Person and Opportunity List Entries.
The API truncates these nested arrays of Persons or Companies **at 100
entries**. For example, if an
Opportunity is associated with 200 Persons in Affinity, only 100 of those
Persons will be returned
by the GET `/opportunities` or `/opportunities/{id}` endpoint.
# Changelog
## January 30th, 2026
- The following endpoints are no longer in BETA:
| Method | URL |
Summary |
| ------ | ------------------------------------------- |
---------------------------------------------- |
| GET | `/v2/notes` | Get all
Notes |
| GET | `/v2/notes/{noteId}` | Get a Note with a
given id |
| GET | `/v2/notes/{noteId}/attached-companies` | Get directly
attached companies for a Note |
| GET | `/v2/notes/{noteId}/attached-opportunities` | Get directly
attached opportunities for a Note |
| GET | `/v2/notes/{noteId}/attached-persons` | Get directly
attached persons for a Note |
| GET | `/v2/notes/{noteId}/replies` | Get reply notes for
a given Note |
## January 26th, 2026
- Added the following endpoints in BETA:
| Method | URL |
Summary |
| ------ | ------------------------------------------ |
------------------------------------ |
| GET | `/v2/transcripts` | Get All
Transcripts |
| GET | `/v2/transcripts/{transcriptId}` | Get
Transcript |
| GET | `/v2/transcripts/{transcriptId}/fragments` | Get Fragments on a
single Transcript |
## January 14th, 2026
- Rate limit response headers have been updated to use lowercase formatting.
This change affects all
API endpoints. The new lowercase headers are:
| Header |
Description |
| -------------------------------- |
------------------------------------------------------- |
| x-ratelimit-limit-user | Number of requests allowed per minute
for the user |
| x-ratelimit-limit-user-remaining | Number of requests remaining for the
user |
| x-ratelimit-limit-user-reset | Time in seconds before the limit resets
for the user |
| x-ratelimit-limit-org | Number of requests allowed per month
for the account |
| x-ratelimit-limit-org-remaining | Number of requests remaining for the
account |
| x-ratelimit-limit-org-reset | Time in seconds before the limit resets
for the account |
## January 1st, 2026
- API Change: Handling timestamps for date fields. Affinity is standardizing
how dates are
represented across the platform to ensure consistency between the application and the API.
Starting January 1st, 2026, the API will change how it handles timestamps for date fields. Today,
timestamps sent to date fields over the API are not visible to users in any CRM interface. After
this change, the API will ignore any time information included in requests, storing and returning
values at midnight Pacific Time (PT) on the submitted date.
**Example:**
- API request includes: `2024-04-01T15:30:00Z`
- Affinity will store and return: `2024-04-01T07:00:00.000Z` (equivalent to midnight PT)
Any existing date field values that currently include timestamps will also be updated to reflect
midnight PT on their stored date. No action is required unless your integration depends on time
data within date fields.
## September 25th, 2025
- Added the following endpoints in BETA:
| Method | URL |
Summary |
| ------ | ----------------------------------- |
---------------------------- |
| GET | `/v2/company-merges` | Get All Company Merge
status |
| POST | `/v2/company-merges` | Initiate Company
Merge |
| GET | `/v2/company-merges/{mergeId}` | Get Company Merge
status |
| GET | `/v2/tasks/company-merges` | Get All Company Merge
Tasks |
| GET | `/v2/tasks/company-merges/{taskId}` | Get Company Merge
Task |
## July 30th, 2025
- Added the following endpoints in BETA:
| Method | URL |
Summary |
| ------ | ------------------------------------------- |
---------------------------------------------- |
| GET | `/v2/person-merges` | Get All Person
Merge status |
| POST | `/v2/person-merges` | Initiate Person
Merge |
| GET | `/v2/person-merges/{mergeId}` | Get Person Merge
status |
| GET | `/v2/tasks/person-merges` | Get All Person
Merge Tasks |
| GET | `/v2/tasks/person-merges/{taskId}` | Get Person Merge
Task |
| GET | `/v2/notes` | Get all
Notes |
| GET | `/v2/notes/{noteId}` | Get a Note with a
given id |
| GET | `/v2/notes/{noteId}/attached-companies` | Get directly
attached companies for a Note |
| GET | `/v2/notes/{noteId}/attached-opportunities` | Get directly
attached opportunities for a Note |
| GET | `/v2/notes/{noteId}/attached-persons` | Get directly
attached persons for a Note |
| GET | `/v2/notes/{noteId}/replies` | Get reply notes for
a given Note |
## May 14th, 2025
- Renamed all path parameters named simply "id" to a more descriptive name
(eg. "personId"). This
will not have any effect on the API at runtime, but may impact code relying on the OpenAPI spec
doing type generation.
## April 9th, 2025
- The following endpoints are no longer in BETA:
| Method | URL
| Summary |
| ------ | ----------------------------------------------------------------
| ------------------------------------------------- |
| GET | `/v2/lists/{listId}/list-entries/{listEntryId}`
| Get a single List Entry on a List |
| GET | `/v2/lists/{listId}/list-entries/{listEntryId}/fields`
| Get field values on a single List Entry |
| PATCH | `/v2/lists/{listId}/list-entries/{listEntryId}/fields`
| Perform batch operations on a list entry's fields |
| GET | `/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}`
| Get a single field value |
| POST | `/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}`
| Update a single field value on a List Entry |
## March 31st, 2025
- The following beta endpoints now support updating association fields.
| Method | URL
| Summary |
| ------ | ----------------------------------------------------------------
| ------------------------------------------------- |
| PATCH | `/v2/lists/{listId}/list-entries/{listEntryId}/fields`
| Perform batch operations on a list entry's fields |
| POST | `/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}`
| Update a single field value on a List Entry |
## February 28th, 2025
- Added the following endpoints in BETA:
| Method | URL
| Summary |
| ------ | ----------------------------------------------------------------
| ------------------------------------------------- |
| GET | `/v2/lists/{listId}/list-entries/{listEntryId}`
| Get a single List Entry on a List |
| GET | `/v2/lists/{listId}/list-entries/{listEntryId}/fields`
| Get field values on a single List Entry |
| PATCH | `/v2/lists/{listId}/list-entries/{listEntryId}/fields`
| Perform batch operations on a list entry's fields |
| GET | `/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}`
| Get a single field value |
| POST | `/v2/lists/{listId}/list-entries/{listEntryId}/fields/{fieldId}`
| Update a single field value on a List Entry |
## January 17th, 2025
- Document `X-Ratelimit` headers in the schema for all endpoints.
## January 15th, 2025
- Add default responses to all endpoints to document all possible error
codes that can be returned
by the API.
- Updated 400 error responses to correctly include the `bad-request` error
code as a possible error.
## December 3rd, 2024
- Properly document `listId` property on `CompanyListEntry`,
`PersonListEntry`, and
`OpportunityListEntry` schemas.
## September 25th, 2024
- Upgrade schema to OpenAPI 3.1
## August 5, 2024
- Correct `opp` to `opportunity` to match documentation for the `List`
`type` property.
## July 24, 2024
- More accurate documentation for response properties that are enums — Enums
with `null` as a
possible value will have it listed as one.
## March 25, 2024
- Added the ability to retrieve the date and other details of your firm's
"First Email", "Last
Email", "First Event", "Last Event", "Next Event", "First Chat Message", "Last Chat Message", and
"Last Contact" with a given entity. Use these timestamps to add relationship context to your
applications, and to identify founders and companies that need investors' attention.
- Endpoints that previously required a `fieldIds` parameter to return field
data, now accept either
`fieldIds` or `fieldTypes`, and will return field data accordingly. See the
[Specifying Desired Fields (Field Selection)](/pages/data-model/working-with-field-data) section
of these docs for more information. The new `fieldTypes` parameter should make field data
retrieval easier for users looking to pull data from many similar Fields at a time.
## January 4, 2023
- Most endpoints that return field data now require the user to use the
`fieldIds` parameter to
specify which Fields they want data for. Without `fieldIds` specified, these endpoints will return
basic entity data but not field data.
## December 12, 2023
- Added the ability to retrieve metadata (e.g. ID, name, type, enrichment
source, and data type) on
Fields. See the [Retrieving Field Metadata](/pages/data-model/working-with-field-data) section of
these docs for more information.
license:
name: Proprietary
url: https://www.affinity.co/legal/terms-of-use
termsOfService: https://www.affinity.co/legal/terms-of-use
title: Affinity API v2
x-logo:
url: https://assets.affinity.co/img/logos/full-color-svg.svg
altText: Affinity logo
servers:
- url: https://api.affinity.co
security:
- bearerAuth: []
tags:
- description: Operations about Auth
name: Auth
- description: Operations about Calls
name: Calls
- description: Operations about chat messages
name: Chat Messages
- description: Operations about companies
name: Companies
- description: Operations about company merges
name: Company Merges
- description: Operations about emails
name: Emails
- description: Operations about feedback
name: Feedback
- description: Operations about field value changes
name: Field Value Changes
- description: Operations about files
name: Files
- description: Operations about lists
name: Lists
- description: Operations about meetings
name: Meetings
- description: Operations about notes
name: Notes
- description: Operations about opportunities
name: Opportunities
- description: Operations about person merges
name: Person Merges
- description: Operations about persons
name: Persons
- description: Operations about reminders
name: Reminders
- description: Operations about semantic searches
name: Semantic Search
- description: Operations about transcripts
name: Transcripts
- description: Operations about users
name: Users
paths:
/v2/notes:
post:
tags:
- Notes
summary: Create a Note
description: >
| ⚠️ This endpoint is currently in BETA |
|--|
Create a new note. By default it is authored by the calling user; set
`creator` to attribute
it to a different internal person in your organization. Notes can be
attached directly to
entities (`Persons`, `Companies`, `Opportunities`), anchored to an
interaction (`meeting`,
`call`, or `chat message`), or written as a reply to an existing note.
The `type` field selects the shape of the request body. AI Notetaker
note types
(`ai-notetaker`, `ai-notetaker-reply`) are system-generated and cannot
be created through
this endpoint.
| **`type`** | **Description** | **Required** | **Optional** |
|------------|-----------------|--------------|--------------|
| `entities` | A note attached directly to one or more entities. |
`content`, and at least one of `persons` / `companies` /
`opportunities`. | Any combination of `persons` / `companies` /
`opportunities`. |
| `interaction` | A note anchored to a meeting, call, or chat message. |
`content`, `interaction.{type,id}`. | `persons` / `companies` /
`opportunities`, added as direct associations on top of the
interaction's own participants. |
| `user-reply` | A reply to an existing root note. Replies have no
entity associations or interaction attachment of their own. | `content`,
`parent.id` (must reference an existing root note the caller can
access). | None |
By default a note is authored by the calling user. To attribute a note
to a different member
of your organization, set the optional `creator` field to reference that
person by id. The
referenced person must be an active internal person in your
organization.
By default a note's creation time is the time of the request. To
backfill a historical note,
set the optional `createdAt` field to the time the note should be
recorded as created.
**Body content.** `content.html` is rendered HTML that must use only the
allowed tags;
submitting restricted tags, attributes, URL schemes, or mention spans
will cause the request to
fail. See the request examples below for representative payloads.
operationId: v2_notes__POST
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/notes.NoteToBeCreated'
examples:
entities:
$ref: '#/components/examples/entities-2'
interaction:
$ref: '#/components/examples/interaction-4'
user-reply:
$ref: '#/components/examples/user-reply'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/notes.Note'
examples:
entities:
$ref: '#/components/examples/entities-3'
interaction:
$ref: '#/components/examples/interaction-5'
user-reply:
$ref: '#/components/examples/user-reply-2'
headers:
x-ratelimit-limit-user:
$ref: '#/components/headers/X-Ratelimit-Limit-User'
x-ratelimit-limit-user-remaining:
$ref: '#/components/headers/X-Ratelimit-Limit-User-Remaining'
x-ratelimit-limit-user-reset:
$ref: '#/components/headers/X-Ratelimit-Limit-User-Reset'
x-ratelimit-limit-org:
$ref: '#/components/headers/X-Ratelimit-Limit-Org'
x-ratelimit-limit-org-remaining:
$ref: '#/components/headers/X-Ratelimit-Limit-Org-Remaining'
x-ratelimit-limit-org-reset:
$ref: '#/components/headers/X-Ratelimit-Limit-Org-Reset'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
default:
$ref: '#/components/responses/default'
components:
schemas:
notes.NoteToBeCreated:
title: notes.NoteToBeCreated
description: >-
Request body for creating a note. The `type` field selects between three
variants:
- `entities`: a note attached directly to one or more Persons,
Companies, and/or Opportunities.
- `interaction`: a note attached to a meeting, call, or chat message.
May optionally also be associated with additional entities.
- `user-reply`: a reply to an existing root note. Replies have no entity
associations or interaction attachment of their own.
Additional notes:
- By default a note is authored by the calling user. To attribute it to
another member of your organization, set `creator` to reference that
person by id. The referenced person must be an active internal person in
your organization.
- By default a note's creation time is the time of the request. To
backfill a historical note, set `createdAt` to the time the note should
be recorded as created.
- For enterprise customers, the visibility follows the fallback
visibility behavior for the organization.
- System-generated note types (`ai-notetaker`, `ai-notetaker-reply`,
`email`) cannot be created here.
oneOf:
- $ref: '#/components/schemas/notes.EntitiesNoteToBeCreated'
- $ref: '#/components/schemas/notes.InteractionNoteToBeCreated'
- $ref: '#/components/schemas/notes.UserReplyNoteToBeCreated'
discriminator:
propertyName: type
mapping:
entities:
$ref: '#/components/schemas/notes.EntitiesNoteToBeCreated'
interaction:
$ref: '#/components/schemas/notes.InteractionNoteToBeCreated'
user-reply:
$ref: '#/components/schemas/notes.UserReplyNoteToBeCreated'
notes.Note:
title: notes.Note
description: Note model
oneOf:
- $ref: '#/components/schemas/notes.EntitiesNote'
- $ref: '#/components/schemas/notes.InteractionNote'
- $ref: '#/components/schemas/notes.AiNotetakerRootNote'
- $ref: '#/components/schemas/notes.UserReplyNote'
- $ref: '#/components/schemas/notes.AiNotetakerReplyNote'
discriminator:
propertyName: type
mapping:
entities:
$ref: '#/components/schemas/notes.EntitiesNote'
interaction:
$ref: '#/components/schemas/notes.InteractionNote'
ai-notetaker:
$ref: '#/components/schemas/notes.AiNotetakerRootNote'
user-reply:
$ref: '#/components/schemas/notes.UserReplyNote'
ai-notetaker-reply:
$ref: '#/components/schemas/notes.AiNotetakerReplyNote'
notes.EntitiesNoteToBeCreated:
title: notes.EntitiesNoteToBeCreated
description: >-
Request body for creating a note attached directly to one or more
entities. At least one of `persons`, `companies`, or `opportunities`
must include an entry, since a note of this type requires at least one
attached entity.
type: object
properties:
type:
description: >-
The note type. Must be `entities` to create a note attached to only
entities.
type: string
const: entities
content:
$ref: '#/components/schemas/notes.ContentToBeSaved'
creator:
$ref: '#/components/schemas/PersonReference'
description: >-
The person to record as the note's creator. Defaults to the calling
user when omitted, and must reference an active internal person in
your organization.
createdAt:
description: >-
The time to record as when the note was created. Set this to
backfill historical notes with their original date. Defaults to the
current time when omitted.
type: string
format: date-time
examples:
- '2025-01-15T09:30:00Z'
persons:
description: Persons to attach the note to. Each item references a Person by id.
type: array
items:
$ref: '#/components/schemas/PersonReference'
maxItems: 100
examples:
- - id: 1
- id: 2
companies:
description: >-
Companies to attach the note to. Each item references a Company by
id.
type: array
items:
$ref: '#/components/schemas/CompanyReference'
maxItems: 100
examples:
- - id: 10
opportunities:
description: >-
Opportunities to attach the note to. Each item references an
Opportunity by id.
type: array
items:
$ref: '#/components/schemas/OpportunityReference'
maxItems: 100
examples:
- - id: 100
required:
- type
- content
additionalProperties: false
notes.InteractionNoteToBeCreated:
title: notes.InteractionNoteToBeCreated
description: >-
Request body for creating a note attached to an interaction. Notes can
be attached to a meeting, call, or chat message.
`interaction.type` and `interaction.id` are both required and must
reference a meeting, call, or chat message the caller can access. Notes
of this type are anchored to a single interaction. Entity associations
(`persons`, `companies`, `opportunities`) are optional and can
supplement the interaction attachment as additional direct associations
on top of the interaction's own participants. The interaction
participants are implicitly associated with the note by virtue of the
interaction attachment, so they do not need to be included in the
`persons` array unless the caller wants to create additional direct
associations beyond those implied by the interaction itself.
type: object
properties:
type:
description: The note type. Must be `interaction` to create an interaction note.
type: string
const: interaction
content:
$ref: '#/components/schemas/notes.ContentToBeSaved'
creator:
$ref: '#/components/schemas/PersonReference'
description: >-
The person to record as the note's creator. Defaults to the calling
user when omitted, and must reference an active internal person in
your organization.
createdAt:
description: >-
The time to record as when the note was created. Set this to
backfill historical notes with their original date. Defaults to the
current time when omitted.
type: string
format: date-time
examples:
- '2025-01-15T09:30:00Z'
interaction:
$ref: '#/components/schemas/notes.InteractionReference'
persons:
description: >-
Persons to additionally attach the note to, beyond those implied by
the interaction itself. Each item references a Person by id.
type: array
items:
$ref: '#/components/schemas/PersonReference'
maxItems: 100
companies:
description: >-
Companies to additionally attach the note to. Each item references a
Company by id.
type: array
items:
$ref: '#/components/schemas/CompanyReference'
maxItems: 100
opportunities:
description: >-
Opportunities to additionally attach the note to. Each item
references an Opportunity by id.
type: array
items:
$ref: '#/components/schemas/OpportunityReference'
maxItems: 100
required:
- type
- content
- interaction
additionalProperties: false
notes.UserReplyNoteToBeCreated:
title: notes.UserReplyNoteToBeCreated
description: >-
Request body for creating a user reply to an existing note. `parent.id`
is required and must reference an existing root note (not itself a
reply) that the caller can access.
Reply notes do not support entity associations or interaction
attachments. Replies to AI Notetaker notes are also created with `type:
user-reply`; the reply itself is a user-authored note, not an
AI-generated one.
type: object
properties:
type:
description: The note type. Must be `user-reply` to create a reply note.
type: string
const: user-reply
content:
$ref: '#/components/schemas/notes.ContentToBeSaved'
creator:
$ref: '#/components/schemas/PersonReference'
description: >-
The person to record as the note's creator. Defaults to the calling
user when omitted, and must reference an active internal person in
your organization.
createdAt:
description: >-
The time to record as when the note was created. Set this to
backfill historical notes with their original date. Defaults to the
current time when omitted.
type: string
format: date-time
examples:
- '2025-01-15T09:30:00Z'
parent:
$ref: '#/components/schemas/notes.NoteReference'
required:
- type
- content
- parent
additionalProperties: false
notes.EntitiesNote:
title: notes.EntitiesNote
description: A Note object attached to an entity (Person, Company, Opportunity)
allOf:
- $ref: '#/components/schemas/notes.BaseRootNote'
properties:
type:
description: The type of the note
type: string
const: entities
required:
- type
example:
id: 1
type: entities
content:
html: This is a note!
creator:
id: 1
firstName: Jane
lastName: Smith
primaryEmailAddress: jane.smith@northpointvc.com
type: internal
mentions: []
createdAt: '2023-01-01T00:00:00Z'
updatedAt: '2023-01-21T00:00:00Z'
notes.InteractionNote:
title: notes.InteractionNote
description: >-
A Note object attached to an interaction (Email, Meeting, Call,
ChatMessage)
allOf:
- $ref: '#/components/schemas/notes.BaseRootNote'
properties:
type:
description: The type of the note
type: string
const: interaction
interaction:
$ref: '#/components/schemas/notes.Interaction'
required:
- type
- interaction
example:
id: 1
type: interaction
content:
html: This is a note!
creator:
id: 1
firstName: Jane
lastName: Smith
primaryEmailAddress: jane.smith@northpointvc.com
type: internal
mentions: []
createdAt: '2023-01-01T00:00:00Z'
updatedAt: '2023-01-21T00:00:00Z'
interaction:
id: 2
type: call
notes.AiNotetakerRootNote:
title: notes.AiNotetakerRootNote
description: A Root Note object created by the AI Notetaker
allOf:
- $ref: '#/components/schemas/notes.BaseRootNote'
properties:
type:
description: The type of the note
type: string
const: ai-notetaker
interaction:
$ref: '#/components/schemas/notes.MeetingInteraction'
description: The meeting this AI Notetaker was invited to.
transcriptId:
description: The id of the transcript of the AI notetaker note
type: integer
format: int32
minimum: 1
maximum: 2147483647
example: 1234
required:
- type
- transcriptId
example:
id: 1
type: ai-notetaker
content:
html: This is an AI Notetaker note!
creator:
id: 1
firstName: Jane
lastName: Smith
primaryEmailAddress: jane.smith@northpointvc.com
type: internal
transcriptId: 1
mentions: []
createdAt: '2023-01-01T00:00:00Z'
updatedAt: '2023-01-21T00:00:00Z'
notes.UserReplyNote:
title: notes.UserReplyNote
description: A reply to a note created by a user
type: object
allOf:
- $ref: '#/components/schemas/notes.BaseReply'
properties:
type:
description: The type of the note
type: string
const: user-reply
required:
- type
example:
id: 2
type: user-reply
content:
html: This is a user reply note!
creator:
id: 1
firstName: Jane
lastName: Smith
primaryEmailAddress: jane.smith@northpointvc.com
type: internal
mentions: []
parent:
id: 1
createdAt: '2023-01-01T00:00:00Z'
updatedAt: '2023-01-21T00:00:00Z'
notes.AiNotetakerReplyNote:
title: notes.AiNotetakerReplyNote
description: A reply to a Note, created by an AI Notetaker
type: object
allOf:
- $ref: '#/components/schemas/notes.BaseReply'
properties:
type:
description: The type of the note
type: string
const: ai-notetaker-reply
interaction:
$ref: '#/components/schemas/notes.MeetingInteraction'
description: The meeting this AI Notetaker was invited to.
transcriptId:
description: The id of the transcript of the AI notetaker reply note
type: integer
format: int32
minimum: 1
maximum: 2147483647
example: 1234
required:
- type
- transcriptId
example:
id: 2
type: ai-notetaker-reply
content:
html: This is an AI Notetaker reply note!
creator:
id: 1
firstName: Jane
lastName: Smith
primaryEmailAddress: jane.smith@northpointvc.com
type: internal
mentions: []
transcriptId: 1
parent:
id: 1
createdAt: '2023-01-01T00:00:00Z'
updatedAt: '2023-01-21T00:00:00Z'
BadRequestError:
title: BadRequestError
type: object
properties:
code:
description: Error code
type: string
const: bad-request
example: bad-request
message:
description: Error message
type: string
required:
- code
- message
additionalProperties: false
ValidationError:
title: ValidationError
type: object
properties:
code:
description: Error code
type: string
const: validation
example: validation
message:
description: Error message
type: string
param:
description: Param the error refers to
type: string
example: limit
required:
- code
- message
- param
additionalProperties: false
AuthorizationErrors:
title: AuthorizationErrors
description: AuthorizationErrors model
type: object
properties:
errors:
description: AuthorizationError errors
type: array
items:
$ref: '#/components/schemas/AuthorizationError'
required:
- errors
additionalProperties: false
NotFoundErrors:
title: NotFoundErrors
description: NotFoundErrors model
type: object
properties:
errors:
description: NotFoundError errors
type: array
items:
$ref: '#/components/schemas/NotFoundError'
required:
- errors
additionalProperties: false
Errors:
title: Errors
type: object
properties:
errors:
description: Errors
type: array
items:
$ref: '#/components/schemas/Error'
required:
- errors
additionalProperties: false
notes.ContentToBeSaved:
title: notes.ContentToBeSaved
description: >-
The note's body content. Only `html` is supported on write; supply
rendered HTML limited to the allowed tags listed below.
type: object
properties:
html:
description: >
The HTML content of the note.
**Allowed tags (with no attributes other than those explicitly
noted):**
``, `
`, ``, ``, ``, ``, `